branover/hexgraph

# ⬡ HexGraph HexGraph 是一个自托管的 AI 辅助漏洞研究工作台，完全运行在你自己的机器上。 你只需将一个二进制文件或固件镜像指向它，它就会替你完成那些繁琐的工作：它会获取目标， 将固件拆解为组件二进制文件，运行由你现有的模型权限驱动的分析任务，并将每个结果以 结构化的 **finding** 形式写入由 SQLite 支持的强类型图中。该图将所有内容联系在一起： 目标、函数、套接字、假设和发现，它们通过类型化和带属性的边连接起来。与图并存的 是一个共享的工作记忆，它保存了推理过程，而不仅仅是结果：一个自由格式的、带时间戳的 markdown 笔记的 **研究日志**，由你或 agent 编写，其中 `@` 提及可以直接链接到图中的 任何对象，此外还有一个 **假设工作清单**，你可以随着线索被确认或排除，对其进行排序、 筛选和勾选。你可以通过仅监听 localhost 的 Web UI 浏览所有内容、启动新任务并对发现 进行分类，而且编码 agent 也可以通过 MCP 执行相同的操作。  有三个原则是不可妥协的，它们决定了其他一切： - **保持本地化。** API 和 UI 只绑定到 `127.0.0.1`。HexGraph 永远不会向我们 运营的服务器发送数据；没有遥测，也没有自动更新检测。 - **带上你自己的密钥，否则一无所有。** 模型权限来自你自己的 Anthropic API key、 本地 Claude Code 会话或内置的 **mock** 后端。mock 是默认的，它不需要 密钥也不需要网络，并且允许你以 $0 的成本运行整个循环。 - **每个目标都被视为恶意的。** 所有对目标字节的解析、解包和分析 都在一个没有网络且具有严格资源限制的一次性 Docker 容器中进行。HexGraph 在 默认情况下是纯静态的。执行目标、访问网络和重新托管固件每一项都是你刻意选择启用的 独立功能，即使如此，它们仍然在该相同的严格沙箱中运行。模型永远不会看到原始的目标 字节，只能看到 HexGraph 为其运行的工具输出（反编译、字符串、导入等）。 ## 安装 你需要 Python 3.11 或更高版本，一个你的用户可以与之通信的 Docker daemon （通过 `docker run --rm hello-world` 检查），带有 npm 的 Node.js 18+ （设置程序会构建 Web UI），以及 Linux 或 macOS。不需要 API key， 因为默认的 mock 后端完全离线运行。 有两种等效的引导方式，因此如果你不想的话，**不需要**安装 [`just`](https://just.systems) 任务运行器。这两种方式都会构建虚拟环境、安装 依赖项和 Web UI，然后让你进入同一个交互式设置向导 —— 选择 你喜欢的一种： ``` git clone https://github.com/branover/hexgraph.git hexgraph && cd hexgraph # 选项 A — 使用 `just` task runner（推荐）： just setup # venv + deps + web UI, then the interactive setup wizard just serve # → http://127.0.0.1:8765 # 选项 B — 不使用 `just`，普通 shell script： ./setup.sh # the same venv + deps + web UI, then the same wizard .venv/bin/hexgraph serve # → http://127.0.0.1:8765 ``` （实际上 `just setup` 只是一个调用 `./setup.sh` 的轻量包装器，因此这两条路径不会产生分歧。） 两者都会移交至交互式设置向导。该向导将引导你了解可选 功能，对于每一个放宽安全态势的功能，它都会向你展示其影响，并要求你 在开启前进行确认。然后它会写入你的设置并构建你选择的镜像，并且 它可以选择性地将 HexGraph 的 MCP server 注册到编码 agent，并为你安装 VR 技能 （两者均为纯本地，无密钥）。如果你接受默认设置，你将保持在纯静态 态势；除此之外的所有内容都需要你自己开启，且要做到心中有数。要跳过提示并 采用纯静态默认设置，请传入 `--yes`（`just setup --yes` 或 `./setup.sh --yes`）。有关向导、 手动分步指南、非交互式 CI 模式以及 Ghidra，请参阅 **[docs/setup.md](docs/setup.md)**。 在稍后执行 `git pull` 之后，`just refresh`（即 `just setup --refresh`）是一个快速的一致性同步：它 会保留你的配置，并且只重建过时的内容 —— package、Web UI、Dockerfile 发生变动的任何 镜像、MCP 注册以及 VR 技能。在 `just serve` 之前运行它，以确保 你使用的是所有内容的最新构建。 ### 或者使用 Docker 运行 如果你不想在宿主机上安装任何东西，你可以在容器中运行整个工作台。 从代码检出目录开始，一条命令即可将其启动： ``` docker compose up --build # or: just up → http://127.0.0.1:8765 ``` 这会构建一个捆绑了 Web UI 和 Python 后端的应用镜像，在启动时运行数据库迁移， 并提供工作台服务。该服务仅在宿主机回环地址上发布 （`127.0.0.1:8765:8765`），因此它完全像 pip 安装一样 保持在你机器的本地。如果你设置了 `ANTHROPIC_API_KEY`，它将 从环境中传递进来，镜像中永远不会内置任何密钥，如果未设置任何内容，容器将 回退到离线 mock 后端。 在选择此路径之前，有一件事值得了解。compose 文件将宿主机的 Docker 套接字挂载到应用容器中，因为 HexGraph 需要与 Docker daemon 通信以启动其 一次性沙箱、构建、模糊测试和重新托管容器。在这种部署中，这些兄弟容器 在你的宿主机 daemon 上运行，其隔离方式与在 pip 安装下相同。挂载 daemon 套接字实际上赋予了应用容器对宿主机 Docker 的 root 等效控制权。对于你在自己机器上运行的 单用户、本地、自托管工具来说，这是一个深思熟虑的权衡，而且它 并不是一种经过强化或多租户的态势。请勿将此堆栈暴露给不受信任的用户或网络。如果 你不想做出这种权衡，上方的宿主机 pip 路径仍然是开发和 运行 HexGraph 的主要且推荐的方式。 使用 `docker compose down`（或 `just down`）停止堆栈；你的项目数据库和发现 将持久化存储在命名的 Docker 卷中。 使用 HexGraph 即表示你同意仅将其用于你有权分析的目标。请阅读 [DISCLAIMER.md](DISCLAIMER.md)。 ## 核心循环 HexGraph 中的一切都是为了证明一个循环：**目标 → 任务 → 结构化发现 → 图 → 生成 下一个任务。** 观察此过程的最快方法是演示，它会在捆绑的目标上运行整个 流程，离线、免费运行，并退出代码 0： ``` just demo ``` 你也可以自己驱动它。获取一个目标（recon 会自动运行并将固件解包为 子目标），然后从 UI 启动任务并对它们产生的发现进行分类： ``` .venv/bin/hexgraph ingest tests/fixtures/synthetic_fw.bin --name demo .venv/bin/hexgraph serve # → http://127.0.0.1:8765 ``` 有两种驱动循环的方法。两者都写入同一个图中，并且都将目标字节 保留在沙箱内。 第一种是 **Web UI**：选择一个目标，选择一个任务（recon、静态分析、逆向工程 (RE)、模式 扫描、harness 生成、模糊测试或 PoC），然后运行它。在你选择的后端背后，HexGraph 运行 一个 agent 循环。模型请求沙箱工具（反编译、字符串、导入、交叉引用、模糊测试），HexGraph 执行它们，循环继续，直到模型输出发现。你对结果进行分类，并且可以一键执行它建议的任何后续操作。 第二种是通过 **MCP 进行的编码 agent**。`hexgraph mcp install` 会打印注册 HexGraph 作为 MCP server 的步骤（设置向导也可以为你完成），然后 Claude Code、Codex 或 gemini-cli 会通过相同的沙箱工具自行检查目标并填充图。 详细信息请参阅 **[docs/mcp.md](docs/mcp.md)**。 在这两种情况下，模型永远只是在指导工作；运行工具的是 HexGraph。一个普通的 API key 本身 就足够了，不需要外部编码 agent。 | 后端 | 选择方式 | 备注 | |---|---|---| | `mock`（默认） | — | 基于 fixture 的确定性、schema 有效的发现。无密钥，无网络。支持开发、CI 和 `just demo`。 | | `anthropic` | `--backend anthropic` / `HEXGRAPH_LLM_BACKEND=anthropic` | 通过 `ANTHROPIC_API_KEY`（环境变量或 `config.toml`）使用你自己的密钥。消耗真实 token。需要 `pip install -e ".[byok]"`。 | | `claude_code` | `--backend claude_code` | 在 headless 模式下使用你本地的 `claude` CLI。 | HexGraph 永远不会记录或存储你的 API key。 ## 功能 纯静态基线以上的所有功能默认都是关闭的，可以在 **Settings** 中切换（或者使用 `hexgraph config set `）。每一个放宽安全态势的功能都是其独立的、 明确的选择启用项。 | 功能 | 添加内容 | 文档 | |---|---|---| | **强类型图 + 发现** | 目标、函数、套接字、endpoint、假设和发现作为强类型节点，通过类型化和带属性的边连接，全部在具有三个窗格的 UI 中进行浏览、启动和分类。 | [graph-ui.md](docs/graph-ui.md) | | **研究日志和假设工作清单** | 一个自由格式、带时间戳的 markdown 日志，由你或 agent 编写，其 `@` 提及可以直接链接到任何节点或发现，此外还有提升为可排序、可勾选工作清单的假设。这是一个共享的工作记忆，记录了尝试了什么、了解了什么以及接下来值得追踪哪些线索。 | [journal.md](docs/journal.md) | | **外部 RE 工具** | 超越 radare2 和 Ghidra 的专业静态分析工具：GNU binutils 快速事实传递、FLOSS 混淆字符串恢复、全语料库 YARA 模式扫描，以及用于求解到达 sink 的具体输入的 angr 符号执行。全部为静态且经过沙箱化；angr 提供在其自己的可选镜像中。 | [re-external-tools.md](docs/re-external-tools.md) | | **验证与保障阶梯** | 每个发现都带有保障级别（`code_present`/`input_reachable` × `static`/`dynamic`），并且选择启用的 **PoC 验证** 会针对不可伪造的 `{{NONCE}}` 预言机执行目标（通过 qemu-user 支持异构架构）。 | [verification-assurance.md](docs/verification-assurance.md) | | **模糊测试** | 覆盖率引导、表面感知、活动驱动的模糊测试（AFL++、libFuzzer、qemu-mode、boofuzz、desock），支持分离式且具备崩溃安全性，具有实时分类、去重、最小化以及一键重新验证功能。活动可以在你拥有的更强大的宿主机上运行。 | [fuzzing.md](docs/fuzzing.md) | | **从源码构建** | 通过 HexGraph 在沙箱中运行的已记录配方，将受管理的源代码树编译为经过插桩的、可重现的构件，并自动连接从构建到模糊测试的交接。包含带有覆盖率阴影的浏览器内 **Source / IDE 选项卡**。 | [build-from-source.md](docs/build-from-source.md) | | **动态表面、重新托管与远程** | 将运行中的 Web 服务或原始 TCP daemon 建模为一等公民 **surface**，在系统级模拟下 **重新托管** 整个固件镜像，或者通过 SSH/telnet 评估物理 **远程** 设备，所有这些都带有受限且经过审计的出站流量。 | [dynamic-surfaces-rehosting-remote.md](docs/dynamic-surfaces-rehosting-remote.md) | | **编码 agent 集成** | 从 Claude Code、Codex 或 gemini-cli 驱动 HexGraph，或者让 HexGraph 在委托模式下驱动 headless agent。无论哪种方式，agent 都被限制在 HexGraph 的沙箱工具中。 | [mcp.md](docs/mcp.md) | ### 选择启用的策略层级简介 强制执行的默认设置是使用 `--network none` 的纯静态模式。由此开始，每个更高的层级都在其 自己的网关之后，除了单一的 [策略接口](docs/verification-assurance.md) 之外，任何地方的策略都不会 放宽。`features.poc` 和 `features.fuzzing` 允许在沙箱中执行；`features.build` 编译源码树； `features.build_fetch` 添加单独的、经过审计的、白名单依赖项获取；`features.network` 允许 受限的回环和私有网络出站流量；`features.rehost` 启动系统级模拟；`features.remote` 连接 一个经过授权的真实设备；`features.fuzz_remote` 在你拥有的计算宿主机上运行活动。你只需 开启特定任务所需的功能。 ## CLI 运行 `.venv/bin/hexgraph `（或者在激活的虚拟环境中直接运行 `hexgraph`）： ``` hexgraph ingest [--name N] [--project ID] [--no-recon] [--backend B] hexgraph targets hexgraph run --type T [--objective TEXT] [--function F] [--backend B] [--mock-scenario S] hexgraph rehost [--brand HINT] # boot firmware under emulation (needs features.rehost) hexgraph findings [--status S] [--export FILE] hexgraph graph --export FILE hexgraph doctor [--clean] # reconcile on-disk project dirs vs the DB; --clean removes orphans hexgraph config list | get K | set K V # managed settings + optional-feature toggles hexgraph mcp [--tools read,write,run] | mcp install [--agent A] | mcp --check hexgraph serve [--host H] [--port P] # loopback-only API/UI (default 127.0.0.1:8765) ``` 任务类型包括 `recon`、`static_analysis`、`reverse_engineering`、`pattern_sweep` 和 `harness_generation`，以及在你启用它们后的 `fuzz`、`poc` 和 `agent_delegate`。Web surface 增加了 `surface_recon`、`web_discover` 和 `web_recon`。完整的配置说明（环境变量、 `config.toml` 以及各层是如何互相覆盖的）在 **[docs/setup.md](docs/setup.md)** 中。 ## 安全模型 - **仅限回环地址。** 除非你设置了 `HEXGRAPH_I_KNOW_WHAT_IM_DOING=1`， 否则服务器拒绝绑定到非回环地址。 - **恶意目标隔离。** 每个对目标字节的操作都在一个新的容器中运行，该容器带有 `--network none`、只读的根文件系统、tmpfs 暂存空间、内存、CPU 和 PID 限制， 以及挂钟时间超时限制。只有 HexGraph 自己的探测脚本会在其中运行。 - **默认静态，具备可选择启用且分层级的功能。** 每个层级都是一个独立的、 明确的选择启用项，它改变了单一的策略接口，而其他任何地方的策略都不会放宽。相同的 沙箱强化适用于每个层级，异构架构的工作在 qemu-user 下运行，而 不是在宿主机上。完整的阶梯位于 [docs/verification-assurance.md](docs/verification-assurance.md) 中。 - **模型永远不会看到原始目标字节**，只能看到工具输出。 - **从不持久化或记录密钥。** 你的 API key 以及任何 SSH 或远程 Docker 凭据仅存在于你的环境或 `config.toml` 中。HexGraph 会按需读取它，并且 仅报告其存在与否，绝不会报告其具体值。 ## 工作原理 HexGraph 围绕着几个清晰的接口构建。你通过在接口背后替换实现来改变行为， 而不是根据后端、层级或执行器进行分支。 - **`LLMBackend`** 使 `mock`、`anthropic` 和 `claude_code` 可以互换；任务代码永远 不知道正在使用哪一个。 - **Executor** 是所有目标字节处理的单一容器边界，无论该容器 是在本地还是远程 Docker 上运行。 - **Decompiler** 默认为 radare2，Ghidra 可在相同的接口后使用。 - **Rehoster** 驱动系统级固件模拟，对供应商二进制大对象使用 FirmAE，对 磁盘镜像使用 qemu+KVM。 - **Policy** 是唯一一个放宽纯静态不变式的地方，也是仅有的一处。 发现 是该产品的核心。每个任务和每个后端（包括 mock）都会输出 相同的固定 schema（`src/hexgraph/schemas/finding.schema.json`），并且 `finding_type` 字段（保留在 DB 信封中，而不是 schema 中）会对其进行分类以便进行分类处理。 数据模型是通过 SQLAlchemy 实现的 SQLite，具有 UUID id 和 WAL 模式，因此 UI 和 agent 的 MCP server 可以同时共享数据库。它包含一个 `project`、一个 `target`（一个自引用 的可达表面树）、`node` 行（类型化的子文件和概念实体）、一个多态 的、类型化的、带属性的 `edge`、一个 `task` 和一个 `finding`。该图是关系型的， 而 Neo4j 被刻意排除在范围之外。更多详细信息位于 [docs/graph-ui.md](docs/graph-ui.md) 中。 `tests/fixtures/` 下提供了一些测试目标（使用 `just fixtures` 重新生成它们）：带有 无界 `strcpy` 的 `vuln_httpd`、作为模式扫描兄弟项的 `libupnp.so`，以及可以解包出 这两者的 squashfs 固件 `synthetic_fw.bin`。一组逐步升级的、CVE 级别的挑战目标位于 `tests/fixtures/challenges/` 下。 ## 开发 ``` just # list every recipe, grouped just test # the full suite (mock backend; sandbox/Docker tests auto-skip without the image) just demo # the full offline loop, exits 0 — doubles as a smoke test just ui # rebuild the SPA (after any frontend/ change) just showcase --reset && just capture # regenerate the doc screenshots (see docs/images/README.md) ``` 源代码位于 `src/hexgraph/`（`models/`、`llm/`、`db/`、`sandbox/`、`engine/`、`api/`、 `cli.py`、`mcp_server.py`）。有关工作协议、接口规则以及工作树和 PR 规范，请阅读 [`CLAUDE.md`](CLAUDE.md)。发布历史记录在 [`CHANGELOG.md`](CHANGELOG.md) 中。 ## 设计上的不适用范围 HexGraph 不涉及账户或多用户、云或托管计算、漏洞利用*生成*、Neo4j 或 Kubernetes。动态执行仅作为上述选择启用、策略控制、沙箱化的路径存在。 它永远不会在非沙箱环境中运行，也永远不会在宿主机上运行。 ## License HexGraph 基于 [**AGPL-3.0**](LICENSE) 协议发布。它是免费且开源的：你可以随意 使用、运行、学习和修改它。Copyleft 条款意味着你分发或通过网络向他人 提供的任何修改版本，也必须按照 AGPL-3.0 协议发布，这正是保持该项目开放 并防止出现闭源、专有分支的原因。没有许可证限制，也没有付费层级。

标签：AI智能体, MITM代理, 二进制分析, 云安全运维, 云资产清单, 固件分析, 情报收集, 漏洞研究, 请求拦截, 逆向工具, 逆向工程