Skip to main content

配置依赖项审查

可以使用依赖项评审来捕获漏洞,以避免将其添加到项目中。

关于依赖项评审

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

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

有关详细信息,请参阅“关于依赖项评审”和“审查拉取请求中的依赖项更改”。

关于配置依赖项审查

依赖项审查包含在公共存储库的 GitHub Enterprise Cloud 中。 若要在组织拥有的专用存储库中使用依赖项审查,必须具有 GitHub Advanced Security 许可证并启用依赖项关系图。

存储库管理员可以启用或禁用私有 存储库或内部 存储库的依赖项关系图。

您也可以为用户帐户拥有的所有存储库启用或禁用依赖项关系图。 有关详细信息,请参阅“管理个人帐户的安全和分析设置”。

还可以同时为组织中的多个存储库启用依赖项关系图。 有关详细信息,请参阅“保护你的组织”。

  1. 在 GitHub 上,导航到存储库的主页面。

  2. 在存储库名称下,单击 “设置”。 如果看不到“设置”选项卡,请选择“”下拉菜单,然后单击“设置”。

    存储库标头的屏幕截图,其中显示了选项卡。 “设置”选项卡以深橙色边框突出显示。

  3. 在边栏的“安全性”部分中,单击“ 代码安全性和分析”。

  4. 阅读有关授予 GitHub Enterprise Cloud 只读访问存储库数据的消息,以启用依赖项关系图,然后在“依赖项关系图”旁边单击“启用”。

    显示如何为存储库启用依赖项关系图的屏幕截图。 “启用”按钮以深橙色轮廓突出显示。

    可以随时单击“代码安全性和分析”的设置页上“依赖项关系图”旁边的“禁用”来禁用依赖项关系图。

  5. 向下滚动页面,如果尚未启用“GitHub Advanced Security”,请单击该功能旁边的“启用”。

关于配置 依赖项审查操作

依赖项审查操作 扫描拉取请求,查看是否存在依赖项更改,如果有任何新的依赖项存在已知漏洞,则会引发错误。 API 终结点支持此操作,该终结点比较两个修订之间的依赖关系,并报告任何差异。

有关操作和 API 终结点的详细信息,请参阅 dependency-review-action 文档和“适用于依赖项评审的 REST API 终结点”。

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

下面是常见的配置选项列表。 有关详细信息和选项的完整列表,请参阅 GitHub Marketplace 上的依赖项评审

选项必选使用情况
fail-on-severity定义严重性级别(lowmoderatehighcritical)的阈值。
对于引入指定严重性级别或更高级别的漏洞的任何拉取请求,该操作都将失败。
allow-licenses包含允许的许可证列表。 可以在 API 文档的许可证页中找到此参数可能的值。
如果拉取请求引入许可证与该列表不匹配的依赖项,此操作将会失败。
deny-licenses包含禁止的许可证列表。 可以在 API 文档的许可证页中找到此参数可能的值。
如果拉取请求引入许可证与该列表匹配的依赖项,此操作将会失败。
fail-on-scopes包含一个字符串列表,这些字符串表示要支持的生成环境(developmentruntimeunknown)。
如果拉取请求引入与列表匹配的范围内的漏洞,此操作将会失败。
comment-summary-in-pr作为拉取请求中的注释启用或禁用审阅摘要报告。 如果启用,则必须向工作流或作业授予 pull-requests: write 权限。
allow-ghsas包含可在检测过程中跳过的 GitHub Advisory Database ID 列表。 可以在 GitHub Advisory Database 中找到此参数的可能值。
config-file指定配置文件的路径。 配置文件可以在存储库本地,也可以位于外部存储库中。
external-repo-token指定用于提取配置文件的令牌(如果该文件位于某个专用外部存储库中)。 该令牌必须具有该存储库的读取访问权限。

提示:allow-licensesdeny-licenses 选项互斥。

配置 依赖项审查操作

可通过两种方法配置 依赖项审查操作:

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

请注意,所有示例使用操作 (v3) 的短版本号,而不是 semver 版本号(例如,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

延伸阅读