在 CI 系统中配置 CodeQL CLI

您可以配置持续集成 系统以运行CodeQL CLI,执行 CodeQL 分析,并将结果上传到 GitHub Enterprise Server 以显示为 代码扫描 警报。

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

注:站点管理员必须为 your GitHub Enterprise Server instance 启用 代码扫描,然后您才可使用此功能。 更多信息请参阅“为设备配置 代码扫描”。

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

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

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

  1. database create 以创建 CodeQL 数据库,以代表仓库中每种支持的编程语言的层次结构。
  2. database analyze 以运行查询,以分析每个 CodeQL 数据库,并在 SARIF 文件中概括结果。
  3. github upload-results 将结果的 SARIF 文件上传到结果匹配分支或拉请求的 GitHub Enterprise Server,并显示为 代码扫描 警报。

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

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

创建 CodeQL 数据库进行分析

  1. 检出要分析的代码:

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

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

  4. 从仓库的检出根目录运行 codeql database create 并构建代码库。

    # Single supported language - create one CodeQL databsae
    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。

选项 必选 用法
<database> 指定要为 CodeQL 数据库创建的目录的名称和位置。 如果您试图覆盖现有目录,命令将失败。 如果您也指定 --db-cluster, 这是上级目录,并为分析的每种语言创建一个子目录。
`--language` 指定用于创建数据库的语言标识符:`cpp`, `csharp`, `go`, `java`, `javascript`, and `python` (使用 javascript 分析TypeScript 代码)。
当使用 `--db-cluster`时,该选项接受逗号分隔的列表,或者可以指定多次。
`--command` 推荐。 用于指定调用代码库生成过程的生成命令或脚本。 命令从当前文件夹或指定的位置运行 `--source-root`. 不需要用于 Python 和 JavaScript/TypeScript 分析。
`--db-cluster` 可选. 在多语言代码库中为指定的每种语言生成一个数据库 `--language`.
`--no-run-unnecessary-builds` 推荐。 用于抑制 CodeQL CLI 不需要监视生成的语言的生成命令(例如,Python 和 JavaScript/TypeScript)。
`--source-root` 可选. 适用于在仓库的检出根目录之外运行 CLI 的情况。 默认情况下,database create 命令假设当前目录为源文件的根目录,使用此选项可指定不同的位置。

更多信息请参阅 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 为检出的仓库创建两个 CodeQL 数据库。 它使用:

  • --db-cluster 以请求分析多种语言。
  • --langue 以指定为哪种语言创建数据库。
  • --command 以向工具告知代码库的构建命令,这里是 make
  • --no-run-unnecessary-build 以向工具告知对不需要的语言跳过构建命令(如 Python)。

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

$ 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. Create a CodeQL database (see above).
  2. Run codeql database analyze on the database and specify which queries to use.
    codeql database analyze <database> --format=<format> \
        --output=<output>   <queries> 

注意: 如果您分析了一个以上的 CodeQL 数据库的单项提交,您必须为此命令生成的每组结果指定 SARIF 类别。 当您上传结果到 GitHub Enterprise Server 时,代码扫描 使用此类别来分别存储每种语言的结果。 如果你忘记了这样做,每次上传都会覆盖以前的结果。

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <queries>
选项 必选 用法
<database> 指定包含要分析的 CodeQL 数据库的目录路径。
<packs,queries> Specify CodeQL packs or queries to run. To run the standard queries used for 代码扫描, omit this parameter. 要查看 CodeQL CLI 捆绑包中包含的其他查询套件,请查看 /<extraction-root>/codeql/qlpacks/codeql-<language>/codeql-suites。 有关创建您自己的查询套件的信息,请参阅 CodeQL CLI 文档中的创建 CodeQL 查询套件
`--format` 指定命令生成的结果文件的格式。 要上传到 GitHub,这应该是:sarifv2.1.0。 更多信息请参阅“代码扫描 的 SARIF 支持”。
`--output` 指定保存 SARIF 结果文件的位置。
--sarif-category 可选用于单个数据库分析。 当您分析多个数据库在仓库中的单个提交时,需要定义语言。 指定要在用于此分析的 SARIF 结果文件中包含的类别。 A category is used to distinguish multiple analyses for the same tool and commit, but performed on different languages or different parts of the code.|
`--threads` 可选. 如果您想使用多个线程来运行查询,请使用。 默认值为 1 。 您可以指定更多的线程来加速查询执行。 要将线程数设置为逻辑处理器的数量,指定 0
`--verbose` 可选. 用于从数据库创建过程获取有关分析过程的更详细的信息 和诊断数据。

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

基本示例

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

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

注意:

  • SARIF upload supports a maximum of 5000 results per upload. 超过此限制的任何结果均被忽略。 如果工具产生太多结果,则应更新配置,以专注于最重要的规则或查询的结果。

  • For each upload, SARIF upload supports a maximum size of 10 MB for the gzip-compressed SARIF file. Any uploads over this limit will be rejected. If your SARIF file is too large because it contains too many results, you should update the configuration to focus on results for the most important rules or queries.

在将结果上传到 GitHub Enterprise Server 之前,您必须确定将之前创建的 GitHub 应用程序 或个人访问令牌传递给 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-url=<URL> --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-url` 指定 GitHub Enterprise Server 的 URL。
`--github-auth-stdin` 可选. 用于通过标准输入传递为向 GitHub 的 REST API 验证而创建的 CLI 或 GitHub 应用程序 个人访问令牌。 如果命令可以使用此令牌设置的 GITHUB_TOKEN 环境变量,这是不必要的。

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

基本示例

此示例将结果从 SARIF 文件 temp/example-repo-js.sarif 上传到仓库 my-org/example-repo。 它告诉 代码扫描 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-url=https://github.example.com \
    --github-auth-stdin

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

用于 CodeQL 分析的示例 CI 配置

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

# 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 疑难解答

查看日志和诊断信息

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

有关可用的诊断信息类型的更多信息,请参阅“查看 代码扫描 日志”。

代码扫描 只显示被分析语言之一的分析结果

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

如果您想将多组结果上传到 代码扫描 API 以在存储库中提交,则必须将每组结果识别为唯一的一组结果。 对于您创建多个 CodeQL 数据库以分析每个提交的仓库, 使用 --sarif-categories 为每个你生成的 SARIF 文件指定一个语言或其他独特的类别。

如果您的 CI 系统无法触发 CodeQL CLI,则提供替代方案

如果 CodeQL CLI 不适合在您的 CI 系统中使用,CodeQL runner 可以作为替代。 通常,这在设置 CI 系统以协调编译器调用以及运行 CodeQL 分析时需要。 更多信息请参阅“在 CI 系统中运行 CodeQL runner”。

Note: The CodeQL runner is being deprecated. Please use the CodeQL CLI version 2.6.2 or greater instead. GitHub Enterprise Server 3.3 will be the final release series that supports the CodeQL runner. On GitHub Enterprise Cloud, the CodeQL runner will be supported until March 2022. For more information, see the CodeQL runner deprecation.

延伸阅读

此文档对您有帮助吗?

隐私政策

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

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

做出贡献

或者, 了解如何参与。