HexWitness

Function names live in a decompiler. Runtime behavior lives in traces. Protocol findings land in scratch files. Weeks later, the build changed and nobody remembers which observation proved the conclusion.

HexWitness turns that scattered work into durable, evidence-backed knowledge.

flowchart LR
  S["Binary Ninja · IDA · Ghidra"] --> J["Portable evidence JSONL"]
  R["Frida · debuggers · wire observers"] --> P["Sealed capture pack"]
  P --> J
  J --> E[("Evidence graph")]
  E --> D["Read-only daemon"]
  D --> C["CLI / REST"]
  D --> M["MCP agents"]

What it does

HexWitness is target-agnostic. No application, game, protocol, address, packet layout, or private evidence is built into the core.

Related MCP server: NEAT MCP Server

Let the agent drive

HexWitness is not intended to make a person memorize another command vocabulary. Connect its MCP server, describe the investigation, and let the agent choose the evidence sequence:

Use HexWitness to determine which function validates message length before dispatch
and whether the failing capture reached it. Select the exact build and reuse retained
evidence first. If the proof is missing and Binary Ninja or IDA is connected, inspect
only the smallest missing scope read-only, then prepare the bounded export that makes
the result durable. Separate proof, inference, contradictions, and unknowns.

The agent performs:

memory → exact build → resolve → explain → focused evidence → answer
                                              ↓ missing
                                      live viewer read-only
                                              ↓
                                      bounded promotion

Three MCP prompts package the high-value workflows:

• hexwitness_start_investigation drives a complete static or mixed investigation;

• hexwitness_compare_runtime_behavior finds the first divergence between working and failing captures;

• hexwitness_promote_live_finding turns a transient Binary Ninja or IDA result into a minimal durable handoff.

See AI-first workflows for realistic protocol, crash, class-recovery, vulnerability, and team-handoff examples. Connect Binary Ninja or IDA MCP as optional live eyes.

Durable memory: investigate once, reuse it

HexWitness is not just a search wrapper around a live disassembler. It is persistent project memory.

1. An exporter or capture pack turns a finding into build-scoped evidence.

2. Idempotent ingestion stores entities, calls, types, UUIDs, offsets, runtime events, relationships, claims, and provenance in SQLite.

3. Humans and agents query that memory before asking Binary Ninja, IDA, Ghidra, Frida, or another live tool.

4. A live tool is called only when retained evidence cannot answer the question.

5. The new bounded result is exported and ingested, so the next investigation reuses it.

hexwitness memory
curl http://127.0.0.1:7878/v1/memory

MCP agents get the same view through hexwitness_memory_status. The response shows durable evidence counts, database size, latest ingest and capture, retention policy, and recent privacy-preserving activity.

One important boundary: HexWitness does not silently retain every proprietary viewer response. A live result becomes durable after the viewer adapter exports it or the result is otherwise ingested. Query activity is stored separately as operation hashes, timing, status, and result counts—never full arguments or returned evidence.

Quick start

Requirements: Git and Node.js 22.13 or newer.

Install directly from GitHub and launch the wizard:

npm install --global github:siaginw/HexWitness
hexwitness setup

Or work from a source checkout:

git clone https://github.com/siaginw/HexWitness.git
cd HexWitness
npm install
npm run demo
npm run setup

The setup wizard asks which AI clients to configure and whether to add Binary Ninja or IDA live inspection. It installs a client-native HexWitness skill for Codex, Claude Code, Cursor, and GitHub Copilot, with wording and discovery paths tailored to each agent. Claude Desktop and generic MCP clients receive the same workflow as an MCP guide. The installed hexwitness-agent entrypoint starts the local daemon automatically—no second terminal or background-service ceremony.

Then ask the agent:

Use HexWitness to explain 0x401120 in build toy-v1. Separate proven evidence,
conflicting claims, and missing proof. Drive the investigation yourself.

The bundled demo is synthetic and redistributable. It contains no third-party binary data.

See the AI setup wizard for non-interactive installs, dry runs, safe replacement, and supported clients. Granular CLI commands remain available for CI, scripting, and recovery.

Export a binary

Open a binary you are authorized to analyze, run an exporter, then ingest its JSONL:

hexwitness init
hexwitness ingest ./program.hexwitness.jsonl
hexwitness serve

Exporters hash the input executable and do not embed its bytes. Decompiled text is opt-in. Read the binary dump guide before designing a large export.

Capture runtime behavior

Put the collector output and a tiny capture.json manifest in one folder:

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

Then run one command:

hexwitness capture ./private/roundtrip

HexWitness detects the conventional files, applies the baseline gate, normalizes, seals, verifies, and imports the result atomically. Missing evidence fails closed without leaving a half-built output. Raw payload-like fields become length and SHA-256; common secret fields are removed recursively.

See sealed capture packs for collector contracts, directory layout, scenario markers, and privacy rules.

Query vocabulary

The CLI, REST daemon, and MCP server expose the same investigation concepts:

• query, search, explain, callers, callees, xrefs, and bounded reach;

• memory status showing retained evidence and query-before-live-tool policy;

• functions, classes, class, uuid, types, vtable, dataflow, and slices;

• evidence, contradictions, gaps, worklist, and coverage;

• capture list, detail, timeline, search, graph, compare, and first divergence.

The daemon publishes its current route manifest at GET /v1/routes.

Connect an agent

The setup wizard installs this autostart MCP entry automatically. The equivalent manual configuration is:

{
  "mcpServers": {
    "hexwitness": {
      "command": "node",
      "args": ["/absolute/path/to/HexWitness/bin/hexwitness-agent.mjs"],
      "env": {
        "HEXWITNESS_AGENT_SESSION": "my-analysis-project"
      }
    }
  }
}

An agent starts with health and memory status, selects an exact build, resolves a target, reads its dossier, and only then performs focused graph or capture queries. AGENTS.md contains the full evidence discipline.

For a combined workspace with optional live viewers, copy .mcp.ai-first.json.example. The recommended pairings are BinAssistMCP for Binary Ninja and ida-pro-mcp/idalib-mcp for IDA. These third-party viewers provide live context; HexWitness provides durable memory, build identity, provenance, contradiction handling, and promotion.

HexWitness's core is Node.js. The small Python files are viewer-native exporters for Binary Ninja, IDA, and Ghidra—not a second command framework users must operate by hand.

Evidence model

• Build — exact artifact identity and analysis provenance.

• Entity — static or runtime object with a build-scoped stable key.

• Edge — call, reference, control-flow, ownership, type, vtable, or dataflow relationship.

• Slice — bounded IL, SSA, decompiler, block, codec, or manually reviewed analysis.

• Evidence — observation with source, timestamp, classification, and confidence.

• Claim — interpretation linked to supporting or opposing evidence.

• Capture pack — sealed scenario, artifacts, markers, normalized events, and checksums.

• Relationship — runtime correlation between events, markers, requests, responses, and objects.

• Gap — prioritized missing artifact or observation needed to prove a behavior.

Addresses are canonical hexadecimal strings, preserving unsigned 64-bit values. Imports are transactional and idempotent.

Privacy and trust boundary

raw private material  →  normalized project evidence  →  synthetic/public fixtures

• The daemon binds to localhost and exposes read-only queries.

• Ingestion and capture mutation remain local CLI operations.

• A non-local bind requires HEXWITNESS_API_TOKEN; use TLS through a trusted tunnel or proxy.

• Activity retention stores operation names, argument hashes, timing, result counts, and optional session hashes—not prompts or returned evidence.

• The release audit rejects common credentials, proprietary binary formats, captures, dumps, oversized payloads, and personal absolute paths.

Read the privacy model and security policy.

Documentation

Status

HexWitness 0.4 defines and tests the generic evidence, query, capture-pack, comparison, CLI, REST, MCP, installer, tailored agent-skill, and one-command packaging contracts with synthetic fixtures. Vendor GUI adapters remain compatibility-sensitive because their APIs change between releases; the core interchange does not.

No benchmark, adoption, or universal vendor-version claim is implied beyond the checks published in this repository.

Contributing

Focused issues and pull requests are welcome. Read CONTRIBUTING.md before submitting an adapter or fixture. Never attach proprietary binaries, vendor databases, credentials, or captures you cannot redistribute.

License

Apache-2.0. Analyzed binaries, imported evidence, vendor SDKs, and reverse-engineering databases retain their own terms and are not part of HexWitness.