audit-prep-assistant

审计准备助手

用途

使用 Trail of Bits 的清单帮助为安全审查做准备。准备充分的代码库能让审查过程更顺畅、更有效。

适用时机：安全审计前 1–2 周

---

准备流程

第 1 步：设定审查目标

帮助明确你希望通过审查达成什么目标：

关键问题：

• 你希望达到怎样的整体安全水平？
• 哪些方面最令你担忧？
  • 以往审计发现的问题？
  • 复杂组件？
  • 脆弱部分？
• 对你的项目来说，最坏的情况是什么？

将目标整理成文档，与评估团队分享。

---

第 2 步：解决简单问题

运行静态分析并帮助修复容易解决的问题：

运行静态分析：

对于 Solidity：

slither . --exclude-dependencies

对于 Rust：

dylint --all

对于 Go：

golangci-lint run

对于 Go/Rust/C++：

# CodeQL and Semgrep checks

然后我会：

• 对所有发现的问题进行分类
• 帮助修复简单问题
• 记录已接受的风险

提高测试覆盖率：

• 分析当前覆盖率
• 找出未经测试的代码
• 建议新增测试
• 运行完整测试套件

移除死代码：

• 查找未使用的函数/变量
• 找出未使用的库
• 定位过时功能
• 建议清理

目标：获得干净的静态分析报告、较高的测试覆盖率，并尽量减少死代码

---

第 3 步：确保代码易于访问

帮助让代码清晰易懂、便于审查：

提供详细的文件列表：

• 列出所有纳入审查范围的文件
• 标记不在范围内的文件
• 说明文件夹结构
• 记录依赖项

创建构建说明：

• 编写分步设置指南
• 在全新环境中测试
• 记录依赖项及其版本
• 验证构建成功

冻结稳定版本：

• 确定审查所用的 commit 哈希
• 创建专用分支
• 标记发布版本
• 锁定依赖项

识别样板代码：

• 标记复制或派生的代码
• 突出显示你的修改
• 记录第三方代码
• 将审查重点放在你的代码上

---

第 4 步：生成文档

帮助创建文档：

流程图和时序图：

• 梳理主要工作流
• 展示组件之间的关系
• 可视化数据流
• 找出关键路径

用户故事：

• 定义用户角色
• 记录用例
• 说明交互方式
• 明确预期

链上/链下假设：

• 数据验证流程
• 预言机信息
• 跨链桥假设
• 信任边界

参与方和权限：

• 列出所有参与方
• 记录角色
• 定义权限
• 梳理访问控制

面向外部开发者的文档：

• 将文档链接到代码
• 保持同步
• 说明架构
• 记录 API

函数文档：

• 系统和函数不变量
• 参数范围（最小值/最大值）
• 算术公式和精度损失
• 复杂逻辑说明
• Solidity 的 NatSpec

术语表：

• 定义领域术语
• 解释缩略语
• 统一术语
• 说明业务逻辑概念

视频讲解（可选）：

• 复杂工作流
• 关注领域
• 架构概览

---

工作方式

调用时，我会：

1. 帮助设定审查目标 - 询问你的顾虑并记录下来
2. 运行静态分析 - 根据你的平台运行适当的工具
3. 分析测试覆盖率 - 找出差距并建议改进
4. 查找死代码 - 搜索未使用的代码和库
5. 检查可访问性 - 检查构建说明和范围是否清晰
6. 生成文档 - 创建流程图、用户故事和术语表
7. 创建准备清单 - 跟踪已完成和待完成的事项

会根据以下情况进行调整：

• 你的平台（Solidity、Rust、Go 等）
• 可用工具
• 现有文档
• 审查时间安排

---

合理化借口（请勿跳过）

合理化借口	错误原因	必须采取的行动
“README 已涵盖设置，无需详细的构建说明”	README 假定了审计人员并不具备的背景知识	在全新环境中测试构建，并记录每个依赖项的版本
“静态分析已经运行过，无需再次运行”	自上次运行以来代码库已有更改	执行静态分析工具，生成最新报告
“测试覆盖率看起来还不错”	“看起来还不错”并不是经过衡量的覆盖率	运行覆盖率工具，找出具体未测试的代码路径
“没多少死代码需要担心”	手动审查时很难发现死代码	使用自动检测工具查找未使用的函数和变量
“架构很简单，不需要图表”	文字描述无法体现视觉模式	生成实际的流程图和时序图
“审计前冻结版本即可”	最后才冻结版本会导致仓促交接	现在就确定并记录提交哈希，创建专用分支
“术语不言自明”	领域知识并非人人具备	创建全面的术语表，收录所有领域专用术语
“我稍后再做这一步”	各步骤环环相扣，跳过会造成缺漏	按顺序完成全部 4 个步骤，并使用清单跟踪进度

---

输出示例

准备工作完成后，你将获得以下具体交付成果：

=== AUDIT PREP PACKAGE ===

Project: DeFi DEX Protocol
Audit Date: March 15, 2024
Preparation Status: Complete

---

## REVIEW GOALS DOCUMENT

Security Objectives:
- Verify economic security of liquidity pool swaps
- Validate oracle manipulation resistance
- Assess flash loan attack vectors

Areas of Concern:
1. Complex AMM pricing calculation (src/SwapRouter.sol:89-156)
2. Multi-hop swap routing logic (src/Router.sol)
3. Oracle price aggregation (src/PriceOracle.sol:45-78)

Worst-Case Scenario:
- Flash loan attack drains liquidity pools via oracle manipulation

Questions for Auditors:
- Can the AMM pricing model produce negative slippage under edge cases?
- Is the slippage protection sufficient to prevent sandwich attacks?
- How resilient is the system to temporary oracle failures?

---

## STATIC ANALYSIS REPORT

Slither Scan Results:
✓ High: 0 issues
✓ Medium: 0 issues
⚠ Low: 2 issues (triaged - documented in TRIAGE.md)
ℹ Info: 5 issues (code style, acceptable)

Tool: slither . --exclude-dependencies
Date: March 1, 2024
Status: CLEAN (all critical issues resolved)

---

## TEST COVERAGE REPORT

Overall Coverage: 94%
- Statements: 1,245 / 1,321 (94%)
- Branches: 456 / 498 (92%)
- Functions: 89 / 92 (97%)

Uncovered Areas:
- Emergency pause admin functions (tested manually)
- Governance migration path (one-time use)

Command: forge coverage
Status: EXCELLENT

---

## CODE SCOPE

In-Scope Files (8):
✓ src/SwapRouter.sol (456 lines)
✓ src/LiquidityPool.sol (234 lines)
✓ src/PairFactory.sol (389 lines)
✓ src/PriceOracle.sol (167 lines)
✓ src/LiquidityManager.sol (298 lines)
✓ src/Governance.sol (201 lines)
✓ src/FlashLoan.sol (145 lines)
✓ src/RewardsDistributor.sol (178 lines)

Out-of-Scope:
- lib/ (OpenZeppelin, external dependencies)
- test/ (test contracts)
- scripts/ (deployment scripts)

Total In-Scope: 2,068 lines of Solidity

---

## BUILD INSTRUCTIONS

Prerequisites:
- Foundry 0.2.0+
- Node.js 18+
- Git

Setup:
```bash
git clone https://github.com/project/repo.git
cd repo
git checkout audit-march-2024  # Frozen branch
forge install
forge build
forge test

验证： ✓ 构建成功，无错误 ✓ 全部 127 项测试通过 ✓ 编译器未发出警告

---

文档

生成的文件： ✓ ARCHITECTURE.md - 含图表的系统概览 ✓ USER_STORIES.md - 12 个用户交互流程 ✓ GLOSSARY.md - 定义了 34 个领域术语 ✓ docs/diagrams/contract-interactions.png ✓ docs/diagrams/swap-flow.png ✓ docs/diagrams/state-machine.png

NatSpec 覆盖率：100% 的公共函数

---

部署信息

网络：Ethereum Mainnet 提交：abc123def456（audit-march-2024 分支） 已部署的合约：

• SwapRouter：0x1234...
• PriceOracle：0x5678... [... 等]

---

软件包已准备好接受审计 ✓ 下一步：分享给 Trail of Bits 评估团队

---

## What You'll Get

**Review Goals Document**:
- Security objectives
- Areas of concern
- Worst-case scenarios
- Questions for auditors

**Clean Codebase**:
- Triaged static analysis (or clean report)
- High test coverage
- No dead code
- Clear scope

**Accessibility Package**:
- File list with scope
- Build instructions
- Frozen commit/branch
- Boilerplate identified

**Documentation Suite**:
- Flowcharts and diagrams
- User stories
- Architecture docs
- Actor/privilege map
- Inline code comments
- Glossary
- Video walkthroughs (if created)

**Audit Prep Checklist**:
- [ ] Review goals documented
- [ ] Static analysis clean/triaged
- [ ] Test coverage >80%
- [ ] Dead code removed
- [ ] Build instructions verified
- [ ] Stable version frozen
- [ ] Flowcharts created
- [ ] User stories documented
- [ ] Assumptions documented
- [ ] Actors/privileges listed
- [ ] Function docs complete
- [ ] Glossary created

---

## Timeline

**2 weeks before audit**:
- Set review goals
- Run static analysis
- Start fixing issues

**1 week before audit**:
- Increase test coverage
- Remove dead code
- Freeze stable version
- Start documentation

**Few days before audit**:
- Complete documentation
- Verify build instructions
- Create final checklist
- Send package to auditors

---

## Ready to Prep

Let me know when you're ready and I'll help you prepare for your security review!