CodeQL パックの作成と操作

CodeQL パックと CodeQL CLI について

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

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

• クエリ パックは、実行するように設計されています。 クエリ パックが発行されると、バンドルにはすべての推移的な依存関係とコンパイル キャッシュが含まれます。 これにより、パック内のクエリの一貫した効率的な実行が保証されます。

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

CodeQL CLI の pack コマンドを使用して、CodeQL パックを作成したり、パックに依存関係を追加したり、依存関係をインストールまたは更新したりできます。 pack コマンドを使用して、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 ファイルを編集する必要があります。

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

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

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

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

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

codeql pack install

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