# 关于依赖项评审

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

## 关于依赖项评审

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

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

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

> \[!NOTE]
> “依赖项审查操作”指的是在 GitHub Actions 上下文中，可以报告拉取请求中差异的特定操作，并将执行机制添加到 GitHub Actions 工作流中。 更多信息，请参阅本文后文的 [依赖项审查操作](#about-the-dependency-review-action)。

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

通过检查拉取请求中的依赖项审查并更改被标记为有漏洞的任何依赖项，可以避免将漏洞添加到项目中。 有关依赖审查工作原理的更多信息，请参阅 [审核拉取请求中的依赖项变更](/zh/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request)。

Dependabot alerts 将会查找依赖项中存在的漏洞，但避免引入潜在问题比在以后修复它们要好得多。 有关 Dependabot alerts 的更多信息，请参阅 [关于 Dependabot 警报](/zh/code-security/dependabot/dependabot-alerts/about-dependabot-alerts#dependabot-alerts-for-vulnerable-dependencies)。

依赖项审查支持与依赖关系图相同的语言和包管理生态系统。 有关详细信息，请参阅“[依赖项关系图支持的包生态系统](/zh/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems#supported-package-ecosystems)”。

有关 GitHub 上提供的供应链功能的详细信息，请参阅 [关于供应链安全性](/zh/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security)。

## 启用依赖项审查

启用依赖关系图时，依赖项审查功能可用。 有关详细信息，请参阅[启用依赖项关系图](/zh/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph#enabling-the-dependency-graph)。

## 关于 依赖项审查操作

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

![使用依赖审查操作的工作流运行截图。](/assets/images/help/graphs/dependency-review-action.png)

默认情况下，如果 依赖项审查操作 检查发现任何易受攻击的包，它将失败。 当存储库所有者需要依赖项审查检查才能通过时，失败的检查将阻止拉取请求合并。 有关详细信息，请参阅“[关于受保护分支](/zh/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging)”。

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

组织所有者可以通过在组织中跨存储库强制使用 依赖项审查操作 来大规模推出依赖项审查。 这涉及使用将 依赖项审查操作 设置为所需工作流的存储库规则集，这意味着一旦工作流通过所有必需的检查，只能合并拉取请求。 有关详细信息，请参阅“[在整个组织内强制执行依赖项审查](/zh/code-security/supply-chain-security/understanding-your-software-supply-chain/enforcing-dependency-review-across-an-organization)”。

该操作使用依赖关系审查 REST API 来获取基本提交和头提交之间的依赖关系更改差异。 可以使用依赖关系审查 API 获取存储库上任意两个提交之间的依赖关系更改（包括漏洞数据）的差异。 有关详细信息，请参阅“[适用于依赖项评审的 REST API 终结点](/zh/rest/dependency-graph/dependency-review)”。 该操作也会考虑通过 依赖项提交 API 提交的依赖项。 有关 依赖项提交 API 的详细信息，请参阅 [使用依赖项提交 API](/zh/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api)。

> \[!NOTE]
> 依赖关系审查 API 和 依赖项提交 API 协同工作。 这意味着依赖关系审查 API 将包括通过 依赖项提交 API 提交的依赖关系。

你可以配置 依赖项审查操作 以更好地满足你的需求。 例如，可以指定将导致操作失败的严重级别，或者为要扫描的许可证设置允许或拒绝列表。 有关详细信息，请参阅“[配置依赖项评审操作](/zh/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-review-action)”。

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

## 延伸阅读

* [自定义依赖项评审操作配置](/zh/code-security/supply-chain-security/understanding-your-software-supply-chain/customizing-your-dependency-review-action-configuration)