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

          CodeQL パックを共有またはダウンロードし、CodeQL データベースを分析します。

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

CodeQL は、次の種類のリポジトリで使用できます:

  • GitHub.com のパブリック リポジトリについては、「GitHub CodeQL の使用条件」を参照してください
  • GitHub Code Security が有効になっている GitHub Team または GitHub Enterprise Cloud 上の organization 所有のリポジトリ

この記事で

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

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

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` の詳細については、「[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 Cloudのパックを管理できるようになりました。

認証中 GitHubContainer registries

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

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



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

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

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

同様に、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>を使用し、GitHub.comでContainer registryに認証します。
  • トークン<token2>を使用して、企業のhttps://containers.SUBDOMAIN.ghe.comでContainer registryに対して認証を行います。
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組織のパッケージ セクションに表示されます。

メモ

既定のセットアップ構成の一部として組織内のすべてのリポジトリにカバレッジを拡張するためにモデル パックを GitHubContainer registry に発行する場合は、コード スキャンを実行しているリポジトリがそれらのモデル パックにアクセスできることを確認する必要があります。 詳細については、「既定設定の構成を編集する」および「パッケージのアクセス制御と可視性の設定」を参照してください。

既存の 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>

メモ

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