hunchom/claude-code-gauntlet

安装 · 运行 · 管道 · 限制 · 对比 · 架构

**一个将漏洞研究转化为可审计管道的 Claude Code 插件。** 十七个子代理通过六层梯子协调运行 — `A → B → B.5 → C → C.5 → D` — 每个阶段都要求在磁盘上有具体的证据： - **ASan 栈哈希**：在模糊测试主机上能复现 3/3 - **符号执行见证**：可从确定性种子重放 - **新鲜上下文验证器裁决**：两个隔离代理的结论 - **Merkle 根**：覆盖发现中每个事实性原子 如果任一阶段拒绝，发现会在人类看到之前终止。 ### 来自 Claude Code 会话 ``` /vuln-audit # interactive /vuln-audit-autonomous # hands-off loop /vuln-audit-status # state snapshot ``` ### 来自终端 ``` ./bin/vr status # one-line state ./bin/vr dashboard # full dashboard ./bin/vr review # Gate-D review TUI ./bin/vr watch # tail .vr-state/events/ ``` ## 管道 ``` flowchart LR A([scope]) --> B([reachable + ASan 3/3]) B --> B5([symex witness]) B5 --> C([dual fresh validators]) C --> C5([counter-symex on release tag]) C5 --> D([human send]) classDef gate fill:#0E1116,stroke:#5A6472,stroke-width:1px,color:#E6E9EF classDef send fill:#0E1116,stroke:#FF5C4D,stroke-width:2px,color:#FF5C4D class A,B,B5,C,C5 gate class D send ``` 每个箭头对应 `hooks/gate-*.sh` 中的一个钩子。钩子是一个 **Shell 脚本，而非提示** — 它读取 `.vr-state/` 并写入阶段通过条目或拒绝转换。没有 LLM 自我报告；没有自然语言中的“我已验证”。 ## 安装 **1. 克隆并引导。** 安装主机工具、Python 虚拟环境、CodeQL、GitNexus 和 `vr` 包。`all` 在最后自动提示选择后端。 ``` git clone https://github.com/hunchom/claude-code-gauntlet.git cd claude-code-gauntlet ./install all # tools + venv + codeql + gitnexus + interactive backend prompt ./install doctor # diagnostic — re-run anytime to verify integrity ``` `all` 运行是幂等的。首次安装会获取约 1GB（主要是 CodeQL），可安全重用以补全遗漏依赖。 **2. 注册插件到 Claude Code。** 两种方式： ``` # 针对本地克隆的开发： /plugin dev-install ~/claude-code-guantlet # 针对固定版本的 GitHub 发布： /plugin marketplace add hunchom/claude-code-gauntlet /plugin install claude-code-gauntlet@hunchom ``` 两种路径都会将 17 个子代理、阶段钩子和 `/vuln-audit` 斜杠命令注册到会话中。 **3. 运行审计**，可在任意 Claude Code 会话中执行： ``` /vuln-audit # interactive /vuln-audit-autonomous # hands-off loop /vuln-audit-status # state snapshot ``` 这 17 项技能也可作为真实的 Python 包在 Claude 之外导入使用： ``` python -m vr.skills.provenance_merkle build-atom \ --claim "heap-buffer-overflow at src/parser.c:412" \ --source-type file_content \ --source-ref "src/parser.c#L412@a1b2c3d" \ --repo-root /opt/src/target ``` ## 你运行什么 | 命令 | 用途 | |---|---| | `/vuln-audit ` | 交互式 — 范围提示，随后阶段梯子 | | `/vuln-audit-autonomous ` | 免手动循环，跨压缩会话继续 | | `/vuln-audit-status` | 只读活动状态 | | `/vuln-audit-dashboard` | 候选表与最近阶段事件 | | `/vuln-audit-kill` | 设置停止标志；下次迭代退出 | | `/vuln-audit-intake ` | 导入线索（OSS-Fuzz / Syzbot / 回滚） | | `/vuln-audit-postmortem` | 活动后的事后分析报告 | `` 可以是 Git URL（`https://`、`git@`、`ssh://`、`file://`）或指向已克隆本地仓库的绝对路径/`~/` 前缀路径。远程 URL 克隆到 `targets/`；本地路径则以只读方式符号链接并锁定其当前 HEAD 作为提交。无论哪种方式，插件都会通过 GitNexus 索引，运行阶段梯子并在 Gate D 停止，由人类批准。不会将任何内容发送到外部收件箱。 ## 执行后端 通过 `./install backend` 选择一个： | 后端 | 模糊 + 符号执行主机 | 所需条件 | 主机操作系统 | |---|---|---|---| | `remote_vm` | Linux，通过 SSH | `user@host` + SSH 代理密钥 | 任意 | | `local_container` | Docker 或 Podman | 已安装 Docker / Podman | 任意 | | `local_host` | 当前机器 | 仅限 Linux | Linux | ## 仓库布局 ``` claude-code-gauntlet/ |-- .claude-plugin/plugin.json plugin manifest |-- ARCHITECTURE.md 82KB design document (gates, V1..V9 spine) | |-- agents/ 17 subagents (Opus 4.6, pinned) |-- commands/ 15 slash commands |-- skills/vr-*/SKILL.md 17 skill definitions (authoritative CLI + reference pseudocode) |-- lib/python/vr/ installable Python package | |-- _common/ atomic_state, errors, hashing, ssh | |-- skills/*.py 17 authoritative skill modules | `-- __main__.py python -m vr dispatcher | |-- hooks/ 17 hook scripts (gate-a..gate-d + dispatch guards) |-- mcp/ 9 MCP servers (gitnexus, nvd, klee-runner, ...) |-- bin/ orchestrator, dispatcher, TUI, status line |-- schemas/intent.schema.json JSON Schema for orchestrator intents `-- tests/ pytest suite (44 tests, runs <0.5s) ``` ## 阶段链如何工作 规范 Gate-B 链（可达性与可复现）： ``` 1 asan_poc cycle build with ASan+UBSan, run PoC 3x, capture stack hashes 2 fingerprint_match stab. require 3/3 identical signatures 3 provenance_merkle verify live-rehash every file / CVE / commit-SHA atom 4 write_gate write G_B pass append to gates.json, back-patch candidates.json ``` 每个技能都有三种状态的退出码： | 退出码 | 含义 | 阶段行为 | |---|---|---| | `0` | 成功 | 写入阶段通过条目 | | `1` | 基础设施错误（磁盘、SSH、网络） | 重试 / 汇报给操作员 | | `2` | 验证不匹配 — 真实负例 | 阶段失败，候选被埋 | 编排器读取退出码，而非自然语言。

全部五个链条

``` python -m vr.skills.chain list # gate_b_pass, gate_b5_pass, gate_c_pass, gate_c5_pass, gate_d_send python -m vr.skills.chain show --name gate_d_send ```

## 限制 - **TP 率目标是展望性的，尚未测量。** 尚未积累发现的校准账本（`ARCHITECTURE.md` §13 技术 8 仅作骨架）。在此之前，文档中的任何数字都是架构目标，而非基准。 - **端到端尚未在真实目标上运行。** 所有组件独立测试通过（44 个 pytest 绿色）；尚未完成从 A 到 D 的完整活动并产生公开发现。不要期望即插即用的 CVE 生成器。 - **符号执行见证的大规模重放未测试。** KLEE + angr 运行器分发正确且签名比对技能可重放，但尚未观察到端到端的 Gate B.5 `SAT_CONCRETE_VERIFIED`。激励生成仍由 LLM 起草且脆弱。 - **新鲜验证器的独立性是部分的。** 两个使用不同 `system_prompt_flavor` 启动的 Opus 代理共享底层权重 — 共享先验幻觉仍可能通过 V5。V1–V7 联合可部分缓解，但无法完全消除。 - **macOS 仅限开发。** 模糊测试、符号执行与 ASan 重现均在 Linux 上运行。macOS 上请选择 `remote_vm` 或 `local_container`。 - **不是扫描器。** 消费预目标化的仓库并执行阶段梯子，不会扫描整个代码主机以寻找目标。 ## 对比 | 工具 | 方法 | 是否验证可复现 | 适用场景 | |---|---|---|---| | **claude-code-gauntlet** | LLM 审计员 + 6 个机械阶段 | ASan 3/3 + 符号执行重放 | 针对性研究 | | OSS-Fuzz | 持续黑盒模糊测试 | ASan 崩溃报告 | 上游项目 | | Semgrep + CodeQL | 静态模式匹配 | 否 — 需逐条筛选 | CI 时防护 | | 手动审计 + 模糊器 | 专家时间 | 依赖每个引擎的纪律 | 深度一次性分析 | ## 配置 首次运行 `/plugin install` 时提示，或通过环境变量用于脚本化运行： | 变量 | 默认值 | 含义 | |---|---|---| | `FUZZ_HOST` | *(未设置)* | `remote_vm` 模式下 SSH 的 `user@host` | | `NVD_API_KEY` | *(未设置)* | 提升 NVD 速率限制；无缓存也可运行 | | `GITHUB_TOKEN` | 继承 `gh auth` | GHSA 咨询查询 | | `DO_API_TOKEN` | *(未设置)* | 仅当使用 DigitalOcean VM 时需要 | | `AUTONOMOUS_MODE` | `false` | `true` 时自动批准推进阶段的调用 | ## 反幻觉脊柱（V1..V9）

点击查看简要版本

| 检查 | 强制内容 | |---|---| | V1 | 物理证实 — ASan 栈哈希在模糊主机上复现 3/3 | | V2 | 溯源 Merkle — 每个原子均可对活源代码重新哈希 | | V3 | 预言机三角测量 — Semgrep / CodeQL找到同一汇点 | | V4 | 补丁反转 — 草案补丁使 PoC 不再崩溃 | | V5 | 双新鲜验证器 — 两个隔离代理达成“漏洞”结论 | | V6 | 魔鬼代言人 — 结构化反证尝试 | | V7 | 阶段模式 — 每个 `gates.json` 的 JSON Schema | | V8 | 校准账本 — 滚动 Brier 评分控制活动 | | V9 | 批量评审节奏 — 人类在 Gate C 与 Gate D 进行裁决 | 参见 `ARCHITECTURE.md` §13 获取完整原理。

## 许可证 AGPL-3.0-or-later。详见 [`LICENSE`](LICENSE)。

标签：AGPL-3.0, ASan, Chaos, Claude Code插件, Cutter, hands-off, Merkle树, Python技能模块, quarantined agents, seed-based replay, stack hash verification, 上下文验证, 六门梯, 可审计管道, 子代理协调, 开源安全工具, 情报收集, 意图消费者循环, 测试用例, 漏洞审计, 漏洞研究, 确定性分析, 符号执行, 自动化取证, 证据链, 请求拦截, 逆向工具, 逆向工程平台