scv-scan

智能合约漏洞审计

采用四阶段方法，对 Solidity 代码库进行系统化漏洞审计，在全面性与效率之间取得平衡。

适用场景

• 在部署前审计 Solidity 代码库中的安全漏洞
• 检查智能合约代码中常见的攻击模式（重入、溢出、访问控制等）
• 对整个 Solidity 项目进行结构化漏洞扫描
• 修改后验证合约是否遵循安全最佳实践

不适用场景

• 审计非 Solidity 智能合约（Vyper、Rust/Anchor、Move）——这些模式特定于 Solidity
• 检查链下代码（JavaScript、TypeScript 后端）——应改用通用安全审查
• 用户只需要 Gas 优化或代码风格反馈时——本工具专注于可利用的漏洞
• 进行不变量的形式化验证时——应改用 Certora、Halmos 或 Echidna 等工具

应拒绝的理由

• “编译器版本 >=0.8.0，所以不可能溢出”——unchecked 代码块、汇编和类型向下转换仍会发生回绕
• “它使用了 OpenZeppelin，所以很安全”——集成错误、不正确的继承顺序，以及自定义函数缺少修饰符都很常见
• “该函数是内部函数，所以无法被利用”——从外部入口点调用的内部函数会继承调用者的上下文
• “没有涉及 ETH，所以不适用重入攻击”——ERC721 _safeMint、ERC1155 安全转账和 ERC777 钩子都会触发回调
• “合约可升级，所以以后可以修复”——未使用 initializer 修饰符的 initialize() 本身就是严重漏洞

参考资料结构

references/
  CHEATSHEET.md          # Condensed pattern reference — always read first
  reentrancy.md          # Full reference files — read selectively in Phase 3
  overflow-underflow.md
  ...

references/ 中的每个完整参考文件都包含以下部分：

• 前置条件 — 漏洞存在所需满足的条件
• 易受攻击模式 — 附带注释的 Solidity 反模式
• 检测启发式 — 用于确认漏洞的逐步推理过程
• 误报 — 模式存在但无法被利用的情形
• 修复方法 — 如何修复

审计工作流

阶段 1：加载速查表

在接触任何 Solidity 文件之前，完整阅读 {baseDir}/skills/scv-scan/references/CHEATSHEET.md。

该文件为每种已知漏洞类型提供了精简条目：名称、需要检查的内容（语法和语义）以及默认严重程度。熟记这些模式——它们是扫描阶段的检测范围。此时不要阅读任何完整参考文件。

阶段 2：扫描代码库

对代码库进行两轮互补检查。

检查 A：语法 grep 扫描

使用 grep 或 ripgrep 搜索速查表“可用 grep 搜索的关键词”中列出的触发模式。

对每个匹配项，记录：文件、行号、匹配模式和疑似漏洞类型。

检查 B：结构／语义分析

此轮用于发现没有可靠 grep 特征的漏洞。通读代码库，查找与速查表所述相关逻辑相似的内容。

对本轮发现的每个问题，记录：文件、行号、问题描述和疑似漏洞类型。

汇总候选列表

合并检查 A 和检查 B 的结果，并去重，形成候选列表。每个条目应如下所示：

- File: `path/to/file.sol` L{start}-L{end}
- Suspected: [vulnerability-name] (from CHEATSHEET.md)
- Evidence: [brief description of what was found]

阶段 3：选择性深入验证

对于列表中的每个候选项：

1. 阅读可疑漏洞类型对应的完整参考文件（例如，{baseDir}/skills/scv-scan/references/reentrancy.md）。现在阅读——不要提前阅读。
2. 根据实际代码逐步检查每条检测启发式规则。务必准确——追踪变量值、检查修饰符、跟进调用链。
3. 检查每项误报条件。如果符合任何误报条件，就舍弃该发现并说明原因。
4. 交叉参照：同一代码位置可能匹配多种漏洞类型。如果速查表将同一模式映射到多个参考文件，请分别阅读并验证。
5. **确认或舍弃。**只有已确认的发现才写入最终报告。

阶段 4：报告

对于每项已确认的发现，输出：

### [Vulnerability Name]

**File:** `path/to/file.sol` L{start}-L{end}
**Severity:** Critical | High | Medium | Low | Informational

**Description:** What is vulnerable and why, in 1-3 sentences.

**Code:**
```solidity
// The vulnerable code snippet

**建议：**给出具体修复方案，并参照参考文件的修复部分。

After all findings, include a summary section:

摘要

严重程度	数量
严重	N
高	N
中	N
低	N
信息	N

Write the final report to `scv-scan.md`.

## Severity Guidelines

- **Critical**: Direct loss of funds, unauthorized fund extraction, permanent freezing of funds
- **High**: Conditional fund loss, access control bypass, state corruption exploitable under realistic conditions
- **Medium**: Unlikely fund loss, griefing attacks, DoS on non-critical paths, value leak under edge conditions
- **Low**: Best practice violations, gas inefficiency, code quality issues with no direct exploit path
- **Informational**: Unused variables, style issues, documentation gaps

## Key Principles

- **Cheatsheet first, references on-demand.** Never read all full reference files upfront. The cheatsheet gives you ambient awareness; full references are for validation only.
- **Semantic > syntactic.** The hardest bugs don't grep. Cross-function reentrancy, missing access control, incorrect inheritance — these require reading and reasoning, not pattern matching.
- **Trace across boundaries.** Follow state across function calls, contract calls, and inheritance chains. Hidden external calls (safe mint/transfer hooks, ERC-777 callbacks) are as dangerous as explicit `.call()`.
- **One location, multiple bugs.** A single line can be vulnerable to reentrancy AND unchecked return value. Check all applicable references.
- **Version matters.** Always check `pragma solidity` — many vulnerabilities are version-dependent (e.g., overflow is checked by default in >=0.8.0).
- **False positives are noise.** Be rigorous about checking false positive conditions. A shorter report with high-confidence findings is more valuable than a long one padded with maybes.