kcolbchain/audit-checklist

# audit-checklist 可执行智能合约审计清单 — 用于 Foundry 的现成测试模板，涵盖常见漏洞类别。由 [kcolbchain](https://kcolbchain.com) 创建（始于 2015）。 ## 存在的原因 大多数审计清单是 PDF 格式，而这份是代码。将其导入你的 Foundry 项目并运行 `forge test` — 它会针对你的合约检查重入、访问控制缺口、预言机操纵、升级风险以及闪电贷向量。 基于自 2019 年以来的真实审计模式。 ## 快速开始 ``` # 如果尚未安装 Foundry，请安装 Foundry curl -L https://foundry.paradigm.xyz | bash foundryup # 创建新的 Foundry 项目（或使用现有项目） forge init my-audit-project cd my-audit-project # 安装 audit-checklist forge install kcolbchain/audit-checklist ``` ### 你的第一次审计 — 5 分钟教程 本教程将从头到尾针对一个**故意存在漏洞的合约**进行审计（该合约随仓库一起发布：`VulnerableVault.sol`）。完成之后，你将运行一次真实的审计并看到每个检查标记出的真实漏洞。 #### 1. 安装 ``` forge init my-audit-project && cd my-audit-project forge install kcolbchain/audit-checklist ``` 此时 `remappings.txt` 应包含：`audit-checklist/=lib/audit-checklist/src/`。 #### 2. 编写审计 harness 创建 `test/VaultAudit.t.sol` —— 每个检查都需要一个 `setUp()`，在其中部署目标合约并让 `targetContract` 指向它，以及任何协议特定的钩子（例如如何存款、要调用哪个函数取款）。 检查类继承自 `forge-std/Test`，因此你可以使用所有常规的 Foundry 辅助函数。 ``` // SPDX-License-Identifier: MIT pragma solidity ^0.8.24; import {ReentrancyCheck} from "audit-checklist/checks/ReentrancyCheck.sol"; import {AccessControlCheck} from "audit-checklist/checks/AccessControlCheck.sol"; import {VulnerableVault} from "audit-checklist/examples/VulnerableVault.sol"; contract VaultReentrancyAudit is ReentrancyCheck { VulnerableVault vault; function setUp() public { vault = new VulnerableVault(); vault.initialize(); targetContract = address(vault); } // Tell ReentrancyCheck how to trigger a withdraw + how to seed deposits. function getWithdrawCalldata() internal pure override returns (bytes memory) { return abi.encodeWithSignature("withdraw()"); } function performDeposit(address depositor, uint256 amount) internal override { vm.prank(depositor); vault.deposit{value: amount}(); } } ``` 请参考本仓库中的 `test/Example.t.sol`，其中对 `AccessControlCheck`、`OracleCheck`、`UpgradeCheck` 和 `FlashLoanCheck` 使用了相同的模式。 #### 3. 运行检查 ``` forge test -vv ``` 针对 `VulnerableVault` 的预期输出如下： ``` Running 1 test for test/VaultAudit.t.sol:VaultReentrancyAudit [FAIL. Reason: Reentrancy detected: balance drained by recursive call] test_Reentrancy_WithdrawDoesNotFollowCEI() ``` 这正是工具**按设计工作**的表现 —— 测试失败意味着某个检查发现了漏洞。对于你自己的合约，干净的 `forge test` 运行表示没有匹配到任何模式；失败则是一条需要调查的漏洞线索。 #### 4. 解读结果 | 结果 | 含义 | |------|------| | ✅ 所有检查通过 | 未触发本清单中的任何模式。仍需手动审计。 | | ❌ 某项检查失败 | 匹配到了已知的不良模式。请阅读失败原因并手动验证。 | | ⚠️ `setUp` 期间测试回滚 | 你的钩子（例如 `performDeposit`）有误 — 检查实际上并未运行。 | #### 5. 浏览内置示例 ``` forge test --match-contract Example -vvv ``` 此命令会对 `VulnerableVault` 运行所有检查，该合约包含四个**故意设计的漏洞**（缺少初始化保护、`withdraw` 中的重入、缺少 `emergencyWithdraw` 的访问控制、现货价格预言机问题）。每个检查都应失败，从而确认你的安装正常，并为你提供真实失败样式的参考。 ### 运行特定检查 ``` // Run only reentrancy checks import {ReentrancyCheck} from "audit-checklist/checks/ReentrancyCheck.sol"; contract MyAudit is ReentrancyCheck { ... } // Run only access control checks import {AccessControlCheck} from "audit-checklist/checks/AccessControlCheck.sol"; contract MyAudit is AccessControlCheck { ... } // Run all checks import {ReentrancyCheck, AccessControlCheck, OracleCheck, UpgradeCheck, FlashLoanCheck} from "audit-checklist/checks/ReentrancyCheck.sol"; contract MyAudit is ReentrancyCheck, AccessControlCheck, OracleCheck, UpgradeCheck, FlashLoanCheck { ... } ``` ### 审计漏洞合约示例 本仓库包含 `VulnerableVault.sol`，用于演示这些检查如何工作： ``` # 运行示例审计 forge test --match-contract Example -vvv ``` 此命令会对故意设计为脆弱的演示合约运行所有检查，展示每个测试捕获的问题。 ## 在浏览器中浏览检查 一个交互式探索器位于 [`web/`](web/) —— 每个检查一页，包含检测逻辑、所需钩子以及它在 `VulnerableVault` 中标记的真实漏洞。 你可以通过以下方式运行它： - 本地运行：`python3 -m http.server -d web 8080` - 或直接打开：`[在线演示](web/index.html)` ## 覆盖的漏洞类别 | 检查 | 检测内容 | |------|----------| | `ReentrancyCheck` | 检查效应与交互顺序违规、通过回调的跨函数重入 | | `AccessControlCheck` | 未受保护的管理函数、未保护的初始化器、缺失的角色检查 | | `OracleCheck` | 可操纵的现货价格读取、缺少 TWAP、单源预言机 | | `UpgradeCheck` | 代理中的存储布局冲突、未初始化的实现合约 | | `FlashLoanCheck` | 易受闪电贷价格/状态操纵的函数 | ## 架构 ``` src/ ├── ChecklistBase.sol — Base contract with shared test helpers ├── checks/ │ ├── ReentrancyCheck.sol — Reentrancy detection tests │ ├── AccessControlCheck.sol — Access control verification │ ├── OracleCheck.sol — Oracle manipulation checks │ ├── UpgradeCheck.sol — Proxy upgrade safety │ └── FlashLoanCheck.sol — Flash loan resistance ├── examples/ │ └── VulnerableVault.sol — Intentionally vulnerable demo contract test/ └── Example.t.sol — Full example audit against VulnerableVault ``` ## 许可证 MIT ## 贡献 欢迎提出问题和 PR。如果你发现了未被覆盖的漏洞模式，请打开议题或提交一个检查。

标签：DeFi安全, Foundry测试模板, kcolbchain, SOC Prime, Solidity安全, 区块链安全, 升级风险, 可执行审计清单, 合约审计, 安全模板, 对称加密, 开发工具, 智能合约审计, 检查列表, 自动化审计, 访问控制漏洞, 重入漏洞, 闪电贷向量, 预言机操纵