Advanced setup of the CodeQL CLI

You can modify your CodeQL CLI setup to use a local checkout of the CodeQL repository for analysis, set up multiple versions of the CodeQL CLI, and analyze databases you have downloaded from GitHub.

谁可以使用此功能？

CodeQL 可用于以下存储库类型：

本文内容

About advanced setup of the CodeQL CLI

If you plan to use CodeQL for more than just code scanning, you may prefer an advanced setup of the CodeQL CLI.

  • If you want to contribute to open source shared CodeQL queries, you may prefer working with the CodeQL source code directly.
  • If you want to use the latest CodeQL features to generate code scanning alerts for a codebase, but also want to analyze another codebase that is only compatible with a specific version of the CodeQL CLI, you may want to install multiple versions of the CodeQL CLI.
  • If you are researching or developing queries, you may want to download interesting or unique databases from GitHub.com.

For information on the most simple setup of the CodeQL CLI, see Setting up the CodeQL CLI.

Checking out the CodeQL source code directly

Some users prefer working with CodeQL query sources directly in order to work on or contribute to the Open Source shared queries. In order to do this, the following steps are recommended.

1. Download the CodeQL CLI tar archive

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

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

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

捆绑包还有 tar.gz 变体，这些变体与 tar.zst 变体相同，但使用效率较低的 gzip 算法进行压缩。 下载 tar.gz 变体的唯一原因是使用不支持 Zstandard 压缩算法的较旧解压缩工具。

2. Create a new CodeQL directory

Create a new directory where you can place the CLI and any queries and libraries you want to use. For example, $HOME/codeql-home.

The CLI’s built-in search operations automatically look in all of its sibling directories for the files used in database creation and analysis. Keeping these components in their own directory prevents the CLI searching unrelated sibling directories while ensuring all files are available without specifying any further options on the command line.

3. Obtain a local copy of the CodeQL queries

The CodeQL repository contains the queries and libraries required for CodeQL analysis of all supported languages. Clone a copy of this repository into codeql-home.

By default, the root of the cloned repository will be called codeql. Rename this folder codeql-repo to avoid conflicting with the CodeQL CLI that you will extract in step 1. If you use git on the command line, you can clone and rename the repository in a single step by running git clone git@github.com:github/codeql.git codeql-repo in the codeql-home folder.

Within this repository, the queries and libraries are organized into CodeQL packs. Along with the queries themselves, CodeQL packs contain important metadata that tells the CodeQL CLI how to process the query files. For more information, see Creating and working with CodeQL packs.

注意

There are different versions of the CodeQL queries available for different users. Check out the correct version for your use case:

  • For the queries that are intended to be used with the latest CodeQL CLI release, check out the branch tagged codeql-cli/latest. You should use this branch for databases you’ve built using the CodeQL CLI or recently downloaded from GitHub.
  • For the most up to date CodeQL queries, check out the main branch. This branch represents the very latest version of CodeQL’s analysis.

4. Extract the CodeQL CLI tar archive

Extract the tar archive into the directory you created in step 2.

For example, if the path to your copy of the CodeQL repository is $HOME/codeql-home/codeql-repo, then extract the CLI into $HOME/codeql-home/.

5. Launch codeql

提取后，可以通过多种方式运行 codeql 可执行文件来运行 CodeQL 进程：

  • 通过执行 <extraction-root>/codeql/codeql，其中 <extraction-root> 是要在其中提取 CodeQL CLI 包的文件夹。
  • 通过将 <extraction-root>/codeql 添加到 PATH，这样就可以像 codeql 一样运行可执行文件。

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

6. Verify your CodeQL CLI setup

CodeQL CLI has subcommands you can execute to verify that you are correctly set up to create and analyze databases:

  • Run codeql resolve languages to show which languages are available for database creation. This will list the languages supported by default in your CodeQL CLI package.
  • Run codeql resolve qlpacks to show which CodeQL packs the CLI can find. This will display the names of all the CodeQL packs directly available to the CodeQL CLI. This should include:
  • Query packs for each supported language, for example, codeql/{language}-queries. These packs contain the standard queries that will be run for each analysis.
  • Library packs for each supported language, for example, codeql/{language}-all. These packs contain query libraries, such as control flow and data flow libraries, that may be useful to query writers.
  • Example packs for each supported language, for example, codeql/{language}-examples. These packs contain useful snippets of CodeQL that query writers may find useful.
  • Legacy packs that ensure custom queries and libraries created using older products are compatible with your version of CodeQL.

Using two versions of the CodeQL CLI

If you want to use the latest CodeQL features to execute queries or CodeQL tests, but also want to prepare databases that are compatible with a specific version of CodeQL code scanning on GitHub Enterprise Server, you may need to install two versions of the CLI. You can download the versions of the CodeQL CLI that you want, and unpack both CLI archives in the same parent directory.

Downloading databases from GitHub.com

GitHub stores CodeQL databases for over 200,000 repositories on GitHub.com, which you can download using the REST API. The list of repositories is constantly growing and evolving to make sure that it includes the most interesting codebases for security research.

You can also analyze databases from GitHub.com using the CodeQL for VS Code extension. For more information, see Running CodeQL queries.

You can check if a repository has any CodeQL databases available for download using the /repos/<owner>/<repo>/code-scanning/codeql/databases endpoint. For example, to check for CodeQL databases using the GitHub CLI you would run:

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

This command returns information about any CodeQL databases that are available for a repository, including the language the database represents, and when the database was last updated. If no CodeQL databases are available, the response is empty.

When you have confirmed that a CodeQL database exists for the language you are interested in, you can download it using the following command:

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

For more information, see the documentation for the Get CodeQL database endpoint.

Before running an analysis with the CodeQL CLI, you must unzip the databases.