设置 CodeQL CLI

本文内容

若要开始使用 CodeQL CLI，需要下载并设置 CLI，以便它可以访问创建和分析数据库所需的工具和库。

GitHub CodeQL 在安装后按用户授权。 根据许可证限制，只能将 CodeQL 用于某些任务。 有关详细信息，请参阅“关于 CodeQL CLI”。

如果你有 GitHub Advanced Security 许可证，则可以使用 CodeQL 进行自动分析、持续集成和持续交付。 有关详细信息，请参阅“关于 GitHub 高级安全性”。

设置 CodeQL CLI

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

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

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

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

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

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

1. 下载 CodeQL CLI zip 包

The CodeQL CLI download package is a zip archive containing tools, scripts, and various CodeQL-specific files. If you don’t have a GitHub Enterprise license then, by downloading this archive, you are agreeing to the GitHub CodeQL Terms and Conditions.

You should download the CodeQL bundle from https://github.com/github/codeql-action/releases. The bundle contains:

  • CodeQL CLI product
  • A compatible version of the queries and libraries from https://github.com/github/codeql
  • Precompiled versions of all the queries included in the bundle

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

注意：CodeQL 包管理功能（包括 CodeQL 包）当前为 beta 版本，可能会发生更改。

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

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

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

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:

  1. mv ~/Downloads/codeql\*.zip ${extraction-root}
  2. cd ${extraction-root}
  3. /usr/bin/xattr -c codeql\*.zip
  4. 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 分析准备代码”。