# 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](https://github.com/morluto/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**.

| Capability | EvidenceForge v0.1 |
| --- | --- |
| Offline Python 3.10+, stdlib-only runtime | ✅ |
| ELF, PE, Mach-O, JavaScript/TypeScript and ZIP recognition | ✅ Shallow metadata |
| Folder and safe ZIP entry inventory | ✅ Bounded |
| SHA-256, entropy and evidence offset recording | ✅ |
| Selected web endpoints (redacted) and Electron configuration clues | ✅ Heuristic |
| JSON snapshot + standalone HTML review | ✅ |
| Deterministic release comparisons | ✅ |
| Read-only, allowlisted MCP tools | ✅ Experimental |
| Native decompilation / debugger / runtime tracing | ❌ Out of scope |
| Malware verdicts and vulnerability proof | ❌ Out of scope |

## Quick start

```bash
# 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**:

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

**Windows PowerShell**:

```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

```bash
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](SECURITY.md).

### Testing

```bash
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

```text
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](https://github.com/morluto/rea).