CodeQL CLI の設定

CodeQL CLI を設定する

CodeQL コマンドを実行するには、データベースの作成と分析に必要なツール、クエリ、ライブラリにアクセスできるように CLI を設定する必要があります。

CodeQL CLI は、さまざまなユース ケースとディレクトリ構造をサポートするように設定できます。 すぐに使い始めるには、次の手順で説明するように、比較的簡単なセットアップを採用することをお勧めします。

セキュリティ調査やクエリのテストまたは投稿に CodeQL CLI を使用する場合は、CodeQL CLI のより高度なセットアップが必要になる場合があります。 詳しくは、「CodeQL CLI の高度なセットアップ」をご覧ください。

CI システムで CodeQL CLI を設定している場合は、CodeQL code scanning 分析を実行するすべての CI サーバーで、CodeQL CLI バンドルの完全なコンテンツを利用できるようにする必要があります。 たとえば、内部的な中央の場所からバンドルをコピーして展開するよう、各サーバーを設定することになるでしょう。 あるいはREST APIを使ってバンドルをGitHubから直接取得し、クエリに対する最新の改善を活用できるようにすることもできます。 詳しくは、REST API ドキュメントの「リリースとリリース資産の REST API エンドポイント」をご覧ください。

Apple シリコン (例: Apple M1) の macOS を使用している場合は、Xcode コマンド ライン開発者ツールと Rosetta 2 がインストールされていることを確実にします。

1. CodeQL CLI の tar アーカイブをダウンロードする

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. CodeQL CLI の tar アーカイブを抽出する

CodeQL CLI の tar アーカイブを任意のディレクトリに抽出します。

3. codeql を起動する

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

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

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

CodeQL CLI の構成のテスト

CodeQL CLI バンドルを抽出したら、次のコマンドを実行し、データベースを作成して分析するように CLI が正しく構成されたことを確認できます。

• /<extraction root>/codeql が PATH にある場合は、codeql resolve packs。
• それ以外の場合は /<extraction root>/codeql/codeql resolve packs。

成功すると、以下の抜粋のような出力が表示されます。

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
...

結果は簡潔にするために切り捨てられています。 実際の結果はより長く、より詳細になります。

出力が期待した言語を含んでいるか、そしてqlpackファイルのディレクトリの場所が正しいかもチェックする必要があります。 場所は、抽出された CodeQL CLI バンドル内にある必要があります (前の例では <extraction root> として示されています)。 CodeQL CLIが期待された言語のqlpackの場所を知ることができないなら、CodeQL CLIのスタンドアローンのコピーではなくCodeQLバンドルをダウンロードしたかを確認してください。

codeql resolve languages を実行して、データベースの作成に使用できる言語を表示することもできます。 これを使用すると、CodeQL CLI パッケージで既定でサポートされている言語が一覧表示されます。

オプションで、実行したい事前コンパイル済のクエリを含むいくつかの CodeQL パックをダウンロードできます。 詳しくは、「CodeQL パックを使った分析のカスタマイズ」をご覧ください。

codeql resolve packs コマンドは、CodeQL CLI で分析に使用できるクエリ パックが見つからない場合の問題の診断に役立ちます。

次のステップ

CodeQL CLI によって分析されるコードを準備する方法については、「CodeQL 分析のためのコードの準備」をご覧ください。