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

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

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

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

サイト管理者が 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>
default-suite: # optional, one or more queries in the pack to run by default
    - query: <relative-path>/query-file>.ql
default-suite-file: 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、はパックの名前です。
default-suite または default-suite-file のうち、許可されるのは 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 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>

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

`dependencies`

他のパックに対する CodeQL パッケージの依存関係を定義するクエリとライブラリパックで必須。
パック参照から、このパックと互換性のあるセマンティックバージョン範囲へのマップを定義します。 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
```

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

`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 バージョン 2.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
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 パックを発行して使用する

この機能を使用できるユーザーについて

この記事の内容

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

実行中 `codeql pack publish`

実行中 `codeql pack download <scope>/<pack>`

CodeQL パックを使って CodeQL データベースを分析する

GitHub Enterprise Server で CodeQL パックを操作する

GitHub Container registries

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

`qlpack.yml` プロパティ

`name`

`version`

`dependencies`

`defaultSuiteFile`

`defaultSuite`

`groups`

`library`

`suites`

`tests`

`extractor`

`authors`

`license`

`description`

`libraryPathDependencies`

`dbscheme`

`upgrades`

`warnOnImplicitThis`

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

カスタム CodeQL パックの例

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

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

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

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

コアライブラリパック

コアクエリパック

コア CodeQL パックのテスト