CodeQL パックの作成と操作

この記事の内容

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

GitHub CodeQL は、インストール時にユーザーごとにライセンスされます。 CodeQL は、ライセンスの制限の下で特定のタスクでのみ使用できます。 詳しくは、「CodeQL CLI について」を参照してください。

GitHub Advanced Security ライセンスがある場合は、CodeQL を使用して、自動分析、継続的インテグレーション、継続的デリバリーを行うことができます。 詳しくは、「GitHub Advanced Security について」を参照してください。

注: CodeQL パッケージ管理機能 (CodeQL パックを含む) は現在ベータ版として利用でき、変更される可能性があります。 ベータ版リリース中、CodeQL パックは GitHub パッケージ (Container registry) を使用してのみ利用できます。 このベータ機能を使用するには、 https://github.com/github/codeql-action/releases から最新バージョンの CodeQL CLI バンドルをインストールします。

CodeQL パックと CodeQL CLI について

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

CodeQL パックの 、三つの タイプがあります。クエリ パック、ライブラリ パック、およびモデル パック。

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

  • ライブラリ パックは、クエリ パック (またはその他のライブラリ パック) で使用するように設計されており、クエリ自体は含まれません。 ライブラリはseparately発行されたときにコンパイル キャッシュが含まれません。

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

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

発行されたクエリ パックと異なる CodeQL リリース間の互換性について詳しくは、「CodeQL パックを発行して使用する」をご覧ください。

サポートされているすべての言語の標準 CodeQL パッケージは、Container registry で公開されています。 CodeQL リポジトリには、サポートされているすべての言語の標準 CodeQL パックのソース ファイルが含まれています。 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 モデル パックの作成

注: モデル パックは現在ベータ版で、変更される可能性があります。 ベータ版の間は、モデル パックは Java 解析でのみサポートされます。

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

既存のレガシ QL パックを変更して CodeQL パックを作成する

既に qlpack.yml ファイルがある場合は、それを手動で編集して、CodeQL パックに変換できます。

  1. <scope>/<name> 形式と一致するように name プロパティを編集します。ここで、<scope> は発行先の GitHub組織またはユーザー アカウントの名前です。

  2. qlpack.yml ファイルに、semver 識別子を持つ version プロパティと、省略可能な dependencies ブロックを含めます。

  3. libraryPathDependencies の依存関係の一覧を dependencies ブロックに移行します。 各依存関係のバージョン範囲を指定します。 範囲が重要でない場合、または互換性が不明な場合は、"\*" を指定できます。これは、任意のバージョンを受け入れることができ、codeql pack install を実行すると既定で最新バージョンに設定されることを示します。

プロパティについて詳しくは、「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 ソースよりも優先して使用されます。