CodeQL CLI 高级设置

您可以修改 CodeQL CLI 设置以使用 CodeQL 仓库的本地检出进行分析，设置多个版本的 CodeQL CLI，以及分析您从 GitHub 下载的数据库。

谁可以使用此功能？

CodeQL 可用于以下代码仓库类型

本文档内容

关于 CodeQL CLI 的高级设置

如果您计划将 CodeQL 用于不仅仅是代码扫描，则可能更喜欢 CodeQL CLI 的高级设置。

  • 如果您想为开源共享 CodeQL 查询做出贡献，则可能更喜欢直接使用 CodeQL 源代码。
  • 如果您想使用最新的 CodeQL 功能为代码库生成代码扫描警报，但也想分析另一个仅与特定版本的 CodeQL CLI 兼容的代码库，则可能需要安装多个版本的 CodeQL CLI。
  • 如果您正在研究或开发查询，则可能需要从 GitHub.com 下载有趣或独特的数据库。

有关 CodeQL CLI 最简单设置的信息，请参阅“设置 CodeQL CLI”。

直接检出 CodeQL 源代码

一些用户更喜欢直接使用 CodeQL 查询源来处理或贡献开源共享查询。为此，建议执行以下步骤。

1. 下载 CodeQL CLI tar 归档文件

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

您应该从 https://github.com/github/codeql-action/releases 下载 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 以及您要使用的任何查询和库。例如，$HOME/codeql-home。

CLI 的内置搜索操作会自动在其所有同级目录中查找数据库创建和分析中使用的文件。将这些组件保存在其自己的目录中，可以防止 CLI 搜索无关的同级目录，同时确保所有文件都可用，而无需在命令行上指定任何其他选项。

3. 获取 CodeQL 查询的本地副本

CodeQL 仓库包含所有受支持语言的 CodeQL 分析所需的查询和库。将此仓库的副本克隆到codeql-home。

默认情况下，克隆的仓库的根目录将命名为codeql。将其重命名为codeql-repo，以避免与您将在步骤 1 中提取的 CodeQL CLI 冲突。如果您在命令行上使用 git，则可以通过在codeql-home文件夹中运行git clone [email protected]:github/codeql.git codeql-repo来在一个步骤中克隆和重命名仓库。

在此仓库中，查询和库被组织成 CodeQL 包。除了查询本身之外，CodeQL 包还包含重要的元数据，这些元数据告诉 CodeQL CLI 如何处理查询文件。有关更多信息，请参阅“创建和使用 CodeQL 包”。

注意

针对不同的用户，提供了不同版本的 CodeQL 查询。请检出适合您用例的正确版本。

  • 对于旨在与最新 CodeQL CLI 版本一起使用的查询，请检出标记为codeql-cli/latest的分支。您应该将此分支用于使用 CodeQL CLI 构建或最近从 GitHub 下载的数据库。
  • 对于最新的 CodeQL 查询，请检出main分支。此分支代表 CodeQL 分析的最新版本。

4. 解压 CodeQL CLI tar 归档文件

将 tar 归档文件解压到您在步骤 2 中创建的目录中。

例如，如果 CodeQL 仓库副本的路径为$HOME/codeql-home/codeql-repo，则将 CLI 解压到$HOME/codeql-home/。

5. 启动codeql

解压后，您可以通过以下两种方式运行 CodeQL 进程：运行codeql可执行文件。

  • 执行<extraction-root>/codeql/codeql，其中<extraction-root>是您解压 CodeQL CLI 包的文件夹。
  • 将<extraction-root>/codeql添加到您的PATH中，以便您可以像运行codeql一样运行可执行文件。

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

6. 验证您的 CodeQL CLI 设置

CodeQL CLI 有一些您可以执行的子命令，以验证您是否已正确设置以创建和分析数据库。

  • 运行codeql resolve languages以显示哪些语言可用于数据库创建。这将列出 CodeQL CLI 包中默认支持的语言。
  • 运行codeql resolve qlpacks以显示 CLI 可以找到哪些 CodeQL 包。这将显示 CodeQL CLI 直接可用的所有 CodeQL 包的名称。这应该包括：
  • 每种受支持语言的查询包，例如codeql/{language}-queries。这些包包含将在每次分析中运行的标准查询。
  • 每种受支持语言的库包，例如codeql/{language}-all。这些包包含查询库，例如控制流和数据流库，这些库可能对查询编写者有用。
  • 每种受支持语言的示例包，例如codeql/{language}-examples。这些包包含查询编写者可能觉得有用的 CodeQL 代码片段。
  • 确保使用旧产品创建的自定义查询和库与您的 CodeQL 版本兼容的旧版包。

使用两个版本的 CodeQL CLI

如果您想使用最新的 CodeQL 功能来执行查询或 CodeQL 测试，但又希望准备与 GitHub Enterprise Server 上特定版本的 CodeQL 代码扫描兼容的数据库，则可能需要安装两个版本的 CLI。您可以下载所需的 CodeQL CLI 版本，并将两个 CLI 归档文件解压到同一个父目录中。

从 GitHub.com 下载数据库

GitHub 在 GitHub.com 上存储了超过 200,000 个仓库的 CodeQL 数据库，您可以使用 REST API 下载这些数据库。仓库列表不断增长和发展，以确保它包含最有趣的安全研究代码库。

您还可以使用 CodeQL for VS Code 扩展分析来自 GitHub.com 的数据库。有关更多信息，请参阅“运行 CodeQL 查询”。

您可以使用/repos/<owner>/<repo>/code-scanning/codeql/databases端点检查仓库是否有任何可供下载的 CodeQL 数据库。例如，要使用GitHub CLI检查 CodeQL 数据库，您需要运行：

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases

此命令将返回有关仓库中可用的任何 CodeQL 数据库的信息，包括数据库代表的语言以及数据库上次更新的时间。如果没有可用的 CodeQL 数据库，则响应为空。

确认您感兴趣的语言存在 CodeQL 数据库后，您可以使用以下命令下载它：

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/<language> -H 'Accept: application/zip' > path/to/local/database.zip

有关更多信息，请参阅获取 CodeQL 数据库端点的文档。

在使用 CodeQL CLI 运行分析之前，必须解压数据库。