EvidenceForge

Offline binary and application artifact triage, with reproducible evidence and beautiful release diffs.

EvidenceForge is a small, independent Python project for anyone who needs to answer: What's in this build? Which endpoints or dangerous configuration clues appeared? What changed between releases? It requires no Hopper, Ghidra, Node.js or cloud model, and never executes the target.

Scope: EvidenceForge is an early working alternative for static artifact inventory and comparison, not a replacement for full decompilation or runtime investigation. It is not affiliated with or endorsed by REA.

Why this exists

Deep reverse-engineering frameworks are excellent for call graphs, decompilation and runtime tracing. EvidenceForge optimizes a narrower workflow: download an artifact → produce immutable, reviewable observations → diff before/after → hand summaries to an AI agent.

Related MCP server: EvidenceLens MCP

Quick start

# Python 3.10+; no install required from a checked-out repository
PYTHONPATH=src python -m evidenceforge scan ./path/to/app --json build-a.json --html build-a.html

# Optionally install editable CLI from this source tree
python -m pip install -e .
evidenceforge scan ./release-v1 --json baseline.json --html baseline.html
evidenceforge scan ./release-v2 --json current.json --html current.html
evidenceforge diff baseline.json current.json --json delta.json --html delta.html

On Windows PowerShell, after python -m pip install -e ., use the evidenceforge command directly. Review the HTML offline in your browser. --stdout-json prints the complete report to the terminal; normal output is a compact summary.

Reports are not silently overwritten; pass --overwrite if you explicitly want to replace a file. If the scanner hits a budget or unsafe entry, summary.complete is false and the warning explains the limit.

Example agent integration via MCP

MCP tools are read-only, and disabled for file access until approved roots are provided.

macOS/Linux:

export EVIDENCEFORGE_ALLOWED_ROOTS='["/absolute/path/to/samples"]'
evidenceforge mcp

Windows PowerShell:

$env:EVIDENCEFORGE_ALLOWED_ROOTS='["C:\\Users\\you\\samples"]'
evidenceforge mcp

Configure your MCP-compatible client to start the evidenceforge mcp command, passing that environment variable in the registration. The tools are evidenceforge_scan and evidenceforge_compare. This MCP endpoint is intentionally minimal; compatibility should be verified against your specific client.

Understanding the evidence

Each file record includes path, size, sha256, format, entropy, and selected evidence with byte offsets and either:

• confidence: observed — literal bytes such as a URL were seen at an offset; this does not imply the endpoint is used.

• confidence: inferred — static text suggests a security-relevant code setting or API. It is not proof of reachable behavior.

The report digest is canonical SHA-256 over the JSON content without its own digest field; the CLI verifies it before diffing. It is not signed and cannot prove provenance against a determined attacker.

Tuning resource limits

evidenceforge scan ./my-build --max-files 500 --max-file-mb 16 --max-total-mb 128 --json artifact.json

Default scanning is bounded at 1,500 files, 8 MiB each, 64 MiB total, depth 12, and 200:1 ZIP compression ratio. The scanner does not follow symlinks or recurse into archive members that themselves are ZIPs. For detailed threat boundaries, see SECURITY.md.

Testing

python -m pip install -e .
python -m unittest discover -s tests -v

CI runs these tests on Linux, Windows, and macOS, with Python 3.10 and 3.13.

Architecture

src/evidenceforge/
├── scanner.py       # Controlled file / folder / ZIP reading, evidence extraction
├── formats.py       # Shallow ELF / PE / Mach-O / file type recognition
├── diff.py          # Deterministic comparison, no execution
├── model.py         # Stable schemas and integrity digests
├── report.py        # Script-free HTML renderer
├── mcp.py           # Root-confined, read-only MCP adapter
└── cli.py           # User-facing commands

Roadmap

• Optional signed attestations and report verification

• Better PE import and ELF dynamic-symbol parsing with strict bounds

• Source maps / ASAR parsing in read-only mode

• Better graph/visual diff of Electron security boundary changes

• MCP client integration tests and advanced schema validation

Legal and ethical use

Analyze only software that you own or are authorized to inspect. Respect software licenses, privacy, export rules, and applicable law. The program is provided without any guarantee that its observations are complete or secure.

License

MIT. Independent original implementation; no code copied from REA. Reference: morluto/rea.