注: この記事は、2023 年 1 月に CodeQL ドキュメント Web サイトから移行されました。
カスタム クエリと CodeQL CLI について
特定の脆弱性やエラーを強調表示する独自のクエリを記述して、CodeQL 分析をカスタマイズすることができます。
このトピックでは、database analyze コマンドで使用するクエリを記述して解釈された結果を得る方法について具体的に説明します。
注: database analyze で実行されるクエリには、厳密なメタデータ要件があります。 次のプラミング レベルのサブコマンドを使用してクエリを実行することもできます。
- database run-queries は、解釈されていない結果を BQRS と呼ばれる中間バイナリ形式で出力します
- クエリの実行 は、BQRS ファイルを出力するか、結果テーブルをコマンド ラインに直接出力します。 コマンド ラインで結果を直接表示すると、CLI を使用した反復クエリ開発に役立つ場合があります。
これらのコマンドを使用して実行されるクエリについては、メタデータの要件は同じではありません。 ただし、人間が判読できるデータを保存するには、bqrs decode プラミング サブコマンドを使って各 BQRS 結果ファイルを処理する必要があります。 そのため、ほとんどのユース ケースの場合、データベース分析を使用して、解釈された結果を直接生成するのが最も簡単です。
有効なクエリの記述
カスタム分析を実行する前に、有効なクエリを記述し、.ql 拡張子付きのファイルに保存する必要があります。 クエリの記述に役立つ広範なドキュメントがあります。 詳しくは、「CodeQL クエリ」を参照してください。
クエリ メタデータを含める
クエリ メタデータは各クエリ ファイルの先頭に含まれます。 これにより、クエリに関する情報がユーザーに提供され、CodeQL CLI にクエリ結果の処理方法が示されます。
database analyze コマンドを使用してクエリを実行する場合は、結果が確実に正しく解釈されるように、次の 2 つのプロパティを含める必要があります。
-
クエリ識別子 (
@id):/または-で区切られた小文字あるいは数字で構成される一連の単語。クエリを識別して分類します。 -
クエリの種類 (
@kind): クエリをシンプルなアラート (@kind problem)、一連のコードの場所で文書化されたアラート (@kind path-problem)、抽出のトラブルシューティング (@kind diagnostic)、またはサマリー メトリック (@kind metricと@tags summary) として識別します。
これらのメタデータ プロパティについて詳しくは、「CodeQL クエリのメタデータ」と「クエリ メタデータ スタイル ガイド」を参照してください。
注: 他のアプリケーションでクエリを使用する場合は、メタデータ要件が異なることがあります。 詳しくは、「CodeQL クエリのメタデータ」を参照してください。
カスタム QL クエリのパッケージ化
注: CodeQL パックを含む CodeQL パッケージ管理機能は、現在ベータ版リリースであり、変更される可能性があります。 ベータ版リリース中、CodeQL パックは GitHub パッケージ (Container registry) を使用してのみ利用できます。 このベータ機能を使用するには、 https://github.com/github/codeql-action/releases から最新バージョンの CodeQL CLI バンドルをインストールします。
他のユーザーと共有する目的で独自のクエリを記述する場合は、カスタム CodeQL パックに保存する必要があります。 このパックは、CodeQL パックとして GitHub Packages - GitHub Container registry に発行できます。 詳しくは、「CodeQL パックについて」を参照してください。
CodeQL パックでは、CodeQL 分析で使用されるファイルをまとめ、クエリ、ライブラリ ファイル、クエリ スイート、および重要なメタデータを格納できます。 そのルート ディレクトリには、qlpack.yml という名前のファイルが含まれている必要があります。 カスタム クエリは、CodeQL パック ルートまたはそのサブディレクトリに保存する必要があります。
CodeQL パックごとに、qlpack.yml ファイルには、クエリのコンパイル方法、パックが依存する他の CodeQL パックとライブラリ、およびクエリ スイート定義の検索場所を CodeQL CLI に示す情報が含まれています。 このファイルに含める内容について詳しくは、「CodeQL パックについて」を参照してください。
CodeQL リポジトリへの投稿
他の CodeQL ユーザーとクエリを共有したい場合は、CodeQL リポジトリで pull request を開くことができます。 詳しくは、「CodeQL への投稿」を参照してください。