在 CI 系统中配置 CodeQL CLI

关于使用 CodeQL CLI 生成代码扫描结果

一旦您在 CI 系统中提供了 CodeQL CLI 服务器， 并确保他们可以通过 GitHub 进行身份验证，便可生成数据。

您使用三个不同的命令生成结果并将它们上传到 GitHub：

1. database create 以创建 CodeQL 数据库，用于表示存储库中每种支持的编程语言的层次结构。
2. 使用 database analyze 运行查询以分析每个 CodeQL 数据库，并将结果汇总到 SARIF 文件中。
3. github upload-results 将得到的 SARIF 文件上传到结果与分支或拉取请求匹配并显示为 code scanning 警报的 GitHub。

可以使用 --help 选项显示任何命令的命令行帮助。

创建 CodeQL 数据库进行分析

1. 查看要分析的代码：

   • 对于分支，请查看要分析的分支的头。
   • 对于拉取请求，请签出拉取请求的头部提交，或签出 GitHub 生成的拉取请求的合并提交。

2. 设置代码库的环境，确保所有依赖项都可用。 有关详细信息，请参阅 CodeQL CLI 的文档中的为未编译的语言创建数据库和为已编译的语言创建数据库。

3. 查找代码库的生成命令（如果有）。 通常可在 CI 系统的配置文件中找到。

4. 从存储库的签出根目录运行 codeql database create，并生成代码库。

   # Single supported language - create one CodeQL database
   codeql database create <database> --command<build> --language=<language-identifier>
   
   # Multiple supported languages - create one CodeQL database per language
   codeql database create <database> --command<build> \
         --db-cluster --language=<language-identifier>,<language-identifier>

   注意：如果使用容器化构建，需要在执行构建任务的容器内运行 CodeQL CLI。

有关详细信息，请参阅 CodeQL CLI 文档中的创建 CodeQL 数据库。

单语言示例

此示例在 /checkouts/example-repo 为签出的存储库创建 CodeQL 数据库。 它使用 JavaScript 提取器在存储库中创建 JavaScript 和 TypeScript 代码的分层表示形式。 生成的数据库存储在 /codeql-dbs/example-repo 中。

$ 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.

多语言示例

此示例在 /checkouts/example-repo-multi 为签出的存储库创建两个 CodeQL 数据库。 它使用：

• --db-cluster 用于请求分析多种语言。
• --language 用于指定要为其创建数据库的语言。
• --command 用于告知工具代码库的生成命令，此处为 make。
• --no-run-unnecessary-builds 用于告知工具跳过不需要的语言（如 Python）的生成命令。

生成的数据库存储在 /codeql-dbs/example-repo-multi 的 python 和 cpp 子目录中。

$ codeql database create /codeql-dbs/example-repo-multi \
    --db-cluster --language python,cpp \
    --command make --no-run-unnecessary-builds \
    --source-root /checkouts/example-repo-multi
Initializing databases at /codeql-dbs/example-repo-multi.
Running build command: [make]
[build-stdout] Calling python3 /codeql-bundle/codeql/python/tools/get_venv_lib.py
[build-stdout] Calling python3 -S /codeql-bundle/codeql/python/tools/python_tracer.py -v -z all -c /codeql-dbs/example-repo-multi/python/working/trap_cache -p ERROR: 'pip' not installed.
[build-stdout] /usr/local/lib/python3.6/dist-packages -R /checkouts/example-repo-multi
[build-stdout] [INFO] Python version 3.6.9
[build-stdout] [INFO] Python extractor version 5.16
[build-stdout] [INFO] [2] Extracted file /checkouts/example-repo-multi/hello.py in 5ms
[build-stdout] [INFO] Processed 1 modules in 0.15s
[build-stdout] <output from calling 'make' to build the C/C++ code>
Finalizing databases at /codeql-dbs/example-repo-multi.
Successfully created databases at /codeql-dbs/example-repo-multi.
$

分析 CodeQL 数据库

1. 创建 CodeQL 数据库（见上文）。
2. 对数据库运行 codeql database analyze，并指定要使用的包和/或查询。

   codeql database analyze <database> --format=<format> \
       --output=<output>  --download <packs,queries>

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>

有关详细信息，请参阅 CodeQL CLI 的文档中的使用 CodeQL CLI 分析数据库。

基本示例

此示例分析存储在 /codeql-dbs/example-repo 的 CodeQL 数据库并将结果保存为 SARIF 文件：/temp/example-repo-js.sarif。 它使用 --sarif-category 在 SARIF 文件中包含将结果标识为 JavaScript 的额外信息。 当你有多个 CodeQL 数据库来分析存储库中的单个提交时，这一点至关重要。

$ codeql database analyze /codeql-dbs/example-repo  \
    javascript-code-scanning.qls --sarif-category=javascript \
    --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

在将结果上传到 GitHub 之前，必须确定将 GitHub App 或之前创建的 personal access token 传递给 CodeQL CLI 的最佳方式（请参阅在 CI 系统中安装 CodeQL CLI）。 建议查看 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

有关详细信息，请参阅 CodeQL CLI 文档中的 github 上传结果。

基本示例

此示例将结果从 SARIF 文件 temp/example-repo-js.sarif 上传到存储库 my-org/example-repo。 它告诉 code scanning API，结果用于 main 分支上的提交 deb275d2d5fe9a522a0b7bd8b6b6a1c939552718。

$ 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 中探索 code scanning 警告。 可以直接在拉取请求或分支的“安全性”选项卡上看到警报，具体取决于签出的代码。有关详细信息，请参阅“对拉取请求中的 code scanning 警报分类”和“管理存储库的 code scanning 警报”。

下载和使用 CodeQL 查询包

CodeQL CLI 捆绑包中包括由 GitHub 专家、安全研究人员和社区贡献者维护的查询。 如果要运行其他组织开发的查询，CodeQL 查询包提供了一种高效可靠的下载和运行查询的方法。 有关详细信息，请参阅“关于使用 CodeQL 进行代码扫描”。

在使用 CodeQL 包分析数据库之前，必须从 GitHub Container registry 下载所需的任何包。 这可以通过使用 --download 标志作为 codeql database analyze 命令的一部分来完成。 如果包不是公开可用，需要使用 GitHub App 或 personal access token 进行身份验证。 有关详细信息和示例，请参阅上面的将结果上传到 GitHub。

基本示例

此示例运行包含 --download 选项的 codeql database analyze 命令来执行以下操作：

1. 下载最新版本的 octo-org/security-queries 包。
2. 下载与版本 1.0.1 兼容的 octo-org/optional-security-queries 包版本（在本例中为版本 1.0.2）。 有关 SemVer 兼容性的详细信息，请参阅 npm 的语义化版本范围文档。
3. 在 octo-org/security-queries 中运行所有默认查询。
4. 在 octo-org/optional-security-queries 中仅运行查询 queries/csrf.ql

$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
    octo-org/security-queries \
    octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.

直接下载 CodeQL 包

如果要在不立即运行 CodeQL 包的情况下进行下载，则可以使用 codeql pack download 命令。 如果要避免在运行 CodeQL 查询时访问 Internet，此选项非常有用。 运行 CodeQL 分析时，可以采用与上一示例相同的方式指定包、版本和路径：

echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...

从多 GitHub 容器注册表下载 CodeQL 包

如果 CodeQL 包存在于多个容器注册表上，就必须指示 CodeQL CLI 在何处查找每个包。 有关详细信息，请参阅“配置 code scanning”。

用于 CodeQL 分析的示例 CI 配置

这是一系列命令的示例，您可以使用两种支持的语言分析代码库，然后上传结果到 GitHub。

# Create CodeQL databases for Java and Python in the 'codeql-dbs' directory
# Call the normal build script for the codebase: 'myBuildScript'

codeql database create codeql-dbs --source-root=src \
    --db-cluster --language=java,python --command=./myBuildScript

# Analyze the CodeQL database for Java, 'codeql-dbs/java'
# Tag the data as 'java' results and store in: 'java-results.sarif'

codeql database analyze codeql-dbs/java java-code-scanning.qls \
    --format=sarif-latest --sarif-category=java --output=java-results.sarif

# Analyze the CodeQL database for Python, 'codeql-dbs/python'
# Tag the data as 'python' results and store in: 'python-results.sarif'

codeql database analyze codeql-dbs/python python-code-scanning.qls \
    --format=sarif-latest --sarif-category=python --output=python-results.sarif

# Upload the SARIF file with the Java results: 'java-results.sarif'

echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif --github-auth-stdin

# Upload the SARIF file with the Python results: 'python-results.sarif'

echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif --github-auth-stdin

CI 系统中的 CodeQL CLI 疑难解答

查看日志和诊断信息

当您使用 code scanning 查询套件分析 CodeQL 数据库时，除了生成有关警报的详细信息外，CLI 还报告数据库生成步骤和汇总指标的诊断数据。 对于警报很少的存储库，您可能会发现此信息可用于确定代码中是否真的存在很少的问题，或者生成 CodeQL 数据库时是否出错。 要获取 codeql database analyze 更详细的输出，请使用 --verbose 选项。

有关可用的诊断信息类型的更多信息，请参阅查看 code scanning 日志。

Code scanning 只显示被分析语言之一的分析结果

默认情况下， code scanning 预计每个仓库需要一个SARIF 结果文件。 因此，当您上传第二个 SARIF 结果文件进行提交时，将被视为原始数据集的替换。

如果您想将多组结果上传到 code scanning API 以在存储库中提交，则必须将每组结果识别为唯一的一组结果。 对于需要创建多个 CodeQL 数据库来分析每个提交的存储库，使用 --sarif-category 为每个为该存储库生成的 SARIF 文件指定一个语言或其他独特的类别。

Python 提取的问题

我们将弃用对 CodeQL CLI 的 Python 2 支持，更具体地说，是对 CodeQL 数据库生成阶段（代码提取）的支持。

如果使用 CodeQL CLI 在用 Python 编写的代码上运行 CodeQL code scanning，请必须确保 CI 系统已安装 Python 3。

延伸阅读

• 创建 CodeQL 数据库
• 使用 CodeQL CLI 分析数据库
• 发布及使用 CodeQL 包