カスタム クエリと CodeQL CLI について
特定の脆弱性やエラーを強調表示する独自のクエリを記述して、CodeQL 分析をカスタマイズすることができます。
このトピックでは、database analyze コマンドで使用するクエリを記述して解釈された結果を得る方法について具体的に説明します。
Note
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 パックとして GitHub Packages - GitHub Container registry に発行できます。 詳しくは、「CodeQL パックを使った分析のカスタマイズ」を参照してください。
CodeQL パックでは、CodeQL 分析で使用されるファイルをまとめ、クエリ、ライブラリ ファイル、クエリ スイート、および重要なメタデータを格納できます。 そのルート ディレクトリには、qlpack.yml という名前のファイルが含まれている必要があります。 カスタム クエリは、CodeQL パック ルートまたはそのサブディレクトリに保存する必要があります。
CodeQL パックごとに、qlpack.yml ファイルには、クエリのコンパイル方法、パックが依存する他の CodeQL パックとライブラリ、およびクエリ スイート定義の検索場所を CodeQL CLI に示す情報が含まれています。 このファイルに含める内容について詳しくは、「CodeQL パックを使った分析のカスタマイズ」を参照してください。
SARIF ファイルにカスタム CodeQL クエリのクエリ ヘルプを含める
CodeQL CLI を使用してサードパーティの CI/CD システムでコード スキャン分析を実行する場合は、分析中に生成された SARIF ファイルにカスタム クエリのクエリ ヘルプを含めることができます。 SARIF ファイルを GitHub にアップロードした後、カスタム クエリによって生成された警告のコード スキャン UI にクエリ ヘルプが表示されます。
CodeQL CLI v2.7.1 以降では、codeql database analyze の実行時に --sarif-add-query-help オプションを指定することで、SARIF ファイルに Markdown レンダリング クエリ ヘルプを含めることができます。
カスタム クエリのクエリ ヘルプを Markdown ファイルに直接記述し、対応するクエリと共に保存できます。 または、標準の CodeQL クエリとの一貫性を保つために、クエリ ヘルプを .qhelp 形式で記述することもできます。 .qhelp ファイルに書き込まれたクエリ ヘルプは SARIF ファイルに含めることはできません。また、コード スキャンでは処理できないため、分析を実行する前に Markdown に変換する必要があります。 詳しくは、「クエリ ヘルプ ファイル」と「クエリ ヘルプ ファイルのテスト」をご覧ください。
CodeQL リポジトリへの投稿
他の CodeQL ユーザーとクエリを共有したい場合は、CodeQL リポジトリで pull request を開くことができます。 詳しくは、「CodeQL への投稿」を参照してください。