CodeQL パックの作成と操作

CodeQL パックと CodeQL CLI について

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

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

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

CodeQL パックの、二つのタイプがあります。クエリパックとライブラリパック。

クエリパックは、実行するように設計されています。クエリパックが発行されると、バンドルにはすべての推移的な依存関係と各クエリのプリコンパイル済み表現、およびクエリソースが含まれます。これにより、パック内のクエリの一貫した効率的な実行が保証されます。
ライブラリパックは、クエリパック (またはその他のライブラリパック) で使用するように設計されており、クエリ自体は含まれません。ライブラリはseparately発行されたときにコンパイルキャッシュが含まれません。

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 クエリパックとライブラリパックでのみサポートされます。

コマンド 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 ソースよりも優先して使用されます。