设置 CodeQL CLI

注意

本文介绍了 GitHub Enterprise Server 3.17 的初始发行版中包含的 CodeQL CLI 2.20.7 捆绑包中可用的功能。

如果站点管理员已将 CodeQL CLI 版本更新为较新版本，请参阅本文的 GitHub Enterprise Cloud 版本，了解有关最新功能的信息。

若要运行 CodeQL 命令，需要设置 CodeQL CLI 该命令，以便它可以访问创建和分析数据库所需的工具、查询和库。

          CodeQL CLI 支持多种用例和目录结构。 本文逐步讲解适用于大多数用户和环境的简单设置。

如果打算使用 CodeQL CLI 安全研究或测试或参与查询，则可能需要更高级的设置。有关详细信息，请参阅“关于 CodeQL CLI”。

在您开始之前

如果在 Apple Silicon（例如 Apple M1）上使用 macOS，请确保已安装 Xcode 命令行开发人员工具和 Rosetta 2。

注意

目前 CodeQL CLI 与非 glibc Linux 发行版（如基于 muslc 的）Alpine Linux 不兼容。

1.下载 CodeQL CLI tar 存档

CodeQL CLI 下载包是一个 zip 存档，其中包含工具、脚本和特定于 CodeQL 的各种文件。如果没有 GitHub Enterprise 许可证，那么下载此存档即表示你同意 GitHub CodeQL 条款和条件。

应从 https://github.com/github/codeql-action/releases 下载 CodeQL 包。该捆绑包中包含：

CodeQL CLI 产品
来自 https://github.com/github/codeql 的查询和库的兼容版本
捆绑包中包含的所有查询的预编译版本

注意

对于 GitHub Enterprise Server 3.17，我们建议使用 CodeQL CLI 版本 2.20.7。

应该始终使用 CodeQL 捆绑包。这样可以确保兼容性，并且比单独下载 CodeQL CLI 和检出 CodeQL 查询提供更好的性能。如果只在一个特定平台上运行 CLI，请下载相应的 codeql-bundle-PLATFORM.tar.zst 文件。此外，也可以下载包含所有受支持平台的 CLI 的 codeql-bundle.tar.zst。

捆绑包还有 tar.gz 变体，这些变体与 tar.zst 变体相同，但使用效率较低的 gzip 算法进行压缩。下载 tar.gz 变体的唯一原因是使用不支持 Zstandard 压缩算法的较旧解压缩工具。

2. 提取 CodeQL CLI tar 存档

将 CodeQL CLI tar 存档解压缩到所选目录。

可选：在 CI 系统中设置 CodeQL CLI 以使其可用

如果计划在 CI 系统中运行 CodeQLcode scanning 分析，请确保捆绑包的完整内容 CodeQL CLI 可供运行分析的每个 CI 服务器使用。

例如，您可以：

从中央内部位置复制捆绑包，并在每台服务器上提取它，或
使用 REST API 直接从GitHub中下载组件，确保收到对查询的最新改进。有关详细信息，请参阅“发布和发布资产的 REST API 终结点”。

3. 启动 `codeql`

提取后，可以通过多种方式运行 codeql 可执行文件来运行 CodeQL 进程：

通过执行 <extraction-root>/codeql/codeql，其中 <extraction-root> 是要在其中提取 CodeQL CLI 包的文件夹。
通过将 <extraction-root>/codeql 添加到 PATH，这样就可以像 codeql 一样运行可执行文件。

此时，可以执行 CodeQL 命令。有关 CodeQL CLI 命令的完整列表，请参阅“CodeQL CLI 命令手册”。

注意

如果将codeql添加到你的PATH，CodeQL 可以访问Visual Studio Code以编译和运行查询。有关配置 VS Code 以访问该 CodeQL CLI对象的详细信息，请参阅在 VS Code 扩展中管理 CodeQL CLI。

测试CodeQL CLI配置

提取 CodeQL CLI 捆绑包后，可以运行以下命令来验证 CLI 是否已正确配置为创建和分析数据库：

          如果 `codeql resolve packs` 在 `/<extraction root>/codeql` 上，则 `PATH`。

否则为 /<extraction root>/codeql/codeql resolve packs。

如果成功，你应该会看到类似以下摘录的输出：

Searching directories specified by `--additional-packs`. All directories have equal priority.
  Searching in:
    No packs were found at this location.
Searching directories specified by `--search-path`. Directories are searched in order.
Searching the root of the CodeQL distribution.
  Searching in:
      <extraction root>
    The following packs were found:
      codeql/java-all@<version>: (library) <extraction root>/qlpacks/codeql/javat-all/<version>/qlpack.yml
      codeql/java-queries@<version>: (query) <extraction root>/qlpacks/codeql/java-queries/<version>/qlpack.yml
      codeql/javascript-all@<version>: (library) <extraction root>/qlpacks/codeql/javascript-all/<version>/qlpack.yml
      codeql/javascript-queries@<version>: (query) <extraction root>/qlpacks/codeql/javascript-queries/<version>/qlpack.yml
      codeql/swift-all@<version>: (library) <extraction root>/qlpacks/codeql/swift-all/<version>/qlpack.yml
      codeql/swift-queries@<version>: (query) <extraction root>/qlpacks/codeql/swift-queries/<version>/qlpack.yml
...

为简洁起见，结果已截断。实际结果会更长且更详细。

你应该检查输出是否包含预期的语言，以及 qlpack 文件的目录位置是否正确。位置应位于提取出的 CodeQL CLI 捆绑包内，如之前的示例 <extraction root> 所示。 CodeQL CLI如果找不到预期语言的qlpack，请检查是否下载了CodeQL捆绑包，而不是CodeQL CLI的独立副本。

还可以运行 codeql resolve languages 以显示可用于数据库创建的语言。这将列出包中 CodeQL CLI 默认支持的语言。

（可选）你可以下载一些包含要运行的预编译查询的 CodeQL 包。有关详细信息，请参阅“使用 CodeQL 包自定义分析”。

          `codeql resolve packs`命令在CodeQL CLI无法找到您期望可用于分析的查询包时非常有用，用于诊断问题。

注意

该 codeql resolve packs 命令在 CodeQL CLI 版本 2.19.0 及更高版本中可用。对于较早版本的 CLI，应运行 codeql resolve qlpacks 命令，该命令会产生类似但详细程度较低的输出。

设置 CodeQL CLI

谁可以使用此功能？

在本文中