在 CI 系统中配置 CodeQL 代码扫描

关于在 CI 系统中配置 CodeQL代码扫描

要将 代码扫描 集成到 CI 系统中，您可以使用 CodeQL runner。 更多信息请参阅“在 CI 系统中运行 CodeQL代码扫描”。

一般情况下，调用 CodeQL runner 如下所示。

$ /path/to-runner/codeql-runner-OS  

/path/to-runner/ 取决于您在 CI 系统上保存 CodeQL runner 的位置。 codeql-runner-OS 取决于您使用的操作系统。 CodeQL runner 有三个版本：codeql-runner-linux、codeql-runner-macos 和 codeql-runner-win，分别用于 Linux、macOS 和 Windows 系统。

要自定义 CodeQL runner 扫描代码的方式，您可以使用 --languages 和 --queries 等标志，也可以在单独的配置文件中指定自定义设置。

扫描拉取请求

每当创建拉取请求时扫描代码可防止开发者在代码中引入新的漏洞和错误。

要扫描拉取请求，请运行 analyze 命令，并使用 --ref 标记指定拉取请求。 引用是 refs/pull/<PR-number>/head 或 refs/pull/<PR-number>/merge，具体取决于您是检出拉取请求分支的 HEAD 提交，还是与基础分支合并提交。

$ /path/to-runner/codeql-runner-linux analyze --ref refs/pull/42/merge

覆盖自动语言检测

CodeQL runner 自动检测并扫描用支持的语言编写的代码。

• C/C++
• C#
• Go
• Java
• JavaScript/TypeScript
• Python

如果仓库中包含多种支持的语言的代码，您可以选择要分析的语言。 在有些情况下您可能需要阻止分析某种语言。 例如，项目中可能存在与代码主体语言不同的依赖项，并且您可能不希望看到关于这些依赖项的警报。

要覆盖自动语言检测，请运行 init 命令：带 --languages 标志，后跟以逗号分隔的语言关键字列表。 受支持语言的关键字是 cpp、csharp、go、java、javascript 和 python。

$ /path/to-runner/codeql-runner-linux init --languages cpp,java

运行额外查询

使用 CodeQL 扫描代码时，CodeQL 分析引擎将从代码生成数据库并对其运行查询。 更多信息请参阅“关于 代码扫描”。

CodeQL 分析使用默认的查询集，但除了默认查询外，您还可以指定更多的查询来运行。 要运行的查询必须属于仓库中的 QL 包。 更多信息请参阅“关于 QL 包”。

查询只能依赖于标准库（即查询中的 import LANGUAGE 语句引用的库）或与查询相同的 QL 包中的库。 标准库位于 github/codeql 仓库中。 更多信息请参阅“关于 CodeQL 查询。”

您可以指定一个 .ql 文件（一个目录中包含多个 .ql 文件）、一个 .qls 查询套件定义文件或任意组合。 有关查询套件定义的更多信息，请参阅“创建 CodeQL 查询套件”。

以下查询套件内置于 CodeQL 代码扫描，可供使用。

在指定查询套件时，CodeQL 分析引擎将运行套件中包含的查询，以及默认查询集。

要添加一个或多个查询，请将逗号分隔的路径列表传递给 init 命令的 --queries 标志。 您也可以在配置文件中指定额外查询。

如果您还使用配置文件进行自定义设置，并且还使用 --queries 标志指定额外查询，则 CodeQL runner 将使用 --queries 标志指定的额外查询，而不是配置文件中的任何查询。 如果您要运行使用标志指定的额外查询与配置文件中指定的查询的组合，请在传递给 --queries 的值之前加上前缀 + 符号。 有关配置文件的示例，请参阅“配置文件示例”。

在下面的示例中，+ 符号可确保 CodeQL runner 结合使用额外查询与所引用配置文件中指定的任何查询。

$ /path/to-runner/codeql-runner-linux init --config-file .github/codeql/codeql-config.yml 
    --queries +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main

使用第三方代码扫描工具

您可以在单独的配置文件中指定自定义设置，而不向 CodeQL runner 命令传递额外信息。

配置文件为 YAML 文件。 它使用的语法类似于 GitHub Actions 的工作流程语法，如下例所示。 更多信息请参阅“GitHub Actions 的工作流程语法”。

使用 init 命令的 --config-file 标志指定配置文件。 标志 --config-file 的值是您要使用的配置文件的路径。 此示例加载配置文件 .github/codeql/codeql-config.yml。

$ /path/to-runner/codeql-runner-linux init --config-file .github/codeql/codeql-config.yml

配置文件可以放在您分析的仓库内或外部仓库中。 使用外部仓库允许您在一个位置指定多个仓库的配置选项。 引用位于外部仓库中的配置文件时，您可以使用 OWNER/REPOSITORY/FILENAME@BRANCH 语法。 例如，monacorp/shared/codeql-config.yml@main。

配置文件示例

当您扫描代码时，此配置文件将 security-and-quality 查询套件添加到 CodeQL 运行的查询列表。 有关可供使用的查询套件的更多信息，请参阅“运行其他查询”。

name: "My CodeQL config"

queries:
  - uses: security-and-quality

以下配置文件禁用默认查询，并指定一组要运行的自定义查询。 它还配置 CodeQL 扫描 src 目录中的文件（相对于根目录），并且排除 src/node_modules 目录以及名称以 .test.js 结尾的任何文件。 因此，src/node_modules 中的文件以及名称以 .test.js 结尾的文件被排除在分析之外。

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository QL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript QL pack (run queries from an external repo)
    uses: octo-org/javascript-qlpack@main
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths:
  - src 
paths-ignore: 
  - src/node_modules
  - '**/*.test.js'

为编译语言配置 代码扫描

对于编译语言 C/C++、C# 和 Java，CodeQL 在分析之前构建代码。 CodeQL 也运行 Go 项目的构建来设置项目。 但是，与其他编译语言相比，仓库中的所有 Go 文件都是提取的，而不仅仅是构建的文件。 Go 不支持自定义构建命令。

对于许多常见的构建系统，CodeQL runner 可以自动构建代码。 要尝试自动构建代码，请在 init 与 analyze 步骤之间运行 autobuild。 请注意，如果您的仓库需要特定版本的构建工具，您可能需要先手动安装该构建工具。

autobuild 进程仅尝试为仓库构建一种编译语言。 自动选择用于分析的语言是涵盖文件最多的语言。 如果您要明确选择某种语言，请使用 autobuild 命令的 --language 标志。

$ /path/to-runner/codeql-runner-linux autobuild --language csharp

如果 autobuild 命令无法构建您的代码，您可以在 init 与 analyze 步骤之间手动运行构建步骤。 更多信息请参阅“在 CI 系统中运行 CodeQL代码扫描”。

将 代码扫描 数据上传到 GitHub

默认情况下，当您运行 analyze 命令时，CodeQL runner 上传来自 代码扫描 的结果。 您也可以使用 upload 命令单独上传 SARIF 文件。

上传数据后，GitHub 将在您的仓库中显示警报。

• 如果您上传到拉取请求，例如 --ref refs/pull/42/merge 或 --ref refs/pull/42/head，则结果在拉取请求检查中显示为警报。 更多信息请参阅“对拉取请求中的代码扫描警报分类”。
• 如果您上传到分支，例如 --ref refs/heads/my-branch，则结果将显示在仓库的 Security（安全）选项卡中。 更多信息请参阅“管理仓库的代码扫描警报”。

CodeQL runner 命令引用

CodeQL runner 支持以下命令和标志。

init

为每种要分析的语言初始化 CodeQL runner 并创建 CodeQL 数据库。

autobuild

尝试为编译语言 C/C++、C# 和 Java 构建代码。 对于这些语言，CodeQL 在分析之前构建代码。 在 init 与 analyze 步骤之间运行 autobuild。

analyze

分析 CodeQL 数据库中的代码并将结果上传到 GitHub Enterprise Server。

上传

将 SARIF 文件上传到 GitHub Enterprise Server。