Skip to main content

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

在 CI 系统中配置 CodeQL 运行器

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

代� �扫描 适用于启用了 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”。

Note: Your site administrator must enable 代� �扫描 for 您的 GitHub Enterprise Server 实例 before you can use this feature. For more information, see "Configuring 代� �扫描 for your appliance."

关于在 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-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

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

要覆盖自动语言检测,请运行 init 命令:带 --languages � �志,后跟以逗号分隔的语言关键字列表。 支持语言的关键词是 cppcsharpgojavajavascript、 和 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 代� �扫描 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 代� �扫描,可供使用。

查询套件描述
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 可以自动构建代� �。 要尝试自动构建代� �,请在 initanalyze 步骤之间运行 autobuild。 请注意,如果您的仓库需要特定版本的构建工具,您可能需要先手动安装该构建工具。

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

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

如果 autobuild 命令� 法构建您的代� �,您可以在 initanalyze 步骤之间手动运行构建步骤。 更多信息请参阅“在 CI 系统中运行 CodeQL runner”。

将 代� �扫描 数据上� 到 GitHub

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

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

CodeQL runner 命令引用

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

init

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

� �志必选输入值
--repository要初始化的仓库名称。
--github-url托管仓库的 GitHub 实例的 URL。
--github-auth-stdin从� �准输入读取 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-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 应用程序 令牌或个人访问令牌。
--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。

注意:如果您使用 CodeQL 运行器分析代� �,则 analyze 命令默认会上� 结果。 您可以使用 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 应用程序 令牌或个人访问令牌。
--checkout-path检出仓库的路径。 默认值为当前工作目录。
--debug� . 打印更详细的输出。
-h, --help� . 显示命令的帮助。