设置 CodeQL CLI

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

CodeQL CLI 可以设置为支持许多不同的用例和目录结构。为了快速入门，我们建议采用相对简单的设置，如下面的步骤所述。

如果您计划将 CodeQL CLI 用于安全研究或测试或贡献查询，您可能需要更高级的 CodeQL CLI 设置。有关更多信息，请参阅“CodeQL CLI 的高级设置”。

如果您在 CI 系统中设置 CodeQL CLI，则需要使 CodeQL CLI 包的全部内容可用于您希望在其上运行 CodeQL 代码扫描分析的每个 CI 服务器。例如，您可以配置每个服务器从中心内部位置复制包并将其解压缩。或者，您可以使用 REST API 直接从 GitHub 获取包，确保您受益于对查询的最新改进。有关更多信息，请参阅 REST API 文档中的“REST API 发布和发布资源端点”。

如果您在 Apple 芯片 (例如 Apple M1) 上使用 macOS，请确保安装了 Xcode 命令行开发者工具和 Rosetta 2。

注意

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

1. 下载 CodeQL CLI tar 归档文件

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

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

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

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

该包还有 tar.gz 版本，它们与 tar.zst 版本相同，只是使用效率较低的 gzip 算法进行压缩。下载 tar.gz 版本的唯一原因是如果您使用的是不支持 Zstandard 压缩算法的较旧的解压缩工具。

2. 解压缩 CodeQL CLI tar 归档文件

将 CodeQL CLI tar 归档文件解压缩到您选择的目录。

3. 启动 `codeql`

解压缩后，您可以通过以下几种方式运行 CodeQL 进程：

通过执行 <extraction-root>/codeql/codeql，其中 <extraction-root> 是您解压缩 CodeQL CLI 包的文件夹。
通过将 <extraction-root>/codeql 添加到您的 PATH，以便您可以将可执行文件作为 codeql 运行。

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

注意

如果您将 codeql 添加到您的 PATH，则 CodeQL for Visual Studio Code 可以访问它来编译和运行查询。有关配置 VS Code 以访问 CodeQL CLI 的更多信息，请参阅“配置对 CodeQL CLI 的访问”。

测试 CodeQL CLI 配置

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

如果/<extraction root>/codeql位于PATH环境变量中，则运行codeql resolve packs。
否则，运行/<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无法找到预期语言的qlpacks，请检查您下载的是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

谁可以使用此功能？

本文内容