CodeQL パックについて

注: この記事は、2023 年 1 月に CodeQL ドキュメント Web サイトから移行されました。

注: CodeQL パックを含む CodeQL パッケージ管理機能は、現在ベータ版リリースであり、変更される可能性があります。ベータ版リリース中、CodeQL パックは GitHub パッケージ (Container registry) を使用してのみ利用できます。このベータ機能を使用するには、 https://github.com/github/codeql-action/releases から最新バージョンの CodeQL CLI バンドルをインストールします。

CodeQL パックについて

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

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

CodeQL パックを使用して、CodeQL クエリとライブラリを作成、共有、実行したり、これらに依存したりすることができます。独自の CodeQL パックを公開し、他のユーザーが作成したパックをダウンロードできます。 CodeQL パックには、クエリ、ライブラリファイル、クエリスイート、メタデータが含まれます。

CodeQL パックには、クエリパックとライブラリパックの 2 種類があります。

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

CodeQL CLI のパッケージ管理コマンドを使用して、CodeQL パックの作成、パックへの依存関係の追加、依存関係のインストールまたは更新を行うことができます。詳しい情報については、「CodeQL パックの作成と操作」を参照してください。 CodeQL CLI を使用して、CodeQL パックを発行およびダウンロードすることもできます。詳しくは、「CodeQL パックの発行と使用」を参照してください。

サポートされているすべての言語の標準 CodeQL パッケージは、Container registry で公開されています。 CodeQL リポジトリには、サポートされているすべての言語の標準 CodeQL パックのソースファイルが含まれています。

CodeQL パックの構造

CodeQL パックのルートディレクトリには、qlpack.yml という名前のファイルが含まれている必要があります。 qlpack.yml ファイルの name: フィールドには、形式 <scope>/<pack> に従う値が必要です。ここで、<scope> は、パックが発行される GitHub Organization またはユーザーアカウントで、<pack> はパックの名前です。さらに、CodeQL テストを含むクエリパックとライブラリパックには、パックの解決された依存関係を含む codeql-pack.lock.yml ファイルが含まれます。このファイルは、codeql pack install コマンドの呼び出し中に生成され、手動で編集するためのものではなく、バージョン管理システムに追加する必要があります。

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

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

`qlpack.yml` ファイルについて

クエリ関連のコマンドを実行する場合、CodeQL はまず、インストールディレクトリの兄弟 (およびそのサブディレクトリ) で qlpack.yml ファイルを検索します。次に、ダウンロードされた CodeQL パックのパッケージキャッシュを確認します。これは、クエリをローカルで開発している場合、インストールディレクトリ内のローカルパッケージによって、パッケージキャッシュ内の同じ名前のパッケージがオーバーライドされるため、ローカルの変更をテストできることを意味します。

各 qlpack.yml ファイルのメタデータは、パック内のクエリをコンパイルする方法、パックが依存するライブラリ、クエリスイート定義を検索する場所を CodeQL に指示します。

CodeQL パック (CodeQL 分析で使用されるクエリまたはライブラリ) の内容は、qlpack.yml と同じディレクトリまたはそのサブディレクトリに含まれます。

qlpack.yml ファイルを含むディレクトリは、CodeQL パックの内容のルートディレクトリとして機能します。つまり、パック内のすべての .ql および .qll ファイルについて、CodeQL は、パックのルートにある qlpack.yml ファイルを含むディレクトリに関連するすべてのインポートステートメントを解決します。

`qlpack.yml` プロパティ

qlpack.yml ファイルでは、次のプロパティがサポートされます。

`name`

すべてのパックで必須。
CodeQL パックが発行されるパックのスコープとパックの名前を定義します。名前は、英数字とハイフンを使用して定義します。 CodeQL では同じ名前の CodeQL パックを区別できないため、これは一意である必要があります。パック名を使用して、database analyze を使用して実行するクエリを指定し、CodeQL パック間の依存関係を定義します (次の例を参照)。次に例を示します。
```
name: octo-org/security-queries
```

`version`

発行されるすべてのパックで必須。
SemVer v2.0.0 仕様に準拠する必要がある、この CodeQL パックのセマンティックバージョンを定義します。次に例を示します。
```
version: 0.0.0
```

`dependencies`

他のパックに対する CodeQL パッケージの依存関係を定義するパックで必須。
パック参照から、このパックと互換性のあるセマンティックバージョン範囲へのマップを定義します。 CodeQL CLI バージョン v2.6.0 以降でサポートされています。次に例を示します。
```
dependencies:
  codeql/cpp-all: ^0.0.2`
```

`defaultSuiteFile`

Required by packs that export a set of default queries to run.
Defines the path to a query suite file relative to the package root, containing all of the queries that are run by default when this pack is passed to the codeql database analyze command. Supported from CLI version v2.6.0 and onwards. Only one of defaultSuiteFile or defaultSuite can be defined. For example:
```
defaultSuiteFile: cpp-code-scanning.qls
```

`defaultSuite`

実行する一連の既定のクエリをエクスポートするパックで必須。
このパックが codeql database analyze コマンドに渡されたときに既定で実行されるすべてのクエリを含むインラインクエリスイートを定義します。 CLI バージョン v2.6.0 以降でサポートされています。 defaultSuiteFile または defaultSuite のいずれか 1 つのみを定義できます。次に例を示します。
```
defaultSuite:
  queries: .
  exclude:
    precision: medium
```

`library`

ライブラリパックで必須。
このパックがライブラリパックであるかどうかを示すブール値を定義します。ライブラリパックにはクエリは含まれず、コンパイルされません。クエリパックでは、このフィールドを無視するか、明示的に false に設定できます。次に例を示します。
```
library: true
```

`suites`

クエリスイートを定義するパックの場合は省略可能。
CodeQL CLI に認識させるクエリスイートを含むパック内のディレクトリへのパスを定義します。これは、パックディレクトリを基準に定義されます。 CodeQL パックユーザーは、完全なパスを指定しなくても、パック名を指定することで、このディレクトリに格納されている "既知" のスイートを実行できます。これは、コンテナーレジストリからダウンロードされた CodeQL パックではサポートされていません。クエリスイートについて詳しくは、「CodeQL クエリスイートの作成」を参照してください。次に例を示します。
```
suites: octo-org-query-suites
```

`tests`

CodeQL テストを含むパックの場合は省略可能。テストが含まれていないパックの場合は無視されます。
テストを含むパック内のディレクトリへのパスを定義します。これは、パックディレクトリを基準に定義されます。パック全体を指定するには、. を使用します。 --strict-test-discovery オプションを指定して test run を実行すると、このディレクトリ内のすべてのクエリがテストとして実行されます。 queries または qlpack 命令を使用して特定のパック内のすべてのクエリを要求するクエリスイート定義では、これらのクエリは無視されます。このプロパティがない場合、. と見なされます。次に例を示します。
```
tests: .
```

`extractor`

CodeQL テストを含むすべてのパックで必須。
パック内の CodeQL テストを実行するときに使用する CodeQL 言語抽出子を定義します。クエリのテストについて詳しくは、「カスタムクエリのテスト」を参照してください。次に例を示します。
```
extractor: javascript
```

`authors`

任意。
CodeQL パックが発行されるアカウントのパッケージセクションでパッケージ検索ページに表示されるメタデータを定義します。次に例を示します。
```
authors: author1@github.com,author2@github.com 
```

`license`

任意。
CodeQL パックが発行されるアカウントのパッケージセクションでパッケージ検索ページに表示されるメタデータを定義します。許可されているライセンスの一覧については、SPDX 仕様の SPDX ライセンスリストを参照してください。次に例を示します。
```
license: MIT
```

`description`

任意。
CodeQL パックが発行されるアカウントのパッケージセクションでパッケージ検索ページに表示されるメタデータを定義します。次に例を示します。
```
description: Human-readable description of the contents of the CodeQL pack.
```

`libraryPathDependencies`

省略可能、非推奨。代わりに、dependencies プロパティを使用してください。
以前は、この CodeQL パックが依存する CodeQL パックの名前を配列として定義するために使用されていました。これにより、パックは、依存関係で定義されたライブラリ、データベーススキーマ、クエリスイートにアクセスできるようになります。次に例を示します。
```
libraryPathDependencies: codeql/javascript-all 
```

`dbscheme`

コア言語パックでのみ必須。
この CodeQL 言語用に記述されたすべてのライブラリとクエリのデータベーススキーマへのパスを定義します (次の例を参照)。次に例を示します。
```
dbscheme: semmlecode.python.dbscheme
```

`upgrades`

コア言語パックでのみ必須。
データベースアップグレードスクリプトを含むパック内のディレクトリへのパスを定義します。これは、パックディレクトリを基準に定義されます。データベースのアップグレードは、別のバージョンの CodeQL CLI で作成されたデータベースと CLI の現在のバージョンとの互換性を確保するために内部的に使用されます。次に例を示します。
```
upgrades: .
```

`codeql-pack.lock.yml` ファイルについて

codeql-pack.lock.yml ファイルには、CodeQL パックの解決された推移的依存関係のバージョンが格納されます。このファイルは、まだ存在していない場合、codeql pack install コマンドによって作成されます。これは、バージョン管理システムに追加する必要があります。 qlpack.yml ファイルの dependencies セクションには、パックと互換性のあるバージョン範囲が含まれます。 codeql-pack.lock.yml ファイルによって、バージョンが正確な依存関係にロックされます。これにより、このパックで codeql pack install を実行すると、互換性のある新しいバージョンが存在する場合でも、常に同じバージョンの依存関係が取得されます。

たとえば、qlpack.yml ファイルに次の依存関係が含まれている場合、

dependencies:
  codeql/cpp-all: ^0.1.2
  my-user/my-lib: ^0.2.3
  other-dependency/from-source: "*"

codeql-pack.lock.yml ファイルは、次のような内容になります。

dependencies:
  codeql/cpp-all:
    version: 0.1.4
  my-user/my-lib:
    version: 0.2.4
  my-user/transitive-dependency:
    version: 1.2.4

codeql/cpp-all 依存関係は、バージョン 0.1.4 にロックされます。 my-user/my-lib 依存関係は、バージョン 0.2.4 にロックされます。推移的な依存関係であり、qlpack.yml ファイルでは指定されていない my-user/transitive-dependency は、バージョン 1.2.4 にロックされます。 other-dependency/from-source は、ソースから解決されるため、ロックファイルには存在しません。この依存関係は、パックと同じ CodeQL ワークスペースで使用できる必要があります。 CodeQL ワークスペースと、ソースからの依存関係の解決について詳しくは、「CodeQL ワークスペースについて」を参照してください。

ほとんどの場合、ライブラリパックは実行可能ファイルではなく、通常は推移的な依存関係を修正する必要がないため、codeql-pack.lock.yml ファイルはクエリパックにのみ関係があります。これに対する例外は、テストを含むライブラリパックの場合です。この場合、codeql-pack.lock.yml ファイルを使用して、テストが常に同じバージョンの依存関係で実行されるようにし、依存関係が一致しない場合に偽りのエラーが発生するのを回避します。

カスタム CodeQL パックの例

カスタムクエリまたはテストを記述する場合、それらをカスタム CodeQL パックに保存する必要があります。わかりやすくするために、各パックを論理的に整理してみてください。詳しい情報については、「CodeQL パックの構造」を参照してください。クエリとテスト用のファイルを個別のパックに保存し、可能であれば、カスタムパックをターゲット言語ごとに特定のフォルダーに整理します。これは、CodeQL パックを発行して他のユーザーと共有したり、コードスキャンに使用したりする場合に特に役立ちます。詳しくは、「CodeQL によるコードスキャンについて」を参照してください。

カスタムライブラリ用の CodeQL パック

クエリやテストを含まないカスタム C++ ライブラリを含むカスタム CodeQL パックには、qlpack.yml ファイルが含まれる場合があります。このファイルの内容は次のようになります。

name: my-github-user/my-custom-libraries
version: 1.2.3
library: true
dependencies:
  codeql/cpp-all: ^0.1.2

ここで、codeql/cpp-all は、CodeQL リポジトリに含まれる C/C++ 分析用の CodeQL パックの名前です。バージョン範囲 ^0.1.2 は、このパックが、codeql/cpp-all の 0.1.2 以上で 0.2.0 未満のすべてのバージョンと互換性があることを示します。このパックで定義された CodeQL ライブラリファイル (拡張子が .qll のファイル) は、依存関係ブロックにこのパックを含むクエリパックで定義されたクエリで使用できます。

library プロパティは、このパックがライブラリパックであり、クエリが含まれていないことを示します。

カスタムクエリ用の CodeQL パック

カスタム C++ クエリとライブラリを含むカスタム CodeQL パックには、qlpack.yml ファイルが含まれる場合があります。このファイルの内容は次のようになります。

name: my-github-user/my-custom-queries
version: 1.2.3
dependencies:
  codeql/cpp-all: ^0.1.2
  my-github-user/my-custom-libraries: ^1.2.3
suites: my-custom-suites

ここで、codeql/cpp-all は、CodeQL リポジトリに含まれる C/C++ 分析用の CodeQL パックの名前です。バージョン範囲 ^0.1.2 は、このパックが、codeql/cpp-all の 0.1.2 以上で 0.2.0 未満のすべてのバージョンと互換性があることを示します。 my-github-user/my-custom-libraries は、C++ 用のカスタム CodeQL ライブラリを含む CodeQL パックの名前です。このパックで定義されている CodeQL ライブラリファイル (拡張子が .qll のファイル) は、my-github-user/my-custom-queries パック内のクエリで使用できます。

suites プロパティは、"既知" のクエリスイートが見つかるディレクトリを示します。これらのスイートは、完全なパスではなく、名前のみを参照してコマンドラインで使用できます。クエリスイートについて詳しくは、「CodeQL クエリスイートの作成」を参照してください。

カスタムテスト用の CodeQL パック

テストファイルを含むカスタム CodeQL パックの場合、test run コマンドでテストデータベースの作成方法を認識できるように、extractor プロパティも含める必要があります。 tests プロパティを指定することもできます。

次の qlpack.yml ファイルは、my-github-user/my-query-tests が 1.2.3 以上で 2.0.0 未満のバージョンの my-github-user/my-custom-queries に依存していることを示しています。また、テストデータベースの作成時に CLI で Java extractor を使用する必要があることを宣言します。 tests: . 行では、--strict-test-discovery オプションを指定して codeql test run を実行する際に、パック内のすべての .ql ファイルをテストとして実行する必要があることを宣言します。通常、テストパックに version プロパティは含まれません。これにより、それらが誤って発行されるのを防ぐことができます。

  name: my-github-user/my-query-tests
  dependencies:
    my-github-user/my-custom-queries: ^1.2.3
  extractor: java
  tests: .

テストの実行について詳しくは、「カスタムクエリのテスト」を参照してください。

CodeQL リポジトリ内の CodeQL パックの例

CodeQL リポジトリの各言語には、次の 4 つの主要な CodeQL パックがあります。

言語で使用されるデータベーススキーマ、CodeQL ライブラリ、クエリを含む言語用コアライブラリパック (<language>/ql/lib)
言語の既定のクエリとクエリスイートを含む言語用コアクエリパック (<language>/ql/src)
コア言語ライブラリとクエリのテスト (<language>/ql/test)
言語のクエリ例 (<language>/ql/examples)

コアライブラリパック

C/C++ 分析ライブラリコア言語パックの qlpack.yml ファイルの例を次に示します。

name: codeql/cpp-all
version: x.y.z-dev
dbscheme: semmlecode.cpp.dbscheme
library: true
upgrades: upgrades

次のプロパティに関する追加の注意事項:

library: これは、実行可能クエリが含まれていないライブラリパックであることを示します。他のパックの依存関係として使用することのみを目的としています。
dbscheme および upgrades: これらのプロパティは CodeQL CLI の内部用であり、言語のコア QL パックでのみ定義する必要があります。

コアクエリパック

C/C++ 分析クエリコアクエリパックの qlpack.yml ファイルの例を次に示します。

name: codeql/cpp-queries
version: x.y.z-dev
dependencies:
    codeql/cpp-all: "*"
    codeql/suite-helpers: "*"
suites: codeql-suites
defaultSuiteFile: codeql-suites/cpp-code-scanning.qls

次のプロパティに関する追加の注意事項:

dependencies: このクエリパックは、codeql/cpp-all と codeql/suite-helpers に依存します。これらの依存関係はソースから解決されるため、互換性のある CodeQL パックのバージョンは関係ありません。ソースからの依存関係の解決について詳しくは、「ソース依存関係」を参照してください。
suites: "既知" のクエリスイートを含むディレクトリを示します。
defaultSuiteFile: クエリスイートが指定されていない場合に使用される既定のクエリスイートファイルの名前。

コア CodeQL パックのテスト

C/C++ 分析クエリコアテストパックの qlpack.yml ファイルの例を次に示します。

name: codeql/cpp-tests
dependencies:
  codeql/cpp-all: "*"
  codeql/cpp-queries: "*"
extractor: cpp
tests: .

次のプロパティに関する追加の注意事項:

dependencies: このパックは、C++ のコア CodeQL クエリパックとライブラリパックに依存します。
extractor: これは、すべてのテストで同じ C++ 抽出子を使用してテスト用のデータベースを作成することを指定します。
tests: これは、テストの場所を指定します。この場合、テストは、パックのルートフォルダー (およびすべてのサブフォルダー) 内にあります。
version: テストパックの version プロパティはありません。これにより、テストパックが誤って発行されるのを防ぐことができます。

CodeQL パックについて

この記事の内容