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

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

对于 GitHub Enterprise Server 3.13，建议使用 CodeQL CLI 版本 2.16.5。

应该始终使用 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 以及要使用的任何查询和库。 例如，$HOME/codeql-home。

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

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

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

默认情况下，克隆存储库的根称为 codeql。 重命名此文件夹 codeql-repo 可避免与将在步骤 1 中提取的 CodeQL CLI 发生冲突。 如果在命令行上使用 git，则可以通过在 codeql-home 文件夹中运行 git clone git@github.com:github/codeql.git codeql-repo 来一步克隆和重命名存储库。

在此存储库中，查询和库组织成 CodeQL 包。 除了查询本身，CodeQL 包还包含重要的元数据，这些元数据指示 CodeQL CLI 如何处理查询文件。 有关详细信息，请参阅“创建并使用 CodeQL 包”。

Note

不同用户可以使用不同版本的 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 下载这些存储库。 存储库列表在不断发展壮大，以确保其包含最有趣的安全研究代码库。

还可以使用适用于 VS Code 的 CodeQL 扩展，从 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 运行分析之前，必须解压缩数据库。