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