CodeQL クエリパック参照

CodeQL パックの互換性

クエリパックが発行されると、分析速度を向上させるために、その中のすべてのクエリのプリコンパイル済み表現が含まれます。ただし、分析を実行する CodeQL のバージョンが、 codeql pack publish実行したバージョンより 6 か月以上新しい場合は、分析中にソースからクエリをコンパイルする必要があり、プロセスが大幅に遅くなる可能性があります。

CodeQL の最新のパブリックリリースによって公開されたパックは、code scanning および GitHub Actions によって使用される CodeQL のバージョンで使用できます。ただし、これは少し古いリリースであることがよくあります。

分析に次のような行が含まれている場合、CodeQL はプリコンパイル済みクエリを正常に使用します。

[42/108] Loaded /long/path/to/query/Filename.qlx.

分析に次のような行が含まれている場合は、CodeQL がソースからクエリを手動で再コンパイルしました。

Compiling query plan for /long/path/to/query/Filename.ql.
[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql.

クエリパックのユーザーが事前コンパイル済みクエリを利用できるように、最新リリースの CodeQL を使用してパックを発行することをお勧めします。さらに、更新された CodeQL バージョンを 6 か月ごとに使用して、新しいバージョンのパックを発行する必要があります。

バンドルされている CodeQL バイナリを使う GitHub Enterprise Server インストールで使う目的でクエリパックを公開する場合は、同じ CodeQL バージョンを使って codeql pack publish を実行します。

          `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 仕様](https://semver.org/spec/v2.0.0.html)に準拠する必要がある、この CodeQL パックのセマンティック バージョンを定義します。 例えば次が挙げられます。

version: 0.0.0

`dataExtensions`

モデルパックで必須。
クエリパックまたはライブラリパックのルートを基準にしてデータ拡張ファイルが配置される場所を指定する glob パターンの一覧を取得します。

`dependencies`

他のパックに対する CodeQL パッケージの依存関係を定義するクエリとライブラリパックで必須。モデルパックでは依存関係を定義できず、代わりに extensionTargets を使用できます。
パック参照から、このパックと互換性のあるセマンティックバージョン範囲へのマップを定義します。 CodeQL CLI バージョン v2.6.0 以降でサポートされています。例えば次が挙げられます。
```
dependencies:
  codeql/cpp-all: ^0.0.2
```
不明な場合、または使用するバージョンが重要でない場合は、この依存関係の任意のバージョンがこのパックと互換性があることを示す "*" を使用できます。実際には、これは通常、公開されている依存関係の最も高いバージョンに解決されます。

特別なバージョンのプレースホルダーがあります。これは、${workspace}この CodeQL パックが、同じワークスペース内にある依存関係のバージョンによって異なることを示します。詳しくは、「CodeQL ワークスペースについて」をご覧ください。

`defaultSuiteFile`

実行する一連の既定のクエリをエクスポートするパックで必須。
このパックが codeql database analyze コマンドに渡されたときに既定で実行されるすべてのクエリを含む、パッケージルートを基準とするクエリスイートファイルへのパスを定義します。 CLI バージョン v2.6.0 以降でサポートされています。 defaultSuiteFile または defaultSuite のいずれか 1 つのみを定義できます。例えば次が挙げられます。
```
defaultSuiteFile: cpp-code-scanning.qls
```

`defaultSuite`

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

`extensionTargets`

モデルパックで必須。
モデルパック内の拡張機能が適用されるクエリパックを宣言します。拡張機能パックは、指定されたバージョン範囲内にあり、評価で使用されている場合、extensionTargets ディクショナリに名前が付けられた各パックにデータ拡張機能を挿入します。

`groups`

このフィールドは省略可能です。
CodeQL ワークスペース内のパックの論理グループを定義します。グループの使用は、ワークスペース内のパックのサブセットにパック操作を適用する方法です。たとえば、次のパックは、java グループと experimental グループの一部として定義されています。
```
groups:
  - java
  - experimental
```
```
        `codeql pack publish --groups java,-experimental` を実行すると、`java` グループ内のすべてのパック (__ パックを除く`experimental`) がパブリッシュされます。 
        `codeql pack ls --groups [-]<group>[,[-]<group>...]` コマンドを実行すると、指定したグループのセットに一致するワークスペース内のパックを一覧表示できます。
```
次の場合、上記ワークスペースの CodeQL パックは一覧に含まれます。
- マイナス記号なしで一覧表示されているグループの少なくとも 1 つに属している (マイナス記号なしでリストされているグループがない場合、この条件は自動的に満たされます)。
- マイナス記号が付いた一覧表示されているどのグループにも属していません。

`library`

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

`suites`

クエリスイートを定義するパックの場合は省略可能。これにより、ユーザーは完全なパスを指定せずに、パック名を指定することで、指定したディレクトリに保存されているクエリスイートを実行できます。
現在、CodeQL CLI バンドルに含まれている標準クエリパックでのみサポートされています。
このオプションは、GitHub コンテナレジストリからダウンロードされた CodeQL パックではサポートされていません。

`tests`

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

`extractor`

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

`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: .
```

`warnOnImplicitThis`

このフィールドは省略可能です。 false プロパティが定義されていない場合、既定値は warnOnImplicitThis に設定されます。
暗黙的な this 呼び出しレシーバー (つまり、明示的なレシーバーなし) を指定するメンバー述語呼び出しに関する警告をコンパイラが出力するかどうかを指定するブール値を定義します。 CodeQL CLI v2.13.2 以降で使用できます。例えば次が挙げられます。
```
warnOnImplicitThis: true
```

          `codeql-pack.lock.yml` ファイル

          `codeql-pack.lock.yml` ファイルには、CodeQL パックの解決された推移的依存関係のバージョンが格納されます。 このファイルは、まだ存在していない場合、`codeql pack install` コマンドによって作成されます。これは、バージョン管理システムに追加する必要があります。 
          `dependencies` ファイルの `qlpack.yml` セクションには、パックと互換性のあるバージョン範囲が含まれます。 
          `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 にロックされます。 推移的な依存関係であり、`my-user/transitive-dependency` ファイルでは指定されていない `qlpack.yml` は、バージョン 1.2.4 にロックされます。 
          `other-dependency/from-source` は、ソースから解決されるため、ロック ファイルには存在しません。 この依存関係は、パックと同じ CodeQL ワークスペースで使用できる必要があります。 CodeQL ワークスペースおよびソースからの依存関係の解決に関する詳細については、「[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces)」を参照してください。

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

カスタム 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

ここで、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 パック内のクエリで使用できます。

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

テストファイルを含むカスタム CodeQL パックの場合、extractor コマンドでテストデータベースの作成方法を認識できるように、test run プロパティも含める必要があります。 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-kotlin
tests: .

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

CodeQLのリポジトリにあるCodeQLパックの例

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

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

コアライブラリパック

          `qlpack.yml` コア言語パックの [](https://github.com/github/codeql/blob/main/cpp/ql/lib/qlpack.yml) ファイルの例を次に示します。

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

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

        `library`: これは、実行可能クエリが含まれていないライブラリ パックであることを示します。 他のパックの依存関係として使用することのみを目的としています。

        `dbscheme` および `upgrades`: これらのプロパティは CodeQL CLI の内部用であり、言語のコア CodeQL パックでのみ定義する必要があります。

コアクエリパック

          `qlpack.yml` コア クエリ パックの [](https://github.com/github/codeql/blob/main/cpp/ql/src/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 パックのバージョンは関係ありません。 ソースからの依存関係の解決について詳しくは、「[ソース依存関係](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#source-dependencies)」を参照してください。

        `suites`: "既知" のクエリ スイートを含むディレクトリを示します。

        `defaultSuiteFile`: クエリ スイートが指定されていない場合に使用される既定のクエリ スイート ファイルの名前。

コア CodeQL パックのテスト

          `qlpack.yml` コア テスト パックの [](https://github.com/github/codeql/blob/main/cpp/ql/src/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 パックの互換性

`name`

`version`

`dataExtensions`

`dependencies`

`defaultSuiteFile`

`defaultSuite`

`extensionTargets`

`groups`

`library`

`suites`

`tests`

`extractor`

`authors`

`license`

`description`

`libraryPathDependencies`

`dbscheme`

`upgrades`

`warnOnImplicitThis`

カスタム CodeQL パッケージの例

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

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

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

CodeQLのリポジトリにあるCodeQLパックの例

コアライブラリパック

コアクエリパック

コア CodeQL パックのテスト