公開前に qlpack.yml
ファイルを構成する
注: この記事では、GitHub Enterprise Server 3.14 の初期リリースに含まれている CodeQL CLI 2.17.6 バンドルで使用できる機能について説明します。
サイト管理者が CodeQL CLI のバージョンをより新しいリリースに更新している場合は、この記事の GitHub Enterprise Cloud バージョンで最新の機能に関する情報を参照してください。
公開する前に、CodeQL パックの構成の詳細を確認して変更できます。 任意のテキスト エディターで qlpack.yml
ファイルを開きます。
library: # set to true if the pack is a library. Set to false or omit for a query pack
name: <scope>/<pack>
version: <x.x.x>
description: <Description to publish with the package>
defaultSuite: # optional, one or more queries in the pack to run by default
- query: <relative-path>/query-file>.ql
defaultSuiteFile: default-queries.qls # optional, a pointer to a query-suite in this pack
license: # optional, the license under which the pack is published
dependencies: # map from CodeQL pack name to version range
-
name:
は<scope>/<pack>
形式に従う必要があります。<scope>
は公開先の GitHub Organization、<pack>
はパックの名前です。 -
defaultSuite
またはdefaultSuiteFile
のうち、許可されるのは 1 つのみです。 この 2 つは、実行する既定のクエリ スイートを定義する異なる方法です。1 つ目は qlpack.yml ファイルにクエリを直接指定し、2 つ目はパックにクエリ スイートを指定します。
実行中 codeql pack publish
パックを GitHub Container registry に公開する準備ができたら、パック ディレクトリのルートで次のコマンドを実行できます。
codeql pack publish
公開されたパッケージは、qlpack.yml
ファイル内のスコープで指定した GitHub Organization のパッケージ セクションに表示されます。
注: 既定のセットアップ構成の一部として組織内のすべてのリポジトリにカバレッジを拡張するために、GitHub Container registry にモデル パックを発行する場合は、コード スキャンを実行しているリポジトリがそれらのモデル パックにアクセスできることを確認する必要があります。 詳細については、「既定のセットアップの構成を編集する」および「パッケージのアクセス制御と可視性の設定」を参照してください。
実行中 codeql pack download <scope>/<pack>
他のユーザーが作成したパックを実行するには、まず次のコマンドを実行してダウンロードする必要があります。
codeql pack download <scope>/<pack>@x.x.x
<scope>
: ダウンロード元の GitHub Organization の名前。<pack>
: ダウンロードするパックの名前。@x.x.x
: 省略可能なバージョン番号。 省略すると、最新バージョンがダウンロードされます。
このコマンドは、複数のパックの引数を受け入れます。
ダウンロードするクエリ パックの特定のバージョン番号を指定するスクリプトを記述する場合は、CodeQL のバージョンを新しいバージョンに更新する際に、クエリ パックも新しいバージョンに切り替える必要があることに留意してください。 CodeQL の新しいバージョンは、非常に古いバージョンに固定されているクエリ パックと一緒に使うと、パフォーマンスが低下する "可能性があります"。__ 詳しくは、「CodeQL パックの互換性について」を参照してください。
CodeQL パックを使って CodeQL データベースを分析する
CodeQL パックを使って CodeQL データベースを分析するには、次のコマンドを実行します。
codeql database analyze <database> <scope>/<pack>@x.x.x:<path>
<database>
: 分析対象の CodeQL データベース。<scope>
: パックが公開されている GitHub Organization の名前。<pack>
: 使うパックの名前。@x.x.x
: 省略可能なバージョン番号。 省略すると、最新バージョンが使われます。:<path>
: クエリ、ディレクトリ、またはクエリ スイートへの省略可能なパス。 省略すると、パックの既定のクエリ スイートが使われます。
analyze
コマンドを使って、指定した CodeQL パックの既定のスイートを実行します。 CodeQL データベースの分析に使う CodeQL パックは複数指定できます。 次に例を示します。
codeql <database> analyze <scope>/<pack> <scope>/<other-pack>
注: codeql pack download
コマンドでは、ダウンロードされたパックが、ローカルの変更を意図していない内部の場所に格納されます。 パックをダウンロード後に変更すると、予期しない (トラブルシューティングが難しい) 動作が発生する可能性があります。 パックのカスタマイズについて詳しくは、「CodeQL パックの作成と操作」をご覧ください。
CodeQL パックの互換性について
クエリ パックが公開されると、その中にすべてのクエリのプリコンパイル済みの表現が含まれます。 これらのプリコンパイル済みクエリは、一般に、分析中に QL ソースをゼロからコンパイルする場合よりもはるかに高速に実行できます。 ただし、プリコンパイル済みクエリは QL エバリュエーターの特定の内部にも依存するため、分析を実行する CodeQL のバージョンが codeql pack publish
を実行したバージョンと大きく異なる場合は、代わりに分析中にソースからクエリをコンパイルする必要があるかもしれません。 再コンパイルは自動的に行われ、分析の "結果" には影響しませんが、分析速度が大幅に低下する可能性があります。__
通常、CodeQL のあるリリースでパックが公開されている場合、その中のプリコンパイル済みクエリは、リリース日が 6 か月を超えない限り、CodeQL の "以降" のリリースで直接使うことができると想定されます。__ 新しいリリースの互換性をそれよりも長期間保つために当然の努力をしますが、約束はしません。
また、CodeQL の "最新" のパブリック リリースによって公開されたパックは、code scanning と GitHub Actions で使われる CodeQL のバージョンでも使うことができると想定されます。ただし、それは多くの場合、少し古いリリースです。__
公開されたクエリ パックのユーザーは、クエリ パックを使う分析実行のターミナル出力を調べると、CodeQL でプリコンパイル済みクエリを使っていることを確認できます。 次のような行が含まれている場合、プリコンパイル済みクエリが正常に使われました。
[42/108] Loaded /long/path/to/query/Filename.qlx.
一方、代わりに次のように表示される場合は、プリコンパイル済みクエリの使用に失敗しました。
Compiling query plan for /long/path/to/query/Filename.ql.
[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql.
この場合でも分析の結果に問題はありませんが、最適なパフォーマンスを得るには、場合によっては CodeQL CLI またはクエリ パックの新しいバージョンにアップグレードする必要があります。
他のユーザーが使うことができるように GitHub.com の Container registry でクエリ パックを公開する場合は、CodeQL の最新リリースを使って codeql pack publish
を実行し、使ったバージョンが 6 か月になる前に、更新された CodeQL バージョンのパックの新しいバージョンを公開することをお勧めします。 そうすることで、パックのユーザーが "自分" の CodeQL を最新の状態に保ち、パック内のプリコンパイル済みクエリの恩恵を受けられるようにできます。__
バンドルされている CodeQL バイナリを使う GitHub Enterprise Server インストールで使う目的でクエリ パックを公開する場合は、同じ CodeQL バージョンを使って codeql pack publish
を実行します。 新しいバージョンで、GitHub Enterprise Server で認識されない可能性のあるプリコンパイル済みクエリが生成される場合があります。 GitHub Enterprise Server 管理者は、新しいバージョンの CodeQL に定期的にアップグレードすることを選ぶことができます。 その場合は、指示に従ってください。
GitHub Enterprise Server で CodeQL パックを操作する
既定では、CodeQL CLI は、GitHub.com の Container registry から CodeQL パックをダウンロードし、そこにパックを公開することを想定しています。 ただし、qlconfig.yml
ファイルを作成して、各パックに使う Container registry を CLI に指示することで、GitHub Enterprise Server の Container registry 内の CodeQL パックを操作することもできます。
任意のテキスト エディターを使って ~/.codeql/qlconfig.yml
ファイルを作成し、エントリを追加して、1 つ以上のパッケージ名パターンに使うレジストリを指定します。
たとえば、次の qlconfig.yml
ファイルは、GitHub.com の Container registry に関連付けられている、GHE_HOSTNAME
にある GitHub Enterprise Server の Container registry にすべてのパック (codeql/\*
に一致するパックは除く) を関連付けます。
registries:
- packages:
- 'codeql/*'
- 'other-org/*'
url: https://ghcr.io/v2/
- packages: '*'
url: https://containers.GHE_HOSTNAME/v2/
CodeQL CLI は、registries
リストで、そのパッケージ名に一致する packages
プロパティを持つ最初の項目を見つけて、特定のパッケージ名に使うレジストリを決定します。
つまり、通常は、最も明確なパッケージ名パターンを最初に定義したいと考えます。 packages
プロパティには、単一のパッケージ名、glob パターン、またはパッケージ名と glob パターンの YAML リストを指定できます。
registries
リストは、codeql-workspace.yml
ファイル内に配置することもできます。 そうすることで、特定のワークスペース内で使うレジストリを定義でき、ワークスペースの他の CodeQL ユーザー間で共有できるようにします。 codeql-workspace.yml
内の registries
リストはマージされ、グローバルな qlconfig.yml
内のリストよりも優先されます。 codeql-workspace.yml
について詳しくは、「CodeQL ワークスペースについて」をご覧ください。
codeql pack publish
、codeql pack download
、codeql database analyze
を使って、GitHub Enterprise Server でパックを管理できるようになりました。
GitHub Container registries への認証
適切な GitHub Container registry に対して認証することで、パックを公開し、プライベート パックをダウンロードできます。
次の 2 つの方法で GitHub.com の Container registry に対して認証できます。
- CodeQL CLI に
--github-auth-stdin
オプションを渡し、標準入力を介して GitHub Apps トークンまたは personal access token を提供します。 GITHUB_TOKEN
環境変数を GitHub Apps トークンまたは personal access token に設定します。
同様に、次の 2 つの方法で GitHub Enterprise Server Container registry に対して認証、または複数のレジストリに対して同時に認証することができます (複数のレジストリからプライベート パックをダウンロードまたは実行する場合など)。
- CodeQL CLI に
--registries-auth-stdin
オプションを渡し、標準入力を介してレジストリ認証文字列を提供します。 CODEQL_REGISTRIES_AUTH
環境変数をレジストリ認証文字列に設定します。
レジストリ認証文字列は、<registry-url>=<token>
ペアのコンマ区切りのリストです。registry-url
は Container registry URL (https://containers.GHE_HOSTNAME/v2/
など)、token
はその GitHub Container registry の GitHub Apps トークンまたは personal access token です。
これにより、各トークンは、指定した Container registry にのみ確実に渡されます。
たとえば、次のレジストリ認証文字列は、CodeQL CLI で GitHub.com の Container registry に対してトークン <token1>
を使い、GHE_HOSTNAME
の GHES インスタンスの Container registry に対してトークン <token2>
を使って認証する必要があるように指定しています。
https://ghcr.io/v2/=<token1>,https://containers.GHE_HOSTNAME/v2/=<token2>
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
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 テストを含むパックの場合は省略可能。 テストが含まれていないパックの場合は無視されます。
-
テストを含むパック内のディレクトリへのパスを定義します。これは、パック ディレクトリを基準に定義されます。 パック全体を指定するには、
.
を使用します。--strict-test-discovery
オプションを指定してtest run
を実行すると、このディレクトリ内のすべてのクエリがテストとして実行されます。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
-
省略可能。
warnOnImplicitThis
プロパティが定義されていない場合、既定値はfalse
に設定されます。 -
暗黙的な
this
呼び出しレシーバー (つまり、明示的なレシーバーなし) を指定するメンバー述語呼び出しに関する警告をコンパイラが出力するかどうかを指定するブール値を定義します。 CodeQL CLI v2.13.2 以降で使用できます。 次に例を示します。warnOnImplicitThis: true
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
ここで、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 パックの場合、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-kotlin
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 の内部用であり、言語のコア CodeQL クエリ パックでのみ定義する必要があります。
コア クエリ パック
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
プロパティはありません。 これにより、テスト パックが誤って発行されるのを防ぐことができます。