上传 SARIF 文件到 GitHub

如果您使用第三方分析工具或 CI/CD 系统扫描代码漏洞，您可以生成 SARIF 文件并将其上传到 GitHub。最佳的上传方式取决于您如何生成 SARIF 文件。

例如，如果您使用

GitHub Actions 运行 CodeQL 操作，则无需额外操作。CodeQL 操作在完成分析后会自动上传 SARIF 文件。
GitHub Actions 运行兼容 SARIF 的分析工具时，您可以在工作流中添加一个最终步骤来上传结果。参见使用 GitHub Actions 上传代码扫描分析。
使用 CodeQL CLI 在您的 CI 系统中运行代码扫描时，您可以使用 CLI 将结果上传到 GitHub。参见在现有 CI 系统中使用代码扫描。
如果某工具将结果作为制品生成在仓库之外，您可以使用代码扫描 API 上传文件。参见代码扫描的 REST API 端点。

默认情况下，代码扫描要求每次分析在仓库中只有一个 SARIF 结果文件。如果您想为同一次提交上传多个结果集，则必须将每个结果集标记为唯一集合。

注意

对私有和内部仓库而言，只有在为仓库启用了 GitHub 代码安全功能时才能使用代码扫描。如果看到错误 GitHub Code Security or GitHub Advanced Security must be enabled for this repository to use code scanning，请检查已启用 GitHub 代码安全。更多信息请参见管理仓库的安全和分析设置。

使用 GitHub Actions 上传代码扫描分析

要使用 GitHub Actions 将第三方 SARIF 文件上传到仓库，需要编写一个工作流。详情请参见编写工作流。

您的工作流需要使用 upload-sarif 动作，该动作位于 github/codeql-action 仓库中。它提供可配置的输入参数，用于设置上传。您主要会使用的输入参数包括

sarif_file：指定要上传的 SARIF 文件或目录。目录或文件路径相对于仓库根目录。
category（可选）：为 SARIF 文件中的结果指定类别。这样即可对同一次提交进行多种方式的分析，并通过 GitHub 的代码扫描视图查看结果。例如，您可以使用多种工具进行分析；在单体仓库中，您还能基于已更改文件的子集对不同代码块进行分析。

更多信息请参见 upload-sarif 动作。

upload-sarif 动作可以配置为在 push 和 scheduled 事件发生时运行。有关 GitHub Actions 事件的详细信息，请参见触发工作流的事件。

如果您的 SARIF 文件未包含 partialFingerprints，upload-sarif 动作会为您计算该字段，并尝试防止重复警报。当仓库同时包含 SARIF 文件和用于静态分析的源代码时，GitHub 才能生成 partialFingerprints。有关防止重复警报的更多信息，请参见代码扫描的 SARIF 支持。

请检查 SARIF 属性的大小是否符合上传要求，并确认文件与代码扫描兼容。更多信息请参见代码扫描的 SARIF 支持。

仓库外生成的 SARIF 文件示例工作流

您可以创建一个新工作流，在将 SARIF 文件提交到仓库后上传它们。这在 SARIF 文件作为制品在仓库外生成时非常有用。

此示例工作流会在任何提交推送到仓库时运行。该动作使用 partialFingerprints 属性判断是否有更改。除了在推送时运行外，工作流还计划每周运行一次。详情请参见触发工作流的事件。

此工作流会上传位于仓库根目录的 results.sarif 文件。有关创建工作流文件的更多信息，请参见编写工作流。

或者，您可以修改此工作流以上传包含多个 SARIF 文件的目录。例如，您可以在仓库根目录创建名为 sarif-output 的目录，并将动作的输入参数 sarif_file 设置为 sarif-output。注意，如果上传的是目录，则每个 SARIF 文件必须包含唯一的 runAutomationDetails.id 来为结果定义类别。更多信息请参见代码扫描的 SARIF 支持。

name: "Upload SARIF"

# Run workflow each time code is pushed to your repository and on a schedule.
# The scheduled workflow runs every Thursday at 15:45 UTC.
on:
  push:
  schedule:
    - cron: '45 15 * * 4'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      # required for all workflows
      security-events: write
      # only required for workflows in private repositories
      actions: read
      contents: read
    steps:
      # This step checks out a copy of your repository.
      - name: Checkout repository
        uses: actions/checkout@v5
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v4
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif
          # Optional category for the results
          # Used to differentiate multiple results for one commit
          category: my-analysis-tool

运行 ESLint 分析工具的示例工作流

如果您在持续集成（CI）工作流中生成第三方 SARIF 文件，可以在 CI 测试后添加 upload-sarif 动作作为一步。如果尚未拥有 CI 工作流，可使用 GitHub Actions 模板创建。详情请参见 GitHub Actions 入门指南。

此工作流演示了在工作流步骤中运行 ESLint 静态分析工具的示例。Run ESLint 步骤会执行 ESLint 并输出 results.sarif 文件。随后工作流使用 upload-sarif 动作将该文件上传至 GitHub。有关创建工作流文件的更多信息，请参见了解 GitHub Actions。

name: "ESLint analysis"

# Run workflow each time code is pushed to your repository and on a schedule.
# The scheduled workflow runs every Wednesday at 15:45 UTC.
on:
  push:
  schedule:
    - cron: '45 15 * * 3'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      # required for all workflows
      security-events: write
      # only required for workflows in private repositories
      actions: read
      contents: read
    steps:
      - uses: actions/checkout@v5
      - name: Run npm install
        run: npm install
      # Runs the ESlint code analysis
      - name: Run ESLint
        # eslint exits 1 if it finds anything to report
        run: node_modules/.bin/eslint build docs lib script spec-main -f node_modules/@microsoft/eslint-formatter-sarif/sarif.js -o results.sarif || true
      # Uploads results.sarif to GitHub repository using the upload-sarif action
      - uses: github/codeql-action/upload-sarif@v4
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

为一次提交上传多个 SARIF 文件

默认情况下，代码扫描要求每个仓库每次分析仅有一个 SARIF 结果文件。因此，当您为一次提交上传第二个 SARIF 结果文件时，它会被视为对原始数据的替换。如果您的分析工具为每种语言或每套规则生成不同的 SARIF 文件，您可能希望为同一次分析上传两个不同的 SARIF 文件。若要在仓库中为一次提交上传多个结果集，必须将每个结果集标记为唯一集合。

当为一次提交上传多个 SARIF 文件时，必须为每个分析指定一个 “category”。指定类别的方式取决于使用的分析方法。

直接使用 CodeQL CLI 时，在生成 SARIF 文件时向 codeql database analyze 命令传递 --sarif-category 参数。更多信息请参见关于 CodeQL CLI。
在 GitHub Actions 中使用 codeql-action/analyze 时，类别会自动根据工作流名称和矩阵变量（通常是 language）设置。您可以通过为动作指定 category 输入来覆盖此设置，这在单个工作流中分析 monorepo 的不同部分时非常有用。
在 GitHub Actions 中上传其他静态分析工具的结果时，如果在同一工作流中为同一工具上传多个结果文件，则必须为动作指定 category 输入。更多信息请参见将 SARIF 文件上传到 GitHub。
如果不使用上述任一方式，则必须在每个 SARIF 文件中指定唯一的 runAutomationDetails.id 进行上传。有关此属性的更多信息，请参见 runAutomationDetails 对象。

如果您为同一次提交上传第二个具有相同类别且来自同一工具的 SARIF 文件，之前的结果将被覆盖。不过，如果在同一次 GitHub Actions 工作流运行中尝试为同一工具和类别上传多个 SARIF 文件，系统会检测到配置错误并导致运行失败。

谁可以使用此功能？

本文内容

使用 GitHub Actions 上传代码扫描分析

仓库外生成的 SARIF 文件示例工作流

运行 ESLint 分析工具的示例工作流

为一次提交上传多个 SARIF 文件

延伸阅读