在 CI 系统中运行 CodeQL CLI

您可以使用 CodeQL CLI 在第三方持续集成系统中执行 CodeQL 代码扫描。

代码扫描 适用于所有公共仓库以及启用了 GitHub Advanced Security 的组织拥有的私有仓库。 更多信息请参阅“关于 GitHub Advanced Security”。

关于 CodeQL CLI

您可以使用 CodeQL CLI 在第三方持续集成 (CI) 系统中处理的代码上运行 代码扫描。 代码扫描 是一项功能,可用于分析 GitHub 仓库中的代码,以查找安全漏洞和编码错误。 分析发现的任何问题都显示在 GitHub 中。 更多信息请参阅“关于 代码扫描”。

CodeQL CLI 是一个可用来分析代码的独立产品。 其主要用途是生成代码空间的数据库表示形式,即 CodeQL 数据库。 数据库准备就绪后,您可以进行交互式查询,或者运行一系列查询以生成一组 SARIF 格式的结果,然后将结果上传到 GitHub。

您也可以在 CI 系统中使用 CodeQL runner,或者使用 GitHub Actions 在 GitHub 中运行 代码扫描。 有关 CI 系统选项的概述,请参阅“关于 CI 系统中的 CodeQL 代码扫描”。 有关使用操作进行 代码扫描 的信息,请参阅“为仓库设置 代码扫描”。

注: CodeQL CLI 可免费用于 GitHub.com 上维护的公共仓库,也可用于具有 Advanced Security 许可证的客户所拥有的私有仓库。 有关信息请参阅“GitHub CodeQL 条款和条件”和“CodeQL CLI”。

下载 CodeQL CLI

您应该从 https://github.com/github/codeql-action/releases 下载 CodeQL 包。 包中包含:

您应该始终使用 CodeQL 包,因为这样可以确保兼容性,并且比单独下载 CodeQL CLI 和检出 CodeQL 查询提供更好的性能。 如果您只在一个特定平台上运行 CLI,请下载相应的 codeql-bundle-PLATFORM.tar.gz 文件。 或者,您可以下载 codeql-bundle.tar.gz,其中包含所有支持平台的 CLI 。

在 CI 系统中设置 CodeQL CLI

您需要将 CodeQL CLI 包的全部内容提供给要运行 CodeQL 代码扫描 分析的每个 CI 服务器。 例如,您可以配置每台服务器从中央内部位置复制包并提取它。 或者,您可以使用 REST API 直接从 GitHub 获取包,以确保您从查询的最新改进中受益。 CodeQL CLI 的更新每 2-3 周发布一次。 例如:

$ wget https://github.com/github/codeql-action/releases/latest/download/codeql-bundle-linux64.tar.gz
$ tar -xvzf ../codeql-bundle-linux64.tar.gz

提取 CodeQL CLI 包后,您可以在服务器上运行 codeql 可执行文件:

  • 通过执行 /extraction-root/codeql/codeql,其中 <extraction-root> 是您提取 CodeQL CLI 包的文件夹。
  • 通过将 /extraction-root/codeql 添加到 PATH,以便您可以像 codeql 一样运行可执行文件。

测试 CodeQL CLI 设置

提取 CodeQL CLI 包后,您可以运行以下命令来验证是否正确设置了 CLI 以创建和分析数据库。

  • codeql resolve languages if /extraction-root/codeql is on the PATH.
  • /extraction-root/codeql/codeql resolve languages otherwise.

成功输出示例:

cpp (/extraction-root/codeql/cpp)
csharp (/extraction-root/codeql/csharp)
csv (/extraction-root/codeql/csv)
go (/extraction-root/codeql/go)
html (/extraction-root/codeql/html)
java (/extraction-root/codeql/java)
javascript (/extraction-root/codeql/javascript)
properties (/extraction-root/codeql/properties)
python (/extraction-root/codeql/python)
xml (/extraction-root/codeql/xml)

如果 CodeQL CLI 无法口解析预期的语言, 检查您是否下载了 CodeQL 包,而不是 CodeQL CLI 的独立副本。

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

每个 CI 服务器都需要 GitHub 应用程序 或用于 CodeQL CLI 的个人访问令牌,才能将结果上传到 GitHub。 您必须使用具有 >security_events 写入权限的访问令牌或 GitHub 应用程序。 如果CI 服务器已使用具有此作用域的令牌从 GitHub 检出仓库, 您可以允许 CodeQL CLI 使用相同的令牌。 否则,您应该创建具有 security_events 写入权限的新令牌,然后将其添加到 CI 系统的密钥存储区。 更多信息请参阅“构建 GitHub 应用程序”和“创建个人访问令牌”。

使用 CodeQL CLI 生成数据并将其上传到 GitHub

您可以通过三个步骤调用 CodeQL CLI 来分析代码库:

  1. 使用 codeql database create:创建 CodeQL 数据库以表示仓库中的一种编程语言
  2. 使用 codeql database analyze:运行查询以分析 CodeQL 数据库并将结果汇总到 SARIF 文件中
  3. 使用 codeql github upload-results:将 SARIF 文件上传到 GitHub,其中结果与分支或拉取请求匹配,并显示为 代码扫描 警报

每个命令都有几个强制性选项,其他选项可用于修改命令的行为。 您可以显示任何命令的命令行帮助:使用 --help 选项.

注:上传 SARIF 数据以显示为 GitHub 中的 代码扫描 结果适用于启用了 GitHub Advanced Security 的组织拥有的仓库和 GitHub.com 上的公共仓库。 更多信息请参阅“管理仓库的安全和分析设置”。

创建 CodeQL 数据库进行分析

  1. 检出要分析的代码:

    • 对于分支,请检出要分析的分支的头部。
    • 对于拉取请求,请检出拉取请求的头部提交,或检出 GitHub 生成的拉取请求的合并提交。
  2. 设置代码库的环境,确保任何依赖项都可用。 更多信息请参阅 CodeQL CLI 文档中的为非编译语言创建数据库为编译语言创建数据库

  3. 从仓库的检出根目录运行 codeql database create

    codeql database create <database> --language=<language-identifier>

    注:如果使用容器化构建,您需要在进行构建任务的容器内运行 CodeQL CLI。

选项 必选 用法
<database> 指定要为 CodeQL 数据库创建的目录的名称和位置。 如果您试图覆盖现有目录,命令将失败。
`--language` 指定用于创建数据库的语言标识符:`cpp`、`csharp`、`go`、`java`、`javascript` 和 `python`。 (使用 javascript 分析TypeScript 代码)。
`--source-root` 可选. 适用于在仓库的检出根目录之外运行 CLI 的情况。 默认情况下,database create 命令假设当前目录为源文件的根目录,使用此选项可指定不同的位置。
`--command` 用于编译语言的可选项。 适用于要覆盖 CLI 的自动构建系统检测和编译的情况。 指定调用编译器的构建命令或脚本。 命令从当前文件夹或指定的位置运行 `--source-root`. 不要将此选项用于 Python 和 JavaScript/TypeScript 分析。

更多信息请参阅 CodeQL CLI 文档中的创建 CodeQL 数据库

基本示例
$ codeql database create /codeql-dbs/example-repo --language=javascript \
    --source-root /checkouts/example-repo

> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
    in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
... 
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.

有关更多信息和示例,请参阅 CodeQL CLI 文档中的创建 CodeQL 数据库

分析 CodeQL 数据库

  1. 创建 CodeQL 数据库(见上文)。
  2. 对数据库运行 codeql database analyze 并指定要使用的查询。
    codeql database analyze <database> --format=<format> \
        --output=<output>  <queries> 
选项 必选 用法
<database> 指定包含要分析的 CodeQL 数据库的目录路径。
<queries> 指定要运行的查询。 要运行用于 代码扫描 的标准查询,请使用: <language>-code-scanning.qls,其中 <language> 是数据库语言的短代码。 要查看 CodeQL CLI 捆绑包中包含的其他查询套件,请查看 /extraction-root/codeql/qlpacks/codeql-<language>/codeql-suites。 有关创建您自己的查询套件的信息,请参阅 CodeQL CLI 文档中的创建 CodeQL 查询套件
`--format` 指定命令生成的结果文件的格式。 要上传到 GitHub,这应该是:sarif-latest。 更多信息请参阅“代码扫描 的 SARIF 支持”。
`--output` 指定保存 SARIF 结果文件的位置。
--sarif-category 可选. 指定要在用于此分析的 SARIF 结果文件中包含的类别。 类别可用于区分同一工具和提交的多次分析,但是在不同语言或代码的不同部分进行。 这个值将会出现在 SARIF v1 的 <run>.automationId 属性、SARIF v2 的 <run>.automationLogicalId 属性和 SARIF v2.1.0 的 <run>.automationDetails.id 属性中。 |
`--threads` 可选. 如果您想使用多个线程来运行查询,请使用。 默认值为 1 。 您可以指定更多的线程来加速查询执行。 要将线程数设置为逻辑处理器的数量,指定 0

更多信息请参阅 CodeQL CLI 文档中的使用 CodeQL CLI 分析数据库

基本示例
$ codeql database analyze /codeql-dbs/example-repo  \
    javascript-code-scanning.qls --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/
    codeql-javascript/AngularJS/DisablingSce.ql.
... 
> Shutting down query evaluator.
> Interpreting results.

上传结果到 GitHub

注:SARIF 上传支持每次上传最多 5000 个结果。 超过此限制的任何结果均被忽略。 如果工具产生太多结果,则应更新配置,以专注于最重要的规则或查询的结果。

在将结果上传到 GitHub 之前,您必须确定将之前创建的 GitHub 应用程序 或个人访问令牌传递给 CodeQL CLI 的最佳方式(请参阅 生成向 GitHub 验证的令牌)。 我们建议您查看 CI 系统关于安全使用密钥存储库的指南。 CodeQL CLI 支持:

  • 使用 --github-auth-stdin 选项通过标准输入传递令牌到 CLI(推荐)。
  • 在环境变量 GITHUB_TOKEN 中保存密钥并运行不包含 --github-auth-stdin 选项的 CLI。

当您决定为您的 CI 服务器提供最安全、最可靠的方法时,请在 SARIF 结果文件上运行 codeql github upload-results,并包括 - github-auth-stdin,除非令牌在环境变量 GITHUB_TOKEN 中可用。

echo "$UPLOAD_TOKEN" | codeql github upload-results --repository=<repository-name> \
      --ref=<ref> --commit=<commit> --sarif=<file> \
      --github-auth-stdin
选项 必选 用法
`--repository` 指定要上传数据到其中的仓库的 OWNER/NAME。 所有者必须是拥有 GitHub Advanced Security 许可证的企业内的组织,而 GitHub Advanced Security 必须为仓库启用, 除非仓库是公共的。 更多信息请参阅“管理仓库的安全和分析设置”。
`--ref` 指定拉取请求 指定您检出并分析的 ref,以便结果可以匹配正确的代码。 对于分支,使用 refs/heads/BRANCH-NAME;对于拉取请求的头部提交,使用 refs/pulls/NUMBER/head;或者对于拉取请求的 GitHub 生成的合并提交,使用 refs/pulls/NUMBER/merge
`--commit` 指定所分析的提交的完整 SHA。
`--sarif` 指定要加载的 SARIF 文件。
`--github-auth-stdin` 可选. 用于通过标准输入传递为向 GitHub 的 REST API 验证而创建的 CLI 或 GitHub 应用程序 个人访问令牌。 如果命令可以使用此令牌设置的 GITHUB_TOKEN 环境变量,这是不必要的。

更多信息请参阅 CodeQL CLI 文档中的 github upload-results

基本示例
$ echo $UPLOAD_TOKEN | codeql  github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-auth-stdin

除非上传未成功,否则此命令不会输出。 上传完成并开始数据处理时,命令提示返回。 在较小的代码库中,您应该能够在稍后的 GitHub 中探索 代码扫描 警告。 警报直接显示在拉取请求或分支的 Security(安全性)选项卡上,具体取决于检出的代码。 更多信息请参阅“对拉取请求中的 代码扫描 警报分类”和“管理仓库的 代码扫描 警报”。

延伸阅读

此文档对您有帮助吗?隐私政策

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。