カスタム CodeQL クエリとは
カスタム クエリ CodeQL組み込みのセキュリティ分析を拡張して、コードベースに固有の脆弱性、コーディング標準、パターンを検出します。
メモ
database analyze で実行されるクエリには、厳密なメタデータ要件があります。 次のプラミング レベルのサブコマンドを使用してクエリを実行することもできます。
- データベース実行クエリ は、解釈されていない結果を BQRS と呼ばれる中間バイナリ形式で出力します
- クエリの実行 は、BQRS ファイルを出力するか、結果テーブルをコマンド ラインに直接出力します。 コマンド ラインで結果を直接表示すると、CLI を使用した反復クエリ開発に役立つ場合があります。
これらのコマンドを使用して実行されるクエリについては、メタデータの要件は同じではありません。 ただし、人間が判読できるデータを保存するには、bqrs をデコードする プラミング サブコマンドを使って各 BQRS 結果ファイルを処理する必要があります。 そのため、ほとんどのユース ケースの場合、データベース分析を使用して、解釈された結果を直接生成するのが最も簡単です。
カスタム クエリを使用する場合
カスタム クエリを使用して以下を行います。
- アプリケーションのアーキテクチャまたはフレームワークに固有の脆弱性を検出する
- 組織固有のコーディング標準またはベスト プラクティスを適用する
- 標準の CodeQL クエリ パックでカバーされていないパターンを検索する
- CodeQLを使用して
database analyzeコマンドを使用してCodeQL CLIデータベースを分析し、解釈された結果を生成する
クエリ構造
カスタム クエリは、 .ql 拡張機能と共に保存されるクエリ ファイルに書き込まれます。 これらのファイルには、クエリの目的に関する情報を提供し、結果の処理方法を CodeQL CLI に示す重要なメタデータも含まれています。 必須のプロパティは次のとおりです。
- クエリ識別子 (
@id): 小文字または数字。/または- - クエリの種類 (
@kind):problem- 単純なアラートpath-problem- コードの場所シーケンスを使用したアラートdiagnostic- Extractor のトラブルシューティングmetric- 概要メトリック (@tags summaryが必要)
メモ
他のアプリケーションでクエリを使用する場合は、メタデータ要件が異なることがあります。 詳細については、「CodeQL クエリのメタデータ」を参照してください。
クエリ メタデータの詳細については、「CodeQL クエリのメタデータ」および「クエリ メタデータ スタイル ガイド」を参照してください。
クエリのドキュメンテーション
クエリドキュメントは、クエリが検出した内容と、特定された問題に対処する方法をユーザーが理解するのに役立ちます。 カスタム クエリのドキュメントは、次の 2 つの形式で含めることができます。
- Markdown ファイル: クエリと共に保存され、SARIF ファイルに含め、 code scanning UI に表示できます
.qhelpファイル: 標準の CodeQL クエリと一致しますが、使用するには Markdown に変換する必要があります code scanning
クエリ ヘルプを含む SARIF ファイルを GitHubにアップロードすると、クエリによって生成されたすべてのアラートのドキュメントが code scanning UI に表示されます。
詳細については、「 ヘルプ ファイルのクエリ」を参照してください。
カスタム クエリの共有
独自のクエリ パックを発行することで、カスタム クエリをコミュニティと共有できます。 「CodeQL パックを発行して使用する」を参照してください。