将 SARIF 文件上传到 GitHub

注意

网站管理员必须启用 code scanning，然后你才能使用此功能。有关详细信息，请参阅“为设备配置代码扫描”。

如果企业所有者在企业级别设置了 GitHub Advanced Security 策略，则你可能无法启用或禁用 code scanning。有关详细信息，请参阅“强制实施企业的代码安全性和分析策略”。

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

例如，如果使用：

        GitHub Actions 若要运行该 CodeQL 操作，则无需执行进一步操作。 该 CodeQL 操作在完成分析时自动上传 SARIF 文件。

        GitHub Actions 若要运行与 SARIF 兼容的分析工具，可以更新工作流以包含上传结果的最后一步。 请参阅 [使用code scanning上传分析GitHub Actions](#uploading-a-code-scanning-analysis-with-github-actions)。

要在 CodeQL CLI 中的 CI 系统中运行 code scanning，可以使用 CLI 将结果上传到 GitHub。请参阅“在现有 CI 系统上使用代码扫描”。
将结果生成为存储库外部的项目的工具，可以使用 code scanning API 上传文件。请参阅“适用于代码扫描的 REST API 终结点”。

默认情况下，code scanning 期望为存储库的每次分析提供一个 SARIF 结果文件。如果你想上传多组结果以在存储库中提交，则必须将每组结果标识为唯一的一组结果。

使用 code scanning 上传分析 GitHub Actions

要将第三方 SARIF 文件通过 GitHub Actions 上传到存储库，您需要一个工作流。有关详细信息，请参阅“撰写工作流程”。

工作流将需要使用 upload-sarif 操作，该操作是 github/codeql-action 存储库的一部分。它包含可用于配置上传的输入参数。您将使用的主要输入参数是：

        `sarif_file`，用于配置要上传的 SARIF 文件的文件或目录。 目录或文件路径相对于存储库的根目录。

        `category`（可选），用于为 SARIF 文件中的结果分配类别。 这样，您可以通过多种方式分析同一提交，并使用 code scanning 视图在 GitHub 中审核结果。 例如，您可以使用多个工具进行分析，在单存储库中，您可以根据已更改文件的子集分析存储库的不同片段。

有关详细信息，请参阅 upload-sarif 操作。

          `upload-sarif` 操作可以配置为在 `push` 和 `scheduled` 事件发生时运行。 有关 GitHub Actions 事件的详细信息，请参阅 [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows)。

如果你的 SARIF 文件不包含 partialFingerprints，则 upload-sarif 操作将为你计算 partialFingerprints 字段并尝试防止重复警报。 GitHub 仅当存储库同时包含 SARIF 文件和静态分析中使用的源代码时，才能创建 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@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 操作将 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@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 文件

默认情况下， code scanning 存储库的每个分析需要一个 SARIF 结果文件。因此，当你上传第二个 SARIF 结果文件进行提交时，将被视为原始数据集的替换。例如，如果分析工具为它分析的每种语言或使用的每个规则集生成不同的 SARIF 文件，则可能需要上传两个不同的 SARIF 文件以进行一次分析。如果你想上传多组结果以在存储库中提交，则必须将每组结果标识为唯一的一组结果。

为一个提交上传多个 SARIF 文件时，必须为每个分析指定一个“类别”。指定类别的方式因分析方法而异：

在生成 SARIF 文件时，直接使用CodeQL CLI，将--sarif-category参数传递给codeql database analyze命令。有关详细信息，请参阅“关于 CodeQL CLI”。
使用GitHub Actions和codeql-action/analyze后，会根据工作流名称及任何矩阵变量（通常为language）自动设置类别。可以通过为操作指定 category 输入来覆盖此值，这在单个工作流程中分析单一存储库的不同部分时非常有用。
使用 GitHub Actions 工具上传其他静态分析工具的结果时，如果在一个工作流中为同一工具上传多个结果文件，则必须指定 category 输入。有关详细信息，请参阅“将 SARIF 文件上传到 GitHub”。
如果不使用这两种方法中的任何一种，则必须在每个 SARIF 文件中指定要上传的唯一 runAutomationDetails.id。有关此属性的详细信息，请参阅 runAutomationDetails 对象。

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

延伸阅读

        [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/troubleshooting/troubleshooting-sarif-uploads)

        [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions)

        [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history)

        [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system)

        [AUTOTITLE](/rest/code-scanning/code-scanning#upload-an-analysis-as-sarif-data)

谁可以使用此功能？

在本文中

使用 code scanning 上传分析 GitHub Actions

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

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

为提交上传多个 SARIF 文件

延伸阅读