Muzziebear/chainreaper

Chainreaper 自动化了智能合约审计员在漏洞赏金目标上遵循的工作流程：它拉取并索引源代码，推理协议的 invariant 和攻击面，生成候选发现，然后**通过在 mainnet fork 上运行可执行的 proof-of-concept 来证明或反驳每一个候选发现**。其核心设计目标是_抗误报_ —— 一个对抗性的 critic 阶段会重新运行每个提出的 exploit，并尝试在报告之前将其破解。 ## 目录 - [为什么选择 Chainreaper](#why-chainreaper) - [功能](#features) - [工作原理](#how-it-works) - [安装](#installation) - [快速开始](#quickstart) - [配置](#configuration) - [项目结构](#project-layout) - [开发](#development) - [许可证](#license) ## 功能 - **基于证据的发现** — 每个候选发现都由在 mainnet fork 上运行的 Foundry PoC 验证；未经验证的声明将被丢弃。 - **对抗性验证** — N 个独立的 critic agent 重新运行每个 PoC 并尝试反驳它； 判定结果聚合为 true-positive / false-positive / needs-proof。 - **确定性编排** — 一个简单的 sequencer 驱动各个阶段；只有推理阶段会调用 LLM，且每个阶段都会输出一个经验证的 Pydantic contract 供下一阶段使用。 - **校准套件** — 重放已知的 exploit，以在实际挖掘之前衡量检测敏感度。 - **深度分析工具链** — stateful fuzzing（Echidna / Medusa）、静态分析（Slither）、 跨合约经济建模，以及 stress-fork / adverse-market 模拟。 - **攻击面覆盖** — 治理与升级安全检查、外部集成信任建模， 以及用于清单外技术的威胁研究员模式。 - **可插拔的 LLM 后端** — 官方 `anthropic` SDK（结构化输出 + agentic tool-runner）或本地 Claude CLI 后端。 ## 工作原理 一个确定性的 orchestrator 对六个阶段进行排序。每个阶段都会使用上一阶段经验证的数据 contract，因此 pipeline 可以在任何边界进行检查和恢复。 ``` S0 S1 S2 S3 S4 S5 Discovery → Index → Recon → Prefilter → Hunt → Validate scope codemap hunt queue gate/rank fork PoCs critic verdicts ``` | 阶段 | 名称 | 职责 | | :----: | --------- | ---------------------------------------------------------------------------------------------------------------- | | **S0** | Discovery | 从漏洞赏金项目或本地 repo 解析目标；枚举范围内的合约。 | | **S1** | Index | 构建结构化的 codemap（Slither，可选 Tree-sitter）：函数、call graph、升级面。 | | **S2** | Recon | 多 agent 综合 — 推导协议规范、进行探索、对攻击面建模，并生成排序的挖掘队列。 | | **S3** | Prefilter | 对队列进行确定性有效性 + 预算把关（丢弃 / 排序 / 限制 / 标记）。 | | **S4** | Hunt | _hunter_ agent 驱动 Foundry sandbox，在 mainnet fork 上编写并运行 PoC。 | | **S5** | Validate | 独立的 _critic_ agent 重新运行每个 PoC 并尝试反驳它；判定结果聚合为 TP / FP / needs-proof。 | 两个重度推理阶段 —— **Recon (S2)** 和 **Hunt (S4)** —— 承担了大部分工作。 每个阶段都作为具有特定工具表面的不同阶段的序列运行。 ### S2 · Recon — 从源码到排序的挖掘队列 Recon 是一个多 agent 综合过程，它将索引的 codebase 转化为一个去重且排序的队列，其中包含要测试的具体假设。每个推理 agent 都在**只读工具面**上工作 —— 它可以查询代码索引、读取文件并 grep，但不能写入或执行任何操作。 | # | 阶段 | 作用 | 输出 | |:-:|-------|--------------|--------| | 1 | **Spec 研究** _(启用 Web)_ | 阅读协议文档中记录的承诺（文档、注释、白皮书）—— 即无论具体实现如何，协议_声称_始终应成立的条件。 | **Intent invariant** (`origin=spec`) | | 2 | **探索与形式化** | recon agent 遍历 entrypoints → call graph → 会计状态 → 外部调用，并将代码与文档承诺进行核对。此阶段_不_输出任何任务。 | **协议概况**（机制、参与者、价值流）+ **针对 codebase 的 invariant 套件**，每个 invariant 绑定到一个真实的函数 hook 和一个可运行的 checker | | 3 | **威胁研究** _(清单外)_ | 一个独立的 agent 寻找新颖/有创意的攻击思路，输入概况和 invariant 套件，使其能够瞄准_正交补集_，而不是重新推导已覆盖的属性。 | **候选线索**，每个线索都包含假设和先例 | | 4 | **综合** | 最后一个 agent 是队列的**唯一作者**。输入概况摘要、完整的 invariant 套件和威胁档案，它会为每个高/严重级别的 invariant 输出一个破坏任务，将每个独特的威胁线索保留下来，覆盖完整的攻击类别分类（跨合约、依赖、治理、激励），折叠真实的重复项，并分配具有区分度的优先级。即使某个阶段没有产出，基于 invariant 的兜底机制也能保证生成队列。 | 统一且排序的 `HunterTask` 队列 | 一个 **invariant→工具路由** 步骤将在索引时运行的静态分析器与主机上安装的 stateful fuzz / 符号工具结合起来，因此每个 invariant 都会被路由到最适合它的 checker，_并_确保在 S4 中可运行。 ### S3 · 预过滤 这是一个对队列进行的纯确定性把关 —— 不使用 LLM。它验证每个任务，丢弃不可行的任务，进行去重，按预期价值排序，限制在运行预算内，并为每个幸存的任务标记一个 `rank` 和 S4 会使用的 fuzzing `seed`。 ### S4 · Hunt — 证明或反驳每个假设 每个调度的任务都独立进行挖掘。hunter 是唯一拥有**读写权限、可执行 sandbox**（配置好的 Foundry 项目）的 agent，它通过一个漏斗式的流程处理任务，从低成本的静态检查一直到在实时链的 fork 上进行完整的 exploit 复现。 | # | 阶段 | 作用 | |:-:|-------|--------------| | 1 | **Fork 预检** | 针对每个目标链，在特定区块解析 → 验证 → 固定 archive RPC，启动一个共享的本地 `anvil` fork（验证 chain-id 和合约代码大小，以避免 stale-fork 陷阱），并为 sandbox 导出 `_RPC_URL`。如果没有 RPC，则平滑降级为仅本地运行。 | | 2 | **活动脚手架** | 为_此_任务生成一个 Chimera 风格的分层 fuzzing harness，以绑定的 invariant 和可达面为键。根据任务的不同，它会组合一个 **attacker-primitive** 层（跨合约 stateful 链 —— `deposit→borrow`，`mint→donate→redeem`）、一个 **adverse-market 压力**层（扭曲 oracle 价格、池储备、锚定汇率、资金费率/利用率）、一个**依赖**层（外部集成变得 stale / 极端 / 回退 / reentrant），以及 **multi-actor**（联盟-PnL）+ **long-horizon**（`vm.warp`/`vm.roll`）层。 | | 3 | **挖掘循环** | hunter 通过漏斗运行任务：手写的 **Foundry** invariant/单元测试 → 使用 **Echidna** 和 **Medusa** 进行 stateful fuzzing（断言、属性、fork 和优化模式） → 使用 **Halmos** 进行符号检查。任何反例都会输入到 **fork-PoC 漏斗**中，在此阶段，hunter 会编写一个 Foundry 测试，在 fork 上的_真实部署合约_上复现其影响。 | | 4 | **结果** | 任务产生一个 `Finding` + 一个可运行的 `PoC`，或者一个诚实的_空结果_。hunter 对可达性进行分类（参见 [AGENTS.md](AGENTS.md#methodology-the-adversary-model))，而不是夸大严重性。 | ### S5 · 验证 N 个独立的 **critic** agent 在一个新的 sandbox 中重新运行每个 PoC，并积极尝试_反驳_它 — 如果不确定，默认判定为已反驳。判定结果聚合为 **true-positive / false-positive / needs-proof**，只有存活的发现才会被报告。 ### 工具 | 类别 | 工具 | |----------|-------| | **静态分析 / 索引** | [Slither](https://github.com/crytic/slither)，可选的 [Tree-sitter](https://tree-sitter.github.io)（AST/symbols），可查询的 SQLite 代码索引 | | **编译与执行** | [Foundry](https://getfoundry.sh)（`forge`、`cast`、`anvil`、`chisel`），通过 `solc-select` 调用 `solc` | | **Stateful fuzzing** | [Echidna](https://github.com/crytic/echidna)，[Medusa](https://github.com/crytic/medusa)（断言 / 属性 / fork / 优化模式） | | **符号执行** | [Halmos](https://github.com/a16z/halmos) | | **Forking** | 每条链固定的 archive-node RPC，由共享的本地 `anvil` 作为前端 | | **LLM 后端** | 官方 [`anthropic`](https://pypi.org/project/anthropic/) SDK（结构化输出 + agentic tool-runner），或本地 Claude CLI 后端 | ## 安装 **前置条件：** Python 3.11+，[Foundry](https://getfoundry.sh)，以及通过捆绑的安装脚本安装的外部分析 工具链（Slither、Echidna、Medusa）。 ``` # clone git clone https://github.com/Muzziebear/chainreaper.git cd chainreaper # 安装 package python -m venv .venv && source .venv/bin/activate pip install -e ".[agents,index,dev]" # 安装 external analysis toolchain (Foundry, Slither, Echidna, Medusa, ...) bash tools_poc/setup/install.sh # 验证环境 chainreaper doctor ``` ## 快速开始 ``` # 1. 配置 credentials（参见下方的 Configuration） mkdir -p .chainreaper && cp .env.example .chainreaper/env # then fill in your keys # 2. 针对 known exploits 进行校准，以确认检测灵敏度 chainreaper calibrate # 3. 搜索 target chainreaper scan --help ``` 该 pipeline 是可恢复的 —— `chainreaper resume ` 会从最后完成的阶段继续。 ## 配置 密钥在启动时从 `.chainreaper/env`（被 git 忽略）加载。复制 `.env.example` 并填写： | 变量 | 用途 | | ------------------- | ---------------------------------------------------------------------------------------------------- | | `ANTHROPIC_API_KEY` | 用于推理阶段 (S2+) 的 LLM 后端。 | | `ETHERSCAN_API_KEY` | 已验证源码解析。 | | `_RPC_URL` | 每条链的 Archive RPC 端点，用于 mainnet-fork PoC。仅需要你作为目标的链。 | ## 项目结构 ``` chainreaper/ the Python package — orchestrator, stages, agents, backends, tooling tests/ smoke tests for each stage, plus fixtures bench/ self-contained replay cases used by the calibration suite tools_poc/ setup script and invariant notes for the external analysis toolchain docs/ implementation spec and design notes ``` ## 开发 ``` pip install -e ".[dev]" python tests/smoke_s0.py # each stage ships a runnable smoke test ruff check chainreaper/ # lint ``` 完整的设计原理位于 [`docs/IMPLEMENTATION-SPEC.md`](docs/IMPLEMENTATION-SPEC.md) 和 [`docs/IMPL-NOTES.md`](docs/IMPL-NOTES.md) 中。 ## 许可证 基于 [MIT 许可证](LICENSE) 发布。

标签：DLL 劫持, 区块链安全, 多智能体, 大语言模型, 智能合约审计, 逆向工具