Skip to main content

此版本的 GitHub Enterprise 已停止服务 2022-09-28. 即使针对重大安全问题,也不会发布补丁。 为了获得更好的性能、更高的安全性和新功能,请升级到最新版本的 GitHub Enterprise。 如需升级帮助,请联系 GitHub Enterprise 支持

在 CI 系统中配置 CodeQL 运行器

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

Code scanning is available for organization-owned repositories in GitHub Enterprise Server. This feature requires a license for GitHub Advanced Security. 有关详细信息,请参阅“关于 GitHub Advanced Security”。

注意:CodeQL runner 将被弃用。 对于 GitHub Enterprise Server 3.0及更高版本,可以安装 CodeQL CLI 版本 2.6.3 来替换 CodeQL runner。

有关详细信息,请参阅 CodeQL 运行器弃用。 有关迁移到 CodeQL CLI 的信息,请参阅从 CodeQL 运行器迁移到 CodeQL CLI

注意:站点管理员必须为 your GitHub Enterprise Server instance 启用 code scanning,你才能使用这些功能。 有关详细信息,请参阅“为设备配置 code scanning”。

关于在 CI 系统中配置 CodeQLcode scanning

要将 code scanning 集成到 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-linuxcodeql-runner-macoscodeql-runner-win,分别适用于 Linux、macOS 和 Windows 系统。

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

扫描拉取请求

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

若要扫描拉取请求,请运行 analyze 命令并使用 --ref 标志来指定拉取请求。 引用为 refs/pull/<PR-number>/headrefs/pull/<PR-number>/merge,具体取决于你签出的是拉取请求分支的 HEAD 提交还是基础分支的合并提交。

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

注意:如果你使用第三方工具分析代码,并希望结果显示为拉取请求检查,则必须运行 upload 命令并使用 --ref 标志来指定拉取请求而不是分支。 引用为 refs/pull/<PR-number>/headrefs/pull/<PR-number>/merge

覆盖自动语言检测

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

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

如果存储库包含的代码支持多种语言,可以选择要分析的语言。 有几种原因可能使你想阻止对某种语言进行分析。 例如,项目中可能有其他语言的代码主体依赖项,你可能不想看到这些依赖项的警报。

要替代自动语言检测,请运行带有 --languages 标志的 init 命令,后跟以逗号分隔的语言关键字列表。 支持语言的关键词是 cpp, csharp, go, java, javascript, and python

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

运行额外查询

When you use CodeQL to scan code, the CodeQL analysis engine generates a database from the code and runs queries on it. CodeQL analysis uses a default set of queries, but you can specify more queries to run, in addition to the default queries.

Any additional queries you want to run must belong to a QL pack in a repository. For more information, see "About code scanning with CodeQL."

You can specify a single .ql file, a directory containing multiple .ql files, a .qls query suite definition file, or any combination. For more information about query suite definitions, see "Creating CodeQL query suites."

以下查询套件内置于 CodeQL code scanning,可供使用。

查询套件说明
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

示例配置文件

This configuration file adds the security-and-quality query suite to the list of queries run by CodeQL when scanning your code. For more information about the query suites available for use, see "Running additional queries."

name: "My CodeQL config"

queries:
  - uses: security-and-quality

The following configuration file disables the default queries and specifies a set of custom queries to run instead. It also configures CodeQL to scan files in the src directory (relative to the root), except for the src/node_modules directory, and except for files whose name ends in .test.js. Files in src/node_modules and files with names ending .test.js are therefore excluded from analysis.

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'

为编译语言配置 code scanning

对于编译语言 C/C++、C# 和 Java,CodeQL 在分析之前构建代码。 CodeQL 也运行 Go 项目的构建来设置项目。 但与其他编译的语言不同,存储库中的所有文件都将被提取,而不只是生成的文件。 可以使用自定义生成命令跳过提取生成时不会接触到的 Go 文件。

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

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

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

如果 autobuild 命令无法生成代码,可以在步骤 initanalyze 之间自行运行生成步骤。 有关详细信息,请参阅“在 CI 系统中运行 CodeQL runner”。

将 code scanning 数据上传到 GitHub

默认情况下,当你运行 analyze 命令时,CodeQL runner 会上传来自 code scanning 的结果。 还可以使用 upload 命令单独上传 SARIF 文件。

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

  • 如果已上传到拉取请求,例如 --ref refs/pull/42/merge--ref refs/pull/42/head,则结果会在拉取请求检查中显示为警报。 有关详细信息,请参阅在拉取请求中对代码扫描警报进行会审
  • 如果已上传到分支,例如 --ref refs/heads/my-branch,则结果会显示在存储库的“安全”选项卡中。 有关详细信息,请参阅“管理存储库的代码扫描警报”。

CodeQL runner 命令引用

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

init

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

标志必需输入值
--repository要初始化的仓库名称。
--github-url托管仓库的 GitHub 实例的 URL。
--github-auth-stdin从标准输入读取 GitHub Apps 令牌或个人访问令牌。
--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-nameAdvanced, Windows only. 注入此进程的 Windows 追踪器的过程名称。
--trace-process-levelAdvanced, Windows only. 注入此进程的 Windows 追踪器的父进程级别数。
-h, --help无。 显示命令的帮助。

autobuild

尝试为编译语言 C/C++、C# 和 Java 构建代码。 对于这些语言,CodeQL 在分析之前构建代码。 在步骤 initanalyze 之间运行 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/mainrefs/pull/42/merge。 在 Git 或 Jenkins 中,这对应于 git symbolic-ref HEAD 的值。 在 Azure DevOps 中,这对应于 $(Build.SourceBranch)
--github-url托管仓库的 GitHub 实例的 URL。
--github-auth-stdin从标准输入读取 GitHub Apps 令牌或个人访问令牌。
--checkout-path检出仓库的路径。 默认值为当前工作目录。
--no-upload无。 阻止 CodeQL runner 将结果上传到 GitHub Enterprise Server。
--output-dir存储输出 SARIF 文件的目录。 默认在临时文件目录中。
--ram运行查询时要使用的内存量。 默认使用所有可用的内存。
--no-add-snippets无。 从 SARIF 输出排除代码片段。
--category用于此分析的 SARIF 结果文件中要包含的类别。 类别可用于区分同一工具和提交的多次分析,但是在不同语言或代码的不同部分进行。 该值将显示在 SARIF v2.1.0 中的 <run>.automationDetails.id 属性中。
--threads运行查询时要使用的线程数。 默认使用所有可用的核心。
--temp-dir存储临时文件的目录。 默认为 ./codeql-runner
--debug无。 打印更详细的输出。
-h, --help无。 显示命令的帮助。

upload

将 SARIF 文件上传到 GitHub Enterprise Server。

注意:如果使用 CodeQL 运行器分析代码,则 analyze 命令默认上传 SARIF 结果。 可以使用 upload 命令上传由其他工具生成的 SARIF 结果。

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