CodeQL CLI 入门

CodeQL CLI 入门

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

设置 CodeQL CLI

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

如果使用 Linux、Windows 或 macOS 版本 10.14（“Mojave”）或更早版本，只需按照以下步骤操作即可。 对于 macOS 版本 10.15（“Catalina”）或更新版本，针对某些步骤提供有附加说明。 如果在 Apple Silicon（例如 Apple M1）上使用 macOS，请确保已安装 Xcode 命令行开发人员工具和 Rosetta 2。

有关在 CI 系统中安装 CodeQL CLI 以创建在 GitHub 中显示为代码扫描警报的结果的信息，请参阅在 CI 系统中安装 CodeQL CLI。

1. 下载 CodeQL CLI zip 包

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

如果使用 Linux、Windows 或 macOS 版本 10.14（“Mojave”）或更早版本，只需下载所需版本的 zip 存档即可。

如果需要特定平台的 CLI，请下载相应的 codeql-PLATFORM.zip 文件。 此外，也可以下载包含所有受支持平台的 CLI 的 codeql.zip。

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

如果使用 macOS 版本 10.15（“Catalina”）、版本 11（“Big Sur”）或即将推出的版本 12（“Monterey”），需要确保 Web 浏览器不会自动提取 zip 文件。 如果使用 Safari，请在下载 CodeQL CLI zip 存档之前完成以下步骤：

1. 打开 Safari。
2. 在 Safari 菜单中，选择“首选项...”。
3. 单击“常规”选项卡。
4. 确保未选中标记为“下载后打开安全的文件”的复选框。

2. 提取 zip 存档

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

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

macOS“Catalina”、“Big Sur”或“Monterey”用户应在终端中运行以下命令，其中 ${extraction-root} 是提取 CodeQL CLI zip 存档的目录的路径：

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 命令手册”。

4. 验证 CodeQL CLI 设置

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

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

• （可选）可以下载一些“CodeQL 包”，其中包含要运行的预编译查询。 若要实现该操作，请运行 codeql pack download <pack-name> [...pack-name]，其中 pack-name 是要下载的包的名称。 可以从核心查询包开始。 它们是：

  • codeql/cpp-queries
  • codeql/csharp-queries
  • codeql/go-queries
  • codeql/java-queries
  • codeql/javascript-queries
  • codeql/python-queries
  • codeql/ruby-queries

或者，可以在分析期间使用 codeql database analyze 命令的 --download 标志下载查询包。

直接签出 CodeQL 源代码

某些用户更喜欢直接使用 CodeQL 查询源，以便处理或参与开放源代码共享查询。 为此，建议执行以下步骤： 请注意，以下说明是使用 CodeQL 包的一种较为复杂的替代方法，如上所述。

1. 下载 CodeQL CLI zip

按照上一部分中的步骤 1 进行操作。

2. 创建新的 CodeQL 目录

创建一个新目录，可在其中放置 CLI 以及要使用的任何查询和库。 例如，$HOME/codeql-home。

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

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

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

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

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

4. 提取 zip 存档

对于 Linux、Windows 和 macOS 用户（版本 10.14“Mojave”及更早版本），只需将 zip 存档提取到步骤 2 中创建的目录。

例如，如果 CodeQL 存储库副本的路径为 $HOME/codeql-home/codeql-repo，则将 CLI 提取到 $HOME/codeql-home/。

5. 启动 codeql

请参阅上一部分中的步骤 3。

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。 建议的目录设置取决于要安装的版本：

• 如果两个版本均为 2.0.2（或更新版本），则可以将两个 CLI 存档解压缩到同一父目录中。
• 如果至少有一个版本是 2.0.1（或更低版本），则解压缩的 CLI 存档不能位于同一父目录中，但它们可以共享同一祖父目录。 例如，如果将版本 2.0.2 解压缩到 $HOME/codeql-home/codeql-cli 中，则应将旧版本解压缩到 $HOME/codeql-older-version/old-codeql-cli 中。 在这里，共同的祖父级为 $HOME 目录。