将 CodeQL 分析结果上传到 GitHub

可以使用 CodeQL CLI 将 CodeQL 分析结果上传到 GitHub Enterprise Cloud。

谁可以使用此功能？

GitHub CodeQL 在安装后按用户授权。 根据许可证限制，只能将 CodeQL 用于某些任务。 有关详细信息，请参阅“关于 CodeQL CLI”。

如果你有 GitHub Advanced Security 许可证，则可以使用 CodeQL 进行自动分析、持续集成和持续交付。 有关详细信息，请参阅“关于 GitHub 高级安全性”。

本文内容

关于 SARIF 输出

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

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

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

注意：上传 SARIF 数据以显示为 GitHub Enterprise Cloud 中的 code scanning 结果适用于启用了 GitHub Advanced Security 的组织拥有的数据库 和 GitHub.com 上的公共存储库。 有关详细信息，请参阅“管理存储库的安全和分析设置”。

使用 GitHub Enterprise Cloud 生成用于身份验证的令牌

在将结果上传到 GitHub Enterprise Cloud 之前，首先需要生成具有 security_events 写入权限的 personal access token。 有关详细信息，请参阅“管理个人访问令牌”。

如果已在第三方 CI 系统中安装了 CodeQL CLI 以创建结果，从而以代码扫描警报的形式显示在 GitHub 中，则可以使用 GitHub App 或 personal access token 将结果上传到 GitHub Enterprise Cloud。 有关详细信息，请参阅“在现有 CI 系统上使用代码扫描”。

上传结果到 GitHub Enterprise Cloud

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

在将结果上传到 GitHub Enterprise Cloud 之前，必须确定将 GitHub App 或前一部分创建的 personal access token 传递到 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指定要将数据上传到的存储库的所有者/名称。 所有者必须是拥有 GitHub Advanced Security 许可证的企业内的组织，而必须为存储库启用 GitHub Advanced Security，除非存储库是公共的。 有关详细信息，请参阅“管理存储库的安全和分析设置”。
--ref指定你签出和分析的 ref 的名称，以便使结果与正确的代码匹配。 用于分支：refs/heads/BRANCH-NAME，用于拉取请求的头提交：refs/pull/NUMBER/head，或者用于拉取请求的 GitHub 生成的合并提交：refs/pull/NUMBER/merge。
--commit指定分析的提交的完整 SHA。
--sarif指定要加载的 SARIF 文件。
--github-auth-stdin通过标准输入，将为对 GitHub 的 REST API 进行身份验证而创建的 GitHub App 或 personal access token 从机密存储库传递给 CLI。 如果命令有权访问使用此令牌设置的 GITHUB_TOKEN 环境变量，则不需要执行此操作。

有关详细信息，请参阅“github upload-results”。

注意： 如果你针对某个提交分析了一个以上的 CodeQL 数据库，则必须为此命令生成的每组结果指定 SARIF 类别。 当您上传结果到 GitHub Enterprise Cloud 时，code scanning 使用此类别来分别存储每种语言的结果。 如果忘记执行此操作，则每次上传都会覆盖之前的结果。 有关详细信息，请参阅“使用 CodeQL 查询分析代码”。

将结果上传到 GitHub Enterprise Cloud 的基本示例

下面的示例将结果从 SARIF 文件 temp/example-repo-js.sarif 上传到存储库 my-org/example-repo。 它告诉 code scanning API，结果用于 main 分支上的提交 deb275d2d5fe9a522a0b7bd8b6b6a1c939552718。 该示例假设为对 GitHub 的 REST API 进行身份验证而创建的 GitHub App 或 personal access token 使用 GITHUB_TOKEN 环境变量。

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

除非上传未成功，否则此命令不会输出。 上传完成并开始数据处理时，命令提示返回。 在较小的代码库中，您应该能够在稍后的 GitHub Enterprise Cloud 中探索 code scanning 警告。 可以直接在拉取请求或分支的“安全性”选项卡中查看警报，具体取决于检出的代码。有关详细信息，请参阅“鉴定拉取请求中的代码扫描警报”和“管理存储库的代码扫描警报”。

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

CodeQL CLI 成功完成数据库分析后，它会收集诊断信息（例如文件覆盖率、警告和错误），并将这些信息以及结果包含在 SARIF 文件中。 将 SARIF 文件上传到 GitHub 时，诊断信息将显示在存储库的 code scanning 工具状态页 上，以便轻松查看 CodeQL 的性能如何并调试任何问题。 有关详细信息，请参阅“关于代码扫描的工具状态页”。

但是，如果 codeql database analyze 因任何原因失败，则没有 SARIF 文件可上传到 GitHub，也没有诊断信息可显示在存储库的 code scanning 工具状态页 上。 这使得用户难以对分析进行故障排除，除非他们有权访问你的 CI 系统中的日志文件。

建议将 CI 工作流配置为在分析失败时导出诊断信息并将其上传到 GitHub Enterprise Cloud。 可以使用以下简单命令来导出诊断信息并将其上传到 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 Enterprise Cloud，在 工具状态页 上提供此诊断信息，例如：

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

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