gebug-audit

专为 Claude Code 设计的两阶段 Web3 智能合约审计工作流。
头脑风暴确定范围，然后执行审计。仅限 EVM。

`gebug-audit` 是一对 Claude Code 技能（skills），可以将漏洞赏金页面、GitHub 仓库或已部署的合约地址转化为： - 经过审查的范围文档（`DEFINITION.md`）， - 有理有据的初始漏洞候选列表（`CANDIDATES.md`）， - 经用户签字确认的安全预检（`SAFETY_PREFLIGHT.md`）， - 原样复制的赏金严重程度矩阵（`BOUNTY_MATRIX.md`）， - 带有通过的 Foundry fork PoC 的逐项发现报告， - 核心审计报告以及可复现的逐项漏洞利用。 这两个技能分别是： | 技能 | 运行时机 | 功能 | |-------|-----------------|--------------| | `/gebug-brainstorm` | 第一步 | 访谈、源码获取、轻量级侦察、生成假设。编写四个定义文件。 | | `/gebug-work` | 头脑风暴之后 | 静态分析、模糊测试、并行漏洞猎手代理（vuln-hunter agents）、有效性验证门控、Foundry fork PoC、逐项发现文件、核心报告。 | ## 为什么分为两个技能 这种划分反映了经验丰富的审计员的工作方式： - **阶段 1（brainstorm）**成本低、对话式且可审查。用户可以在进行任何繁重工作之前纠正范围。 - **阶段 2（work）**成本高（并行代理、模糊测试、PoC）。它拒绝在四个定义文件存在之前启动，从而最大程度地减少代理的无用运行。 它还在最重要的时刻强制进行了人工干预（human-in-the-loop）检查：就在确定范围之后、在任何主动分析运行之前。 ## 功能 ### 贯穿每次审计的强硬原则 - **对抗姿态**：审计员 + 攻击者，而不是代码解释器。 - **有效性原则**：每个假设都引用 `file:line`；没有通过的 PoC 或逐符号的数学推导，任何东西都不会发布。 - **仅凭证据拒绝规则**：怀疑不等于拒绝。PoC 才是证伪手段。 - **锐边规则（Sharp-edge rules）**：将“安全”、“有界限”、“不可操纵”视为假设，而非结论。 - **反谄媚（Anti-sycophancy）**：不盲从用户的直觉或过往报告，必须从代码中重新推导。 - **诚实的负面结果**：只有在流水线完全运行后（加载了所有攻击向量、运行了模糊测试、为每个候选者尝试了 PoC），“无发现”才是可接受的结果。 - **最终反幻觉检查**：在报告发布前，每一处引用、每一个合约/函数/地址都必须经过 `grep` 验证。 ### 流水线护栏 - **场景 A 与 B 自动检测**：brainstorm 阶段会检查 `cwd` 中是否存在 `foundry.toml`+`src/`+`test/`、Hardhat 配置，或者包含 Foundry / Hardhat 依赖的 `package.json`。外部仓库审计会存放在 `cwd//docs/gebug-audit/`；自我审计存放在 `cwd/gebug-audit/`。在任何主动侦察之前，都会公示并确认该选择。 - **强制模糊测试退出关卡**：除非存在带有证据的 `fuzzing/FUZZING.md`，否则 `/gebug-work` 拒绝进入阶段 3。阶段 2 的静默跳过是真实漏洞（不变性被破坏、Halmos 反例、模糊测试种子崩溃）逃脱审计的最常见方式。 - **阶段 6.5 怀疑论筛选器（skeptical-triager）**：一个独立的现实性过滤器，对每个 MEDIUM+ 候选者应用经济和防御者的证伪手段，并返回带有量化引用的 AFFIRM（肯定） / DOWNGRADE（降级） / REJECT（拒绝）。它抵消了漏洞猎手固有的浮现偏见，而不会沦为敷衍的驳回。 - **阶段 4 的 Token 预算门控**：当范围内的代码行数（LoC）会生成超过 10 个 `vuln-hunter` 代理时，编排器将打印预估的输出 token 成本，并拒绝在没有用户批准的情况下继续执行。 - **差异聚焦模式（Diff-focused mode）**：针对移动了 `source_commit` 的重复审计的可选流水线。仅在已更改文件的调用图（call-graph）影响范围内重新运行阶段 4，记录先前已清除的 SHA 以便检测篡改，并使用旧 + 新提交标记报告。 ### 安全策略 - 仅审计 `SAFETY_PREFLIGHT.md` 中明确列出的资产。 - 漏洞验证仅通过 `vm.createSelectFork` 在本地 fork 上运行。 - 绝不广播交易。绝不运行 `cast send`、`forge create`、`forge script --broadcast`，或任何使用真实私钥的命令。 - 将目标仓库视为不受信任。在执行它们之前，会审查 `foundry.toml`、脚本、FFI 设置和重映射（remappings）。 - 绝不自动提交发现。用户会审查每一份草稿。 - 生成的文件中绝不使用破折号（em dashes）（保持格式一致）。 ### 攻击向量覆盖（开箱即用） | 文档 | 覆盖范围 | |-----|--------| | `amm.md` | Uniswap v2/v3/v4 hooks、Curve、Balancer、JIT、k-invariant、捐赠、只读重入、LP 公允价值 | | `bridge.md` | LayerZero、Wormhole、CCIP、Axelar、Hyperlane；欺骗、重放、无凭据铸造、ZK 证明验证 | | `governance.md` | Compound Bravo 分叉、OZ Governor、Snapshot / SafeSnap；闪电贷投票、绕过 timelock、操纵法定人数 | | `lending.md` | Aave / Compound / Morpho / HyperLend；清算、IRM、LTV、借贷预言机、隔离 / e-mode | | `lst-lrt.md` | LST / LRT 机制；铸造、销毁、提款队列、费率提供者、转换率操纵 | | `oracle-integration.md` | Chainlink、Pyth、Redstone、Uniswap TWAP、排序器正常运行时间 feed、LP 公允价值 | | `restaking.md` | EigenLayer M2-Pectra、Symbiotic、Karak；公钥抢占（front-run）、AVS 选择加入、罚没逻辑 | ### 输出布局 该技能在调用时会自动检测审计场景，并相应地路由输出： - **场景 A**（外部仓库，`cwd` 中无 Foundry/Hardhat 标记）：审计树位于克隆源代码内的 `cwd//docs/gebug-audit/`。 - **场景 B**（自我审计，`cwd` 本身就是 Foundry 或 Hardhat 项目）：审计树位于用户 `src/` 和 `test/` 旁边的 `cwd/gebug-audit/`。无需克隆。 在这两种情况下，子树结构是相同的： ``` / (resolved per Scenario A or B) ├── definition/ OUTPUT of /gebug-brainstorm │ ├── DEFINITION.md │ ├── CANDIDATES.md │ ├── SAFETY_PREFLIGHT.md │ └── BOUNTY_MATRIX.md │ ├── _scratch/ intermediate work (gitignored) │ ├── finding/ OUTPUT of /gebug-work (1 file per finding) │ ├── CRITICAL_.md │ ├── HIGH_.md │ └── ... │ ├── fuzzing/ │ ├── FUZZING.md │ ├── *_Invariant.t.sol │ ├── echidna.yaml │ └── halmos_*.out │ ├── exploit/ │ └── Exploit.sol headline exploit │ └── report/ ├── REPORT.md ├── INVARIANTS.md ├── slither-summary.txt ├── slither-high-impact.txt └── POC/ └── / ├── Exploit.t.sol └── reproduce.sh (executable) ``` ## 环境要求 - [Claude Code](https://claude.com/claude-code)。 - [Foundry](https://book.getfoundry.sh/) (`forge`, `cast`, `anvil`)。 - [Slither](https://github.com/crytic/slither) (`pip install slither-analyzer`)。 - `git`。 可选但推荐： - [Aderyn](https://github.com/Cyfrin/aderyn) (`cargo install aderyn`)。 - [Echidna](https://github.com/crytic/echidna)。 - [Halmos](https://github.com/a16z/halmos) (`pipx install halmos`)。 - [Medusa](https://github.com/crytic/medusa)。 ## 安装说明 ### 选项 1：安装脚本（推荐） ``` git clone git@github.com:TarasBrilian/gebug-audit.git cd gebug-audit ./install.sh ``` 安装程序会将 `skills/gebug-brainstorm/` 和 `skills/gebug-work/` 符号链接到 `~/.claude/skills/` 中，这样通过 `git pull` 进行的更新会自动生效。 安装后请重启 Claude Code（或开启新会话）。 ### 选项 2：手动复制 ``` git clone git@github.com:TarasBrilian/gebug-audit.git cp -R gebug-audit/skills/gebug-brainstorm ~/.claude/skills/ cp -R gebug-audit/skills/gebug-work ~/.claude/skills/ ``` ### 选项 3：项目级别安装 如果你只想在单个项目中使用这些技能： ``` git clone git@github.com:TarasBrilian/gebug-audit.git mkdir -p .claude/skills ln -s "$PWD/gebug-audit/skills/gebug-brainstorm" .claude/skills/gebug-brainstorm ln -s "$PWD/gebug-audit/skills/gebug-work" .claude/skills/gebug-work ``` ### 卸载 ``` cd gebug-audit ./uninstall.sh ``` ## 用法 在 Claude Code 内部： ``` /gebug-brainstorm ``` 然后描述目标。示例： ``` /gebug-brainstorm audit this bounty: https://cantina.xyz/competitions/ ``` ``` /gebug-brainstorm scope contracts at github.com// ``` ``` /gebug-brainstorm I want to hunt vulnerabilities in 0xAbCd... on Ethereum ``` 该技能会提出 1 到 3 批结构化问题，获取源代码，运行 Slither 以获取上下文，并编写四个定义文件。 完成后，运行： ``` /gebug-work ``` `/gebug-work` 会读取定义文件并运行完整审计： 静态分析、模糊测试、并行 `vuln-hunter` 代理、跨合约分析、有效性验证门控、Foundry fork PoC、逐项发现文件以及核心报告。 ### 聚焦模式（在 brainstorm 之后） | 模式 | 功能 | |------|--------------| | `audit-only ` | 跳过 PoC；在提供 PoC 之前将严重程度限制在 HIGH。 | | `exploit-only ` | 仅针对单个候选者运行阶段 7。 | | `fork-test ` | 在不同的区块上重新运行现有的 PoC。 | | `triage ` | 将有效性验证门控应用于单个候选者。 | | `report-only` | 从现有的 PoC 重新生成报告。 | | `diff-focused` | 针对移动了 `source_commit` 的重复审计：仅在更改文件的调用图影响范围内重新运行，并使用旧 + 新提交标记报告。 | ## 支持的目标 - **语言**：Solidity、Vyper。 - **链**：Ethereum、BSC、Polygon、Arbitrum、Base、Optimism、Avalanche 以及任何其他兼容 EVM 的链。非 EVM（Solana、Move、CosmWasm）有意不包含在范围内；请为此使用其他技能。 - **框架**：Foundry、Hardhat 或任何能生成标准 Solidity / Vyper 构件的 EVM 工具链。 - **赏金平台**：Cantina、Immunefi、Code4rena、Sherlock、Hats 或私人项目。 ## 典型审计流程 1. 用户将 Cantina 漏洞赏金 URL 粘贴到 Claude Code 中： `/gebug-brainstorm audit https://cantina.xyz/competitions/xyz`。 2. 技能从 `cwd` 检测场景 A 或 B，公布解析出的输出目录，并要求用户确认。 3. 技能询问：赏金平台、目标类型、链、源代码位置。 4. 技能询问：范围内的合约、范围外的合约、严重性矩阵、先前的审计。 5. 技能编写 `SAFETY_PREFLIGHT.md`，用户予以确认。 6. 技能克隆仓库（场景 A）或复用 `cwd`（场景 B），运行 Slither，生成初始候选者。 7. 技能编写 `DEFINITION.md`、`CANDIDATES.md`、`BOUNTY_MATRIX.md`。 8. 用户审查；如果出现任何偏差，用户纠正并重新运行相关阶段。 9. 用户运行 `/gebug-work`。 10. 技能验证这四个文件存在，运行完整流水线，并在生成超过 10 个 `vuln-hunter` 代理之前请求批准。如果缺少 `fuzzing/FUZZING.md` 证据，阶段 2 拒绝继续。 11. 阶段 6.5 对每个 MEDIUM+ 候选者运行怀疑论筛选器，并为每个候选者记录 AFFIRM（肯定） / DOWNGRADE（降级） / REJECT（拒绝）。 12. 技能生成逐项发现文件、逐项发现 PoC（每个都带有可运行的 `reproduce.sh`）、核心漏洞利用以及最终的 `REPORT.md`。 13. 用户审查；没有任何内容会自动提交。 ## 项目结构 ``` gebug-audit/ ├── README.md this file ├── CLAUDE.md instructions for Claude Code in this repo ├── CONTRIBUTING.md ├── LICENSE MIT ├── install.sh symlink installer ├── uninstall.sh ├── assets/ │ └── logo.png ├── scripts/ │ └── check-layout-sync.sh pre-commit guard against output-tree drift ├── tests/ │ └── fixtures/ │ └── vulnerable-vault/ manual regression target (see its README) └── skills/ ├── gebug-brainstorm/ │ ├── SKILL.md │ ├── README.md │ └── references/ │ └── brainstorm-pipeline.md └── gebug-work/ ├── SKILL.md ├── README.md ├── agents/ │ ├── vuln-hunter.md spawned per subsystem in Phase 4 │ ├── skeptical-triager.md spawned in Phase 6.5 │ └── exploit-writer.md spawned per surviving candidate in Phase 7 └── references/ ├── work-pipeline.md ├── finding-template.md per-finding file template (loaded in Phase 8) └── attack-vectors/ ├── amm.md ├── bridge.md ├── governance.md ├── lending.md ├── lst-lrt.md ├── oracle-integration.md └── restaking.md ``` ## 许可证 [MIT](LICENSE)。 ## 致谢 - [Anthropic Claude Code](https://claude.com/claude-code) 提供了 skill + subagent 系统。 - [Trail of Bits / Crytic](https://github.com/crytic) 提供了 Slither、Echidna 和 Medusa。 - [Foundry](https://book.getfoundry.sh/) 提供了该技能所依赖的 fork-test 基础设施。 - 感谢 Web3 安全研究社区，他们发布的漏洞利用和事后分析塑造了这些攻击向量文档。

标签：AI编程助手, Claude Code, EVM, Foundry, Web3, 对称加密, 智能合约审计, 自动化审计