我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

Configuring CodeQL code scanning in your CI system

您可以配置 CodeQL runner 如何扫描项目中的代码并将结果上传到 GitHub。

代码扫描 可用于您有 Advanced Security 许可的组织拥有的私有仓库。

本文内容

注意:代码扫描 目前处于测试阶段,可能会更改。 有关参加公测的更多信息,请在此注册

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

About configuring CodeQL 代码扫描 in your CI system

要将 代码扫描 集成到 CI 系统中,您可以使用 CodeQL runner。 For more information, see "Running CodeQL 代码扫描 in your CI system."

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

$ /path/to-runner/codeql-runner-OS <COMMAND> <FLAGS>

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

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

覆盖自动语言检测

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

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

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

要覆盖自动语言检测,请运行 init 命令:带 --languages 标志,后跟以逗号分隔的语言关键字列表。 受支持语言的关键字是 cppcsharpgojavajavascriptpython

$ /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 代码扫描,可供使用。

查询套件描述
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

配置文件示例

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

name: "My CodeQL config"

queries:
  - uses: security-and-quality

以下配置文件禁用默认查询,并指定一组要运行的自定义查询。 它还配置 CodeQL 以扫描 src 目录中的文件(相对于根目录),并且排除 node_modules 目录(也相对于根目录)以及名称以 est.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-ignore: 
  - node_modules
  - '**/*.test.js'
paths:
  - src 

为编译语言配置 代码扫描

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

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

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

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

如果 autobuild 命令无法构建您的代码,您可以在 initanalyze 步骤之间手动运行构建步骤。 For more information, see "Running CodeQL 代码扫描 in your CI system."

将 代码扫描 数据上传到 GitHub

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

上传数据后,GitHub 将在您的仓库中显示警报。 For more information, see "Managing 代码扫描 alerts for your repository."

CodeQL runner 命令引用

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

init

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

标志必选输入值
--repository要初始化的仓库名称。
--github-url托管仓库的 GitHub 实例的 URL。
--github-authGitHub 应用程序 令牌或个人访问令牌。
--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 在分析之前构建代码。 在 initanalyze 步骤之间运行 autobuild

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

analyze

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

标志必选输入值
--repository要分析的仓库名称。
--commit要分析的提交的 SHA。 在 Git 和 Azure DevOps 中,这对应于 git rev-parse HEAD 的值。 在 Jenkins 中,这对应于 $GIT_COMMIT
--ref要分析的引用的名称,例如 refs/heads/main。 在 Git 和 Jenkins 中,这对应于 git symbolic-ref HEAD 的值。 在 Azure DevOps 中,这对应于 $(Build.SourceBranch)
--github-url托管仓库的 GitHub 实例的 URL。
--github-authGitHub 应用程序 令牌或个人访问令牌。
--checkout-path检出仓库的路径。 默认值为当前工作目录。
--no-upload无. 阻止 CodeQL runner 将结果上传到 your GitHub Enterprise Server instance。
--output-dir存储输出 SARIF 文件的目录。 默认在临时文件目录中。
--temp-dir存储临时文件的目录。 默认值为 ./codeql-runner
--debug无. 打印更详细的输出。
-h, --help无. 显示命令的帮助。

上传

将 SARIF 文件上传到 your GitHub Enterprise Server instance。

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

此文档对您有帮助吗?

Privacy policy

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

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

做出贡献

或, 了解如何参与。