Archethect/sc-auditor
GitHub: Archethect/sc-auditor
AI驱动的Solidity智能合约审计框架，通过多Agent并行分析和「魔鬼代言人」验证流程系统性发现并证明漏洞。
Stars: 62 | Forks: 10
# sc-auditor
您面向 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 和 [Codex CLI](https://github.com/openai/codex) 的 AI 驱动智能合约安全副驾驶。
**版本：** 2.0.0 | **作者：** [Archethect](https://github.com/Archethect)
## 目录
- [概述](#overview)
- [v2.0.0 新特性](#whats-new-in-v200)
- [工作原理](#how-it-works)
- [前置条件](#prerequisites)
- [安装](#installation)
- [配置](#configuration)
- [快速开始](#quick-start)
- [使用方法](#usage)
- [交互式审计](#interactive-audit-security-auditor)
- [独立 MCP 工具](#individual-mcp-tools)
- [审计方法论](#audit-methodology)
- [故障排除](#troubleshooting)
- [开发](#development)
- [致谢](#credits)
- [许可证](#license)
## 概述
sc-auditor 将您的 AI 编程助手转变为安全审计员。只需将其指向一个 Solidity 代码库，它就会映射架构，调度六个并行 agent 在不同的漏洞类别中搜寻 bug，然后通过 Devil's Advocate（魔鬼代言人）流程验证每一个发现，该流程要求在确认前提供证据。
底层技术包括：静态分析（Slither, Aderyn）、真实世界的漏洞情报、模糊测试（Echidna, Medusa）、符号执行（Halmos），以及严谨的 Map-Hunt-Attack 方法论 —— 所有这些都通过提示驱动的多 agent 流水线进行编排。
1. **交互式审计技能** (`/security-auditor`) —— 一个结构化的多阶段流水线，具有并行 agent 通道，用于系统性的漏洞发现。
2. **独立 MCP 工具** —— 八个可直接调用的工具，用于临时分析。
## v2.0.0 新特性
v2.0.0 是一次彻底的重新架构。硬编码的审计流水线已被替换为 **提示驱动的多 agent 编排模型** —— 每个阶段现在都由并行调度的专门子 agent 执行，并具有结构化的检查点，以实现崩溃恢复和上下文窗口弹性。
**并行搜寻通道** —— 六个专门的 agent 同时搜寻，每个针对一个独特的漏洞类别：回调活性、记账/权益、语义一致性、代币/预言机状态性、经济差异，以及一个自动触发的对抗性深度通道，用于跨合约攻击路径。灵感来自 [@pashov](https://github.com/pashov) 的结构化 agent 通道方法论和对抗性验证方法。
**Devil's Advocate 验证流水线** —— 每个发现都在 ATTACK 阶段经过正式的 6 维度 DA 评估，然后一个独立的怀疑者 (VERIFY) 试图用反转指令打破它。冲突由基于证据的法官解决：“证明它，否则失去它。”
**证明或降级** —— ATTACK agent 必须为确认的漏洞尝试至少一种证明方法（Foundry PoC, Echidna, Medusa, Halmos）。在基准模式下，未证明的 HIGH/MEDIUM 发现会被自动降级。
**检查点纪律** —— Agent 在每个阶段后自我检查。编排器可以在崩溃、上下文压缩或会话中断后从任何阶段恢复。
**扩展的工具套件** —— 八个 MCP 工具：Slither, Aderyn, Solodit 搜索, Cyfrin 检查清单, Foundry PoC 生成, Echidna 模糊测试, Medusa 模糊测试, 以及 Halmos 符号执行。
## 工作原理
```
/security-auditor src/
|
SETUP -----> MAP -----> HUNT -----> ATTACK -----> VERIFY -----> REPORT
(1 agent) (1 agent) (5-6 agents) (N agents) (N agents)
parallel parallel parallel
|
+--------------------+--------------------+
| | | | |
Callback Accounting Semantic Token/ Economic
Liveness Entitlement Consist. Oracle Differ.
| | | | |
+----+-----+---------+----+----+----------+
| |
Adversarial Deep (auto-trigger)
(cross-contract)
```
每个 HUNT 通道产生优先级的热点。您选择要深入分析的热点。ATTACK agent 追踪调用路径，运行 Devil's Advocate 协议，构建漏洞草图，并生成证明。VERIFY agent 独立地以反转指令挑战每一个发现。法官解决冲突。
## 前置条件
### 必需
- **Node.js >= 22** — 从 [nodejs.org](https://nodejs.org/) 下载
- **Claude Code CLI** 或 **Codex CLI** — 参阅 [Claude Code 文档](https://docs.anthropic.com/en/docs/claude-code) 或 [Codex 文档](https://github.com/openai/codex)
- **Solodit API Key** — `search_findings` 工具所需：
1. 前往 [solodit.cyfrin.io](https://solodit.cyfrin.io)
2. 登录 > 下拉菜单（右上角）> **API Keys**
3. 生成并保存您的密钥
### 可选（推荐）
- **Slither** + **solc** — 静态分析：
pip install slither-analyzer solc-select
solc-select install 0.8.20 && solc-select use 0.8.20
将 `solc` 版本与您合约的 `pragma solidity` 语句匹配。
- **Aderyn** — 基于 Rust 的静态分析：
cargo install aderyn
- **Foundry** — 用于 PoC 生成和 forge 测试：[getfoundry.sh](https://getfoundry.sh/)
- **Echidna** / **Medusa** / **Halmos** — 模糊测试和符号执行（参阅它们各自的文档）
## 安装
### Claude Code
1. **克隆并构建：**
git clone https://github.com/Archethect/sc-auditor.git
cd sc-auditor && npm install && npm run build
2. **注册插件** — 添加到您项目的 `.mcp.json` 或 Claude Code 设置中：
{
"mcpServers": {
"sc-auditor": {
"type": "stdio",
"command": "node",
"args": ["/path/to/sc-auditor/dist/mcp/main.js"]
}
}
}
如果作为 Claude Code 插件安装，路径会自动解析。
3. **设置您的 Solodit API key：**
export SOLODIT_API_KEY="your-key-here"
### Codex CLI
```
# 通过 npx
codex mcp add sc-auditor -- npx -y sc-auditor
```
```
# 在你的 Codex config.toml 中
[agent]
multi_agent = true
```
有关详细的 Codex 设置、技能安装和故障排除，请参阅 [docs/codex-setup.md](docs/codex-setup.md)。
## 配置
sc-auditor 从 Solidity 项目根目录的 `config.json` 读取可选配置。可以使用 `SC_AUDITOR_CONFIG` 环境变量覆盖路径。所有字段均为可选 —— 会应用合理的默认值。
### 最小设置
```
{}
```
空的 `config.json`（或无配置文件）是有效的。
### 配置参考
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `default_severity` | string[] | `["CRITICAL","HIGH","MEDIUM"]` | 严重性过滤器。有效值：`CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `GAS`, `INFORMATIONAL` |
| `default_quality_score` | integer | `2` | 最小 Solodit 质量分数 (1-5) |
| `report_output_dir` | string | `"audits"` | 报告输出目录（相对路径，不含 `..`） |
| `max_findings_per_category` | integer | `10` | 每个类别的最大发现数 (1-1000) |
| `max_deep_dives` | integer | `5` | 最大深入分析数 (1-100) |
#### 静态分析 (`static_analysis`)
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `slither_enabled` | boolean | `true` | 运行 Slither |
| `slither_path` | string | `"slither"` | Slither 二进制文件路径 |
| `aderyn_enabled` | boolean | `true` | 运行 Aderyn |
| `aderyn_path` | string | `"aderyn"` | Aderyn 二进制文件路径 |
#### LLM 推理 (`llm_reasoning`)
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `max_functions_per_category` | integer | `50` | 每个类别的最大函数数 (1-500) |
| `context_window_budget` | number | `0.7` | 上下文窗口比例 (0.1-1.0) |
#### 工作流 (`workflow`)
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `mode` | string | `"default"` | `default`, `deep`, 或 `benchmark` |
| `parallel_hunters` | boolean | `false` | 并行运行 HUNT 通道 |
| `autonomous` | boolean | `false` | 跳过用户确认关卡 |
| `require_witness_for_high` | boolean | `false` | 为 HIGH 发现要求 PoC |
**工作流模式：**
- **`default`** — 标准的 Map-Hunt-Attack，带用户审查关卡。
- **`deep`** — 扩展覆盖范围，包含额外的分析轮次。
- **`benchmark`** — 竞争性审计模式。未证明的 HIGH/MEDIUM 发现会被降级。报告分为得分发现（带证明）和研究候选（不带证明）。
#### 证明工具 (`proof_tools`)
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `foundry_enabled` | boolean | `true` | Foundry PoC 生成 |
| `echidna_enabled` | boolean | `false` | Echidna 模糊测试 |
| `medusa_enabled` | boolean | `false` | Medusa 模糊测试 |
| `halmos_enabled` | boolean | `false` | Halmos 符号执行 |
| `ityfuzz_enabled` | boolean | `false` | ItyFuzz 模糊测试 |
#### 验证 (`verify`)
| 字段 | 类型 | 默认值 | 描述 |
|-------|------|---------|-------------|
| `demote_unproven_medium_high` | boolean | `false` (`benchmark` 模式下为 `true`) | 将未证明的 HIGH/MEDIUM 降级为 informational |
### 环境变量
| 变量 | 描述 |
|----------|-------------|
| `SOLODIT_API_KEY` | **必需。** Solodit API key（环境变量或 `.env` 文件） |
| `SC_AUDITOR_CONFIG` | 覆盖 config.json 路径 |
## 快速开始
```
# 1. 设置你的 API key
export SOLODIT_API_KEY="sk_your_key_here"
# 2. 在你的 Solidity 项目中打开 Claude Code
cd my-defi-protocol
# 3. 启动 audit
/security-auditor src/
```
该插件运行静态分析，构建您合约的系统映射，然后调度并行搜寻 agent 来查找漏洞。您审查映射，选择要攻击的热点，并获得带有证明的已验证发现。
您也可以将其指向 GitHub 仓库：
```
/security-auditor https://github.com/example/vault-protocol
```
或特定文件：
```
/security-auditor src/Vault.sol,src/Strategy.sol
```
## 使用方法
### 交互式审计 (`/security-auditor`)
主要模式。带您运行完整的 Map-Hunt-Attack 流水线：
#### 阶段 0：恢复检查
检查 `.sc-auditor-work/checkpoints/` 中是否存在审计状态。如果找到，提供从上一个完成阶段恢复的选项 —— 不会丢失工作。
#### 阶段 0.5：解析输入
将您的输入（本地路径、GitHub URL 或特定文件）解析为项目根目录。检测框架并确定审计范围。
#### 阶段 1：SETUP (1 个 agent)
运行 Slither 和 Aderyn（如果已安装），加载 Cyfrin 检查清单，发现所有 Solidity 文件。返回按严重性分类的发现摘要。
#### 阶段 2：MAP (1 个 agent)
读取所有合约并构建一个全面的 **SystemMapArtifact**：组件、继承树、外部接口、权限接口、状态变量、写入点、调用点、价值流边、配置语义、协议不变量和审计单元。在继续之前，您需审查并修正映射。
#### 阶段 3：HUNT (5-6 个并行 agent)
六个专门的通道同时搜寻：
| 通道 | 查找内容 |
|------|---------------|
| **Callback Liveness** | 重入攻击、Griefing 攻击、蜜罐、提现阻断、用户控制的回调 |
| **Accounting Entitlement** | 过期余额读取、转账/销毁权益漂移、奖励归属 bug、基于过期状态的费用捕获 |
| **Semantic Consistency** | 配置单位不匹配（百分比 vs 基点 vs 除数）、语义变化的复制公式、魔术数字、小数缩放错误 |
| **Token Oracle Statefulness** | 授权滥用、收费代币/重基代币假设、预言机过期和操纵、多交易状态假设 |
| **Economic Differential** | 对称操作不对称（存款 vs 提款）、时间汇率漂移、边界行为（零/最大/尘埃/首次存款）、费用复合、激励错位 |
| **Adversarial Deep** | 跨通道热点链接、闪电贷放大、治理/时间锁利用、三明治/预言机级联 *(检测到跨合约模式时自动触发)* |
每个通道应用渐进式硬负例处理 —— 安全模式被注释并降低优先级，而非被忽略。您选择要分析的热点。
#### 阶段 4：ATTACK (N 个并行 agent)
每个热点一个 agent。每个 agent：
1. 追踪完整的调用路径（入口 → 分支 → 变更 → 退出）
2. 首先运行 **Devil's Advocate 协议**（6 个维度：守卫、重入保护、访问控制、设计分类、经济可行性、空运行）
3. 构建包含 tx 序列、状态增量和数字示例的漏洞草图
4. 生成证明（Foundry PoC, Echidna, Medusa, 或 Halmos）
5. 用 Solodit 先例进行佐证
#### 阶段 5：VERIFY (N 个并行 agent)
独立的怀疑者用 **反转指令** 挑战每一个发现：
- 如果 ATTACK 确认了它 → 怀疑者试图 **否定**（寻找遗漏的守卫）
- 如果 ATTACK 推翻了它 → 怀疑者试图 **复活**（证明守卫实际上没有阻止）
法官用“证明它，否则失去它”协议解决冲突。
#### 阶段 5.5：冲突解决
RE-ATTACK agent 被调度用于需要有效漏洞证明的复活发现。
#### 阶段 6：报告
具有五个部分的最终结构化报告：
1. **Proved Findings** — 经可执行证明验证
2. **Confirmed (Unproven)** — 证据确凿，无可执行证明
3. **Detected Candidates** — 合理，未完全验证
4. **Design Tradeoffs** — 接受风险的有意选择
5. **Discarded** — 排除，附带 DA 链推理
### 独立 MCP 工具
直接使用任何工具进行临时分析，无需运行完整审计：
#### 静态分析
| 工具 | 描述 | 输入 |
|------|-------------|-------|
| `run-slither` | Slither 静态分析 | `{ rootDir }` |
| `run-aderyn` | Aderyn 静态分析 | `{ rootDir }` |
#### 情报
| 工具 | 描述 | 输入 |
|------|-------------|-------|
| `search_findings` | 搜索 Solodit 的真实世界发现（速率限制：60 秒内 20 次请求） | `{ query, severity?, tags?, limit? }` |
| `get_checklist` | Cyfrin 审计检查清单（本地缓存 24 小时） | `{ category? }` |
#### 证明生成与测试
| 工具 | 描述 | 输入 |
|------|-------------|-------|
| `generate-foundry-poc` | 针对热点的 Foundry PoC 脚手架 | `{ rootDir, hotspot }` |
| `run-echidna` | Echidna 模糊测试 | `{ rootDir, contractName?, configPath?, testLimit? }` |
| `run-medusa` | Medusa 模糊测试 | `{ rootDir, targetContract?, configPath?, timeout? }` |
| `run-halmos` | Halmos 符号执行 | `{ rootDir, contractName?, functionName?, loopBound? }` |
**示例：**
```
"Run Slither on my contracts"
"Search Solodit for flash loan reentrancy findings"
"Generate a Foundry PoC for this vulnerability"
"Run Echidna fuzzing on src/Vault.sol"
```
## 审计方法论
### 核心原则
1. **假设驱动** — 每个问题都是待证伪的假设，而非待确认的结论。
2. **交叉引用强制** — 根据多个来源验证：静态分析、检查清单、Solodit 先例、人工审查。
3. **Devil's Advocate 协议** — 正式的 6 维度评估（守卫、重入保护、访问控制、设计分类、经济可行性、空运行），评分从 -3（完全缓解）到 +1（边缘情况可利用）。决策阈值决定结论：推翻、降级、维持或升级。
4. **需要证据** — 具体的行引用、代码路径和至少一个支持来源。
5. **特权角色诚实** — 管理员诚信行事。但权限传播、组合失败、闪电贷治理和配置交互向量不会被忽略。
6. **渐进式硬负例处理** — 安全模式（重入守卫、拉优于推、Gas 限制回调）被注释并降低优先级，从不被静默忽略。
### Solodit 用法（按阶段分级）
Solodit 是佐证工具，而非发现工具：
| 阶段 | 策略 |
|-------|--------|
| SETUP / MAP | **阻塞** — 无 `search_findings` 调用 |
| HUNT | 仅在建立本地锚点后（代码中的合约 + 函数 + bug 家族） |
| ATTACK | 用于佐证已识别的攻击路径 |
| VERIFY | 用于加强或削弱证据 |
| REPORT | **阻塞** |
### 发现生命周期
```
Hotspot (HUNT) → candidate (ATTACK) → verified / judge_confirmed / discarded (VERIFY)
↓
invalidated_by_attack (if DA kills it early)
```
### 发现严重性与置信度
- **严重性：** Critical, High, Medium, Low, Gas, Informational
- **置信度：** Confirmed（带证明）、Likely（证据确凿）、Possible（合理假设）
- **证明类型：** Foundry PoC, Echidna, Medusa, Halmos, ItyFuzz, 或无
## 故障排除
### 配置错误
| 错误 | 原因 | 修复 |
|-------|-------|-----|
| `CONFIG_MISSING` | 无 config.json | 可选 —— 创建一个或使用 `SC_AUDITOR_CONFIG` |
| `CONFIG_PARSE_ERROR` | JSON 无效 | 修复语法（尾随逗号、缺少引号） |
| `CONFIG_VALIDATION` | 字段值无效 | 检查 [配置参考](#configuration-reference) 中的类型和范围 |
### 静态分析错误
| 错误 | 原因 | 修复 |
|-------|-------|-----|
| `TOOL_NOT_FOUND` | 未安装 Slither/Aderyn | `pip install slither-analyzer` 或 `cargo install aderyn` |
| `COMPILATION_FAILED` | solc 版本不匹配 | `solc-select install X.Y.Z && solc-select use X.Y.Z` |
| `EXECUTION_TIMEOUT` | 项目过大 | 缩小范围或增加超时 |
### Solodit API 错误
| 错误 | 原因 | 修复 |
|-------|-------|-----|
| `SOLODIT_AUTH` | API key 无效 | 在 [solodit.cyfrin.io](https://solodit.cyfrin.io) > API Keys 重新生成 |
| `SOLODIT_RATE_LIMIT` | >20 次请求 / 60秒 | 等待重置 |
| `SOLODIT_NETWORK` | 连接问题 | 检查网络连接 |
### 常见问题
- **插件未显示** — 验证 `.mcp.json` 中的路径指向 `dist/mcp/main.js`。首先运行 `npm run build`。
- **阶段顺序运行** — 在您的 Codex 配置中启用并行 agent (`multi_agent = true`)。
- **solc 版本错误** — `solc-select list` 查看已安装版本，`solc-select install X.Y.Z && solc-select use X.Y.Z`。
- **审计状态损坏** — 删除 `.sc-auditor-work/` 并重新开始。
## 开发
### 构建
```
npm run build # Compile TypeScript + generate .agents/ for Codex
```
### 测试
```
npm test # Unit + integration tests (vitest)
```
### Lint 和类型检查
```
npm run lint # Biome linter
npm run typecheck # TypeScript validation
```
### 项目结构
```
src/config/ Configuration loading and validation
src/core/ Solidity file discovery
src/mcp/ MCP server and tool registration
src/mcp/tools/ Tool implementations (executors + parsers)
src/mcp/services/ Checklist fetching and caching
src/types/ Shared TypeScript types
skills/ Audit skill definition and agent prompts
.agents/ Codex-compatible skill files (auto-generated)
scripts/ Build scripts (skills/ -> .agents/ transformer)
tests/ Integration and smoke tests
.claude-plugin/ Plugin manifests
```
## 致谢
- **审计通道架构** — 并行搜寻通道结构和对抗性深度验证方法受到 [@pashov](https://github.com/pashov) 在多 agent 安全审查方法方面开创性工作的启发。专门 agent 独立搜寻不同漏洞类别，然后结合发现进行对抗性跨通道分析的概念，直接借鉴了他的方法。
- **Solodit & Cyfrin** — 通过 [Cyfrin](https://www.cyfrin.io/) 提供的真实世界漏洞情报和审计检查清单。
- **静态分析** — Trail of Bits 的 [Slither](https://github.com/crytic/slither)，Cyfrin 的 [Aderyn](https://github.com/Cyfrin/aderyn)。
## 贡献
欢迎贡献。请遵循现有约定：
- 约定式提交（`feat:`, `fix:`, `refactor:`, `test:`, `docs:`）
- 提交前运行 `npm run lint && npm run typecheck && npm test`
- 带有 `.js` 扩展名的 ESM 导入
- 将测试放在 `__tests__/` 目录中
## 许可证
保留所有权利。
标签：Aderyn, AI 安全副驾驶, Claude Code, Codex CLI, DeFi 安全, Echidna, Halmos, Map Hunt Attack 策略, MCP, Medusa, MITM代理, PE 加载器, PyRIT, Slither, Solidity 安全, Solodit, Web3 安全, 云安全监控, 区块链安全, 多智能体系统, 大模型编程, 对称加密, 智能合约审计, 符号执行, 自动化审计, 自动化攻击, 静态分析, 风险分析