AVFileTrim

    ___ _    _________ __   ______     _         
   /   | |  / / ____(_) /__/_  __/____(_)___ ___ 
  / /| | | / / /_  / / / _ \/ / / ___/ / __ `__ \
 / ___ | |/ / __/ / / /  __/ / / /  / / / / / / /
/_/  |_|___/_/   /_/_/\___/_/ /_/  /_/_/ /_/ /_/ 

  AV signature boundary finder

   / \       / \
  /   \_____/   \        oink oink — sniffing out signatures
 |  0           0 |      one byte at a time...
 |       __       |
  \     (__) ___ /
   `\_________.-'
       | | | |
      (_) (_)

Trim a binary file at regular byte increments and upload each slice to VirusTotal or MetaDefender to pinpoint exactly where an antivirus signature starts. Useful for security research, malware analysis, and understanding detection heuristics.

---

Features

• Multiple scanners — VirusTotal or MetaDefender, selectable with --scanner
• Linear scan — upload every slice and record detections at each offset
• Bisect scan — binary-search for the first detected offset, minimising API calls
• Offline mode — no API key needed; slices are written to disk for manual upload
• Dry run — preview slice offsets without touching the network or disk
• JSON export — machine-readable results with per-engine hits and report permalinks
• Configurable output directory — defaults to ./out/

---

Installation

Requires Python 3.11+.

# recommended: isolated install via pipx
pipx install .

# or inside a virtual environment
python -m venv .venv
source .venv/bin/activate
pip install .

---

Usage

avfiletrim [OPTIONS] FILE

Option	Short	Default	Description
--increment	-i	4096	Byte step between slices
--strategy	-s	linear	linear or bisect
--scanner	-S	virustotal	virustotal or metadefender
--api-key	-k	env var	API key for the chosen scanner (optional)
--delay	-d	per-scanner	Seconds between uploads (16 VT / 6 MetaDefender)
--output	-o	—	Save scan results as JSON
--output-dir	-O	out/	Directory for offline slices
--dry-run			Preview offsets only

Examples

# Slice every 8 KB and scan with VirusTotal — key from environment variable
VT_API_KEY=xxxx avfiletrim malware.exe -i 8192

# Scan with MetaDefender instead
MCL_API_KEY=xxxx avfiletrim malware.exe -S metadefender

# Binary-search with explicit key, save results
avfiletrim sample.exe -s bisect -k $VT_API_KEY -o results.json

# No API key: write slices to ./out/ for manual upload
avfiletrim payload.exe -i 4096

# Write slices to a custom directory
avfiletrim payload.exe -i 4096 -O /tmp/slices

# Preview what would be uploaded without touching anything
avfiletrim payload.exe -i 1024 --dry-run

Offline slice output

Without an API key, slices are saved as:

out/
  payload_0000004096.exe
  payload_0000008192.exe
  payload_0000012288.exe
  ...

Each filename encodes the trim offset, making it easy to sort and correlate results after manual upload.

---

API keys

Each scanner reads its key from a dedicated environment variable, or you can pass it explicitly with --api-key:

Scanner	Sign up	Environment variable
VirusTotal	https://www.virustotal.com	VT_API_KEY
MetaDefender	https://metadefender.opswat.com	MCL_API_KEY

export VT_API_KEY=your_virustotal_key
export MCL_API_KEY=your_metadefender_key

Free tiers are rate-limited (VirusTotal: 4 req/min, 500/day), so AVFileTrim throttles uploads automatically; tune the pace with --delay.

---

License

Apache License 2.0 — see LICENSE.