FirmLoc

Automated vulnerability root cause functions localization approach for IoT firmware.

Quick Start

Copy the example configuration before running the CLI:

cp config/config.ini.example config/config.ini

Run a firmware diff analysis with the required inputs:

python -m vulnagent_cli \
  --old-firmware /path/to/old.bin \
  --new-firmware /path/to/new.bin \
  --cve-id CVE-2024-0000 \
  --workdir runs/demo

Required arguments:

• --old-firmware: path to the pre-patch firmware-like input that can be extracted and processed.
• --new-firmware: path to the post-patch firmware-like input that can be extracted and processed.
• --cve-id: CVE identifier for reproduction mode, for example CVE-2024-0000.
• --workdir: directory where runtime state, extracted artifacts, IDA output, BinDiff output, and reports are written.

Useful optional arguments:

• --config: configuration file path; defaults to config/config.ini.
• --target: optional device, product, firmware, or binary name to guide candidate selection, for example DIR-878 or httpd; omit it to let CVE details and firmware differences drive selection.
• --idat32-path: override the [IDA] idat32_path setting for the current run.
• --idat64-path: override the [IDA] idat64_path setting for the current run.
• --analysis-mode: choose auto or firmware for the current supported path.
• --skip-online-search: use local CVE details only and skip online search.
• --cve-details-file: read CVE details from a local text file.
• --json: print progress events as JSON lines on stdout.

Direct Linux IDA Requirements

Real analysis runs invoke IDA directly on the local Linux host. Install and configure:

• idat for 32-bit IDA batch execution.
• idat64 for 64-bit IDA batch execution.
• BinExport plugin available to the configured IDA installation.
• Hex-Rays decompiler; the current analysis path exports pseudo-C.
• BinDiff CLI for comparing generated BinExport files.
• binwalk or 7z for firmware extraction, plus configured LLM credentials.

Configure the direct IDA command paths in config/config.ini:

[IDA]
idat32_path = /opt/ida/idat
idat64_path = /opt/ida/idat64

The CLI flags --idat32-path and --idat64-path override those config values for a single run.

Output Layout

Each run writes artifacts under the directory passed with --workdir:

• events.jsonl: append-only progress events.
• run_state.json: latest run inputs, layout, status, and error state when applicable.
• report.json: final machine-readable report for completed runs.
• report.md: final Markdown summary for completed runs.
• online_search/: online CVE search artifacts when online search is enabled.
• binwalk/: firmware extraction artifacts.
• ida/: copied target binaries, BinExport files, pseudo-C exports, and IDA logs.
• bindiff/: BinDiff outputs per analyzed binary pair.

Tests

Run the test suite with:

PYTHONDONTWRITEBYTECODE=1 pytest -q -p no:cacheprovider

Tests monkeypatch external integrations and do not run real Binwalk, BinDiff, IDA, NVD, or LLM services.