CodeQL パックの作成と操作

CodeQL パックを使用して、CodeQL クエリとライブラリを作成、共有、依存、および実行できます。

この機能を使用できるユーザーについて

CodeQL は、次の種類のリポジトリで使用できます:

この記事の内容

CodeQL パックと CodeQL CLI について

CodeQL パックを使用して、CodeQL クエリとライブラリを作成、共有、実行したり、これらに依存したりすることができます。 CodeQL パックには、クエリ、ライブラリ ファイル、クエリ スイート、メタデータが含まれます。 CodeQL パックと CodeQL CLI のパッケージ管理コマンドを使用すると、カスタム クエリを発行してコードベース分析に統合できます。

CodeQL パックには、クエリ パック、ライブラリ パック、モデル パックの 3 種類があります。

  • クエリ パックは、実行するように設計されています。 クエリ パックが発行されると、バンドルには、クエリ ソースに加えて、各クエリのすべての推移的な依存関係とプリコンパイル済みの表現が含まれます。 これにより、パック内のクエリの一貫した効率的な実行が保証されます。

  • ライブラリ パックは、クエリ パック (またはその他のライブラリ パック) で使用するように設計されており、クエリ自体は含まれません。 ライブラリは個別にコンパイルされません。

  • モデル パックを使用すると、code scanning 分析を展開して、既定ではサポートされていない依存関係を含めることができます。 モデル パックは現在 パブリック プレビュー にあり、変更される可能性があります。 パブリック プレビュー 期間中、モデル パックは C/C++、C#、Java/Kotlin、Python、Ruby 解析に使用できます。 独自のモデル パックを作成する方法の詳細については、「CodeQL モデル パックの作成」を参照してください。

CodeQL CLI の pack コマンドを使用して、CodeQL パックを作成したり、パックに依存関係を追加したり、依存関係をインストールまたは更新したりできます。 pack コマンドを使用して、CodeQL パックを発行してダウンロードすることもできます。 詳しくは、「CodeQL パックを発行して使用する」をご覧ください。

公開されたクエリ パックとさまざまな CodeQL リリースの間の互換性に関する詳細については、「CodeQL パックを発行して使用する」を参照してください。

サポートされているすべての言語の標準 CodeQL パッケージは、Container registry で公開されています。 CodeQL リポジトリには、サポートされているすべての言語の標準 CodeQL パックのソース ファイルが含まれています。 Cコア クエリ パックは CodeQL CLI バンドルに含まれていますが、別途ダウンロードできるコア クエリ パックは次のとおりです。

  • codeql/cpp-queries
  • codeql/csharp-queries
  • codeql/go-queries
  • codeql/java-queries
  • codeql/javascript-queries
  • codeql/python-queries
  • codeql/ruby-queries

CodeQL パックの構造

CodeQL パックのルート ディレクトリには、qlpack.yml という名前のファイルが含まれている必要があります。 qlpack.yml ファイルの name: フィールドには、形式 <scope>/<pack> に従う値が必要です。ここで、<scope> は、パックが発行される GitHub組織またはユーザー アカウントで、<pack> はパックの名前です。 さらに、CodeQL テストを含むクエリ パックとライブラリ パックには、パックの解決された依存関係を含む codeql-pack.lock.yml ファイルが含まれます。 このファイルは、codeql pack install コマンドの呼び出し中に生成され、手動で編集するためのものではなく、バージョン管理システムに追加する必要があります。

パック内のその他のファイルとディレクトリは論理的に整理されます。 たとえば、通常は次のようになります。

  • クエリは、特定のカテゴリのディレクトリに整理されます。

  • 特定の製品、ライブラリ、フレームワークのクエリは、それぞれ独自のトップレベル ディレクトリに整理されます。

CodeQL パックの作成

プロジェクトのチェックアウト ルートから次のコマンドを実行して、CodeQL パックを作成できます。

codeql pack init <scope>/<pack>

ユーザーは次のものを指定する必要があります。

  • <scope>: 発行先の GitHub組織またはユーザー アカウントの名前。

  • <pack>: 作成するパックの名前。

codeql pack init コマンドにより、CodeQL パックのディレクトリ構造と構成ファイルが作成されます。 既定では、コマンドによってクエリ パックが作成されます。 ライブラリ パックを作成する場合は、library:true プロパティを含めることでファイルをライブラリ パックとして明示的に宣言するように qlpack.yml ファイルを編集する必要があります。

CodeQL モデル パックの作成

メモ

CodeQL モデル パックは現在 パブリック プレビュー 段階であり、変更される可能性があります。 モデル パックは C/C++、C#、Java/Kotlin、Python、Ruby 分析でサポートされます。

Visual Studio Code 用 CodeQL 拡張機能の CodeQL モデル エディターでは、C#、Java/Kotlin、Python、Ruby に対する依存関係のモデリングがサポートされています。

モデル パックを使用すると、code scanning 分析を展開して、既定でサポートされていないライブラリとフレームワークを認識できます。 モデル パックでは、YAML として実装されるデータ拡張機能を使用し、新しい依存関係のデータを追加する方法を説明します。 モデル パックを指定すると、そのパック内のデータ拡張機能が code scanning 分析に自動的に追加されます。 CodeQL モデル パックとデータ拡張機能の詳細については、「CodeQL モデル エディターの使用」を参照してください。

モデル パックは、qlpack.yml ファイル内の次の特性を持つ CodeQL パックです。

  • これは library: true を定義します。
  • 依存関係はありません。
  • それは1つ以上 extensionTargets を持っています.
  • 1 つ以上のデータ拡張ファイルを指す dataExtensions プロパティがあります。

モデル パックは、指定されたバージョン範囲内にある場合、指定されたデータ拡張機能を、extensionTargets に名前が付けられた各クエリ パックに挿入します。 次に例を示します。

name: my-repo/my-java-model-pack
version: 1.2.3
extensionTargets:
  codeql/java-all: ~1.2.3
  codeql/util: ~4.5.6
dataExtensions:
  - models/**/*.yml

この例では、モデル パックによって、models/**/ のすべてのデータ拡張機能が、1.2.3 から最大および 1.3.0 を含むバージョンの codeql/java-all クエリ パックと、4.5.6 から最大および 4.6.0 を含むバージョンの codeql/util クエリ パックに挿入されます。 詳しくは、「セマンティック バージョニングの使用」(npm のドキュメント内) と「セマンティック バージョニングの仕様」を参照してください。

モデル パックを作成したら、他の CodeQL パックと同じ方法で発行できます。 詳しくは、「CodeQL パックを発行して使用する」をご覧ください。 その後、発行されたモデル パックを、--model-packs オプションを使用して code scanning 分析で使用できます。 詳しくは、「CodeQL パックを使った分析のカスタマイズ」をご覧ください。

CodeQL パックへの依存関係の追加とインストール

メモ

これは、CodeQL クエリ パックとライブラリ パックでのみサポートされます。

コマンド codeql pack add を使用して、CodeQL パックに依存関係を追加できます。 スコープ、名前、および (必要に応じて) 互換性のあるバージョン範囲を指定する必要があります。

codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>

バージョン範囲を指定しない場合は、最新バージョンが追加されます。 それ以外の場合は、要求された範囲を満たす最新バージョンが追加されます。

このコマンドを実行すると、要求された依存関係で qlpack.yml ファイルが更新され、パッケージ キャッシュにダウンロードされます。 このコマンドを実行すると、ファイルが再フォーマットされ、すべてのコメントが削除されることに注意してください。

qlpack.yml ファイルを手動で編集して依存関係を含め、コマンドを使用して依存関係をインストールすることもできます。

codeql pack install

このコマンドを実行すると、すべての依存関係がローカル ディスク上の共有キャッシュにダウンロードされます。

メモ

  • codeql pack add と codeql pack install コマンドを実行すると、codeql-pack.lock.yml ファイルが生成または更新されます。 このファイルはバージョン管理にチェックインする必要があります。 codeql-pack.lock.yml ファイルには、パックで使用される正確なバージョン番号が含まれています。 詳しくは、「codeql-pack.lock.yml ファイルについて」を参照してください。
  • 既定では、codeql pack install により、GitHub.com の Container registry から依存関係がインストールされます。 qlconfig.yml ファイルを作成することで、GitHub Enterprise Server Container registry から依存関係をインストールできます。 詳しくは、GitHub Enterprise Server のドキュメントの「CodeQL パックを発行して使用する」を参照してください。

ダウンロードした CodeQL パックのカスタマイズ

パックの変更を試す場合は、ソース コードを含むリポジトリをクローンすることをお勧めします。

ソース リポジトリを使用できず、Container registry からダウンロードしたパックに基づいて変更を行う必要がある場合、これらのパックはダウンロード後に変更やカスタマイズされるものではなく、今後、十分な通知なしに形式が変更される可能性があることに注意してください。 コンテンツを変更する必要がある場合は、パックをダウンロードした後に次の手順を行うことをお勧めします。

  • qlpack.yml でパックの ''名前'' を変更して、変更されていないパックの結果との混同を避けるようにします。__

  • アンパックされたディレクトリ構造内の任意の場所にある *.qlx という名前のファイルをすべて削除します。 これらのファイルにはプリコンパイル済みバージョンのクエリが含まれており、場合によっては、CodeQL では、変更した QL ソースよりも優先して使用されます。