注意: 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-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
注意:如果您用第三方工具分析代� �并希望结果显示为拉请求检查, 您必须运行 upload
命令,并使用 --ref
� �志来指定合并请求而不是分支。 引用是 refs/pull/<PR-number>/head
或 refs/pull/<PR-number>/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
运行额外查询
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
$ /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-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-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-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/main 或 refs/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 | � . 显示命令的帮助。 |