代码检查器 - OpenZeppelin 文档

本文档介绍了OpenZeppelin Code Inspector，它是一个与Github集成的代码分析工具，通过机器学习和安全专家开发的工具自动进行代码分析，识别潜在漏洞并提出改进建议。

代码检查器

代码检查器与 Github 无缝集成，通过机器学习智能和安全专家开发的最先进工具驱动的自动代码分析，在开发的每个步骤中最大限度地提高安全性。

对于推送的每一段代码，OpenZeppelin 代码检查器都会进行详细检查，识别潜在的漏洞并提出改进建议，以提高代码质量。它会生成一份简明扼要的报告，可在你的 PR 评论中进行总结，以便快速直接访问，同时更详细的报告可在 Defender 上获得。

使用案例

  • 自动对 pull request 进行安全分析，识别漏洞并提出改进建议。

  • 利用 pull request 中的总结报告，立即了解代码的健康状况和安全性。

  • 访问 Defender 上的全面、详细的报告，以深入了解潜在的漏洞和代码优化领域。

  • 使用 OpenZeppelin 的依赖项检查器来识别重用的合约，并将它们与已知漏洞数据库进行匹配。

  • 将静态分析规则应用于 Solidity 文件，识别潜在问题及其严重性，以实现高质量的代码维护。

功能
代码检查器发现的一些问题是由我们的 AI 模型检测到的。请记住，虽然我们提供置信度级别，但模型有时可能会生成不正确或具有误导性的信息。请务必相应地验证信息，我们很乐意听取你的反馈。

代码检查器具有广泛的功能，旨在提高安全性、效率和代码质量。这些过程由机器学习模型和我们的安全专家开发的最先进工具驱动。

  • 重用代码：通过为每个合约生成唯一的指纹并将其与已知问题数据库进行匹配，从而识别重用智能合约代码中的漏洞。

  • 易受攻击的依赖项：当使用具有已知漏洞的 OpenZeppelin 合约依赖项时发出通知，为你提供解决该问题所需的必要信息。

  • 测试建议：有机会对函数应用模糊测试，为你提供进一步测试可能被证明有益的领域。

  • 外部调用安全：外部调用的安全性，高亮显示任何可能构成严重性问题的实例。

  • 标准兼容性：你的合约与已建立标准的兼容性，标记潜在的兼容性问题。

  • 重入攻击向量：文件和函数级别的潜在重入攻击向量，为这些威胁分配高严重性标签。

  • 代码可读性：函数中缺少文档字符串以及整个代码库中拼写错误的单词，确保你的代码尽可能清晰易懂。

  • 代码效率和安全实践：你可以改进代码以获得更好性能的领域，并突出潜在的安全风险，从而使你能够更有效地优化和保护你的合约。

安装
必须从 Defender 启动安装。直接从 GitHub 安装应用程序将无法正确设置集成。

安装过程会将你的 Defender 帐户和 GitHub 仓库连接起来。请按照以下步骤操作：

  1. 在 Defender 上导航至 代码检查器页面。

  2. 单击“安装代码检查器”按钮，这将你重定向到 Github。

  3. 选择并批准要安装该应用程序的仓库。

  4. 通过在安装了该应用程序的仓库上创建或更新 pull request 来生成你的第一个报告。

目前，安装仅通过 Defender 完成，以确保报告的无缝连接。安装完成后，无需其他设置。如果你遇到安装问题，请参阅我们的故障排除部分以获取指导。

用法

代码检查器旨在简化你的代码分析工作流程。安装完成后，每当在你的 GitHub 仓库中打开 pull request (PR) 或将新提交推送到现有 PR 时，都会触发该应用程序。为避免跳过报告，PR 必须至少包含对任何 Solidity 文件或 package.json 文件的修改。

该应用程序会自动为每个新提交生成一份摘要报告，该报告作为评论发布在你的 PR 中。此摘要报告会不断更新最新提交中发现的最新问题，并且提交哈希可以直接在报告中查看。

除了 PR 评论中的摘要报告外，还会创建每个提交的详细报告，并且可以在 Defender 上访问，从而提供有关已识别问题以及如何修复它们的深入信息。

如果你希望停止接收特定仓库的报告，只需导航至代码检查器设置并将相应的仓库从列表中删除即可。

状态

以下是报告的可能状态：

  • Running：报告已触发，正在运行。

  • Succeeded：报告已成功生成，可在 Defender 和 Github 中获得。

  • Failed：报告失败。确保你的仓库包含有效的 Solidity 文件。如果此问题仍然存在，请联系我们。

  • Throttled：由于你的租户超出了代码检查器配额限制，因此报告已被限制。如果你想增加配额，请联系我们。

  • Skipped：报告已被跳过。检查 PR 和/或提交是否至少包含对 Solidity 文件或 package.json 文件的修改。

报告

摘要报告

摘要报告清楚地概述了在审查过程中检测到的代码中的潜在漏洞。该报告按过程和严重性级别方便地进行分类，从而更容易识别需要注意的区域。你可以通过提供的链接导航到 Defender 上的完整报告。每个报告都与特定的提交相关联，从而确保随着时间的推移准确跟踪更改和问题。

! [摘要报告] (https://img.learnblockchain.cn/2025/05/31/code-report-summary.png)

在此示例中，你可以看到代码检查器检测到的问题数量及其各自的严重性级别。通过单击报告底部的链接，你可以在 Defender 上查看这些漏洞的完整详细信息。

问题

完整报告使用广泛的规则识别智能合约中的问题。这些规则涵盖了许多方面，例如已知漏洞、最佳实践、代码效率和安全编码原则。

! [完整报告 1] (https://img.learnblockchain.cn/2025/05/31/contract-inspector-detailed-report.png)

根据对合约功能和安全的潜在影响，为每个问题分配一个严重性级别。每个标记的问题都附带一个解释，阐明了关注的原因。

每个问题都有一个量身定制的建议解决方案，旨在提高你的代码质量和整体安全性。这可能包括改进你的代码、修改可见性范围、应用必要的数学检查、改进文档或遵守特定的 Ethereum 标准的建议。

下面描述了一个在依赖项中检测到的漏洞的示例，并简要描述了其潜在影响。概述了特定的依赖项及其版本，从而确定了问题存在的位置。

! [依赖项检查器报告] (https://img.learnblockchain.cn/2025/05/31/dependency-checker-detailed-report.png)

为了帮助你解决这些问题，提供了有关可以解决漏洞的更新或补丁的建议，以及相关咨询链接，以便更详细地了解该问题。

通过查看和应用本报告中提出的解决方案，你可以提高智能合约的稳健性和可靠性，确保遵守最佳实践和行业标准。这使审计过程更加顺畅，并提高了合约为成功部署所做的准备。

标准

此功能在报告中引入了一个名为 Standards 的新部分。本节提供了对实现 OpenZeppelin 合约库中的接口的合约的见解。例如，如果你使用的是 IERC20，代码检查器将检查实现细节和属性，以确保你正确使用此 ERC。

详细检查

对于接口中定义的每个函数和事件，代码检查器都会执行全面的检查，以验证是否符合标准。这些检查包括：

  • 签名： 确保函数或事件签名与标准规范匹配。示例：transfer(address,uint256)

  • 可见性： 检查函数和事件的可见性是否符合标准要求。示例：external，public

  • 可变性： 对于函数，确保根据标准正确指定可变性。示例：view，pure

  • 返回类型： 验证函数的返回类型是否与标准中定义的预期类型一致。示例 returns (bool)

  • 参数名称： 确认参数名称与标准中定义的参数名称一致，从而提高代码的可读性和可维护性。示例：transfer(address recipient, uint256 amount)

  • 返回名称： 确保在使用的返回变量名称与标准一致。示例：returns (bool success)

如果函数或事件的任何属性失败，则整个函数或事件都将被标记为失败。此外，如果实现中的任何函数或事件失败，则整个实现都被认为不符合标准。

配置

你可以使用根目录中名为 defender.config.json 的文件为代码检查器配置特定于仓库的参数。该文件的结构被分为由代码检查器运行的流程。每个流程都有一个参数列表，你可以根据需要进行调整。例如，你可以指定要扫描的目录，这有助于防止代码检查器分析用 Solidity 编写的测试或脚本文件。

合约检查器

合约检查器运行一组规则来检测代码中的潜在问题。你可以配置以下参数：

  • enabled：能够关闭合约检查器。False 表示不运行，true 表示运行。（默认值：true）

  • scan_directories：要扫描的目录列表，路径从根目录开始。默认值：["."]

  • include_rules：要运行的规则列表。默认值：所有规则。

  • exclude_rules：不运行的规则列表。默认值：无。

依赖项检查器

依赖项检查器验证你的依赖项是否容易受到已知问题的影响。你可以配置以下参数：

  • enabled：能够关闭依赖项检查器。False 表示不运行，true 表示运行。（默认值：true）
示例

以下 defender.config.json 配置文件将禁用依赖项检查器，并在 src/contracts1 和 src/contracts2 目录上运行合约检查器，并排除两个规则（命名约定 和 未使用的状态）。

{
    "contract_inspector": {
        "enabled": true,
        "scan_directories": ["src/contracts1", "src/contracts2"],
        "exclude_rules": ["naming-convention", "unusued-state"]
    },
    "dependency_checker": {
        "enabled": false
    }
}

资产

“资产”页面允许你管理代码检查器资产，支持两种类型：智能合约和 GitHub 仓库。当你安装代码检查器 GitHub 应用程序并选择仓库时，它们将显示在此页面上。此外，你可以从地址簿中的地址创建智能合约资产。请注意，智能合约资产必须在 Etherscan 上验证，此功能才能工作。

可以在报告页面上手动触发智能合约资产的报告。可以从新的 pull request (PR) 和提交手动和自动触发 GitHub 资产。

! [代码资产] (https://img.learnblockchain.cn/2025/05/31/code-assets.png)

设置

“资产设置”页面提供了两个主要设置来管理 Defender 如何处理资产安全：自动生成报告和漏洞检测。

自动触发 Pull Request 报告

自动生成报告，专门用于 GitHub 仓库。启用后，此设置可确保持续监控，方法是在每次打开新的 pull request (PR) 或将新提交推送到 PR 时自动生成新报告。

主动漏洞检测和通知

主动漏洞检测和通知通过自动扫描你的资产以查找新漏洞来提供强大的安全措施。 此设置适用于 GitHub 仓库和智能合约。要为 Github 仓库资产启用此功能，你必须激活该设置并选择要监视的特定分支。

  • 自动扫描：利用 Defender 的高级智能合约扫描功能，当我们的团队意识到新的漏洞时（无论是已披露还是未披露），我们会立即更新我们的扫描算法以检测它。然后，我们会扫描配置为监视的所有资产。

  • 自动通知：自动扫描完成后，将发送自动系统通知电子邮件，通知你是否在受监视的资产中检测到该漏洞。如果检测到，通知将包括与漏洞性质相关的相关信息。

  • 风险缓解：检测到时，为了帮助解决和缓解检测到的漏洞，通知可能包括风险缓解建议，为管理员提供可操作的步骤来保护其智能合约和相关资产。

通过为你的资产启用主动漏洞检测和通知，你可以从持续的自动扫描和及时的通知中受益，从而使你能够快速响应新的威胁并维护智能合约和 GitHub 仓库的安全性。这种主动方法可确保你能够领先于潜在漏洞并有效地保护你的代码。

设置

“设置”页面允许你管理代码检查器的权限和访问级别。如果你需要更改该应用程序有权访问的仓库，则有一个方便的链接可将你直接转至该应用程序的 GitHub 设置页面，从而简化了仓库管理。

在 Github 选项卡中，你可以全局暂停或卸载该应用程序，从而使你可以完全控制其在项目中的操作。

! [代码检查器 Github] (https://img.learnblockchain.cn/2025/05/31/code-settings-advanced.png)

故障排除

安装问题

  • 在 Defender 外部安装应用程序：必须通过 Defender 安装代码检查器。如果你尝试从其他位置安装它，则安装将不会成功。确保你已登录到你的 OpenZeppelin 帐户，然后从 Defender 导航到代码检查器以进行成功安装。

  • 代码检查器访问权限：成功安装需要代码检查器访问权限。如果你发现你没有访问权限并且你认为这是一个错误，请联系 OpenZeppelin 支持部门以获取必要的权限。

仓库大小问题

与分析超时相关的错误通常是由大型代码库引起的。为了缓解此问题，建议使用 defender 配置文件中的 scan_directories 选项将分析范围仅限于相关文件。通过指定要包含在扫描中的目录，配置文件可以显着减少处理时间并防止超时。有关设置配置文件的详细说明，请参阅配置部分。

规则

ID 描述 严重性
alert-uniswap-v2-router-liquidity-considerations 识别 Uniswap Router V2 addLiquidity 调用的任何实例。 注意
array-length-to-stack 识别何时可以将数组的长度写入堆栈以节省 gas。 注意
call-with-arbitrary-address-bytes 识别潜在的不安全外部调用。 中等
chainlink-deprecated-functions 识别 chainlink 的已弃用函数的用法。 中等
check-consistent-usage-of-msgsender-msgdata 当存在 _msgSender() 或 / 和 _msgData() 时，识别 msg.sender 或 msg.data 的用法 注意
check-effect-interact 识别对检查、效果和交互模式的可能违规。 ethtrust
check-erc4337-compatibility 识别合约是否可能与 ERC-4337 不兼容。 注意
check-return-data-from-external-call 识别何时缺少外部调用返回数据检查。 注意
constants-not-using-proper-format 识别常量何时未使用正确的格式。 注意
dangerous-strict-equality 识别可能导致 Gridlock 的严格相等性的用法。 中等
default-values-assigned 识别初始化为其默认值的变量的实例。 注意
delegatecall-to-arbitrary-address 识别何处存在委派调用或代码调用到任意地址。 高
delegatecall-usage 识别委派调用的实例。 ethtrust
different-pragma-directives 识别是否使用了不同的 Solidity 版本。 低
disableinitializers-not-called-in-implementation-constructor 识别 _disableInitializers() 是否未在 Initializable 合约的构造函数中调用 注意
doc-code-mismatch-model 识别可能的文档字符串和代码不匹配。 低
duplicated-import 识别重复的导入。 注意
exact-balance 识别余额是否与精确值进行比较。 ethtrust
external-call-reentrancy-attack-vector 将外部调用识别为重入攻击的可能向量。 注意
fallback-with-return-value 识别是否存在具有返回值的 fallback 函数。 注意
floating-pragma 识别未指定特定、固定 Solidity 版本的 pragma 指令。 低
function-init-state-variable 识别何时由函数初始化状态变量。 注意
function-level-access-control-model 识别函数上可能的访问控制攻击向量。 高
function-level-reentrancy-model 识别函数上可能的重入攻击向量。 高
function-visibility-too-broad 识别函数可见性是否不必要地宽泛。 注意
gas-limit-on-call 识别何时外部调用具有硬编码的 gas 限制。 低
hashing-dynamic-values 识别打包编码的动态值的哈希。 ethtrust
identify-hardhat-console-import 识别 hardhat 控制台导入。 注意
identify-to-do-comments 识别代码中的 todo 注释。 注意
inconsistent-order-contract 识别合约何时具有不一致的顺序。 注意
inconsistent-use-named-returns 识别代码库中命名返回的不一致用法。 注意
incorrect-format-onERC721Received 识别合约何时包含 onERC721Received 函数但格式不正确。 注意
incorrect-modifier 识别修饰符的不正确定义。 中等
incremental-update-optimization 识别使用 i`（而不是 `i）以节省 gas 在 for 循环标头中。 注意
indecisive-license 识别文件何时具有多个 SPDX 许可证。 注意
int-negative-evaluation-overflow 识别何时评估 int 变量的加法逆元。 注意
lack-of-gap-variable 识别可升级合约何时没有 gap 变量。 低
lack-of-indexed-event-parameters 识别何时缺少索引事件参数。 注意
lack-of-security-contact 识别合约何时没有安全联系人。 注意
lack-of-spdx-license-identifier 识别何时缺少 SPDX 许可证标识符。 注意
lock-ether 识别合约中锁定的 ETH 的任何实例。 高
memory-side-effect-assembly 识别某些代码何时可能容易受到 Solidity 编译器漏洞的攻击。 中等
missing-docstrings 识别何时函数缺少文档字符串。 低
missing-initializer-modifier 识别何时函数缺少 initializer 修饰符。 低
missing-mapping-named-parameters 识别何时映射缺少命名参数 注意
missing-return 识别何时函数缺少 return 语句。 低
misuse-boolean-literal 检测布尔文字的误用（在复杂表达式中或作为条件使用）。 中等
msg-value-loop 识别循环内 msg.value 的用法。 注意
multiple-contracts-per-file 识别每个文件的多个合约声明。 注意
name-reused 在代码库中识别何时两个或多个合约具有相同的名称。 注意
non-explicit-imports 识别非显式导入。 注意
not-operator-assembly 识别在汇编代码中使用 not 运算符，因为它与其他语言中的功能不同。 注意
outdated-solidity-version 识别具有过时 Solidity 版本的 Solidity 文件。 注意
overriding-state-values-in-constructor 识别状态变量在合约中显式设置为值但被构造函数覆盖的情况。 注意
possible-incorrect-abi-decode 识别不正确的 ABI 解码的可能性。 注意
possible-return-bomb 识别返回炸弹攻击的可能向量。 注意
pragma-spans-breaking-changes 识别具有 pragma 的 Solidity 文件，该 pragma 跨越了可能已引入重大更改的 solidity 版本。 低
precision-loss-div-before-mul 识别由于乘法之前的除法而可能造成的精度损失 注意
redundant-safemath-library 识别 SafeMath 库的冗余用法。 注意
replace-revert-strings-custom-errors 识别何时可以将 revert 字符串替换为自定义错误。 注意
require-instead-of-revert 识别何时 require 语句未检查任何条件。 低
require-missing-message 识别何时 require 语句中缺少错误消息。 低
require-multiple-conditions 识别具有多个条件的 require 语句。 低
revert-missing-message 识别何时 revert 语句中缺少错误消息。 低
selfdestruct-usage 识别自毁的实例。 ethtrust
state-updated-without-event 识别函数是否在更新状态而没有事件发出。 注意
state-var-visibility-not-explicitly-declared 识别何时未明确声明状态变量的可见性。 注意
sushiswap-callback-attack 识别 sushiswap 回调上可能的攻击，其中伪造的池地址可以通过授权检查。 注意
swapped-arguments-function-call 识别函数调用中的参数何时被交换。 注意
too-many-digits 识别具有许多数字的文字数字。 注意
transferfrom-dangerous-from 识别 transferFrom 的用法，其中 from 参数不是 msg.sender。 高
unchecked-call-success 识别何时缺少外部调用失败检查。 ethtrust
unchecked-increment 识别增量更新未包含在 unchecked 块中。 注意
unchecked-keyword 识别函数内的 unchecked 代码。 注意
unchecked-math 识别 unchecked 数学的潜在不安全用法。 高
unicode-direction-control 识别 unicode 方向控制字符的用法。 ethtrust
unnecessary-assignment 识别变量的不必要赋值。 注意
unnecessary-cast 识别不必要的强制转换。 注意
unsafe-abi-encoding 识别任何不安全的 ABI 编码的用法。 低
unsafe-mint-ERC721 识别在 ERC721 上下文中是否使用了 _mint 函数而不是 _safeMint。 注意
unused-arguments 识别未使用的函数参数。 注意
unused-enum 识别未使用的枚举。 注意
unused-error 识别未使用的错误。 注意
unused-event 识别未使用的事件。 注意
unused-function 识别具有 internal 或 private 可见性的未使用函数。 注意
unused-imports 识别未使用的导入。 注意
unused-named-returns 识别未使用的命名返回变量。 注意
unused-state-variable 识别未使用的状态变量。 注意
unused-struct 识别未使用的结构体。 注意
use-of-transfer-send 识别 transfer 或 send 的实例。 低
use-of-uint-instead-of-uint256 识别是否使用 int/uint 而不是 int256/uint256。 注意
variable-could-be-constant 识别可以声明为 constant 的变量。 注意
variable-could-be-immutable 识别仅在构造函数中设置并且可以是 immutable 的变量。 注意
void-constructor-call 识别对未实现的构造函数的调用。 低

← 概述

审计 →

  • 原文链接： docs.openzeppelin.com/de...
  • 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～
点赞 0
收藏 0
分享
本文参与登链社区写作激励计划 ，好文好收益，欢迎正在阅读的你也加入。

0 条评论

请先 登录 后评论
OpenZeppelin
OpenZeppelin
江湖只有他的大名，没有他的介绍。

OpenZeppelin

如果觉得我的文章对您有用，请随意打赏。你的支持将鼓励我继续创作！