41 lines
1.3 KiB
Markdown
41 lines
1.3 KiB
Markdown
# API Reference: Diffing Malware Samples to Find Changes
|
|
|
|
## Overview
|
|
|
|
`scripts/analyst.py` structurally diffs two PE samples: per-section SHA-256 and entropy, import name
|
|
set differences, and a byte-level similarity ratio, optionally adding an ssdeep comparison score.
|
|
It reads bytes statically and executes nothing. Function-level diffing (BinDiff/Diaphora) is out of
|
|
scope.
|
|
|
|
## Dependencies
|
|
|
|
| Package | Version | Purpose |
|
|
|---------|---------|---------|
|
|
| pefile | latest | import table parsing (optional) |
|
|
| ssdeep | latest | fuzzy-hash similarity (optional) |
|
|
| (stdlib) | — | difflib, hashlib, struct, math, JSON |
|
|
|
|
## Core functions
|
|
|
|
### `diff(path_a, path_b)`
|
|
Returns added/removed/changed sections, added/removed imports, byte similarity ratio, and (if
|
|
available) ssdeep score.
|
|
|
|
### `_sections(data)`
|
|
Per-section SHA-256 and entropy keyed by section name.
|
|
|
|
### `_imports(data)`
|
|
Imported symbol name set via pefile (empty if unavailable).
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
python scripts/analyst.py diff a.bin b.bin
|
|
```
|
|
|
|
## Sources
|
|
|
|
- PE Format (section table, import directory) — https://learn.microsoft.com/windows/win32/debug/pe-format
|
|
- ssdeep context-triggered piecewise hashing — https://ssdeep-project.github.io/ssdeep/
|
|
- Structural variant-diffing approach (section/import deltas) from public triage practice
|