CodeQL CLI のカスタムクエリの作成と共有

この記事では、解釈された結果を生成するために AUTOTITLE コマンドで使用するクエリを記述する方法について説明します。カスタムクエリの概念については、カスタム CodeQL クエリを参照してください。

有効なクエリの記述

カスタム分析を実行する前に、有効なクエリを記述し、.ql 拡張子付きのファイルに保存する必要があります。クエリの記述に役立つ広範なドキュメントがあります。詳しくは、「CodeQL クエリ」を参照してください。

          `database analyze` コマンドを使用してクエリを実行する場合は、結果が確実に正しく解釈されるように、次の 2 つのプロパティを含める必要があります。

クエリ識別子 (@id): / または - で区切られた小文字あるいは数字で構成される一連の単語。クエリを識別して分類します。
クエリの種類 (@kind): クエリをシンプルなアラート (@kind problem)、一連のコードの場所で文書化されたアラート (@kind path-problem)、抽出のトラブルシューティング (@kind diagnostic)、またはサマリーメトリック (@kind metric と @tags summary) として識別します。

これらのメタデータプロパティについて詳しくは、「CodeQL クエリのメタデータ」と「クエリメタデータスタイルガイド」を参照してください。

他のユーザーと共有するクエリを作成するときは、それらをカスタム CodeQL パック内に保存します。

カスタムクエリをパッケージ化するには:

CodeQL パックを作成し、そのルートディレクトリ内に qlpack.yml ファイルを配置します。
カスタムクエリ (.ql ファイル) をパックルートまたはそのサブディレクトリに保存します。
次を指定するように qlpack.yml ファイルを構成します。
- クエリをコンパイルする方法
- 他の CodeQL パッケージとライブラリへの依存関係
- クエリスイートの定義 qlpack.yml プロパティの詳細については、「 CodeQL パックを使った分析のカスタマイズ」を参照してください。
開発中のパックを GitHub Packages へ公開 - GitHub の Container registry 詳しくは、「CodeQL パックを使った分析のカスタマイズ」をご覧ください。

クエリのヘルプとドキュメント形式の詳細については、 AUTOTITLE を参照してください。

コードスキャン分析の実行時に SARIF ファイルにクエリヘルプを含めるには:

次のいずれかの形式でクエリヘルプを記述します。 * Markdown ファイル: 同じ名前のクエリと共に Markdown ファイルを保存します (たとえば、my-query.mdのmy-query.ql)。 * ** .qhelp ファイル**: .qhelp 形式でクエリヘルプを記述し、分析を実行する前に Markdown に変換します。詳しくは、「クエリヘルプファイル」と「クエリヘルプファイルのテスト」を参照してください。

       `codeql database analyze` オプションを使用して`--sarif-add-query-help`を実行します。

codeql database analyze <database> --format=sarif-latest --output=results.sarif --sarif-add-query-help

メモ

       `--sarif-add-query-help` オプションは、 CodeQL CLI v2.7.1 以降から使用できます。

        [CodeQL クエリ](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)