CodeQL CLI ソース コードの取得

ソースコードから直接 CodeQL CLI をセットアップします。

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

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

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

この記事で

オープンソースの共有クエリについて取り組んだり貢献したりするために、CodeQL のクエリ ソースを直接操作することを希望するユーザーもいます。

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 と、使用するクエリとライブラリを配置できる新しいディレクトリを作成します。 たとえば、「 $HOME/codeql-home 」のように入力します。

CLI の組み込み検索操作を行うと、データベースの作成と分析で使用されるファイルのすべての兄弟ディレクトリが自動的に検索されます。 これらのコンポーネントをそれぞれ独自のディレクトリに保持すると、関連のない兄弟ディレクトリは CLI で検索されず、コマンド ラインで追加のオプションを指定せずにすべてのファイルを使用できます。

3. CodeQL クエリのローカル コピーを取得する

          [CodeQL リポジトリ](https://github.com/github/codeql?ref_product=code-scanning&ref_type=engagement&ref_style=text)には、サポートされているすべての言語の CodeQL 分析に必要なクエリとライブラリが含まれています。

このリポジトリのコピーを codeql-home にクローンします。

既定では、クローンされたリポジトリのルートは codeql と呼ばれます。 手順 1 で抽出する CodeQL CLI と競合しないように、このフォルダー codeql-repo の名前を変更します。 コマンド ラインで git を使用する場合は、git clone git@github.com:github/codeql.git codeql-repo フォルダーで codeql-home を実行することで、1 つの手順でリポジトリのクローンと名前変更を行うことができます。

このリポジトリでは、クエリとライブラリが CodeQL パックにまとめられています。 CodeQL パックには、クエリ自体に加えて、クエリ ファイルの処理方法を CodeQL CLI に指示する重要なメタデータが含まれています。 詳しくは、「CodeQL パックの作成と操作」をご覧ください。

メモ

CodeQL クエリには、ユーザーごとに異なるバージョンがあります。 ユース ケースに合った正しいバージョンをチェックアウトしてください。

  • 最新の CodeQL CLI リリースで使用することを目的としたクエリについては、codeql-cli/latest というタグが付いたブランチをチェックアウトします。 CodeQL CLI を使用して構築したデータベース、または最近 GitHub からダウンロードしたデータベースには、このブランチを使用する必要があります。
  • 最新の CodeQL クエリについては、main ブランチをチェックアウトします。 このブランチは、CodeQL の分析の最新バージョンを表します。

4. CodeQL CLI tar アーカイブを抽出する

手順 2 で作成したディレクトリに tar アーカイブを抽出します。

たとえば、CodeQL リポジトリのコピーへのパスが $HOME/codeql-home/codeql-repo の場合は、CLI を $HOME/codeql-home/ に抽出します。

5. codeql を起動する

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

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

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

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 に対応できるようになります。