CodeQL パックの作成と操作

CodeQLパックとCodeQL CLIについて

メモ

この記事では、CodeQL CLI 3.16 の初期リリースに含まれている 2.20.3 GitHub Enterprise Server バンドルで使用できる機能について説明します。

サイト管理者が CodeQL CLI のバージョンをより新しいリリースに更新している場合は、この記事の GitHub Enterprise Cloud バージョンで最新の機能に関する情報を参照してください。

CodeQL パックは、 CodeQL クエリとライブラリの作成、共有、依存、および実行に使用されます。

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

CodeQL パックの作成

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

codeql pack init <scope>/<pack>

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

<scope>: 発行先のGitHub 組織またはユーザーアカウントの名前。
<pack>: 作成するパックの名前。

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

CodeQL モデルパックの作成

メモ

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

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

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

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

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/**/ のすべてのデータ拡張機能が、codeql/java-all から最大および 1.2.3 を含むバージョンの 1.3.0 クエリパックと、codeql/util から最大および 4.5.6 を含むバージョンの 4.6.0 クエリパックに挿入されます。詳細については、npm のドキュメントの「セマンティックバージョニングの使用」、およびセマンティックバージョニング仕様書」を参照してください。

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

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

メモ

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

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

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はContainer registryにGitHub.comからの依存関係をインストールします。 GitHub Enterprise Server ファイルを作成することで、Container registryqlconfig.ymlから依存関係をインストールできます。詳細については、ドキュメントの GitHub Enterprise Server を参照してください。

CodeQL パックのディレクトリ構造の整理

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

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

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

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

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

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

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

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

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

この記事で