CodeQL CLI の高度なセットアップ

CodeQL CLI セットアップを変更して、分析に CodeQL リポジトリのローカル チェックアウトを使用したり、CodeQL CLI の複数のバージョンを設定したり、GitHub からダウンロードしたデータベースを分析したりできます。

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

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

この記事の内容

About advanced setup of the CodeQL CLI について

コード スキャン以外の目的で CodeQL を使用する場合は、CodeQL CLI の高度なセットアップの使用をお勧めします。

  • オープンソースの共有 CodeQL クエリにコントリビューションしたい場合は、CodeQL ソース コードを直接操作することをお勧めします。
  • 最新の CodeQL 機能を使用してコードベースのコード スキャン アラートを生成し、且つ をインストールできます。
  • クエリを調査または開発している場合は、GitHub.com から興味深いデータベースまたは一意のデータベースをダウンロードできます。

CodeQL CLI の最も簡単な設定については、「CodeQL CLI の設定」を参照してください。

CodeQL ソース コード ディレクトリをチェックアウトする

オープンソースの共有クエリについて取り組んだり貢献したりするために、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 からのクエリとライブラリの互換性のあるバージョン
  • バンドルに含まれるすべてのクエリのプリコンパイル済みバージョン
GitHub Enterprise Server 3.11 の場合は、CodeQL CLI バージョン 2.14.6 をお勧めします。

常に 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 リポジトリには、サポートされているすべての言語の CodeQL 分析に必要なクエリとライブラリが含まれています。 このリポジトリのコピーを codeql-home にクローンします。

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

CodeQL CLI の 2 つのバージョンを使用する

最新の CodeQL 機能を使用してクエリまたは CodeQL テストを実行するだけでなく、GitHub Enterprise Server で特定のバージョンの CodeQL コード スキャンと互換性のあるデータベースを準備しようとしている場合は、2 つのバージョンの CLI をインストールすることが必要になる場合があります。 必要な CodeQL CLI のバージョンをダウンロードし、両方の CLI アーカイブを同じ親ディレクトリに解凍できます。

GitHub.comからのデータベースのダウンロード

GitHub では、REST API を使用してダウンロードできる 200,000 を超えるリポジトリの CodeQL データベースを GitHub.com に保存しています。 リポジトリの一覧は、セキュリティ調査のための最も興味深いコードベースが確実に含まれるように、絶えず増加し、進化しています。

VS Code 拡張機能の CodeQL を使用して、GitHub.com からデータベースを分析することもできます。 詳しくは、「CodeQL クエリの実行」を参照してください。

/repos/<owner>/<repo>/code-scanning/codeql/databases エンドポイントを使用して、リポジトリにダウンロード可能な CodeQL データベースがあるかどうかを確認できます。 たとえば、GitHub CLI を使用して CodeQL データベースの有無を確認するには、次のように実行します。

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

このコマンドからは、リポジトリで使用できる CodeQL データベースに関する情報が返されます。データベースが表す言語や、データベースが最後に更新された日時などです。 使用できる CodeQL データベースがない場合、応答は空です。

目的の言語の CodeQL データベースが存在することを確認したら、次のコマンドを使用してダウンロードできます。

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

詳しくは、「CodeQL データベース エンドポイントの取得」のドキュメントを参照してください。

CodeQL CLI を使用して分析を実行する前に、データベースを解凍する必要があります。