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

CodeQL上でパックを扱うデータ所在地付き GitHub Enterprise Cloud

既定では、CodeQL CLIは、CodeQL パックをダウンロードし、Container registryのGitHub.comにパックを発行することを想定しています。 ただし、qlconfig.yml ファイルを作成して各パックに使用する CodeQL を CLI に指示することで、Container registry の データ所在地付き GitHub Enterprise Cloud で Container registry パックを操作することもできます。

Linux/MacOS 上に ~/.codeql/qlconfig.yml ファイルを作成するか、Windowsで %HOMEPATH%\.codeql\qlconfig.yml を作成し、エントリを追加して、1 つ以上のパッケージ名パターンに使用するレジストリを指定します。 たとえば、次のqlconfig.yml ファイルは、Container registryのSUBDOMAIN.ghe.comにすべてのパックを関連付けます。ただし、codeql/\*に一致するパックや、other-org/*のContainer registryに関連付けられているGitHub.com組織を除きます。

registries:
- packages:
  - 'codeql/*'
  - 'other-org/*'
  # Container registry on GitHub.com
  url: https://ghcr.io/v2/
- packages: '*'
  # Container registry hosted at `SUBDOMAIN.ghe.com`
  url: https://containers.SUBDOMAIN.ghe.com

CodeQL CLIは、特定のパッケージ名に一致するregistries プロパティを持つpackagesリストの最初の項目を見つけることで、特定のパッケージ名に使用するレジストリを決定します。 つまり、通常は、最も明確なパッケージ名パターンを最初に定義したいと考えます。 packages プロパティには、単一のパッケージ名、glob パターン、またはパッケージ名と glob パターンの YAML リストを指定できます。

registries リストは、codeql-workspace.yml ファイル内に配置することもできます。 これにより、特定のワークスペース内で使用するレジストリを定義して、ワークスペースの他の CodeQL ユーザー間で共有できるようになります。 registries 内の codeql-workspace.yml リストはマージされ、グローバルな qlconfig.yml 内のリストよりも優先されます。 codeql-workspace.yml の詳細については、「CodeQL ワークスペースについて」を参照してください。

codeql pack publish、codeql pack download、codeql database analyzeを使用して、データ所在地付き GitHub Enterprise Cloudのパックを管理できるようになりました。

認証中 GitHubContainer registries

適切な GitHubContainer registryに認証することで、パックを発行し、プライベート パックをダウンロードできます。

Container registriesでGitHub.comへの認証を行う

Container registryに対して認証するには、次の 2 つの方法があります。

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

Container registries でデータ所在地付き GitHub Enterprise Cloud に認証中

同様に、Container registryでデータ所在地付き GitHub Enterprise Cloudに対して認証を行うか、複数のレジストリに対して同時に認証を行う (複数のレジストリからプライベート パックをダウンロードまたは実行する場合など) には、次の 2 つの方法があります。

1. --registries-auth-stdin オプションをCodeQL CLIに渡し、標準入力を介してレジストリ認証文字列を指定します。
2. CODEQL_REGISTRIES_AUTH 環境変数をレジストリ認証文字列に設定します。

レジストリ認証文字列は、<registry-url>=<token>ペアのコンマ区切りのリストです。ここで、registry-urlはContainer registryなどのhttps://containers.SUBDOMAIN.ghe.com URL であり、tokenはそのGitHub Appsのpersonal access tokenトークンまたはContainer registryです。 これにより、各トークンは、指定した Container registry にのみ渡されます。

たとえば、次のレジストリ認証文字列は、 CodeQL CLI が次のように認証されるように指定します。

• トークン <token1>を使用し、Container registryでGitHub.comに認証します。
• トークン<token2>を使用して、企業のContainer registryでhttps://containers.SUBDOMAIN.ghe.comに対して認証を行います。

https://ghcr.io/v2/=<token1>,https://containers.SUBDOMAIN.ghe.com=<token2>

CodeQL パックの発行

CodeQL パックを他のユーザーと共有するには、Container registryに発行します。

公開前に 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 組織で、 <pack> はパックの名前です。

• defaultSuite または defaultSuiteFile のうち、許可されるのは 1 つのみです。 この 2 つは、実行する既定のクエリ スイートを定義する異なる方法です。1 つ目は qlpack.yml ファイルにクエリを直接指定し、2 つ目はパックにクエリ スイートを指定します。

実行中 codeql pack publish

パックを GitHubContainer registryに発行する準備ができたら、pack ディレクトリのルートで次のコマンドを実行できます。

codeql pack publish

発行されたパッケージは、GitHub ファイルのスコープで指定qlpack.yml組織のパッケージ セクションに表示されます。

既存の CodeQL パックのダウンロード

他のユーザーが作成したパックを実行するには、まず次のコマンドを実行してダウンロードする必要があります。

codeql pack download <scope>/<pack>@x.x.x

• <scope>: ダウンロードする GitHub 組織の名前。
• <pack>: ダウンロードするパックの名前。
• @x.x.x: 省略可能なバージョン番号。 省略すると、最新バージョンがダウンロードされます。

このコマンドは、複数のパックの引数を受け入れます。

ダウンロードするクエリ パックの特定のバージョン番号を指定するスクリプトを記述する場合は、 CodeQL のバージョンを新しいバージョンに更新するときに、新しいバージョンのクエリ パックに切り替える必要がある場合があることに注意してください。 新しいバージョンの CodeQL_may_ は、非常に古いバージョンにピン留めされたクエリ パックで使用するとパフォーマンスが低下します。 詳細については、「CodeQL クエリパック参照」を参照してください。

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

CodeQL パックを使用してCodeQL データベースを分析するには、次のコマンドを実行します。

codeql database analyze <database> <scope>/<pack>@x.x.x:<path>

• <database>: CodeQL データベースを分析する。
• <scope>: パックが発行される GitHub 組織の名前。
• <pack>: 使うパックの名前。
• @x.x.x: 省略可能なバージョン番号。 省略すると、最新バージョンが使われます。
• :<path>: クエリ、ディレクトリ、またはクエリ スイートへの省略可能なパス。 省略すると、パックの既定のクエリ スイートが使われます。

analyze コマンドは、指定したCodeQL パックの既定のスイートを実行します。 CodeQL データベースの分析に使用する複数のCodeQL パックを指定できます。 例えば次が挙げられます。

codeql <database> analyze <scope>/<pack> <scope>/<other-pack>