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

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

既定では、CodeQL CLI は、GitHub.com の Container registry から CodeQL パックをダウンロードし、そこにパックを公開することを想定しています。ただし、qlconfig.yml ファイルを作成して、各パックに使う Container registry を CLI に指示することで、GitHub Enterprise Server の Container registry 内の CodeQL パックを操作することもできます。

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

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

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

          `registries` リストは、`codeql-workspace.yml` ファイル内に配置することもできます。 そうすることで、特定のワークスペース内で使うレジストリを定義でき、ワークスペースの他の CodeQL ユーザー間で共有できるようにします。 
          `registries` 内の `codeql-workspace.yml` リストはマージされ、グローバルな `qlconfig.yml` 内のリストよりも優先されます。 
          `codeql-workspace.yml` の詳細については、「[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#about-codeql-workspaces)」を参照してください。

          `codeql pack publish`、および `codeql pack download`、`codeql database analyze` を使って、GitHub Enterprise Server でパックを管理できるようになりました。

GitHub Container registries への認証

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

Container registries on GitHub.com

への認証

2 日以内に Container registry に対して認証できます。

CodeQL CLI に --github-auth-stdin オプションを渡し、標準入力を介して GitHub Apps トークンまたは personal access token を提供します。

       `GITHUB_TOKEN` 環境変数を GitHub Apps トークンまたは personal access token に設定します。

GitHub Enterprise Server の Container registries への認証

同様に、次の 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 はその Container registry の GitHub Apps トークンまたは personal access token です。これにより、各トークンは、指定した Container registry にのみ確実に渡されます。

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

トークン <token1> を使用して、GitHub.com の Container registry に対して認証します。
トークン <token2> を使って、https://containers.GHE_HOSTNAME/v2/ で、エンタープライズの Container registry に対して認証します。

https://ghcr.io/v2/=<token1>,https://containers.GHE_HOSTNAME/v2/=<token2>

CodeQL パックの公開

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

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

メモ

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

サイト管理者が 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パックをダウンロードする

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

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

        `<scope>`: ダウンロード元の GitHub 組織の名前。

        `<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 組織の名前。

        `<pack>`: 使うパックの名前。

        `@x.x.x`: 省略可能なバージョン番号。 省略すると、最新バージョンが使われます。

        `:<path>`: クエリ、ディレクトリ、またはクエリ スイートへの省略可能なパス。 省略すると、パックの既定のクエリ スイートが使われます。

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

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

メモ

注: codeql pack download コマンドでは、ダウンロードされたパックが、ローカルの変更を意図していない内部の場所に格納されます。パックをダウンロード後に変更すると、予期しない (トラブルシューティングが難しい) 動作が発生する可能性があります。パックのカスタマイズの詳細については、「CodeQL パックの作成と操作」を参照してください。

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

この記事で