2026年3月2日
多年来，在审计智能合约和复杂的去中心化系统时，我们认识到发现漏洞只完成了一半工作。如何处理这些发现，如何传达它们，以及如何指导团队修复它们，才是真正产生影响的地方。
一份好的审计报告不仅仅是列出错误。它讲述了系统如何运作、在哪里出现故障以及如何修复的故事。它成为勤勉的记录、开发人员的参考，并常常是项目与社区之间信任的基础。
在这篇博文中，我们想分享从撰写、修订和重新思考审计报告中吸取的实践经验，有些来自经验，有些来自惨痛的错误。
理解目的
审计报告是审计的唯一永久痕迹。
代码可能会改变。团队可能会轮换。但报告会保留下来。审计报告不仅仅是一份交付物。它是一份技术文档，需要清晰地向几类读者传达信息：
- 将实施修复的核心开发团队
- 需要了解风险状况的利益相关者和投资者
- 有时，是未来可能在你的工作基础上继续的其他审计师
我们曾见过审计报告被用于从募资演示文稿到紧急事件审查的各种场合。这意味着报告必须清晰、诚实且自成体系。它不仅应记录发现的问题，还应包含方法论、范围、设计假设，以及任何风险被推迟或承认的领域。
我们撰写的最佳报告是那些我们能在数月后将其交出，并且仍然相信首次阅读它的人能够完全理解系统、漏洞以及每个严重性标签背后的逻辑。
报告需要做很多事情：告知、说服、赋能并持续存在。
那么，我们如何撰写一份能兼顾这三者的报告呢？
从结构开始：优秀报告的骨架
一份混乱或无序的报告会冲淡即使是最敏锐的发现。随着时间的推移，我们形成了一种平衡清晰度和深度的结构：
- 执行摘要
- 范围和方法论
- 系统概述
- 发现和建议
- 最佳实践与建议
- 审计后开发人员回应（可选）
- 附录（工具、哈希、提交ID等）
让我们逐一分解这些内容。
优秀报告的流程
一份全面的审计报告讲述了一个故事。它从审查了什么开始，解释了系统如何工作，介绍了方法论，并列出了发现的漏洞。它还反映了你的思维过程和勤勉。客户阅读后，不仅应该对代码状态感到自信，还应该对你分析的严谨性感到自信。
首先是简短的执行摘要。这不是泛泛之谈，而是一个真实的快照。如果在一个相对成熟的代码库中发现了多个高严重性错误，直接说明。如果协议相当安全但可以通过 gas 优化和设计清理而受益，也在此处提及。
接下来，概述范围和方法论。详细说明你审查了什么（合约、提交哈希、部署地址）以及没有审查什么。这既保护了你，也保护了客户，避免未来产生误解。我们已经学会了在这里痛苦地明确。有一次，客户假设我们审计了一个完全超出范围的代理实现。缺乏明确性导致生产事故期间的混乱。再也！不会了！
在描述方法论时，尽量不要只提及工具名称。解释我使用了什么（手动审查、Slither、使用 Echidna 进行 Fuzzing 等）以及为什么。每种技术都有其优势。如果你手动跟踪了跨多个合约的重入路径，或者在分叉的 mainnet 环境中模拟了极端情况交互，请记录下来。目的是帮助读者理解审查的深度和广度。
捕捉系统精髓
一份好的审计报告证明你理解了你刚刚审计的系统。这意味着要超越代码语法，深入研究协议逻辑。
这一部分通常是智力要求最高的。它要求你将实现抽象为心智模型，包括合约如何交互，信任边界在哪里，假设是什么，以及状态转换如何发生。
如果项目有创新机制，例如 rebase 代币、L2 消息中继或可升级代理，请指出来。使用图表。即使是 ASCII 图也有帮助。
“该协议包括一个质押合约、一个奖励分发器和一个跨链桥。资金在 L1 上锁定，通过一个由 5 名签名者组成的预言机仲裁团在 L2 上释放。”
我们发现，撰写这一部分会迫使你仔细检查自己的理解，有时，隐藏的风险就是在这里浮出水面的。
一位客户曾告诉我们：“我觉得你们的审计更值得信赖，因为很明显你们理解我们的业务逻辑。”这句话一直萦绕在我们心头。
精确记录发现
这是审计报告的跳动的心脏：发现。
每个问题都需要一个标题和一个严重性标签之外的更多内容。它应该包括对问题是什么、为什么重要、如何重现以及应该如何处理的清晰解释。
我们很早就学会了不要急于完成这一部分。对于每个漏洞，问问自己：六个月后，如果读者没有你的电话解释，他们会理解吗？这就是标准。
严重性评级
- 危急 – 可能导致资金损失、永久锁定或未经授权的访问。
- 高 – 严重错误，但有限制或需要特定条件。
- 中 – 可能导致意外行为或中等程度的财务风险。
- 低 – 不直接影响安全性，但表明设计不良。
- 信息 – gas 优化、代码清晰度或偏离最佳实践。
每个问题应包含：
- 标题（例如，“EmergencyWithdraw 中的访问控制不正确”）
- 严重性（并附有理由）
- 描述（问题是什么以及为什么重要）
- 重现步骤或 PoC
- 修复建议
- 状态（开放 / 已解决 / 已确认）
示例：
标题：无边界循环可能导致 Out-of-Gas 回滚
严重性：中
描述：withdrawAll() 函数迭代所有用户存款时没有上限。在压力测试中，这导致由于区块 gas 限制而发生回滚。
修复：考虑批量提款或限制每次调用的迭代次数。
不要假设，要解释
当你解释某事为什么是一个漏洞，而不仅仅是它是一个漏洞时，客户会很欣赏。
上下文决定一切。
描述上下文至关重要。代理模式中的存储冲突不仅仅是一个 bug，它是一个具有下游影响的设计缺陷。轻微的重入向量可能只有在特定流动性条件下才能被利用。这种细微差别很重要。没有它，你就有可能夸大或低估现实世界的风险。
严重性分级也需要判断。不要只使用检查清单。考虑可利用性、影响和修复的便捷性。在一个时间敏感的预售合约中，一个中等严重性的 bug 可能比一个已暂停或已弃用模块中的高严重性问题更紧迫。
同样重要的是语气。避免危言耸听或傲慢。目标是告知，而不是羞辱。当报告感觉像是一种合作，而不是指责时，开发人员更容易接受。
超越漏洞：增加价值
即使代码库是安全的，也几乎总有一些可以改进的地方：gas 效率低下、冗余检查、非标准模式或文档不足的部分。这一部分并非强制性，但尽量将其包含在每份报告中。你可以在这里提及：
tx.origin 的误用- 可见性修饰符的糟糕使用
- 代码重复
- 未使用的变量或事件
- 缺失的 NatSpec 文档
这表明你不仅关心发现 bug，还关心代码质量。
如果可能，我们会添加一个后续部分，跟踪问题是否已解决。将每个发现与客户的回应（已修复、已确认或不修复）进行映射，增加了透明度，并表明审计不仅仅是走过场。
清晰地撰写
技术准确性是不可协商的，但清晰度才是报告真正有用的关键。
为博士生撰写和为从业者撰写是不同的。最好的审计报告是那些资深工程师无需交叉引用三篇学术论文就能采取行动的报告。
避免为了使用行话而使用行话。你不是为了打动其他审计师，你是在帮助开发人员修复他们的代码，并让用户安心。
不要写：
“访问控制逻辑容易受到因异步函数解析在重入上下文中对可变状态进行非原子更新而导致的竞争条件。”
只需说：
“该函数可以在状态完全更新之前被重入，允许攻击者利用不一致的逻辑。”
保持清晰、简洁和正确。
此外，报告应易于阅读。一致的标题、问题编号、内联代码片段和超链接引用都使读者更容易理解。并且始终包含附录、工具版本、提交哈希、自定义测试脚本，以便可以验证或复现工作。
应避免的常见错误
- 报告中充斥着低影响问题 – 优先考虑重要事项。
- 模糊的建议 – “使用更安全的模式”对任何人都没有帮助。
- 忽略 gas 使用或测试覆盖率见解 – 这些是审计质量的一部分。
- 忽略提及不在范围内的内容 – 始终指明这一点。
- 不进行报告版本控制 – 始终包含报告日期和版本。我们曾遇到过报告数月后被修改，却无法追踪差异的情况。
最终思考
撰写审计报告并非光鲜亮丽。但它可能是影响最大的。一份清晰、彻底的报告可以防止数百万的损失。一份马虎的报告可能制造虚假的安全感，甚至更糟，导致漏洞被遗漏。
在这个代码即法律、漏洞利用迅速蔓延的领域，审计报告往往是勤勉的唯一书面记录。它反映了你的思维过程、你的标准和你的信誉。
所以，花时间认真对待。因为这很重要。
