![\"HexWitness](\"assets/hexwitness-banner.svg\")
\n\n\n ![\"CI\"](\"https://img.shields.io/github/actions/workflow/status/siaginw/HexWitness/ci.yml?branch=main&style=flat-square&label=build\")
![\"Apache-2.0](\"https://img.shields.io/badge/license-Apache--2.0-7c3aed?style=flat-square\"){kind=icon}
![\"Node](\"https://img.shields.io/badge/node-%E2%89%A522.13-22c55e?style=flat-square\"){kind=icon}
![\"MCP](\"https://img.shields.io/badge/MCP-enabled-06b6d4?style=flat-square\"){kind=icon}
![\"npm](\"https://img.shields.io/npm/v/hexwitness?style=flat-square&color=f59e0b\")
\n Give your reverse-engineering agent a memory, a map, and receipts.
\n HexWitness turns static analysis, runtime captures, and human conclusions into one durable evidence graph.\n
\n Quick start ·\n Why it matters ·\n Examples ·\n Docs ·\n How it compares\n
\n\n---\n\nYesterday, 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.\n\nHexWitness stops that loop.\n\n```mermaid\nflowchart LR\n V[\"Binary Ninja · IDA · Ghidra\"] --> X[\"Reviewed evidence\"]\n R[\"Frida · debugger · wire observer\"] --> C[\"Sealed capture\"]\n C --> X\n X --> E[(\"HexWitness memory\")]\n E --> A[\"Your AI agent\"]\n A --> Q[\"Answer with proof\"]\n A -.->|one named gap| V\n```\n\nThe 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.\n\n## See it work in 60 seconds\n\nRequirements: Git and Node.js 22.13 or newer.\n\n```bash\nnpm install --global hexwitness\nhexwitness setup\nhexwitness demo\n```\n\nThe 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.\n\nNow ask:\n\n```text\nUse HexWitness to explain 0x401120 in build toy-v1.\nShow proof, contradictions, and missing evidence separately.\n```\n\nThe demo uses synthetic, redistributable evidence. No third-party binary data ships with HexWitness.\n\nPrefer a checkout?\n\n```bash\ngit clone https://github.com/siaginw/HexWitness.git\ncd HexWitness\nnpm install\nnpm run demo\nnpm run setup -- --client codex --viewer none --yes\nnpm run doctor\n```\n\nReplace `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.\n\n> [!IMPORTANT]\n> The checked-in [`.mcp.json.example`](.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.\n\nHexWitness installs as one command. The service, MCP transport, installer, capture pipeline, and adapter catalog live behind that command:\n\n```bash\nhexwitness agent # daemon autostart + MCP for AI clients\nhexwitness serve # REST daemon only\nhexwitness adapters # list every included viewer/runtime adapter\nhexwitness adapters binary-ninja # print one adapter's exact path and capabilities\nhexwitness contract # inspect the stable 1.x public contract\nhexwitness backup ./evidence.db # create and verify a consistent snapshot\n```\n\nOfficial 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`.\n\nThe 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.\n\n## Why HexWitness feels different\n\nMost 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.\n\n| Approach | Excellent for | The gap HexWitness fills |\n|---|---|---|\n| Viewer MCP | Live decompilation, xrefs, renames, analysis control | Findings are session-scoped unless promoted |\n| Notes and reports | Human narrative | Hard to query, compare, or trace back to exact evidence |\n| General agent memory | Preferences and broad project context | No dedicated build, address, call-graph, capture, or provenance contract |\n| HexWitness | Durable RE evidence and runtime reconstruction | Pairs with viewers instead of replacing them |\n\nThat makes HexWitness especially useful when:\n\n- the binary changes and addresses move;\n- several agents or analysts share work;\n- static code must line up with runtime behavior;\n- a conclusion needs a reproducible chain of evidence;\n- a failed capture must be compared with a working one;\n- “we think” needs to become “we proved.”\n\nRead the honest category comparison in [Why HexWitness](docs/WHY-HEXWITNESS.md).\n\n## Ask real questions\n\nUsers ask about the target. The agent chooses the tools.\n\n```text\nWhich function validates frame length before dispatch?\nReuse retained evidence first. Inspect a live viewer only if one exact edge is missing.\n```\n\n```text\nCompare the working and failing login captures.\nFind the first meaningful divergence, then resolve its static consumer.\n```\n\n```text\nWhere is this UUID used, which class owns it, and did its field offset change\nbetween builds?\n```\n\nHexWitness 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.\n\n## One investigation loop\n\n1. **Remember.** Query retained evidence before touching a live tool.\n2. **Pin.** Select the exact artifact build; never carry an address across builds by habit.\n3. **Resolve.** Search the subject, then read its full evidence dossier.\n4. **Narrow.** Traverse only the calls, fields, slices, or capture window needed.\n5. **Challenge.** Surface provenance, confidence, and contradictory claims.\n6. **Escalate.** If proof ends, name the smallest missing live observation.\n7. **Promote.** Export that bounded result so the next investigation starts smarter.\n\nFor 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.\n\nAgents 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](docs/INVESTIGATION-WORKBENCH.md).\n\nThe database remembers evidence. A separate privacy-safe activity store remembers operation hashes, timing, status, and counts—never prompts, arguments, or returned evidence.\n\n## Runtime capture without command soup\n\nCollectors place conventional files and a small manifest in one private folder:\n\n```text\nroundtrip/\n├── capture.json\n├── wire.jsonl\n├── hooks.jsonl\n├── screen.mp4\n└── context.json\n```\n\nThen:\n\n```bash\nhexwitness capture ./private/roundtrip\n```\n\nHexWitness 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.\n\nSee [Capture packs](docs/CAPTURE-PACKS.md) for collector and scenario contracts.\n\n## Works with your stack\n\n| Tool | Durable bridge |\n|---|---|\n| Binary Ninja | Deep JSONL exporter plus optional official Binary Ninja MCP live viewer |\n| IDA / IDAPython | Functions, strings, imports, references, blocks, and optional Hex-Rays pseudocode plus live MCP |\n| Ghidra | Functions, strings, imports, references, blocks, types, fields, and enum exporter |\n| Frida 17 | Narrow semantic-event observer and fail-closed JSONL normalizer |\n| Other tools | Versioned adapter manifest and vendor-neutral JSONL schema |\n\nHexWitness 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](docs/VIEWER-MCP.md) and the [Adapter SDK](docs/ADAPTER-SDK.md).\n\n## One truth, three interfaces\n\n| Interface | Best use |\n|---|---|\n| MCP | Agent-led investigations, read-only evidence tools, and one explicitly open-world local-tool runner |\n| CLI | Import, capture lifecycle, automation, recovery, and direct queries |\n| REST | Local read-only integration with a published route manifest |\n\nAll three read the same SQLite evidence graph. Imports are transactional and idempotent. Addresses remain canonical hexadecimal strings, including unsigned 64-bit values.\n\n## Evidence, not vibes\n\n- **Build** — exact artifact identity and analysis provenance.\n- **Entity** — function, type, class, field, vtable, runtime object, or project-defined object.\n- **Edge** — call, reference, ownership, inheritance, dataflow, or runtime relationship.\n- **Evidence** — an observation with source, time, classification, and confidence.\n- **Claim** — an interpretation linked to supporting or opposing evidence.\n- **Capture** — a sealed scenario with artifacts, markers, events, and checksums.\n- **Gap** — the next missing fact needed to prove a behavior.\n\nConflicting claims remain visible. Unknown behavior becomes a worklist, not a fabricated answer.\n\n## Private by default\n\n```text\nraw private material → normalized project evidence → synthetic public fixtures\n```\n\n- Daemon binds to localhost and serves GET-only queries, including a loopback-only dashboard.\n- Non-local binding requires an API token and still needs trusted TLS transport.\n- Executable bytes and decompiler text are not exported by default.\n- Capture normalization recursively removes common secret and payload fields.\n- Public-release audit blocks credentials, captures, dumps, proprietary binary formats, large embedded payloads, and personal paths.\n\nRead [Privacy](docs/PRIVACY.md) and [Security](.github/SECURITY.md) before importing sensitive work.\n\n## Documentation\n\n| Start here | What it answers |\n|---|---|\n| [Getting started](docs/GETTING-STARTED.md) | Can I prove the full local loop? |\n| [Why HexWitness](docs/WHY-HEXWITNESS.md) | Why not just use notes, a viewer MCP, or generic memory? |\n| [AI setup wizard](docs/INSTALLER.md) | What gets installed for each agent? |\n| [AI-first workflows](docs/AI-FIRST-WORKFLOWS.md) | What should I ask the agent? |\n| [Capability matrix](docs/CAPABILITY-MATRIX.md) | What is complete, variable, or intentionally out of scope? |\n| [Quality contract](docs/QUALITY.md) | Which claims are machine-checked? |\n| [Stability policy](docs/STABILITY.md) | What remains compatible throughout 1.x? |\n| [Compatibility](docs/COMPATIBILITY.md) | Which runtimes and viewer boundaries are supported? |\n| [Release readiness](docs/RELEASE-READINESS.md) | What does the 1.0 claim include? |\n| [CLI](docs/CLI.md), [REST](docs/API.md), [MCP](docs/MCP.md) | What interfaces are available? |\n| [Architecture](docs/ARCHITECTURE.md) | How do the pieces fit? |\n| [Troubleshooting](docs/TROUBLESHOOTING.md) | What failed and how do I prove it? |\n\n## Project status\n\nHexWitness 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](docs/RELEASE-READINESS.md).\n\nCommercial viewer APIs still vary by edition and release. HexWitness documents that boundary instead of claiming universal compatibility. See [Quality](docs/QUALITY.md) for the exact tested surface.\n\n## Contributing\n\nFocused issues and pull requests welcome. Read [Contributing](.github/CONTRIBUTING.md). Never attach proprietary binaries, vendor databases, credentials, or captures you cannot redistribute.\n\nApache-2.0. Analyzed binaries, imported evidence, vendor SDKs, and RE databases retain their own terms.\n\n\n Built and maintained by SiagiNW.
\n Make every byte testify.\n