ShieldScan

面向 Web3 社区的开源智能合约漏洞扫描器。

## 概述 ShieldScan 是一款安全优先的工具，用于扫描 Solidity 智能合约中的常见漏洞，帮助开发者和审计人员在部署前发现关键问题。提供 **Python CLI 工具**和**交互式 Web 应用**两种使用方式。 本工具的构建理念是：**强大的安全防御工具应当掌握在每个人手中** —— 而不是被昂贵的审计公司所垄断。 ## 功能 - **14+ 种漏洞模式** — 重入攻击、tx.origin、未检查调用、整数溢出等 - **SWC 注册表映射** — 每个发现均关联至智能合约弱点分类 (SWC) - **严重程度分类** — 严重、高、中、低，并提供可操作的修复建议 - **多格式输出** — JSON、Markdown、EVMbench 以及交互式 HTML 报告 - **兼容 EVMbench** — 可针对 Paradigm/OpenAI 提供的真实世界漏洞进行基准测试 - **Claude Code 集成** — 提供 MCP 服务器 + `/security-scan` 技能，支持 AI 驱动的语义分析 - **Web UI** — 在浏览器中粘贴代码即可立即扫描 - **CLI 工具** — 可轻松集成至 CI/CD 管道和开发工作流中 - **100% 开源** — 采用 MIT 许可证，永久免费 ## 快速入门 ### Web 应用（无需安装） 在浏览器中打开 `public/index.html` —— 粘贴 Solidity 代码即可立即扫描。 ### Python CLI ``` # 克隆仓库 git clone https://github.com/Carlys17/ShieldScan.git cd ShieldScan # 安装依赖 pip install -r requirements.txt # 扫描合约 python src/scanner.py examples/VulnerableVault.sol # 输出为 JSON python src/scanner.py examples/VulnerableVault.sol -f json # 输出为 Markdown 报告 python src/scanner.py examples/VulnerableVault.sol -f markdown -o report.md ``` ## 漏洞模式 | ID | 模式 | 严重程度 | SWC | |---|---|---|---| | 01 | 重入攻击 | 严重 | SWC-107 | | 02 | tx.origin 身份验证 | 高 | SWC-115 | | 03 | 未检查的调用返回值 | 高 | SWC-104 | | 04 | 不受信任的 Delegatecall | 严重 | SWC-112 | | 05 | 未受保护的 selfdestruct (自毁) | 严重 | SWC-106 | | 06 | 整数上溢/下溢 | 高 | SWC-101 | | 07 | 时间戳依赖 | 中 | SWC-116 | | 08 | 区块号依赖 | 低 | SWC-120 | | 09 | 缺少访问控制 | 中 | SWC-105 | | 10 | 浮动 Pragma (版本号) | 低 | SWC-103 | | 11 | 未初始化的存储变量 | 高 | SWC-109 | | 12 | Gas 限制导致的 DoS (拒绝服务) | 中 | SWC-128 | | 13 | 缺少事件发射 | 中 | SWC-135 | | 14 | 硬编码地址 | 低 | SWC-134 | ## 项目结构 ``` ShieldScan/ ├── src/ │ └── scanner.py # Core vulnerability scanner engine ├── public/ │ └── index.html # Web app (single-file, no build needed) ├── mcp_server/ │ ├── shieldscan_server.py # MCP server for Claude Code integration │ └── requirements.txt # MCP server dependencies ├── .claude/ │ ├── settings.json # MCP server registration │ └── skills/security-scan/ │ └── SKILL.md # /security-scan slash command ├── benchmark/ │ ├── evmbench_adapter.py # EVMbench format conversion & matching │ ├── evmbench_runner.py # Benchmark orchestration pipeline │ ├── config.yaml # Benchmark configuration │ ├── requirements.txt # Benchmark dependencies (pyyaml, requests) │ ├── shieldscan_agent/ # ShieldScan-only EVMbench agent │ │ ├── config.yaml │ │ ├── start.sh │ │ └── aggregate.py │ └── hybrid_agent/ # ShieldScan + Claude Code hybrid agent │ ├── config.yaml │ ├── start.sh │ ├── DETECT.md │ └── aggregate_hybrid.py ├── examples/ │ ├── VulnerableVault.sol # Example vulnerable contract │ └── SafeVault.sol # Example secure contract ├── docs/ │ ├── screenshot.png # App screenshot │ └── logo.svg # ShieldScan logo ├── requirements.txt ├── LICENSE └── README.md ``` ## 输出示例 ``` ╔══════════════════════════════════════════════════════════════╗ ║ ShieldScan — Smart Contract Vulnerability Scanner ║ ╚══════════════════════════════════════════════════════════════╝ Target: VulnerableVault.sol Lines: 23 | Patterns: 14 | Time: 0.38s ┌─────────────────────────────────────────────────────────┐ │ FINDINGS: 3 total │ │ ● Critical: 1 ● High: 1 ● Medium: 1 ○ Low: 0 │ └─────────────────────────────────────────────────────────┘ [CRITICAL] Reentrancy Vulnerability (SWC-107) Line 11-12 | msg.sender.call{value} before state update Fix: Apply Checks-Effects-Interactions pattern [HIGH] tx.origin Authentication (SWC-115) Line 16 | tx.origin used for authorization Fix: Replace with msg.sender [MEDIUM] Missing Event Emission (SWC-135) Line 21 | State change without event Fix: Emit Deposit event after balance update ``` ## 使用场景 - **部署前审计** — 在主网部署前进行快速的首轮安全扫描 - **学习工具** — 通过真实示例了解常见的智能合约漏洞 - **CI/CD 集成** — 在开发管道中自动化执行安全检查 - **漏洞赏金侦察** — 对 Immunefi、Code4rena 等平台上的目标合约进行快速评估 ## EVMbench 基准测试集成 ShieldScan 支持 [EVMbench](https://github.com/paradigmxyz/evmbench)，这是 Paradigm/OpenAI 提供的智能合约安全基准测试，包含来自 Code4rena 比赛的 40 次真实审计和 100 多个漏洞。 ### EVMbench 输出格式 生成兼容 EVMbench 的提交文件： ``` python src/scanner.py contract.sol -f evmbench -o submission/audit.md ``` ### 运行基准测试 安装基准测试依赖（核心扫描器本身无需任何依赖）： ``` pip install -r benchmark/requirements.txt ``` 针对完整的 EVMbench 数据集运行： ``` python benchmark/evmbench_runner.py --config benchmark/config.yaml ``` 针对特定审计运行： ``` python benchmark/evmbench_runner.py --audit-id 2023-07-pooltogether ``` 针对 EVMbench 数据集的本地副本运行： ``` python benchmark/evmbench_runner.py --audits-dir /path/to/frontier-evals/project/evmbench/audits ``` 结果将保存至 `benchmark/results/` 目录，格式为 `summary.json` 和 `summary.md`。 ### 将 ShieldScan 用作 EVMbench Agent 要在 EVMbench 本地评估框架中注册 ShieldScan，请执行以下操作： 1. 将 `benchmark/shieldscan_agent/` 复制到 `evmbench/agents/shieldscan/` 2. 将 `src/scanner.py` 复制到该 agent 目录中 3. 使用 `--agent shieldscan` 运行 EVMbench 评估 ### 预期性能 ShieldScan 使用基于正则表达式的模式匹配来检测 14 种漏洞类别。EVMbench 的真实标签包含来自真实 Code4rena 审计比赛的复杂、逻辑层面的漏洞。预期结果如下： - **召回率**：较低（约 2-8%）。大多数 EVMbench 漏洞需要超越模式匹配的语义理解能力。 - **精确率**：表现不一。ShieldScan 可能会标记出与真实标签重叠的模式，但在大型代码库中许多可能是误报。 - **最佳匹配项**：重入攻击 (SWC-107)、访问控制问题 (SWC-106)、未检查的返回值 (SWC-104)。 - **最弱匹配项**：业务逻辑缺陷、经济漏洞利用、跨合约交互、预言机操控。 此基准测试的价值在于作为一个基线，以便在 ShieldScan 的分析能力不断增强时衡量其改进幅度。 ## Claude Code 安全集成 ShieldScan 与 [Claude Code](https://claude.com/claude-code) 集成，将快速的正则表达式扫描与 AI 驱动的语义分析结合在一起。 ### MCP Server 通过 Model Context Protocol 将 ShieldScan 作为可由 Claude Code 调用的工具公开： ``` # 安装 MCP 依赖 pip install -r mcp_server/requirements.txt # 注册到 Claude Code claude mcp add shieldscan -- python mcp_server/shieldscan_server.py ``` 可用工具包括：`scan_file`、`scan_code`、`scan_directory`、`get_patterns`。 如果您在 Claude Code 中打开此项目，MCP 服务器将通过 `.claude/settings.json` 自动注册。 ### /security-scan 技能 这是一个斜杠命令，会优先运行 ShieldScan，随后由 Claude 执行深度的语义分析： ``` # 在 Claude Code 中 /security-scan examples/VulnerableVault.sol /security-scan contracts/ ``` 该技能将 ShieldScan 的 14 种正则表达式模式与针对业务逻辑、跨函数数据流、经济攻击向量和治理风险的 AI 分析相结合。每项发现都会被标记为 `[CONFIRMED]`（已确认）、`[AI-DISCOVERED]`（AI 发现）或被判定为误报而剔除。 ### 混合 EVMbench Agent 这是一个两阶段运行的 EVMbench agent，首先使用 ShieldScan 进行快速预扫描，然后利用 Claude Code 进行深度分析： ``` # 复制到 EVMbench cp -r benchmark/hybrid_agent/ /evmbench/agents/hybrid_shieldscan/ cp src/scanner.py /evmbench/agents/hybrid_shieldscan/ # 使用 EVMbench 运行 # --agent hybrid_shieldscan ``` 这种混合方法将 ShieldScan 的发现作为“提示”提供给 Claude，指向潜在的易受攻击点。Claude 随后会验证正则表达式的发现，并挖掘出额外的逻辑层面漏洞，从而显著提高精确率和召回率。 ## 局限性 ShieldScan 是一款**静态模式匹配**扫描器。它不能替代以下工具： - 专业的手动审计 - 符号执行工具 (Mythril、Manticore) - 模糊测试工具 (Echidna、Foundry) - 形式化验证 请将 ShieldScan 用作**第一道防线**，随后结合专业工具对生产级合约进行审计。 ## 许可证 MIT 许可证 —— 可自由使用、修改和分发。 ## 致谢 - [SWC Registry](https://swcregistry.io) — 智能合约弱点分类 - [OpenZeppelin](https://openzeppelin.com) — 安全最佳实践 - [Trail of Bits](https://www.trailofbits.com) — Slither 及安全研究 - [Paradigm](https://paradigm.xyz) — EVMbench 智能合约安全基准测试 - [Claude Code](https://claude.com/claude-code) — 通过 MCP 实现的 AI 驱动代码分析 - [The Covenant of Humanistic Technologies](https://manifest.human.tech) — 普遍安全原则

为 Web3 社区用 🛡️ 精心构建
_{安全是一项公共福利。}

标签：CISA项目, Claude Code集成, EVM兼容链, MCP Server, Python, React, Solidity, SWC Registry, Syscalls, Web3安全, 主机安全, 人工智能辅助分析, 代码安全检测, 加密, 区块链安全, 去中心化应用安全, 开源安全工具, 无后门, 智能合约审计, 智能合约漏洞, 漏洞扫描器, 网络安全, 聊天机器人, 逆向工具, 逆向工程平台, 重入攻击检测, 错误基检测, 隐私保护, 静态代码分析