CodeQL パックの作成と操作

CodeQL パックと CodeQL CLI について

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

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

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

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

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

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

codeql pack install

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

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

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

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

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

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