将 SARIF 文件上传到 GitHub

关于用于代码扫描的 SARIF 文件上传

GitHub 使用静态分析结果交换格式 (SARIF) 文件中的信息在代码库中创建代码扫描警报。可以使用 API 或 GitHub Actions 将 SARIF 文件上传到代码库。有关更多信息，请参阅“使用您现有的 CI 系统进行代码扫描”。

您可以使用许多静态分析安全测试工具（包括 CodeQL）生成 SARIF 文件。结果必须使用 SARIF 2.1.0 版本。有关更多信息，请参阅“代码扫描的 SARIF 支持”。

您可以使用 GitHub Actions、代码扫描 API 或 CodeQL CLI 上传结果。最佳上传方法取决于您生成 SARIF 文件的方式，例如，如果您使用

• GitHub Actions 运行 CodeQL action，则无需进一步操作。CodeQL action 在完成分析时会自动上传 SARIF 文件。
• GitHub Actions 运行兼容 SARIF 的分析工具，您可以更新工作流程以包含上传结果的最后一步（如下所示）。
• CodeQL CLI 在您的 CI 系统中运行代码扫描，您可以使用 CLI 将结果上传到 GitHub（有关更多信息，请参阅“使用您现有的 CI 系统进行代码扫描”)。
• 在代码库外部将结果作为工件生成的工具，您可以使用代码扫描 API 上传文件（有关更多信息，请参阅“代码扫描的 REST API 端点”)。

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

要使用 GitHub Actions 将第三方 SARIF 文件上传到代码库，您需要一个工作流程。有关更多信息，请参阅“编写工作流程”。

您的工作流程需要使用upload-sarif action，它是github/codeql-action 代码库的一部分。它具有可用于配置上传的输入参数。您将使用的主要输入参数为

• sarif-file，它配置要上传的 SARIF 文件的文件或目录。目录或文件路径相对于代码库的根目录。
• category（可选），它为 SARIF 文件中的结果分配一个类别。这使您能够以多种方式分析相同的提交，并使用 GitHub 中的代码扫描视图查看结果。例如，您可以使用多个工具进行分析，并且在单体存储库中，您可以根据已更改文件的子集分析代码库的不同部分。

有关更多信息，请参阅upload-sarif action。

可以将upload-sarif action 配置为在发生push 和scheduled 事件时运行。有关 GitHub Actions 事件的更多信息，请参阅“触发工作流程的事件”。

如果您的 SARIF 文件不包含partialFingerprints，则upload-sarif action 将为您计算partialFingerprints 字段，并尝试防止重复警报。只有当代码库同时包含 SARIF 文件和静态分析中使用的源代码时，GitHub 才能创建partialFingerprints。有关防止重复警报的更多信息，请参阅“代码扫描的 SARIF 支持”。

您可以检查 SARIF 属性是否具有支持的上传大小，以及该文件是否与代码扫描兼容。更多信息，请参见“代码扫描的 SARIF 支持”。

在存储库外部生成的 SARIF 文件的示例工作流程

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

此示例工作流程会在每次将提交推送到存储库时运行。该操作使用partialFingerprints属性来确定是否发生了更改。除了在推送提交时运行外，该工作流程还计划每周运行一次。更多信息，请参见“触发工作流程的事件”。

此工作流程将上传位于存储库根目录中的results.sarif文件。有关创建工作流程文件的更多信息，请参见“编写工作流程”。

或者，您可以修改此工作流程以上传 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@v4
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v3
        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 快速入门”。

此示例工作流程会在每次将提交推送到存储库时运行。该操作使用partialFingerprints属性来确定是否发生了更改。除了在推送提交时运行外，该工作流程还计划每周运行一次。更多信息，请参见“触发工作流程的事件”。

该工作流程显示了一个在工作流程中运行 ESLint 静态分析工具的示例。运行 ESLint步骤运行 ESLint 工具并输出results.sarif文件。然后，工作流程使用upload-sarif操作将results.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@v4
      - 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@v3
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

进一步阅读

• “SARIF 上传疑难解答”
• “GitHub Actions 的工作流程语法”
• “查看工作流程运行历史记录”
• “将代码扫描与您现有的 CI 系统一起使用”
• “代码扫描的 REST API 端点”