如何撰写全面的审计报告：实战经验与教训 – ImmuneBytes

2026年2月24日

多年来，在审计智能合约和复杂的去中心化系统时，我们认识到发现漏洞只完成了一半的工作。如何处理这些发现，如何沟通它们，以及如何指导团队修复它们，这才是真正发挥影响力的地方。

一份好的审计报告不仅仅是列出bug。它讲述了系统如何运作，在哪里出现故障，以及如何修复。它成为勤勉的记录，开发人员的参考，并且常常是项目与社区之间信任的基础。

在这篇博客中，我们希望分享从撰写、修订和重新思考审计报告中吸取到的实践经验，其中一些来自经验，另一些则来自惨痛的教训。

理解目的

审计报告是审计的唯一永久痕迹。

代码可能会改变。团队可能会轮换。但报告会留存。审计报告不仅仅是一个可交付物。它是一份技术文档，需要清晰地传达给多种类型的读者：

• 将实施修复的核心开发团队
• 需要了解风险状况的利益相关者和投资者
• 有时，还有未来可能在你的工作基础上进行构建的其他审计人员

我们见过审计报告被用于从募资演示文稿到紧急事件复盘的各种场合。这意味着报告必须清晰、诚实且独立。它不仅应捕捉发现的问题，还应包含方法论、范围、设计假设以及任何风险被推迟或承认的领域。

我们撰写过的最好的报告是那些几个月后我们仍然可以交付，并且自信地认为首次阅读它的人能够完全理解系统、漏洞以及每个严重性标签背后的逻辑的报告。

报告必须完成很多任务：告知、说服、赋能并持续存在。

那么，我们如何撰写一份能够兼顾这三点的报告呢？

从结构开始：优秀报告的骨架

一份杂乱无章的报告会稀释即使是最敏锐的发现。随着时间的推移，我们形成了一个兼顾清晰度和深度的结构：

1. 执行摘要
2. 范围与方法论
3. 系统概述
4. 发现与建议
   • 按严重性分类
   • 链接到具体的合约/行
5. 最佳实践与建议
6. 审计后开发者回应（可选）
7. 附录（工具、哈希、提交ID等）

让我们分解这些部分。

优秀报告的流程

一份全面的审计报告讲述了一个故事。它从审查了什么开始，解释了系统如何工作，阐述了方法论，并列出了发现的漏洞。它也反映了你的思维过程和勤勉。客户应该能够阅读它，并对他们代码的状态以及你分析的严谨性充满信心。

从一份简短的执行摘要开始。这并非无关紧要，而是一个真实的快照。如果你在一个相对成熟的代码库中发现了多个高严重性bug，直言不讳。如果协议相当安全，但可以从gas优化和设计清理中受益，也在这里说明。

接下来，概述范围和方法论。详细说明你审查了什么（合约、提交哈希、部署地址）以及没有审查什么。这既保护了你，也保护了客户，避免了未来的误解。我们已经学会在这里痛苦地明确。有一次，一个客户假设我们审计了一个完全超出范围的代理实现。缺乏明确性导致了生产事故期间的混乱。再也不会了！

在描述方法论时，尽量不要只提及工具名称。解释你使用了什么（手动审查、Slither、使用Echidna进行模糊测试等）以及原因。每种技术都有其优势。如果你手动跟踪了跨多个合约的重入路径，或者在分叉的主网环境中模拟了边缘情况交互，请记录下来。目的是帮助读者理解审查的深度和广度。

捕捉系统精髓

一份好的审计报告证明你理解了你刚刚审计的系统。这意味着要超越代码语法，深入到协议逻辑。

这一部分通常是智力上要求最高的部分。它要求你将实现抽象成一个心智模型，包括合约如何交互、信任边界在哪里、假设是什么以及状态转换如何发生。

如果项目有创新的机制，如rebase代币、L2消息中继或可升级代理，请指出这些。使用图表。即使是ASCII图表也有帮助。

“该协议包括一个质押合约、一个奖励分发器和一个跨链桥。资金在L1上锁定，并通过由5个签名者组成的预言机仲裁在L2上释放。”

我们发现撰写这一部分会迫使你仔细检查自己的理解，有时，隐藏的风险也正是在这里浮现的。

一位客户曾告诉我们：“我对你们的审计更有信心，因为很明显你们理解我们的业务逻辑。”这句话一直伴随着我们。

精准记录发现

这是审计报告跳动的心脏：发现。

每个问题都需要不仅仅是标题和严重性标签。它应该包括对问题是什么、为什么重要、如何重现以及应该如何处理的清晰解释。

我们很早就认识到不能急于完成这一部分。对于每个漏洞，问问自己：六个月后阅读这份报告的人，在没有你电话解释的情况下，能否理解它？这就是标准。

严重性评级

• 严重 – 可能导致资金损失、永久锁定或未经授权的访问。
• 高 – 严重bug，但有局限性或需要特定条件。
• 中 – 可能导致意外行为或中等财务风险。
• 低 – 不直接影响安全性，但表明设计不佳。
• 信息 – Gas优化、代码清晰度或偏离最佳实践。

每个问题应包含：

• 标题（例如，“EmergencyWithdraw 中不正确的访问控制”）
• 严重性（附理由）
• 描述（问题是什么以及为什么重要）
• 重现步骤或概念验证
• 补救建议
• 状态（开放/已解决/已确认）

示例：

标题： 无边界循环可能导致Gas耗尽回滚

严重性： 中

描述： withdrawAll() 函数在没有上限的情况下迭代所有用户存款。在压力测试中，这由于区块gas限制导致了回滚。

补救措施： 考虑分批提款或限制每次调用的迭代次数。

不要假设，要解释

当你解释某个事物为什么是漏洞，而不仅仅是它是一个漏洞时，客户会很欣赏。

语境决定一切。

描述语境至关重要。代理模式中的存储冲突不仅仅是一个bug，它是一个具有下游影响的设计缺陷。一个轻微的重入向量可能只在特定流动性条件下才能被利用。这种细微差别很重要。没有它，你可能会夸大或低估现实世界的风险。

严重性评级也需要判断。不要只使用清单。考虑可利用性、影响和修复的便捷性。一个在时间敏感的预售合约中属于中等严重性的bug，可能比在暂停或废弃模块中的高严重性问题更紧迫。

同样重要的是语气。避免危言耸听或傲慢。目标是提供信息，而不是羞辱。当报告感觉像合作而非指责时，开发人员会更乐于接受。

超越漏洞：增加价值

即使代码库是安全的，也几乎总有一些可以改进的地方：gas效率低下、冗余检查、非标准模式或文档不足的部分。这一部分并非强制性，但尽量将其包含在每份报告中。你可以在这里提及：

• tx.origin 的误用
• 可见性修饰符的不当使用
• 代码重复
• 未使用的变量或事件
• 缺失的NatSpec文档

这表明你不仅关心发现bug，还关心代码质量。

在可能的情况下，我们会包含一个后续部分，跟踪问题是否已解决。将每个发现与客户的回应（已修复、已确认或不修复）进行映射，增加了透明度，并表明审计不仅仅是形式主义。

清晰撰写

技术准确性是不可协商的，但清晰度才是使报告真正有用的原因。

为博士生撰写和为从业者撰写是有区别的。最好的审计报告是那些高级工程师无需查阅三篇学术论文就能采取行动的报告。

避免为了使用行话而使用行话。你不是在给其他审计人员留下深刻印象，你是在帮助开发人员修复他们的代码，并让用户安心。

不要写：

“访问控制逻辑容易受到因异步函数解析在重入上下文中对可变状态进行非原子更新而导致的竞态条件的攻击。”

只需说：

“该函数可以在状态完全更新之前被重入，允许攻击者利用不一致的逻辑。”

保持清晰、简洁和正确。

此外，报告的格式要易于阅读。一致的标题、问题编号、内联代码片段和超链接引用都能让读者更容易理解。并且务必包含附录、工具版本、提交哈希、自定义测试脚本，以便工作可以被验证或复现。

避免常见错误

• 报告中充斥着低影响问题 – 优先处理重要事项。
• 模糊的建议 – “使用更安全的模式”对任何人都没有帮助。
• 忽视gas使用或测试覆盖率的见解 – 这些是审计质量的一部分。
• 不提及 不在 范围内的内容 – 务必指出这一点。
• 不给报告版本化 – 始终包含报告日期和版本。我们曾遇到过几个月后报告被改动，却无法追踪差异的情况。

最终思考

撰写审计报告并非光鲜亮丽。但它可能是最具影响力的。一份清晰、彻底的报告可以防止数百万的损失。一份草率的报告可能会造成虚假的安全感，或者更糟，导致遗漏漏洞。

在这个代码即法律、漏洞利用迅速蔓延的领域，审计报告往往是勤勉的唯一书面记录。它反映了你的思维过程、你的标准和你的信誉。

所以，花点时间。认真撰写，因为这很重要。

• 原文链接： blog.immunebytes.com/202...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～