配置依赖项审查

关于依赖项审查

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

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

更多信息，请参阅“关于依赖项审查”和“审查拉取请求中的依赖项更改”。

关于配置依赖项审查

所有产品中的所有公共仓库都提供依赖项审查，并且无法禁用。使用 GitHub Enterprise Cloud 并拥有 GitHub 高级安全 许可证的组织拥有的私有仓库中也提供依赖项审查。更多信息，请参阅 GitHub Enterprise Cloud 文档。

关于配置依赖项审查操作

依赖项审查操作会扫描您的拉取请求中的依赖项更改，如果任何新依赖项具有已知漏洞，则会引发错误。该操作由一个 API 端点支持，该端点比较两个修订版之间的依赖项并报告任何差异。

有关操作和 API 端点的更多信息，请参阅 dependency-review-action 文档和“依赖项审查的 REST API 端点”。

组织所有者可以通过强制在组织中的仓库中使用依赖项审查操作来大规模推出依赖项审查。这涉及使用仓库规则集，您将在其中将依赖项审查操作设置为必需的工作流程，这意味着只有在工作流程通过所有必需的检查后才能合并拉取请求。更多信息，请参阅“在组织中强制执行依赖项审查”。

以下是常用配置选项的列表。有关更多信息以及完整的选项列表，请参阅 GitHub Marketplace 上的 依赖项审查。

选项	必需	用法
fail-on-severity		定义严重性级别 (low、moderate、high、critical) 的阈值。 该操作将对引入指定严重性级别或更高严重性级别漏洞的任何拉取请求失败。
allow-licenses		包含允许的许可证列表。您可以在 API 文档的 许可证 页面中找到此参数的可能值。 该操作将对引入与列表不匹配的许可证的依赖项的拉取请求失败。
deny-licenses		包含禁止的许可证列表。您可以在 API 文档的 许可证 页面中找到此参数的可能值。 该操作将对引入与列表匹配的许可证的依赖项的拉取请求失败。
fail-on-scopes		包含表示您要支持的构建环境 (development、runtime、unknown) 的字符串列表。 该操作将对在与列表匹配的范围内引入漏洞的拉取请求失败。
comment-summary-in-pr		启用或禁用将审查摘要作为注释报告到拉取请求中。如果启用，则必须向工作流程或作业授予 pull-requests: write 权限。
allow-ghsas		包含在检测期间可以跳过的 GitHub 安全建议数据库 ID 列表。您可以在 GitHub 安全建议数据库 中找到此参数的可能值。
config-file		指定配置文件的路径。配置文件可以位于仓库本地，也可以位于外部仓库中。
external-repo-token		指定用于获取配置文件的令牌，如果该文件位于私有外部仓库中。该令牌必须具有对仓库的读取访问权限。

配置依赖项审查操作

有两种配置依赖项审查操作的方法

• 在工作流程文件中内联配置选项。
• 在工作流程文件中引用配置文件。

请注意，所有示例都使用操作的简短版本号 (v3)，而不是语义化版本控制发行版号（例如，v3.0.8）。这可确保您使用操作的最新次要版本。

使用内联配置设置依赖项审查操作

1. 将新的 YAML 工作流程添加到您的 .github/workflows 文件夹中。

   YAML

   name: 'Dependency Review'
   on: [pull_request]
   
   permissions:
     contents: read
   
   jobs:
     dependency-review:
       runs-on: ubuntu-latest
       steps:
        - name: 'Checkout Repository'
          uses: actions/checkout@v4
        - name: Dependency Review
          uses: actions/dependency-review-action@v4
   

2. 指定您的设置。

   此依赖项审查操作示例文件说明了如何使用可用的配置选项。

   YAML

   name: 'Dependency Review'
   on: [pull_request]
   
   permissions:
     contents: read
   
   jobs:
     dependency-review:
       runs-on: ubuntu-latest
       steps:
       - name: 'Checkout Repository'
         uses: actions/checkout@v4
       - name: Dependency Review
         uses: actions/dependency-review-action@v4
         with:
           # Possible values: "critical", "high", "moderate", "low"
           fail-on-severity: critical
   
           
           # You can only include one of these two options: `allow-licenses` and `deny-licenses`
           # ([String]). Only allow these licenses (optional)
           # Possible values: Any SPDX-compliant license identifiers or expressions from https://spdx.org/licenses/
           allow-licenses: GPL-3.0, BSD-3-Clause, MIT
           # ([String]). Block the pull request on these licenses (optional)
           # Possible values: Any SPDX-compliant license identifiers or expressions from https://spdx.org/licenses/
           deny-licenses: LGPL-2.0, BSD-2-Clause
           
           # ([String]). Skip these GitHub Advisory Database IDs during detection (optional)
           # Possible values: Any valid GitHub Advisory Database ID from https://github.com/advisories
           allow-ghsas: GHSA-abcd-1234-5679, GHSA-efgh-1234-5679
           # ([String]). Block pull requests that introduce vulnerabilities in the scopes that match this list (optional)
           # Possible values: "development", "runtime", "unknown"
           fail-on-scopes: development, runtime
   

使用配置文件设置依赖项审查操作

1. 将新的 YAML 工作流程添加到您的 .github/workflows 文件夹中，并使用 config-file 指定您正在使用配置文件。

   YAML

   name: 'Dependency Review'
   on: [pull_request]
   
   permissions:
    contents: read
   
   jobs:
     dependency-review:
       runs-on: ubuntu-latest
       steps:
       - name: 'Checkout Repository'
         uses: actions/checkout@v4
       - name: Dependency Review
         uses: actions/dependency-review-action@v4
         with:
          # ([String]). Representing a path to a configuration file local to the repository or in an external repository.
          # Possible values: An absolute path to a local file or an external file.
          config-file: './.github/dependency-review-config.yml'
          # Optional alternative syntax for an external file: OWNER/REPOSITORY/FILENAME@BRANCH (uncomment if preferred)
          # config-file: 'github/octorepo/dependency-review-config.yml@main'
   
          # ([Token]) Use if your configuration file resides in a private external repository.
          # Possible values: Any GitHub token with read access to the private external repository.
          external-repo-token: 'ghp_123456789abcde'
   

2. 在您指定的路径中创建配置文件。

   此 YAML 示例文件说明了如何使用可用的配置选项。

   YAML

     # Possible values: "critical", "high", "moderate", "low"
     fail-on-severity: critical
   
     # You can only include one of these two options: `allow-licenses` and `deny-licenses`
     # ([String]). Only allow these licenses (optional)
     # Possible values: Any SPDX-compliant license identifiers or expressions from https://spdx.org/licenses/
     allow-licenses:
       - GPL-3.0
       - BSD-3-Clause
       - MIT
      # ([String]). Block the pull request on these licenses (optional)
      # Possible values: Any SPDX-compliant license identifiers or expressions from https://spdx.org/licenses/
     deny-licenses:
       - LGPL-2.0
       - BSD-2-Clause
   
      # ([String]). Skip these GitHub Advisory Database IDs during detection (optional)
      # Possible values: Any valid GitHub Advisory Database ID from https://github.com/advisories
     allow-ghsas:
       - GHSA-abcd-1234-5679
       - GHSA-efgh-1234-5679
      # ([String]). Block pull requests that introduce vulnerabilities in the scopes that match this list (optional)
      # Possible values: "development", "runtime", "unknown"
     fail-on-scopes:
       - development
       - runtime
   

有关配置选项的更多详细信息，请参阅 dependency-review-action。

进一步阅读

• “自定义您的依赖项审查操作配置”