CodeQL CLI を設定する

CodeQL CLIの使用を開始するには、データベースの作成と分析に必要なツールとライブラリにアクセスできるように CLI をダウンロードして設定する必要があります。

          CodeQL CLI の設定

メモ

この記事では、GitHub Enterprise Server 3.15 の初期リリースに含まれている CodeQL CLI 2.18.4 バンドルで使用できる機能について説明します。

サイト管理者が CodeQL CLI のバージョンをより新しいリリースに更新している場合は、この記事の GitHub Enterprise Cloud バージョンで最新の機能に関する情報を参照してください。

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

          CodeQL CLIでは、さまざまなユース ケースとディレクトリ構造がサポートされています。 この記事では、ほとんどのユーザーと環境で動作する簡単なセットアップについて説明します。

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

開始する前に

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

メモ

          CodeQL CLIは現在、(muslc ベースの) Alpine Linux などの非 glibc Linux ディストリビューションと互換性がありません。

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 からのクエリとライブラリの互換性のあるバージョン
バンドルに含まれるすべてのクエリのプリコンパイル済みバージョン

メモ

GitHub Enterprise Server 3.15は、CodeQL CLI バージョン 2.18.4 をお勧めします。

常に 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 アーカイブを任意のディレクトリに抽出します。

省略可能: CI システムで CodeQL CLI を使用可能にする

CI システムで CodeQLcode scanning 分析を実行する予定の場合は、分析を実行するすべての CI サーバーで、 CodeQL CLI バンドルの完全なコンテンツを使用できることを確認します。

例えば、あなたは次のことができます:

中央の内部の場所からバンドルをコピーし、各サーバーで抽出するか、または
REST API を使用して、 GitHubからバンドルを直接ダウンロードし、クエリの最新の機能強化を確実に受け取ります。詳細については、「リリースとリリース資産の REST API エンドポイント」を参照してください。

3. `codeql` を起動する

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

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

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

メモ

          `codeql`に`PATH`を追加すると、CodeQLによってアクセスされ、Visual Studio Codeがクエリをコンパイルして実行できます。

          VS CodeにアクセスするためのCodeQL CLIの構成の詳細については、[AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/configuring-access-to-the-codeql-cli) を参照してください。

          CodeQL CLI構成のテスト

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

* codeql resolve packs が /<extraction root>/codeql にある場合は、PATH。 * /<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のスタンドアロンコピーではなく、CodeQL CLI バンドルをダウンロードしたことを確認してください。

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

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

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

メモ

codeql resolve packs コマンドは、CodeQL CLI バージョン 2.19.0 以降で使用できます。それ以前のバージョンの CLI では、codeql resolve qlpacks コマンドを実行する必要があります。このコマンドにより同様の出力が生成されますが、十分な詳細は含まれていません。

次のステップ

          CodeQL CLIによって分析されるコードを準備する方法については、[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis) を参照してください。

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

この記事で