Skip to main content
ドキュメントへの更新が頻繁に発行されており、このページの翻訳はまだ行われている場合があります。 最新の情報については、「英語のドキュメント」を参照してください。
All products
コードセキュリティ

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

この記事の内容

独自の CodeQL パックを公開し、他のユーザーが公開したパックを使うことができます。

GitHub CodeQL は、インストール時にユーザーごとにライセンスされます。 CodeQL は、ライセンスの制限の下で特定のタスクでのみ使用できます。 詳しくは、「CodeQL CLI について」を参照してください。

GitHub Enterprise アカウントと GitHub Advanced Security ライセンスがある場合は、CodeQL を使用して、自動分析、継続的インテグレーション、継続的デリバリーを行うことができます。 営業チームに連絡することで、Enterprise アカウントを作成できます。 詳しくは、「GitHub Advanced Security について」を参照してください。

注: この記事は、2023 年 1 月に CodeQL ドキュメント Web サイトから移行されました。

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

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

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

サイト管理者が 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: は/ 形式に従う必要があります。 は公開先の 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 に対して認証できます。

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

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

  1. CodeQL CLI に --registries-auth-stdin オプションを渡し、標準入力を介してレジストリ認証文字列を提供します。
  2. 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>