关于依赖项评审

本文内容

依赖项审查可让你在将有不安全的依赖项引入你的环境之前找到它们，并提供关于许可证、依赖项和依赖项存在时间的信息。

在公共存储库上启用了依赖项评审。 依赖项评审也可用于使用 GitHub Enterprise Cloud 并拥有 GitHub Advanced Security 的许可证的组织所拥有的专用存储库。 有关详细信息，请参阅“关于 GitHub 高级安全性”。

关于依赖项评审

依赖项审查帮助您了解依赖项变化以及这些变化在每个拉取请求中的安全影响。 它提供了一个易于理解的依赖项变化可视化效果，多差异显示在拉取请求的“更改的文件”选项卡上。 依赖项审查告知您：

  • 哪些依赖项连同发行日期一起添加、删除或更新。
  • 有多少项目使用这些组件。
  • 这些依赖项的漏洞数据。

如果拉取请求针对仓库的默认分支并且包含对包清单或锁定文件的更改，您可以显示依赖项审查以查看更改的内容。 依赖项审查包括对锁定文件中间接依赖项的更改详情，并告诉您任何已添加或更新的依赖项是否包含已知漏洞。

有时，您可能只想更新清单中一个依赖项的版本并生成拉取请求。 但是，如果此直接依赖项的更新版本也更新了依赖项，则拉取请求的更改可能超过您的预期。 每个清单和锁定文件的依赖项审查提供了一种简单的方法来查看更改的内容，以及任何新的依赖项版本是否包含已知的漏洞。

通过检查拉取请求中的依赖项审查并更改被标记为有漏洞的任何依赖项，可以避免将漏洞添加到项目中。 有关依赖项评审工作方式的详细信息，请参阅“审查拉取请求中的依赖项更改”。

有关配置依赖项评审的详细信息，请参阅“配置依赖项审查”。

Dependabot alerts 将会查找依赖项中存在的漏洞，但避免引入潜在问题比在以后修复它们要好得多。 有关 Dependabot alerts 的详细信息，请参阅“关于 Dependabot 警报”。

依赖项审查支持与依赖关系图相同的语言和包管理生态系统。 有关详细信息，请参阅“关于依赖关系图”。

有关 GitHub 上提供的供应链功能的详细信息，请参阅“关于供应链安全性”。

强制实施依赖项审查

该操作适用于所有 公共存储库，以及启用了 GitHub Advanced Security 的专用 存储库。

可使用存储库中的 依赖项审查操作 对拉取请求强制实施依赖项审查。 该操作会扫描拉取请求中包版本更改引入的易受攻击的依赖项版本，并警告你相关的安全漏洞。 这样可以更好地了解拉取请求中发生的变化，并帮助防止漏洞添加到存储库中。 有关详细信息，请参阅 dependency-review-action。

使用依赖项评审操作的工作流运行的屏幕截图。

默认情况下，如果 依赖项审查操作 检查发现任何易受攻击的包，它将失败。 当存储库所有者需要依赖项审查检查才能通过时，失败的检查将阻止拉取请求合并。 有关详细信息，请参阅“关于受保护分支”。

该操作使用依赖关系审查 REST API 来获取基本提交和头提交之间的依赖关系更改差异。 可以使用依赖关系审查 API 获取存储库上任意两个提交之间的依赖关系更改（包括漏洞数据）的差异。 有关详细信息，请参阅“依赖项关系图”。 该操作还考虑通过依赖关系提交 API 提交的依赖关系。 有关依赖项提交 API 的详细信息，请参阅 "使用依赖项提交 API"。

注意： 依赖关系审查 API 和依赖关系提交 API 协同工作。 这意味着依赖关系审查 API 将包括通过依赖关系提交 API 提交的依赖关系。 此功能目前为公共 beta 版本，可能会有变动。

可以配置 依赖项审查操作 来更好地满足你的需求。 例如，可以指定将导致操作失败的严重级别，或者为要扫描的许可证设置允许或拒绝列表。 有关详细信息，请参阅“配置依赖项审查”。

将依赖关系审查 API 和依赖关系提交 API 结合使用的最佳做法

依赖关系审查 API 和 依赖项审查操作 都通过将拉取请求中的依赖关系更改与目标分支（通常为默认分支）的头提交中的依赖关系状态进行比较来发挥作用。

如果存储库仅依赖于 GitHub 支持的生态系统中的静态定义依赖关系，则依赖关系审查 API 和 依赖项审查操作 统一工作。

但是，在生成期间可能需要扫描依赖关系，然后将其上传到依赖关系提交 API。 在这种情况下，应遵循一些最佳做法，以确保在运行依赖关系审查 API 和依赖关系提交 API 的过程中不会引入争用条件，因为这可能会导致数据缺失。

应采取的最佳做法取决于是否使用 GitHub Actions 访问依赖关系提交 API 和依赖关系审查 API，还是使用直接 API 访问。

使用 GitHub Actions 访问依赖关系提交 API 和依赖关系审查 API

如果使用 GitHub Actions 访问依赖关系提交 API 或依赖关系审查 API：

  • 请确保在与 依赖项审查操作 相同的 GitHub Actions 工作流中运行所有依赖关系提交操作。 这样就可以控制执行顺序，并确保依赖关系审查始终正常工作。
  • 如果选择单独运行 依赖项审查操作 作为必需的工作流，则应执行以下操作：
    • 将 retry-on-snapshot-warnings 设置为 true。
    • 将 retry-on-snapshot-warnings-timeout 设置为略微超过运行时间最长的依赖关系提交操作的典型运行时间（以秒为单位）。

使用直接 API 访问依赖关系提交 API 和依赖关系审查 API

如果不使用 GitHub Actions，并且代码依赖于直接访问依赖关系提交 API 和依赖关系审查 API：

  • 确保先运行调用依赖关系提交 API 的代码，然后再运行调用依赖关系审查 API 的代码。
  • 如果选择并行运行依赖关系提交 API 和依赖关系审查 API 的代码，则应实现重试逻辑并注意以下事项：
    • 比较的任一侧都缺少快照时，将在 x-github-dependency-graph-snapshot-warnings 标头中看到对此的相关说明（作为 base64 编码的字符串）。 因此，如果标头不为空，应考虑重试。
    • 实现使用指数退避重试的重试逻辑。
    • 实现合理的重试次数，以考虑依赖关系提交代码的典型运行时间。