在 CI 系统中运行 CodeQL 代码扫描

您可以使用 CodeQL runner 在第三方持续集成系统中执行 CodeQL 代码扫描。

代码扫描在您拥有 GitHub Advanced Security 的许可证时可用。更多信息请参阅“关于 GitHub Advanced Security”。

本文内容

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

将 CodeQL 代码扫描与现有的 CI 系统一起使用

如果您使用 GitHub Actions 以外的持续集成或持续交付/部署 (CI/CD) 系统，您可以使用现有系统运行 GitHub 的 CodeQL，并将结果上传到 GitHub。为此，请使用 CodeQL runner。

关于 CodeQL runner

代码扫描是一项功能，可用于分析 GitHub 仓库中的代码，以查找安全漏洞和编码错误。分析发现的任何问题都显示在 GitHub Enterprise Server 中。更多信息请参阅“关于代码扫描”。

您可以使用 CodeQL runner 在第三方持续集成 (CI) 系统中处理的代码上运行代码扫描。您也可以使用 GitHub Actions 在 GitHub Enterprise Server 上运行代码扫描。相关信息请参阅“为仓库设置代码扫描”。

CodeQL runner 是在 GitHub 仓库的检出上运行 CodeQL 分析的命令行工具。您可以将运行器添加到第三方系统，然后调用运行器以分析代码并将结果上传到 GitHub Enterprise Server。这些结果在仓库中显示为代码扫描警报。

注意：

CodeQL runner 可用于拥有 Advanced Security 许可证的客户。
请勿将 CodeQL runner 与 CodeQL CLI 混淆。 CodeQL CLI 是一个交互式命令行接口，允许您创建用于安全研究的 CodeQL 数据库并运行 CodeQL 查询。更多信息请参阅“CodeQL CLI”。

下载 CodeQL runner

您可以从 https://HOSTNAME/github/codeql-action/releases 下载 CodeQL runner 。在某些操作系统上，您可能需要更改下载文件的权限才能运行它。

在 Linux 上：

chmod +x codeql-runner-linux

在 macOS 中:

chmod +x codeql-runner-macos
sudo xattr -d com.apple.quarantine codeql-runner-macos

You should call the CodeQL runner from the checkout location of the repository you want to analyze. The two main commands are:

将 CodeQL runner 添加到 CI 系统

下载 CodeQL runner 并确认它可执行后，应将运行器提供给您打算用于代码扫描的每个 CI 服务器。例如，您可以配置每台服务器从中央内部位置复制运行器。或者，您也可以使用 REST API 直接从 GitHub 获取运行器，例如：

wget https://HOSTNAME/github/codeql-action/releases/latest/download/codeql-runner-linux
chmod +x codeql-runner-linux

除此之外，每个 CI 服务器还需要：

GitHub 应用程序或供 CodeQL runner 使用的个人访问令牌。您必须使用范围为 repo 的访问令牌，或者具有 security_events 写入权限以及 metadata 和 contents 读取权限的 GitHub 应用程序。更多信息请参阅“构建 GitHub 应用程序”和“创建个人访问令牌”。
访问与此 CodeQL runner 发行版相关联的 CodeQL 包。此包包含 CodeQL 分析所需的查询和库，以及供运行器内部使用的 CodeQL CLI。更多信息请参阅“CodeQL CLI”。

提供 CodeQL 包访问权限的选项：

允许 CI 服务器访问 https://HOSTNAME/github/codeql-action so that the CodeQL runner 可以自动下载捆绑包。
手动下载/提取捆绑包，将其与其他中央资源一起存储，并使用 --codeql-path 标记指定捆绑包在调用中的位置，以初始化 CodeQL runner。

调用 CodeQL runner

您应该从要分析的仓库的检出位置调用 CodeQL runner。两个主要命令是：

init 需要初始化运行器并为需要分析的每种语言创建一个 CodeQL 数据库。这些数据库由后续命令填充和分析。
analyze 需要填充 CodeQL 数据库、进行分析并将结果上传到 GitHub Enterprise Server。

对于这两个命令，都必须指定 GitHub Enterprise Server 的 URL、仓库 OWNER/NAME以及 GitHub 应用程序或用于身份验证的个人访问令牌。您还需要指定 CodeQL 捆绑包的位置，除非 CI 服务器能够直接从 github/codeql-action 仓库下载它。

您可以配置 CodeQL runner 存储 CodeQL 包的位置以便将来在服务器上进行分析，使用： --tools-dir 标志；并配置在分析过程中存储临时文件的位置，使用： --temp-dir.

要查看运行器的命令行引用，请使用 -h 标志。例如，要列出所有运行的命令：codeql-runner-OS -h，或列出所有可用于 init 命令运行的标志：codeql-runner-OS init -h（其中 OS 因使用的可执行文件而异）。更多信息请参阅“在 CI 系统中配置代码扫描”。

注： SAIF 上传支持每次上传最多 1000 个结果。超过此限制的任何结果均被忽略。如果工具产生太多结果，则应更新配置，以专注于最重要的规则或查询的结果。

基本示例

此示例在 Linux CI 服务器上对托管在 https://github.example.com 上的 octo-org/example-repo 仓库运行 CodeQL 分析。这个过程非常简单，因为仓库只包含可通过 CodeQL 直接分析的语言，而无需构建（例如 Go、JavaScript、Python 和 TypeScript）。

在此示例中，服务器可以直接从 github/codeql-action 仓库下载 CodeQL 捆绑包，因此无需使用 --codeql-path 标记。

检出要分析的仓库。
移至检出仓库的目录。

初始化 CodeQL runner 并为检测到的语言创建 CodeQL。

$ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo
    --github-url https://github.example.com --github-auth TOKEN
> Cleaning temp directory /srv/checkout/example-repo/codeql-runner
> ...
> Created CodeQL database at /srv/checkout/example-repo/codeql-runner/codeql_databases/javascript.

填充 CodeQL 数据库、进行分析并将结果上传到 GitHub Enterprise Server。结果将出现在仓库的 Security（安全性）选项卡中。

$ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
    --github-url https://github.example.com --github-auth TOKEN
    --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/my-branch
> Finalizing database creation
> ...
> POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
> Successfully uploaded results

要将代码扫描结果上传为拉取请求检查，请使用 --ref 指定拉取请求标志. 我们建议设置 CodeQL runner，以便它在发生 pull_request web 挂钩事件时运行。

$ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
    --github-url https://github.example.com --github-auth TOKEN
    --commit 1dc7a1346e5ce7b86835b68bbda3078b37d6abbe --ref refs/pull/123/merge
> Finalizing database creation
> ...
> POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
> Successfully uploaded results

有关查看代码扫描警报的更多信息，请参阅“对拉取请求中的代码扫描警报分类”和“管理仓库的代码扫描警报”。

编译语言示例

此示例与前面的示例相似，但此例中的仓库含有用 C/C++、C# 或 Java 编写的代码。要为这些语言创建 CodeQL 数据库，CLI 需要监控构建。在初始化过程结束时，运行器会报告您需要在构建代码之前设置环境的命令。您需要在调用正常的 CI 构建进程之前运行此命令，然后运行 analyze 命令。

检出要分析的仓库。
移至检出仓库的目录。