将 CodeQL 分析结果上传到 GitHub

关于 SARIF 输出

GitHub 使用静态分析结果交换格式 (SARIF) 文件中的信息在仓库中创建代码扫描警报。SARIF 旨在表示各种静态分析工具的输出，并且 SARIF 规范中许多功能都被认为是“可选的”。结果必须使用 SARIF 2.1.0 版本。有关详细信息，请参阅“代码扫描的 SARIF 支持”。

使用 CodeQL CLI 分析 CodeQL 数据库后，您将获得包含结果的 SARIF 文件。有关详细信息，请参阅“使用 CodeQL 查询分析您的代码”。然后，您可以使用 CodeQL CLI 将结果上传到 GitHub。

如果您使用 CodeQL CLI 以外的方法生成结果，则可以使用其他上传方法。有关详细信息，请参阅“将 SARIF 文件上传到 GitHub”。

注意

上传 SARIF 数据以在 GitHub 中显示为代码扫描结果，支持启用了 GitHub 高级安全的组织拥有的仓库以及 GitHub.com 上的公共仓库。有关详细信息，请参阅“管理仓库的安全和分析设置”。

生成用于与 GitHub 进行身份验证的令牌

在您可以将结果上传到 GitHub 之前，您首先需要生成个人访问令牌。

**个人访问令牌（经典）** 需要对所需仓库的“代码扫描警报”**读取和写入**访问权限。
**细粒度个人访问令牌** 需要“repo”**security_events** 访问权限。

有关详细信息，请参阅“管理您的个人访问令牌”。

如果您已在第三方 CI 系统中安装 CodeQL CLI 以创建要在 GitHub 中显示为代码扫描警报的结果，则可以使用 GitHub 应用或个人访问令牌将结果上传到 GitHub。有关详细信息，请参阅“将代码扫描与您现有的 CI 系统一起使用”。

将结果上传到 GitHub

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

在您可以将结果上传到 GitHub 之前，您必须确定将上一节中创建的 GitHub 应用或个人访问令牌传递到 CodeQL CLI 的最佳方法。建议您查看 CI 系统关于安全使用密钥存储的指南。CodeQL CLI 支持

使用--github-auth-stdin 选项（推荐）与密钥存储交互。
将密钥保存在环境变量GITHUB_TOKEN 中，并在不包含--github-auth-stdin 选项的情况下运行 CLI。
出于测试目的，您可以传递--github-auth-stdin 命令行选项，并通过标准输入提供临时令牌。

确定最安全可靠的配置方法后，在每个 SARIF 结果文件上运行codeql github upload-results，并包含--github-auth-stdin，除非令牌在环境变量GITHUB_TOKEN 中可用。

# GitHub App or personal access token available from a secret store
<call-to-retrieve-secret> | codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> --github-auth-stdin

# GitHub App or personal access token available in GITHUB_TOKEN
codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file>

选项	必需	用法
`--repository`		指定要将数据上传到的仓库的OWNER/NAME。所有者必须是拥有 GitHub 高级安全许可证的企业中的组织，并且必须为仓库启用 GitHub 高级安全，除非仓库是公共的。有关详细信息，请参阅“管理仓库的安全和分析设置”。
`--ref`		指定您签出和分析的`ref` 的名称，以便可以将结果与正确的代码匹配。对于分支，使用：`refs/heads/BRANCH-NAME`，对于拉取请求的头部提交，使用`refs/pull/NUMBER/head`，或者对于拉取请求的 GitHub 生成的合并提交，使用`refs/pull/NUMBER/merge`。
`--commit`		指定您分析的提交的完整 SHA。
`--sarif`		指定要加载的SARIF文件。
`--github-auth-stdin`		通过标准输入将GitHub App或为使用GitHub REST API进行身份验证而创建的个人访问令牌从您的密钥存储库传递到CLI。如果命令可以访问已设置此令牌的`GITHUB_TOKEN`环境变量，则不需要此操作。

更多信息，请参见“github upload-results”。

注意

如果您为单个提交分析了多个CodeQL数据库，则必须为该命令生成的每组结果指定一个SARIF类别。将结果上传到GitHub时，代码扫描会使用此类别分别存储每种语言的结果。如果您忘记执行此操作，每次上传都会覆盖之前的结果。更多信息，请参见“使用CodeQL查询分析您的代码”。

以下示例将temp/example-repo-js.sarif SARIF 文件中的结果上传到存储库my-org/example-repo。它告诉代码扫描API，结果适用于main分支上的提交deb275d2d5fe9a522a0b7bd8b6b6a1c939552718。此示例假设用于使用GitHub REST API进行身份验证的GitHub App或个人访问令牌使用GITHUB_TOKEN环境变量。

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif

除非上传失败，否则此命令没有输出。上传完成后并开始数据处理后，命令提示符将返回。在较小的代码库上，您应该很快就能在GitHub中浏览代码扫描警报。您可以直接在拉取请求中或分支的“**安全**”选项卡上查看警报，具体取决于您签出的代码。更多信息，请参见“在拉取请求中分类代码扫描警报”和“评估存储库的代码扫描警报”。

如果分析失败，则将诊断信息上传到GitHub

当CodeQL CLI成功完成数据库分析后，它会收集诊断信息（例如文件覆盖率、警告和错误），并将其与结果一起包含在SARIF文件中。将SARIF文件上传到GitHub时，诊断信息将显示在存储库的代码扫描工具状态页面上，以便轻松查看CodeQL的工作情况并调试任何问题。更多信息，请参见“关于代码扫描的工具状态页面”。

但是，如果codeql database analyze由于任何原因失败，则不会有SARIF文件上传到GitHub，并且不会在存储库的代码扫描工具状态页面上显示诊断信息。这使得用户难以排查分析问题，除非他们可以访问CI系统中的日志文件。

我们建议您配置CI工作流，以便在分析失败时将诊断信息导出并上传到GitHub。您可以使用以下简单命令导出诊断信息并将其上传到GitHub。

如果分析失败，则导出诊断信息

您可以使用“database export-diagnostics”创建失败分析的SARIF文件，例如

$ codeql database export-diagnostics codeql-dbs/example-repo \
    --sarif-category=javascript-typescript --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

此SARIF文件将包含失败分析的诊断信息，包括分析期间生成的任何文件覆盖率信息、警告和错误。

如果分析失败，则上传诊断信息

您可以通过使用“github upload-results”将SARIF文件上传到GitHub，从而在工具状态页面上提供此诊断信息，例如

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif

这与上传来自成功分析的SARIF文件的过程相同。

谁可以使用此功能？

本文档内容