依赖项审查

关于依赖项评审

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

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

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

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

通过检查拉取请求中的依赖项审查并更改被标记为有漏洞的任何依赖项，可以避免将漏洞添加到项目中。 有关依赖审查工作原理的更多信息，请参阅 审核拉取请求中的依赖项变更。

Dependabot alerts 将发现依赖项中已有的漏洞，但最好避免引入潜在问题，而不是在以后修复问题。 有关 Dependabot alerts 的详细信息，请参阅 Dependabot alerts。

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

有关可用的 GitHub供应链功能的详细信息，请参阅 供应链安全。

启用依赖项审查

启用依赖关系图时，依赖项审查功能可用。 有关详细信息，请参阅 启用依赖关系图。

关于 依赖项审查操作

“依赖项审查操作”指的是可以在 GitHub Actions 上下文中报告拉取请求差异的具体操作。 请参阅 dependency-review-action。 可使用存储库中的 依赖项审查操作 对拉取请求强制实施依赖项审查。 该操作会扫描拉取请求中包版本更改引入的易受攻击的依赖项版本，并警告你相关的安全漏洞。 这样可以更好地了解拉取请求中发生的变化，并帮助防止漏洞添加到存储库中。

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

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

组织所有者可以通过在组织中跨存储库强制使用 依赖项审查操作 来大规模推出依赖项审查。 这涉及使用将 依赖项审查操作 设置为所需工作流的存储库规则集，这意味着一旦工作流通过所有必需的检查，只能合并拉取请求。 有关详细信息，请参阅“在整个组织内强制执行依赖项审查”。

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

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

同时使用依赖项评审 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 编码的字符串）。 因此，如果标头不为空，应考虑重试。
  • 实现使用指数退避重试的重试逻辑。
  • 实现合理的重试次数，以考虑依赖关系提交代码的典型运行时间。

延伸阅读

• 自定义依赖项评审操作配置