将 CodeQL 分析结果上传至 GitHub

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

谁可以使用此功能？

具有 写入 访问权限的用户

CodeQL 可用于以下仓库类型

本文内容

在使用 CodeQL CLI 分析 CodeQL 数据库后，您将拥有包含结果的 SARIF 文件。随后可以使用 CodeQL CLI 将结果上传到 GitHub。

如果您使用除 CodeQL CLI 之外的方法生成结果，也可以使用其他上传方式。更多信息请参阅 上传 SARIF 文件到 GitHub。

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

在您能够将结果上传到 GitHub 之前，首先需要生成个人访问令牌。请参阅 管理您的个人访问令牌。

  • 个人访问令牌（经典） 需要在所需仓库上拥有 “Code scanning alerts” 的 读写 访问权限。
  • 精细化个人访问令牌 需要 “repo” 的 security_events 访问权限。

如果您在第三方 CI 系统中安装了 CodeQL CLI，也可以使用 GitHub 应用将结果上传到 GitHub。请参阅 在现有 CI 系统中使用代码扫描。

将结果上传到 GitHub

  1. 检查 SARIF 属性是否符合上传支持的大小，并且文件与代码扫描兼容。更多信息请参阅 SARIF 对代码扫描的支持。

  2. 确定将上一节中创建的 GitHub 应用或个人访问令牌传递给 CodeQL CLI 的最佳方式。我们建议您查阅 CI 系统关于安全使用密钥库的指南。CodeQL CLI 支持

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

  3. 确定最安全、最可靠的配置方法后，对每个 SARIF 结果文件运行 codeql github upload-results，并在令牌未通过环境变量 GITHUB_TOKEN 提供时添加 --github-auth-stdin。

    # 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 Team 计划中，并为该仓库启用了 GitHub Code 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 应用或个人访问令牌传递给 CLI。如果命令已能够访问已设置此令牌的 GITHUB_TOKEN 环境变量，则不需要此参数。

更多信息请参阅 github upload-results。

注意

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

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

以下示例将 SARIF 文件 temp/example-repo-js.sarif 的结果上传至仓库 my-org/example-repo。它告诉代码扫描 API，这些结果对应于 main 分支上提交 deb275d2d5fe9a522a0b7bd8b6b6a1c939552718。示例假设用于 GitHub REST API 身份验证的 GitHub 应用或个人访问令牌已通过 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 文件的流程相同。

© . This site is unofficial and not affiliated with GitHub, Inc.