在 CI 系统中配置 CodeQL 运行器

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

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

一般情况下，调用 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, and python。

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

运行额外查询

使用 CodeQL 扫描代� �时，CodeQL 分析引擎将从代� �生成数据库并对其运行查询。 CodeQL 分析使用默认的查询集，但除了默认查询外，您还可以指定更多的查询来运行。

Any additional queries you want to run must belong to a 仓库中的 QL 包。 更多信息请参阅“关于 代� �扫描CodeQL“。."

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

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

查询套件	描述
security-extended	严重性和精度低于默认查询的查询
security-and-quality	来自 security-extended 的查询，� 上可维护性和可� 性查询

When you specify a query suite, the CodeQL analysis engine will run the default set of queries and any extra queries defined in the additional query suite.

要添� 一个或多个查询，请将逗号分隔的路径列表� 递给 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 语法。 例如 octo-org/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 runner”。

将 代� �扫描 数据上� 到 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 数据库。

� �志	必选	输入值
--repository	✓	要初始化的仓库名称。
--github-url	✓	托管仓库的 GitHub 实例的 URL。
--github-auth	✓	GitHub 应用程序 令牌或个人访问令牌。
--languages		要分析的语言列表，以逗号分隔。 默认情况下，CodeQL runner 检测和分析仓库中所有支持的语言。
--queries		除了默认的安全查询套件之外，要运行的额外查询列表，以逗号分隔。 这将覆盖自定义配置文件中的 queries 设置。
--config-file		自定义配置文件的路径。
--codeql-path		要使用的 CodeQL CLI 可执行文件副本的路径。 默认情况下，CodeQL runner 下载副本。
--temp-dir		存储临时文件的目录。 默认值为 ./codeql-runner。
--tools-dir		在运行之间存储 CodeQL 工具和其他文件的目录。 默认值为主目录的子目录。
--checkout-path		检出仓库的路径。 默认值为当前工作目录。
--debug		� . 打印更详细的输出。
--trace-process-name		Advanced, Windows only. 注入此进程的 Windows 追踪器的过程名称。
--trace-process-level		Advanced, Windows only. 注入此进程的 Windows 追踪器的父进程级别数。
-h, --help		� . 显示命令的帮助。

autobuild

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

� �志	必选	输入值
--language		要构建的语言。 默认情况下，CodeQL runner 构建涵盖最多文件的编译语言。
--temp-dir		存储临时文件的目录。 默认值为 ./codeql-runner。
--debug		� . 打印更详细的输出。
-h, --help		� . 显示命令的帮助。

analyze

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

� �志	必选	输入值
--repository	✓	要分析的仓库名称。
--commit	✓	要分析的提交的 SHA。 在 Git 和 Azure DevOps 中，这对应于 git rev-parse HEAD 的值。 在 Jenkins 中，这对应于 $GIT_COMMIT。
--ref	✓	要分析的引用的名称，例如 refs/heads/main 或 refs/pull/42/merge。 在 Git 或 Jenkins 中，这对应于 git symbolic-ref HEAD 的值。 在 Azure DevOps 中，这对应于 $(Build.SourceBranch)。
--github-url	✓	托管仓库的 GitHub 实例的 URL。
--github-auth	✓	GitHub 应用程序 令牌或个人访问令牌。
--checkout-path		检出仓库的路径。 默认值为当前工作目录。
--no-upload		� . 阻止 CodeQL runner 将结果上� 到 GitHub Enterprise Server。
--output-dir		存储输出 SARIF 文件的目录。 默认在临时文件目录中。
--ram		运行查询时要使用的内存量。 默认使用所有可用的内存。
--no-add-snippets		� . 从 SARIF 输出排除代� �片段。
--threads		运行查询时要使用的线程数。 默认使用所有可用的� �心。
--temp-dir		存储临时文件的目录。 默认值为 ./codeql-runner。
--debug		� . 打印更详细的输出。
-h, --help		� . 显示命令的帮助。

上� 

将 SARIF 文件上� 到 GitHub Enterprise Server。

� �志	必选	输入值
--sarif-file	✓	要上� 的 SARIF 文件，或包含多个 SARIF 文件的目录。
--repository	✓	已分析的仓库名称。
--commit	✓	已分析的提交的 SHA。 在 Git 和 Azure DevOps 中，这对应于 git rev-parse HEAD 的值。 在 Jenkins 中，这对应于 $GIT_COMMIT。
--ref	✓	已分析的引用的名称，例如 refs/heads/main 或 refs/pull/42/merge。 在 Git 或 Jenkins 中，这对应于 git symbolic-ref HEAD 的值。 在 Azure DevOps 中，这对应于 $(Build.SourceBranch)。
--github-url	✓	托管仓库的 GitHub 实例的 URL。
--github-auth	✓	GitHub 应用程序 令牌或个人访问令牌。
--checkout-path		检出仓库的路径。 默认值为当前工作目录。
--debug		� . 打印更详细的输出。
-h, --help		� . 显示命令的帮助。