设置 CodeQL CLI

注意：本文介绍了 GitHub Enterprise Server 3.8 的初始发行版中包含的 CodeQL CLI 2.12.7 捆绑包中可用的功能。

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

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

可以将 CodeQL CLI 设置为支持许多不同的用例和目录结构。若要快速开始使用，建议采用相对简单的设置，如以下步骤中所述。

如果计划将 CodeQL CLI 用于安全研究或测试或参与查询，则你可能希望对 CodeQL CLI 进行更高级的设置。有关详细信息，请参阅“CodeQL CLI 的高级设置”。

如果你在 CI 系统中设置 CodeQL CLI，你需要将 CodeQL CLI 捆绑包的全部内容提供给要运行 CodeQL code scanning 分析的每个 CI 服务器。例如，您可以配置每台服务器从中央内部位置复制包并提取它。或者，您可以使用 REST API 直接从 GitHub 获取包，以确保您从查询的最新改进中受益。有关详细信息，请参阅 REST API 文档中的“发布和发布资产的 REST API 终结点”。

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

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

1. 下载 CodeQL CLI zip 包

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.8，建议使用 CodeQL CLI 版本 2.12.7。

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

下载适用于 macOS“Catalina”（或更新版本）用户的信息

在 macOS 版本 10.15（“Catalina”）及之后的版本中，需要确保 Web 浏览器不会自动提取 zip 文件。如果使用 Safari，请在下载 CodeQL CLI zip 存档之前完成以下步骤：

打开 Safari。
在 Safari 菜单中，选择“首选项...”或“设置...”（版本 13“Ventura”及其之后的版本）。
单击“常规”选项卡。
确保未选中标记为“下载后打开安全的文件”的复选框。

2. 提取 zip 存档

对于 Linux、Windows 和 macOS 用户（版本 10.14“Mojave”及更早版本），只需提取 zip 存档。

适用于 macOS“Catalina”（或更新版本）用户的提取信息

macOS "Catalina", "Big Sur", "Monterey", or "Ventura" users should run the following commands in the Terminal, where ${extraction-root} is the path to the directory where you will extract the CodeQL CLI zip archive:

mv ~/Downloads/codeql\*.zip ${extraction-root}
cd ${extraction-root}
/usr/bin/xattr -c codeql\*.zip
unzip codeql\*.zip

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 的更多信息，请参阅“在 Visual Studio Code 中设置 CodeQL”。

测试 CodeQL CLI 配置

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

codeql resolve qlpacks 如果 /<extraction-root>/codeql 位于 PATH。
否则为 /<extraction-root>/codeql/codeql resolve qlpacks。

如果成功，你应会看到与如下提取类似的输出：

codeql/cpp-all (/<extraction-root>/qlpacks/codeql/cpp-all/<version>)
codeql/cpp-examples (/<extraction-root>/qlpacks/codeql/cpp-examples/<version>)
codeql/cpp-queries (/<extraction-root>/qlpacks/codeql/cpp-queries/<version>)
codeql/csharp-all (/<extraction-root>/qlpacks/codeql/charp-all/<version>)
codeql/csharp-examples (/<extraction-root>/qlpacks/codeql/charp-examples/<version>)
codeql/csharp-queries (/<extraction-root>/qlpacks/codeql/charp-queries/<version>)
codeql/java-all (/<extraction-root>/qlpacks/codeql/java-all/<version>)
codeql/java-examples (/<extraction-root>/qlpacks/codeql/java-examples/<version>)
codeql/java-queries (/<extraction-root>/qlpacks/codeql/java-queries/<version>)
codeql/javascript-all (/<extraction-root>/qlpacks/codeql/javascript-all/<version>)
codeql/javascript-examples (/<extraction-root>/qlpacks/codeql/javascript-examples/<version>)
codeql/javascript-queries (/<extraction-root>/qlpacks/codeql/javascript-queries/<version>)
codeql/python-all (/<extraction-root>/qlpacks/codeql/python-all/<version>)
codeql/python-examples (/<extraction-root>/qlpacks/codeql/python-examples/<version>)
codeql/python-queries (/<extraction-root>/qlpacks/codeql/python-queries/<version>)
codeql/ruby-all (/<extraction-root>/qlpacks/codeql/ruby-all/<version>)
codeql/ruby-examples (/<extraction-root>/qlpacks/codeql/ruby-examples/<version>)
codeql/ruby-queries (/<extraction-root>/qlpacks/codeql/ruby-queries/<version>)
...

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

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

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

后续步骤

要了解如何准备代码以便由 CodeQL CLI 分析，请参阅“为 CodeQL 分析准备代码”。

设置 CodeQL CLI

谁可以使用此功能？

本文内容