TraceForge

TraceForge is a small, read-only toolkit for inspecting native binaries and keeping the result as verifiable Evidence. It does not execute the target, does not upload data, and does not require a cloud service.

$ tforge scan /bin/ls

TraceForge · scan

path     /bin/ls
sha256   13f44bfe1c4af602da4465c834dbe7b16a5441ccbd843178b36116ee23422bfb
size     252,512 bytes
format   mach-o

Slices
  x86_64  64-bit little  executable
    12 sections · 91 imports · 1 exports · 3 libraries
  arm64e  64-bit little  executable
    11 sections · 90 imports · 1 exports · 3 libraries
  arm64   64-bit little  executable
    11 sections · 90 imports · 1 exports · 3 libraries
Evidence ev_157a66f293e5161b44cd5889b8a39555d2878d84e659d33b37019791d568dd75 (scan)

Why TraceForge

• Read-only by construction. Analysis never launches the target.

• Evidence, not screenshots. Every result has a content-addressed evidence_id, a SHA-256 input identity, limitations, and a local JSON record.

• Deterministic records. Stable JSON canonicalization means the same input and result produce the same identity.

• Agent-native. A dependency-free MCP stdio server exposes the same core.

• Zero telemetry. No network calls, no accounts, no background service.

• Small dependency surface. Runtime code uses Node built-ins only.

Related MCP server: Flameox

Install

git clone https://github.com/Mutersec/traceforge.git
cd traceforge
npm ci
npm run build
npm link            # optional: exposes `tforge` and `traceforge`

Or run without linking:

node dist/cli.js scan /bin/ls

Commands

Common flags: --json, --store <dir>, --no-save, --debug. Use --out report.html with report; npm run demo runs the whole showcase.

Evidence is written to .traceforge/evidence by default. Use --no-save for a one-shot inspection.

Evidence report

tforge report /bin/ls --out traceforge-report.html

The report is a standalone HTML file: identity badge, input hash, sections, imports/exports and limitations. It is generated from the same authenticated record and contains no external scripts.

See docs/demo.md for a three-minute non-technical and technical demo script.

MCP

Add TraceForge to any MCP client:

{
  "mcpServers": {
    "traceforge": {
      "command": "node",
      "args": ["/absolute/path/to/traceforge/dist/cli.js", "mcp"],
      "env": {
        "NO_COLOR": "1"
      }
    }
  }
}

Tools:

• scan_binary

• inspect_binary

• compare_binaries

• get_evidence

• list_evidence

The protocol is newline-delimited JSON-RPC 2.0 over stdio. See docs/mcp.md.

Supported formats

TraceForge is an inspector, not a disassembler. It does not reconstruct code or execute targets. Stripped binaries may expose fewer symbols. Parser limits and coverage are documented in docs/parsers.md.

Architecture

flowchart LR
  A[CLI] --> O[Operations]
  M[MCP stdio] --> O
  O --> P[Format parsers]
  O --> E[Evidence store]
  P --> M1[Mach-O]
  P --> E1[ELF]
  P --> P1[PE]
  P --> W1[WASM]
  E --> S[(.traceforge/evidence)]

The parsers own byte interpretation. Operations compose input identity, result and limitations into one record. The store owns durability and authentication; adapters never re-interpret parser facts.

Safety

• Targets are opened read-only.

• Files larger than 512 MiB are rejected before parsing.

• Section hashing is capped at 64 MiB per section.

• Bounds, counts and string lengths are checked before allocation.

• Evidence is written atomically with owner-only permissions.

• The tool does not execute, attach to, or modify targets.

See SECURITY.md for reporting and docs/roadmap.md for the next increments.

Development

npm ci
npm run typecheck
npm test
npm run build
npm run check      # typecheck + tests + build

Tests cover synthetic ELF/PE/WASM fixtures, Evidence integrity, bundle round-trips, MCP protocol and a real macOS Mach-O when run on Darwin. CI runs on Node 22 and 24.

Performance

Measured on an Apple Silicon arm64 host with Node 24, 25 iterations over a 252,512-byte universal Mach-O:

The benchmark is local and parser-only; it does not execute the target or use a network. Reproduce with npm run bench -- /bin/ls. These numbers are a starting point, not a cross-tool comparison.

License

MIT © 2026 Mutersec.