CodeQL パックの作成と操作

CodeQL パックと CodeQL CLI について

CodeQL パックを使用して、CodeQL クエリとライブラリを作成、共有、実行したり、これらに依存したりすることができます。

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

CodeQL パックの作成

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

codeql pack init <scope>/<pack>

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

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

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

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

CodeQL モデル パックの作成

モデル パックを使用すると、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 pack add を使用して、CodeQL パックに依存関係を追加できます。 スコープ、名前、および (必要に応じて) 互換性のあるバージョン範囲を指定する必要があります。

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

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

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

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

codeql pack install

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

CodeQLパックのディレクトリ構造を整理する方法

CodeQL パックのルート ディレクトリには、qlpack.yml という名前のファイルが含まれている必要があります。 qlpack.yml ファイルの name: フィールドには、形式 <scope>/<pack> に従う値が必要です。ここで、<scope> は、パックが発行される GitHub Organization またはユーザー アカウントで、<pack> はパックの名前です。

さらに、CodeQL テストを含むクエリ パックとライブラリ パックには、パックの解決された依存関係を含む codeql-pack.lock.yml ファイルが含まれます。 このファイルは、codeql pack install コマンドの呼び出し中に生成され、手動で編集するためのものではなく、バージョン管理システムに追加する必要があります。

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

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

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

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

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

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

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