将 CodeQL 分析结果上传到GitHub

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

谁可以使用此功能？

具有写入访问权限的用户

CodeQL 可用于以下存储库类型：

在本文中

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

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

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

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

  •         **
        Personal access token (classic)
        **需要对所需存储库具有“警报”Code scanning**读取和写入**访问权限。

  •         **
        Fine-grained personal access token
        ** 需要“存储库” **security_events** 访问。

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

将结果上传到 GitHub

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

  2. 确定将上一节中创建的 GitHub App 或 personal access token 最佳方式传递给 CodeQL CLI。 建议查看 CI 系统有关安全使用机密存储的指南。 支持 CodeQL CLI ：

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

  3. 为配置确定最安全可靠的方法后，请在每个 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-url=<URL> \
    --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> --github-url=<URL> \
选项必选Usage
--repository指定要将数据上传到的存储库的所有者/名称。 除非存储库是公共否则所有者必须是GitHub Code Security企业内部或的组织。 有关详细信息，请参阅“管理存储库的安全和分析设置”。
--ref指定你签出和分析的 ref 的名称，以便使结果与正确的代码匹配。 对于分支使用：使用 refs/heads/BRANCH-NAME。对于拉取请求的头提交，使用 refs/pull/NUMBER/head。或对于拉取请求中由GitHub生成的合并提交，使用 refs/pull/NUMBER/merge。
--commit指定分析的提交的完整 SHA。
--sarif指定要加载的 SARIF 文件。
--github-url指定 你的 GitHub Enterprise Server 实例 的 URL。
--github-auth-stdin使用标准输入将从机密存储中生成的用于认证的GitHub App或personal access token传递到GitHub的REST API进行身份验证。 如果命令有权访问使用此令牌设置的 GITHUB_TOKEN 环境变量，则不需要执行此操作。

有关详细信息，请参阅“GitHub上传结果”。

注意

如果为单个提交分析多个 CodeQL 数据库，则必须为由此命令生成的每个结果集指定一个 SARIF 类别。 将结果 GitHub上传到后， code scanning 使用此类别单独存储每种语言的结果。 如果忘记执行此操作，则每次上传都会覆盖之前的结果。 有关详细信息，请参阅“使用 CodeQL 查询分析代码”。

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

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

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

除非上传未成功，否则此命令不会输出。 上传完成并开始数据处理时，命令提示返回。 在较小的代码库中，你应该可以立即浏览 code scanning 警报 GitHub 。 可以直接在拉取请求（Pull Request）或 Security 分支选项卡上查看警报，具体取决于您签出的代码。

在分析失败时，将诊断信息上传到GitHub

当CodeQL CLI成功分析一个数据库后，它会收集诊断信息，例如文件覆盖、警告和错误，并将其包含在带有结果的SARIF文件中。 将 SARIF 文件上传到 GitHub 后，诊断信息会在 code scanning工具状态页 上显示，以便轻松查看 CodeQL 的工作情况并调试任何问题。 有关详细信息，请参阅“使用工具状态页进行代码扫描”。

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

建议将 CI 工作流配置为在分析失败时导出诊断信息 GitHub 并将其上传到该工作流。 可以使用下面的简单命令执行此操作，以导出诊断信息并将其上传到 GitHub。

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

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

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

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

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

可以通过使用GitHub上传结果将工具状态页上传到GitHub，来提供此诊断信息，例如：

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

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