Setting up the CodeQL CLI

To get started with the CodeQL CLI, you need to download and set up the CLI so that it can access the tools and libraries required to create and analyze databases.

この機能を使用できるユーザーについて

CodeQL は、次の種類のリポジトリで使用できます:

  • GitHub.com のパブリック リポジトリについては、「GitHub CodeQL の使用条件」を参照してください
  • GitHub Code Security が有効になっている GitHub Team または GitHub Enterprise Cloud 上の organization 所有のリポジトリ

この記事で

Setting up the CodeQL CLI

To run CodeQL commands, you need to set up the CodeQL CLI so that it can access the tools, queries, and libraries required to create and analyze databases.

The CodeQL CLI supports a range of use cases and directory structures. This article walks through a simple setup that works for most users and environments.

If you plan to use the CodeQL CLI for security research or to test or contribute queries, you may need a more advanced setup. For more information, see CodeQL CLI について.

Before you begin

If you are using macOS on Apple Silicon (for example, Apple M1), ensure that the Xcode command-line developer tools and Rosetta 2 are installed.

メモ

The CodeQL CLI is currently not compatible with non-glibc Linux distributions such as (muslc-based) Alpine Linux.

1. Download the CodeQL CLI tar archive

CodeQL CLI ダウンロード パッケージは、ツールおよびスクリプトと、さまざまな CodeQL 固有のファイルを含む tar アーカイブです。 GitHub Enterprise ライセンスをお持ちでない場合は、このアーカイブをダウンロードすることで、GitHub CodeQL の使用条件に同意したことになります。

CodeQL バンドルを https://github.com/github/codeql-action/releases からダウンロードする必要があります。 このバンドルには次のものが含まれています。

  • CodeQL CLI製品
  • https://github.com/github/codeql からのクエリとライブラリの互換性のあるバージョン
  • バンドルに含まれるすべてのクエリのプリコンパイル済みバージョン

常に CodeQL バンドルを使用する必要があります。 これにより互換性が保証され、CodeQL CLI のダウンロードと CodeQL クエリのチェックアウトを別に行うよりもはるかに良いパフォーマンスが得られます。 1 つの特定のプラットフォームでのみ CLI を実行する場合は、適切な codeql-bundle-PLATFORM.tar.zst ファイルをダウンロードします。 または、サポートされているすべてのプラットフォーム用の CLI を含む codeql-bundle.tar.zst をダウンロードすることもできます。

バンドルには tar.gz バリアントもありますが、これは効率の低い gzip アルゴリズムを使用して圧縮する以外は tar.zst バリアントと同じです。 tar.gz バリアントをダウンロードする唯一の理由は、Zstandard 圧縮アルゴリズムをサポートしていない古い展開ツールを使用している場合です。

2. Extract the CodeQL CLI tar archive

Extract the CodeQL CLI tar archive to a directory of your choosing.

Optional: Make the CodeQL CLI available in your CI system

If you plan to run CodeQL code scanning analysis in a CI system, ensure that the full contents of the CodeQL CLI bundle are available to every CI server that will run analysis.

For example, you can:

3. Launch codeql

抽出後、codeql の実行可能ファイルを実行することで、CodeQL プロセスを実行できます。方法は 2 通りあります。

  • <extraction-root>/codeql/codeql を実行します。ここで、<extraction-root> は CodeQL CLI パッケージを抽出したフォルダーです。
  • <extraction-root>/codeql を PATH に追加すると、実行可能ファイルを codeql として実行することができます。

この時点で、CodeQL のコマンドを実行できます。 CodeQL CLI コマンドの完全な一覧については、「CodeQL CLI コマンドのマニュアル」を参照してください。

メモ

If you add codeql to your PATH, it can be accessed by CodeQL for Visual Studio Code to compile and run queries. For more information about configuring VS Code to access the CodeQL CLI, see Managing the CodeQL CLI in the VS Code extension.

Testing the CodeQL CLI configuration

After you extract the CodeQL CLI bundle, you can run the following command to verify that the CLI is correctly configured to create and analyze databases:

  • codeql resolve packs if /<extraction root>/codeql is on the PATH.
  • /<extraction root>/codeql/codeql resolve packs otherwise.

If successful, you should see output similar to the extract below:

Searching directories specified by `--additional-packs`. All directories have equal priority.
  Searching in:
    No packs were found at this location.
Searching directories specified by `--search-path`. Directories are searched in order.
Searching the root of the CodeQL distribution.
  Searching in:
      <extraction root>
    The following packs were found:
      codeql/java-all@<version>: (library) <extraction root>/qlpacks/codeql/javat-all/<version>/qlpack.yml
      codeql/java-queries@<version>: (query) <extraction root>/qlpacks/codeql/java-queries/<version>/qlpack.yml
      codeql/javascript-all@<version>: (library) <extraction root>/qlpacks/codeql/javascript-all/<version>/qlpack.yml
      codeql/javascript-queries@<version>: (query) <extraction root>/qlpacks/codeql/javascript-queries/<version>/qlpack.yml
      codeql/swift-all@<version>: (library) <extraction root>/qlpacks/codeql/swift-all/<version>/qlpack.yml
      codeql/swift-queries@<version>: (query) <extraction root>/qlpacks/codeql/swift-queries/<version>/qlpack.yml
...

The results have been truncated for brevity. The actual results will be longer and more detailed.

You should check that the output contains the expected languages and also that the directory location for the qlpack files is correct. The location should be within the extracted CodeQL CLI bundle, shown in the earlier example as <extraction root>. If the CodeQL CLI is unable to locate the qlpacks for the expected languages, check that you downloaded the CodeQL bundle and not a standalone copy of the CodeQL CLI.

You can also 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.

Optionally, you can download some CodeQL packs containing pre-compiled queries you would like to run. For more information, see CodeQL パックを使った分析のカスタマイズ.

The codeql resolve packs command is useful for diagnosing problems when the CodeQL CLI is unable to locate query packs that you expect to be available for analysis.

メモ

The codeql resolve packs command is available in the CodeQL CLI versions 2.19.0 and later. For earlier versions of the CLI, you should run the codeql resolve qlpacks command, which produces similar, but less detailed output.

Next steps

To learn how to prepare your code to be analyzed by the CodeQL CLI, see CodeQL 分析用コードを準備する.