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

将 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

您可以从 https://github.com/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://github.com/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 包访问权限的选项：

1. 允许 CI 服务器访问 https://github.com/github/codeql-action，以便 CodeQL runner 可以自动下载包。
2. 在 GitHub Enterprise Server 上镜像 github/codeql-action 仓库。 除非您指定 --codeql-path 标志，否则运行器将在此位置和 GitHub.com上自动检查包。
3. 手动下载/提取捆绑包，将其与其他中央资源一起存储，并使用 --codeql-path 标记指定捆绑包在调用中的位置，以初始化 CodeQL runner。

调用 CodeQL runner

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

1. init 需要初始化运行器并为需要分析的每种语言创建一个 CodeQL 数据库。 这些数据库由后续命令填充和分析。
2. 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 系统中配置 代码扫描”。

基本示例

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

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

1. 检出要分析的仓库。

2. 移至检出仓库的目录。

3. 初始化 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.

4. 填充 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

5. 要将 代码扫描 结果上传为拉取请求检查，请使用 --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 命令。

1. 检出要分析的仓库。

2. 移至检出仓库的目录。

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

   $ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo-2
       --github-url https://github.example.com --github-auth TOKEN
   > Cleaning temp directory /srv/checkout/example-repo-2/codeql-runner
   > ...
   > CodeQL environment output to "/srv/checkout/example-repo-2/codeql-runner/codeql-env.json"
     and "/srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
     Please export these variables to future processes so that CodeQL can monitor the build, for example by running 
     ". /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".

4. 获取通过 init 操作生成的脚本，以设置监控构建的环境。 请注意以下代码片段中的先导点和空间。

   $ . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh

5. 构建代码。 在 macOS 上，您需要使用环境变量 $CODEQL_RUNNER 构建命令前缀。 更多信息请参阅“CI 系统中 CodeQL 代码扫描故障排除”。

6. 填充 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

7. 要将 代码扫描 结果上传为拉取请求检查，请使用 --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

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

延伸阅读

• "在 CI 系统中配置 代码扫描"
• "CI 系统中的代码扫描 故障排除"