HexWitness

为你的逆向工程 Agent 配备记忆、地图和凭据。
HexWitness 将静态分析、运行时捕获和人工结论汇集为一个持久的证据图谱。

快速开始 · 为何重要 · 示例 · 文档 · 对比说明

---

昨天，你的 Agent 找到了解析器，梳理了调用者，并证明了哪个运行时事件到达了它。今天，新会话启动后，却又让实时反汇编器从头发现一切。

HexWitness 让这种循环就此停止。

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

实时查看器依然是 Agent 的眼睛。HexWitness 则成为它的案件档案：关联到精确的构建版本，可通过各种工具搜索，如实呈现冲突，并可供下一个 Agent 使用。

60 秒见证效果

要求：Git 和 Node.js 22.13 或更新版本。

npm install --global hexwitness
hexwitness setup
hexwitness demo

设置向导会将 HexWitness 连接到 Codex、Claude Code、Cursor、VS Code/Copilot、Claude Desktop 或通用 MCP 客户端。它还会安装为相应 Agent 编写的指导内容。需要时，MCP 入口会启动本地只读守护进程，无需协调多个服务。

现在试着问：

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

演示使用的是可再分发的合成证据。HexWitness 不会附带任何第三方二进制数据。

更喜欢检出代码仓库？

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

根据需要，将 codex 替换为 claude-code、cursor、copilot 或 generic。设置命令会解析检出代码仓库中本地运行时的绝对路径，安装适配所选 Agent 的指导内容，并写入 MCP 连接，无需全局安装。设置完成后，重启所选 AI 客户端，再让它调用 hexwitness_health 和 hexwitness_contract。使用私有证据前，必须确保两者都调用成功。

重要

仓库中提供的 .mcp.json.example 假定你已运行 npm install --global hexwitness。如果使用的是源码检出，请运行 npm run setup，而不要复制该示例；设置命令会记录正确的本地 Node.js 和捆绑运行时路径。

HexWitness 只需一条命令即可安装。服务、MCP 传输、安装程序、捕获流水线和适配器目录都封装在这条命令背后：

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

官方 MCP Registry 标识：io.github.siaginw/hexwitness。支持 Registry 的客户端可以发现通过 npm 发布的同一本地 stdio 服务；其声明的启动约定为 hexwitness agent。

npm 包只附带一个捆绑运行时，不会公开其内部模块树。Python 仅用于轻量的 Binary Ninja、IDA 和 Ghidra 导出器，因为这些产品通过 Python 提供受支持的自动化 API。大型 JSONL 导出和长时间捕获会通过原子化导入和磁盘支持的规范化流程进行流式处理，而不会一次性全部载入内存。

为什么 HexWitness 与众不同

大多数 RE 集成解决的是访问问题：让 Agent 读取反编译器、调试器或跟踪信息。HexWitness 解决的是连续性问题：即使工具、构建或聊天会话已结束，也能保留有用的结果。

方案	擅长之处	HexWitness 弥补的不足
查看器 MCP	实时反编译、交叉引用、重命名、分析控制	除非将发现提升为持久记录，否则它们只在会话期间有效
笔记和报告	人类叙述	难以查询、比较，或追溯到确切证据
通用 Agent 记忆	偏好和宽泛的项目上下文	没有针对构建、地址、调用图、捕获或来源信息的专用约定
HexWitness	持久化 RE 证据和运行时重建	与查看器配合使用，而不是取代它们

因此，HexWitness 在以下情况中特别有用：

• 二进制文件发生变化，地址随之移动；
• 多个 Agent 或分析人员共同开展工作；
• 静态代码必须与运行时行为对应；
• 结论需要可复现的证据链；
• 需要将失败的捕获与成功的捕获进行比较；
• 需要将“我们认为”变成“我们证明了”。

请阅读 Why HexWitness 中坦诚的类别对比。

提出真实问题

用户询问目标，Agent 选择工具。

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 为 Agent 提供一流的查询能力，涵盖构建、函数、类、UUID、类型、字段、虚函数表、调用、交叉引用、路径、数据流、捕获、矛盾、覆盖率、证据缺口、持久化调查、失败尝试、质疑，以及仅用于发现的检索。四个 MCP 提示词封装了调查、运行时比较、实时发现提升和对抗性证据审查工作流。

一轮调查流程

1. 记忆。 接触实时工具前，先查询保留的证据。
2. 固定。 选定确切的制品构建；切勿习惯性地跨构建沿用地址。
3. 解析。 搜索目标，然后读取其完整证据档案。
4. 收窄。 仅遍历所需的调用、字段、切片或捕获窗口。
5. 质疑。 展示来源、置信度和相互矛盾的主张。
6. 升级。 如果证明到此为止，明确指出所缺的最小实时观测。
7. 提升。 导出范围明确的结果，让下一轮调查能从更好的起点开始。

对于较长时间的工作，确定性操作手册会初始化持久化检查清单和操作预算。失败的方法仍可搜索。证据质疑会展示反对意见、缺乏支持的主张和未解决的缺口，同时避免 Agent 共识抬高置信度。

Agent 还可以通过一个明确的 MCP 工具，运行允许列表中的本地 RE 实用程序：仅使用 argv、以 cwd 为根目录、带超时限制、限制输出，并生成回执。这并非 OS 沙箱。工具输出在通过证据模型提升之前仍只是观测。无需环境启用开关或单独的模型提供商密钥。请参阅调查工作台。

数据库会记住证据。另一个独立的隐私安全活动存储会记录操作哈希、耗时、状态和计数，绝不记录提示词、参数或返回的证据。

无需繁杂命令即可进行运行时捕获

采集器会在一个私有文件夹中放置常规文件和一个小型清单：

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

然后：

hexwitness capture ./private/roundtrip

HexWitness 会检查必需的角色和操作标记，将制品复制到隔离的私有包中，规范化安全时间线（移除机密字段，并用长度和 SHA-256 替换负载），密封校验和，验证完整性，并导入证据。缺失或为空的基线制品会导致操作安全失败。规范化失败时，源包仍可恢复。

有关采集器和场景约定，请参阅捕获包。

适配你的技术栈

工具	持久化桥接
Binary Ninja	深度 JSONL 导出器，以及可选的官方 Binary Ninja MCP 实时查看器
IDA / IDAPython	函数、字符串、导入项、引用、代码块，以及可选的 Hex-Rays 伪代码和实时 MCP
Ghidra	函数、字符串、导入项、引用、代码块、类型、字段和枚举导出器
Frida 17	窄范围语义事件观察器和故障时关闭的 JSONL 规范化器
其他工具	版本化适配器清单和厂商中立的 JSONL 架构

HexWitness 不会在项目中附带功能较弱的反汇编器。查看器 MCP 提供实时观察能力。导出器则将经过审核的发现转化为可移植的记忆。请阅读查看器 MCP 桥接和适配器 SDK。

统一事实，三种接口

接口	最适用途
MCP	Agent 主导的调查、只读证据工具，以及一个明确开放世界的本地工具运行器
CLI	导入、采集生命周期、自动化、恢复和直接查询
REST	通过已发布的路由清单进行本地只读集成

三种接口都读取同一个 SQLite 证据图。导入采用事务处理且具备幂等性。地址始终采用规范的十六进制字符串，包括无符号 64 位值。

证据，而非主观臆测

• 构建 — 精确的制品身份和分析来源。
• 实体 — 函数、类型、类、字段、虚表、运行时对象或项目定义的对象。
• 边 — 调用、引用、所有权、继承、数据流或运行时关系。
• 证据 — 带有来源、时间、分类和置信度的观察结果。
• 主张 — 与支持或反对证据关联的解释。
• 采集 — 封存的场景，包含制品、标记、事件和校验和。
• 缺口 — 证明某种行为所需的下一个缺失事实。

相互冲突的主张会继续保留并显示。未知行为会成为待办项，而不是被编造出来的答案。

默认保护隐私

raw private material  →  normalized project evidence  →  synthetic public fixtures

• 守护进程绑定到 localhost，仅提供 GET 查询，包括仅限环回访问的仪表板。
• 非本地绑定需要 API 令牌，且仍需使用可信的 TLS 传输。
• 默认不导出可执行字节和反编译器文本。
• 采集规范化会递归移除常见的机密信息和负载字段。
• 公开发布审计会拦截凭据、采集数据、转储、专有二进制格式、大型嵌入式负载和个人路径。

导入敏感工作前，请阅读隐私和安全。

文档

从这里开始	解答的问题
快速入门	我能证明完整的本地流程吗？
为什么选择 HexWitness	为什么不直接使用笔记、查看器 MCP 或通用记忆？
AI 设置向导	会为每个 Agent 安装什么？
AI 优先工作流	我应该向 Agent 提什么要求？
功能矩阵	哪些功能已完成、视情况而定或有意不纳入范围？
质量契约	哪些主张经过机器验证？
稳定性政策	在整个 1.x 版本系列中，哪些内容保持兼容？
兼容性	支持哪些运行时和查看器边界？
发布就绪情况	1.0 声明包含哪些内容？
CLI、REST、MCP	提供哪些接口？
架构	各个部分如何协同工作？
故障排除	哪里出了问题，如何验证？

项目状态

HexWitness 1.0 是稳定的公开开发者版本。自动化门禁覆盖架构迁移、导入器、证据图、查询引擎、采集生命周期、统一 CLI、打包分发、只读守护进程、并发查询行为、MCP 服务、设置向导、定制 Agent 技能、隐私审计、打包、已安装版本升级，以及 CLI → DB → 守护进程 → MCP 的完整流程。确切的信任边界记录在发布就绪情况中。

商业查看器 API 仍因版本和发行版而异。HexWitness 会如实说明这一边界，而不声称具备普遍兼容性。确切的测试范围请参阅质量。

贡献

欢迎提交有针对性的问题和拉取请求。请阅读贡献指南。切勿附上专有二进制文件、供应商数据库、凭据，或你无权再分发的采集数据。

Apache-2.0。分析的二进制文件、导入的证据、供应商 SDK 和逆向工程数据库均保留各自的条款。

由 SiagiNW 创建并维护。
让每个字节都能作证。