在 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 分析使用默认的查询集，但除了默认查询外，您还可以指定更多的查询来运行。

Any additional queries you want to run must belong to a QL pack in a repository. For more information, see "About 代码扫描."

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

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

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

在指定查询套件时，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 语法。 例如 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代码扫描”。

将 代码扫描 数据上传到 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		除了默认的安全查询套件之外，要运行的额外查询列表，以逗号分隔。
--config-file		自定义配置文件的路径。
--codeql-path		要使用的 CodeQL CLI 可执行文件副本的路径。 默认情况下，CodeQL runner 下载副本。
--temp-dir		存储临时文件的目录。 默认值为 ./codeql-runner。
--tools-dir		在运行之间存储 CodeQL 工具和其他文件的目录。 默认值为主目录的子目录。
--checkout-path		检出仓库的路径。 默认值为当前工作目录。
--debug		无. 打印更详细的输出。
-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		无. 显示命令的帮助。