CodeQL パックを発行して使用する

GitHub Container registries への認証

適切な GitHub Container registry に対して認証することで、パックを公開し、プライベート パックをダウンロードできます。

Container registry への認証には 2 つの方法があります。

1. CodeQL CLI に --github-auth-stdin オプションを渡し、標準入力を介して GitHub Apps トークンまたは personal access token を提供します。
2. GITHUB_TOKEN 環境変数を GitHub Apps トークンまたは personal access token に設定します。

公開前に qlpack.yml ファイルを構成する

公開する前に、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 のパッケージ セクションに表示されます。

実行中 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 パックの互換性について

クエリ パックが公開されると、その中にすべてのクエリのプリコンパイル済みの表現が含まれます。 これらのプリコンパイル済みクエリは、一般に、分析中に 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 に定期的にアップグレードすることを選ぶことができます。 その場合は、指示に従ってください。

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 プロパティはありません。 これにより、テスト パックが誤って発行されるのを防ぐことができます。