HexWitness README

Give your reverse-engineering agent a memory, a map, and receipts.
HexWitness turns static analysis, runtime captures, and human conclusions into one durable evidence graph.

Quick start · Why it matters · Examples · Docs · How it compares

Yesterday, your agent found the parser, mapped its callers, and proved which runtime event reached it. Today, a new chat opens and asks the live disassembler to discover everything again.

HexWitness stops that loop.

flowchart LR
  V["Binary Ninja · IDA · Ghidra"] --> X["Reviewed evidence"]
  R["Frida · debugger · wire observer"] --> C["Sealed capture"]
  C --> X
  X --> E[("HexWitness memory")]
  E --> A["Your AI agent"]
  A --> Q["Answer with proof"]
  A -.->|one named gap| V

The live viewer remains the agent's eyes. HexWitness becomes its case file: tied to an exact build, searchable across tools, honest about conflicts, and ready for the next agent.

See it work in 60 seconds

Requirements: Git and Node.js 22.13 or newer.

npm install --global hexwitness
hexwitness setup
hexwitness demo

The setup wizard connects HexWitness to Codex, Claude Code, Cursor, VS Code/Copilot, Claude Desktop, or generic MCP clients. It also installs guidance written for that agent. The MCP entry starts the local read-only daemon when needed, so there is no service choreography.

Now ask:

Use HexWitness to explain 0x401120 in build toy-v1.
Show proof, contradictions, and missing evidence separately.

The demo uses synthetic, redistributable evidence. No third-party binary data ships with HexWitness.

Prefer a checkout?

git clone https://github.com/siaginw/HexWitness.git
cd HexWitness
npm install
npm run demo
npm run setup -- --client codex --viewer none --yes
npm run doctor

Replace codex with claude-code, cursor, copilot, or generic as needed. The setup command resolves the checkout's absolute local runtime path, installs guidance tailored to the selected agent, and writes the MCP connection without requiring a global install. Restart the selected AI client after setup, then ask it to call hexwitness_health and hexwitness_contract. Both must succeed before using private evidence.

[!IMPORTANT] The checked-in .mcp.json.example assumes npm install --global hexwitness. From a source checkout, run npm run setup instead of copying that example; setup records the correct local Node.js and bundled-runtime paths.

HexWitness installs as one command. The service, MCP transport, installer, capture pipeline, and adapter catalog live behind that command:

hexwitness agent                 # daemon autostart + MCP for AI clients
hexwitness serve                 # REST daemon only
hexwitness adapters              # list every included viewer/runtime adapter
hexwitness adapters binary-ninja # print one adapter's exact path and capabilities
hexwitness contract              # inspect the stable 1.x public contract
hexwitness backup ./evidence.db  # create and verify a consistent snapshot

Official MCP Registry identity: io.github.siaginw/hexwitness. Registry-aware clients discover the same local stdio server published through npm; its declared launch contract is hexwitness agent.

The npm package ships one bundled runtime instead of exposing its internal module tree. Python remains only in the thin Binary Ninja, IDA, and Ghidra exporters because those products expose their supported automation APIs through Python. Large JSONL exports and long captures are streamed through atomic ingest and disk-backed normalization instead of being loaded wholesale into memory.

Why HexWitness feels different

Most RE integrations solve access: let an agent read a decompiler, debugger, or trace. HexWitness solves continuity: keep the useful result after that tool, build, or chat is gone.

That makes HexWitness especially useful when:

• the binary changes and addresses move;
• several agents or analysts share work;
• static code must line up with runtime behavior;
• a conclusion needs a reproducible chain of evidence;
• a failed capture must be compared with a working one;
• “we think” needs to become “we proved.”

Read the honest category comparison in Why HexWitness.

Ask real questions

Users ask about the target. The agent chooses the tools.

Which function validates frame length before dispatch?
Reuse retained evidence first. Inspect a live viewer only if one exact edge is missing.

Compare the working and failing login captures.
Find the first meaningful divergence, then resolve its static consumer.

Where is this UUID used, which class owns it, and did its field offset change
between builds?

HexWitness gives agents first-class queries for builds, functions, classes, UUIDs, types, fields, vtables, calls, xrefs, paths, dataflow, captures, contradictions, coverage, evidence gaps, durable investigations, failed attempts, challenges, and discovery-only retrieval. Four MCP prompts package investigation, runtime comparison, live-finding promotion, and adversarial evidence-review workflows.

One investigation loop

1. Remember. Query retained evidence before touching a live tool.
2. Pin. Select the exact artifact build; never carry an address across builds by habit.
3. Resolve. Search the subject, then read its full evidence dossier.
4. Narrow. Traverse only the calls, fields, slices, or capture window needed.
5. Challenge. Surface provenance, confidence, and contradictory claims.
6. Escalate. If proof ends, name the smallest missing live observation.
7. Promote. Export that bounded result so the next investigation starts smarter.

For longer work, deterministic playbooks seed persistent checklists and operation budgets. Failed methods stay searchable. An evidence challenge surfaces opposition, unsupported claims, and open gaps without allowing agent consensus to inflate confidence.

Agents can also run allowlisted local RE utilities through one explicit MCP tool: argv-only, cwd-rooted, timed, output-capped, and receipt-producing. It is not an OS sandbox. Tool output remains an observation until promoted through the evidence model. No environment enable switch or separate model-provider key is required. See Investigation workbench.

The database remembers evidence. A separate privacy-safe activity store remembers operation hashes, timing, status, and counts—never prompts, arguments, or returned evidence.

Runtime capture without command soup

Collectors place conventional files and a small manifest in one private folder:

roundtrip/
├── capture.json
├── wire.jsonl
├── hooks.jsonl
├── screen.mp4
└── context.json

Then:

hexwitness capture ./private/roundtrip

HexWitness checks the required roles and action markers, copies artifacts into an isolated private pack, normalizes a safe timeline by removing secret fields and replacing payloads with length plus SHA-256, seals checksums, verifies integrity, and imports the evidence. Missing or empty baseline artifacts fail closed. A failed normalization leaves the source pack recoverable.

See Capture packs for collector and scenario contracts.

Works with your stack

HexWitness does not ship a weaker disassembler inside the project. Viewer MCPs provide live eyes. Exporters turn reviewed findings into portable memory. Read Viewer MCP bridges and the Adapter SDK.

One truth, three interfaces

All three read the same SQLite evidence graph. Imports are transactional and idempotent. Addresses remain canonical hexadecimal strings, including unsigned 64-bit values.

Evidence, not vibes

• Build — exact artifact identity and analysis provenance.
• Entity — function, type, class, field, vtable, runtime object, or project-defined object.
• Edge — call, reference, ownership, inheritance, dataflow, or runtime relationship.
• Evidence — an observation with source, time, classification, and confidence.
• Claim — an interpretation linked to supporting or opposing evidence.
• Capture — a sealed scenario with artifacts, markers, events, and checksums.
• Gap — the next missing fact needed to prove a behavior.

Conflicting claims remain visible. Unknown behavior becomes a worklist, not a fabricated answer.

Private by default

raw private material  →  normalized project evidence  →  synthetic public fixtures

• Daemon binds to localhost and serves GET-only queries, including a loopback-only dashboard.
• Non-local binding requires an API token and still needs trusted TLS transport.
• Executable bytes and decompiler text are not exported by default.
• Capture normalization recursively removes common secret and payload fields.
• Public-release audit blocks credentials, captures, dumps, proprietary binary formats, large embedded payloads, and personal paths.

Read Privacy and Security before importing sensitive work.

Documentation

Project status

HexWitness 1.0 is a stable public developer release. Automated gates cover schema migration, importer, evidence graph, query engine, capture lifecycle, unified CLI, bundled distribution, read-only daemon, concurrent query behavior, MCP server, setup wizard, tailored agent skills, privacy audit, packaging, installed upgrade, and the CLI → DB → daemon → MCP journey. The exact trust boundary is documented in Release readiness.

Commercial viewer APIs still vary by edition and release. HexWitness documents that boundary instead of claiming universal compatibility. See Quality for the exact tested surface.

Contributing

Focused issues and pull requests welcome. Read Contributing. Never attach proprietary binaries, vendor databases, credentials, or captures you cannot redistribute.

Apache-2.0. Analyzed binaries, imported evidence, vendor SDKs, and RE databases retain their own terms.

Built and maintained by SiagiNW.
Make every byte testify.