将 SARIF 文件上� 到 GitHub

关于 code scanning 的 SARIF 文件上� 

GitHub 使用静态分析结果交换� �式 (SARIF) 文件中的信息创建 code scanning 警报。 SARIF 文件可通过在用于上� 文件的 GitHub Actions 工作流程中运行的 SARIF 兼容分析工具生成。 或者，当文件生成为仓库外部的构件时， 您可以直接将 SARIF 文件推送到仓库，并使用工作流程上�  SARIF 文件。 有关详细信息，请参阅“管理存储库的 code scanning 警报”。

您可以使用许多静态分析安全测试工具来生成 SARIF 文件，包括 CodeQL。 结果必须使用 SARIF 版本 2.1.0。 有关详细信息，请参阅“code scanning 的 SARIF 支持”。

可以使用 GitHub Actions、code scanning API、CodeQL runner、或 CodeQL CLI 上� 结果。 最佳上� 方法将取决于您如何生成 SARIF 文件，例如，如果您使用：

• GitHub Actions 来运行 CodeQL 操作，则� 需进一步操作。 CodeQL 操作在完成分析后自动上�  SARIF 文件。
• GitHub Actions 运行与 SARIF 兼容的分析工具，您可以更新工作流程以包括上� 结果的最后一步（见下文）。
• CodeQL CLI 在 CI 系统中运行 code scanning，� 可以使用 CLI 将结果上� 到 GitHub（有关详细信息，请参阅“在 CI 系统中安装 CodeQL CLI”）。
• CodeQL runner，要在 CI 系统中运行 code scanning，默认情况下运行程序会在完成后自动将结果上� 到 GitHub。 如果阻止自动上� ，当准备好上� 结果时，可以使用 upload 命令（有关详细信息，请参阅“在 CI 系统中运行 CodeQL runner”）。
• 作为存储库外部工件生成结果的工具，� 可以使用 code scanning API 上� 文件（有关详细信息，请参阅“将分析作为 SARIF 数据上� ”）。

通过 GitHub Actions 上�  code scanning 分析

要使用 GitHub Actions 将第三方 SARIF 文件上� 到存储库，需要工作流程。 有关详细信息，请参阅“了解 GitHub Actions”。

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

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

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

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

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

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

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

只要提交被推送到仓库，此示例工作流程就会运行。 操作使用 partialFingerprints 属性来确定是否发生了更改。 除了在推送提交时运行，工作流计划为每周运行一次。 有关详细信息，请参阅“触发工作流的事件”。

此工作流上� 位于存储库� �目录中的 results.sarif 文件。 有关创建工作流文件的详细信息，请参阅“了解 GitHub Actions”。

或者，您也可以修改此工作流程以上�  SARIF 文件的目录。 例如，您可以将所有 SARIF 文件放在存储库� �目录中名为 sarif-output 的目录中，并将操作的输入参数 sarif_file 设置为 sarif-output。 请注意，如果上� 目录，则每个 SARIF 文件都必须包含唯一的 runAutomationDetails.id 才能定义结果的类别。 有关详细信息，请参阅“runAutomationDetails 对象”。

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@v2
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v1
        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 静态分析工具作为工作流程中一个步骤运行的示例。 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@v2
      - 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@v1
        with:
          # Path to SARIF file relative to the root of the repository
          sarif_file: results.sarif

延伸阅读

• GitHub Actions 的工作流语法
• 查看工作流历史记录
• 关于 CI 系统中的 CodeQL code scanning
• 上� 分析作为 SARIF 数据