CodeQL パックを使った分析のカスタマイズ

CodeQL パックを使用して、他のユーザーが管理している CodeQL クエリを実行したり、自分が開発した CodeQL クエリを共有したりすることができます。

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

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

この記事の内容

CodeQL パックについて

CodeQL パックを使用して、CodeQL クエリとライブラリを作成、共有、実行したり、これらに依存したりすることができます。 CodeQL パックには、クエリ、ライブラリ ファイル、クエリ スイート、メタデータが含まれます。 他のユーザーが作成したパックをダウンロードし、コードベースで実行することで、CodeQL 分析をカスタマイズできます。

CodeQL パックの 、三つの タイプがあります。クエリ パック、ライブラリ パック、およびモデル パック。

  • クエリ パックには、CodeQL データベースで評価できる事前コンパイル済みクエリのセットが含まれています。 クエリ パックは、実行するように設計されています。 クエリ パックが発行されると、バンドルには、クエリ ソースに加えて、各クエリのすべての推移的な依存関係とプリコンパイル済みの表現が含まれます。 これにより、パック内のクエリの一貫した効率的な実行が保証されます。

  • ライブラリ パックは、クエリ パック (またはその他のライブラリ パック) で使用するように設計されており、クエリ自体は含まれません。 ライブラリは個別にコンパイルされません。

  • モデル パックを使用すると、code scanning 分析を展開して、既定でサポートされていないライブラリとフレームワークを認識できます。 モデル パックは現在 パブリック プレビュー にあり、変更される可能性があります。 パブリック プレビュー 期間中、モデル パックは C#、Java/Kotlin、Python、および Ruby 解析に使用できます。 独自のモデル パックの作成に関する詳細については、「CodeQL パックの作成と操作」を参照してください。

サポートされているすべての言語の標準 CodeQL パックは、Container registry で公開されています。 CodeQL CLI バンドルを使用して、標準的な方法で CodeQL CLI をインストールした場合、コア クエリ パックはすでにダウンロードされており、使用できるようになります。 これらは次のとおりです。

  • codeql/cpp-queries
  • codeql/csharp-queries
  • codeql/go-queries
  • codeql/java-queries
  • codeql/javascript-queries
  • codeql/python-queries
  • codeql/ruby-queries
  • codeql/swift-queries

CodeQL CLI を使用して、独自の CodeQL パックを作成したり、パックに依存関係を追加したり、依存関係をインストールまたは更新したりできます。 詳しくは、「CodeQL パックの作成と操作」を参照してください。

CodeQL CLI を使用して作成した CodeQL パックを発行できます。 CodeQL パックの公開とダウンロードの詳細については、「CodeQL パックを発行して使用する」をご覧ください。

CodeQL クエリ パックのダウンロードと使用

CodeQL CLI バンドルには、GitHub の専門家、セキュリティ研究者、コミュニティの共同作成者によって管理されるクエリが含まれます。 他のOrganizationによって開発されたクエリを実行する場合、CodeQL クエリ パックを使用すると、クエリ を効率的かつ信頼性の高い方法でダウンロードして実行できます。一方、モデル パック (パブリック プレビュー ) を使用すると、code scanning 分析を拡張して、既定でサポートされていないライブラリとフレームワークを認識できます 。 クエリ パックについて詳しくは、「CodeQL によるコード スキャンについて」をご覧ください。 独自のモデル パックの記述については、「CodeQL パックの作成と操作」を参照してください。

CodeQL クエリ パックを使ってデータベースを分析する前に、GitHub Container registry から必要なパッケージをすべてダウンロードする必要があります。 これは、codeql database analyze コマンドの一部として --download フラグを使うこと、または codeql pack download を実行することにより行うことができます。 パッケージが一般公開されていない場合は、認証に GitHub App または personal access token を使う必要があります。 詳細と例については、「CodeQL 分析結果を GitHub にアップロードする」をご覧ください。

オプション必須使用法
<scope/name@version:path>コンマ区切りリストを使って、ダウンロードする 1 つまたは複数の CodeQL クエリ パックのスコープと名前を指定します。 必要に応じて、ダウンロードして解凍するバージョンを含めます。 既定では、このパックの最新バージョンがダウンロードされます。 必要に応じて、実行するクエリ、ディレクトリ、またはクエリ スイートへのパスを含めます。 パスが含まれていない場合、このパックの既定のクエリを実行します。
--github-auth-stdinGitHub の REST API での認証用に作成された GitHub App または personal access token を標準入力でシークレット ストアから CLI に渡します。 このトークンを使用して設定された GITHUB_TOKEN 環境変数にコマンドがアクセスできる場合、これは必要ありません。

メモ: 特定のバージョンのクエリ パックを使用するよう指定する場合は、指定したバージョンが、最新バージョンの CodeQL では最終的に古くなりすぎて効率的に使用できなくなる可能性があることに注意してください。 最適なパフォーマンスを確保するために、特定のバージョンのクエリ パックを指定する必要がある場合は、使用している CodeQL CLI をアップグレードするたびに、ピン留めするバージョンを再評価する必要があります。

パックの互換性について詳しくは、「CodeQL パックを発行して使用する」をご覧ください。

クエリ パックのダウンロードと使用の基本的な例

この例では、codeql database analyze コマンドに --download オプションを付けて実行しています。

  1. 最新バージョンの octo-org/security-queries パックをダウンロードします。
  2. バージョン 1.0.1 とocto-org/optional-security-queries互換性のある_バージョンの_パックをダウンロードします (この場合はバージョン 1.0.2 です)。 semver の互換性については、npm のセマンティック バージョンの範囲に関するドキュメントを参照してください。
  3. octo-org/security-queries の既定のクエリをすべて実行します。
  4. octo-org/optional-security-queries のクエリ queries/csrf.ql だけを実行します
$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
    octo-org/security-queries \
    octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.

CodeQL パックの直接ダウンロード

CodeQL パックをダウンロードしてすぐに実行しない場合、codeql pack download コマンドを使用できます。 これは、CodeQL クエリを実行するとき、インターネットへのアクセスをしないようにする場合、便利です。 CodeQL 分析を実行するとき、前の例と同じ方法でパック、バージョン、パスを指定できます。

echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...

複数の GitHub コンテナー レジストリから CodeQL パックをダウンロードする

CodeQL パックが複数のコンテナー レジストリに存在する場合は、各パックを検索する場所を CodeQL CLI に示す必要があります。 詳しくは、「コード スキャン用の高度なセットアップのカスタマイズ」を参照してください。

CodeQL パックで実行するクエリの指定

クエリ指定子は、一連のクエリに対して動作する codeql database analyze やその他のコマンドによって使用されます。 クエリ指定子の完全な形式は scope/name@range:path です。各値は次のとおりです。

  • scope/name は、CodeQL パックの修飾名です。
  • range は semver 範囲です。
  • path は、単一のクエリ、クエリを含むディレクトリ、またはクエリ スイート ファイルへのファイル システム パスです。

scope/name を指定する場合は、range と path を省略できます。 range を省略すると、指定したパックの最新バージョンが使用されます。 path を省略すると、指定したパックの既定のクエリ スイートが使用されます。

path は、.ql クエリ ファイル、1 つまたは複数のクエリを含むディレクトリ、または .qls クエリ スイート ファイルにすることができます。 パック名を省略する場合は、path を指定する必要があります。これは、現在のプロセスの作業ディレクトリに対して相対的であると解釈されます。 glob パターンはサポートされていません。

scope/name と path の両方を指定した場合は、path を絶対にすることはできません。 これは、CodeQL パックのルートに対して相対的であると見なされます。

クエリ指定子の例

  • codeql/python-queries - 最新バージョンの codeql/python-queries パックの既定のクエリ スイート内のすべてのクエリ。

  • codeql/python-queries@1.2.3 - バージョン 1.2.3 の codeql/python-queries パックの既定のクエリ スイート内のすべてのクエリ。

  • codeql/python-queries@~1.2.3 - 最新バージョン (1.2.3 以上、1.3.0 未満) の codeql/python-queries パックの既定のクエリ スイート内のすべてのクエリ。

  • codeql/python-queries:Functions - 最新バージョンの codeql/python-queries パックの Functions ディレクトリ内のすべてのクエリ。

  • codeql/python-queries@1.2.3:Functions - バージョン 1.2.3 の codeql/python-queries パックの Functions ディレクトリ内のすべてのクエリ。

  • codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls - バージョン 1.2.3 の codeql/python-queries パックの codeql-suites/python-code-scanning.qls ディレクトリ内のすべてのクエリ。

  • suites/my-suite.qls - 現在の作業ディレクトリに対して相対的な suites/my-suite.qls ファイル内のすべてのクエリ。

ヒント

標準の CodeQL クエリ パックの既定のクエリ スイートは codeql-suites/<lang>-code-scanning.qls です。 その他の便利なクエリ スイートも、各パックの codeql-suites ディレクトリにあります。 たとえば、codeql/cpp-queries パックには次のクエリ スイートが含まれています。

  • cpp-code-scanning.qls - C++ の標準コード スキャン クエリ。 このパックの既定のクエリ スイート。

  • cpp-security-extended.qls - C++ の既定の cpp-code-scanning.qls スイートからのクエリに加え、重要度と精度の低いクエリ。

  • cpp-security-and-quality.qls - cpp-security-extended.qls からのクエリに加え、保守性および信頼性のクエリ。

これらのクエリ スイートのソースは、CodeQL リポジトリで確認できます。 他の言語のクエリ スイートも同様です。

モデル パックを使用して、依存関係をカスタムする呼び出しを分析する

公開されたモデル パックは、--model-packs オプションを使用して code scanning 分析に含めることができます。 次に例を示します。

$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \
  --model-packs my-repo/my-java-model-pack \
  --output=/temp/my-company.sarif codeql/java-queries

この例では、標準クエリ パック codeql/java-queries の関連するクエリは、モデル パック、my-repo/my-java-model-pack の依存関係情報を使用して、それらの依存関係を呼び出すコードの脆弱性をチェックします。

1 つの分析で複数の公開済みモデル パックを指定できます。

独自のモデル パックの記述について詳しくは、「CodeQL パックの作成と操作」をご覧ください。

発行済みパックについて

パックが分析で使用するために発行されると、codeql pack create または codeql pack publish コマンドによって、コンテンツが完全であることが確認され、コンテンツのいくつかの部分が追加されます。

  • クエリ パックの場合、それが依存する各ライブラリ パックのコピーであり、開発に使用された正確なバージョンです。 クエリ パックのユーザーは、これらのライブラリ パックを個別にダウンロードする必要はありません。

  • クエリ パックの場合、各クエリのプリコンパイル済み表現。 これらは、分析ごとにクエリの QL ソースをコンパイルするよりも高速に実行できます。

このデータのほとんどは、発行済みパック内の .codeql という名前のディレクトリにありますが、プリコンパイル済みクエリは、各クエリの .ql ソースの後にサフィックス .qlx が付いたファイル内にあります。 発行済みパックのクエリを使用してデータベースを分析する場合、CodeQL は、.ql ソースの代わりにこれらのファイルをロードします。 "発行済み" パックのコンテンツを変更する必要がある場合、必ず .qlx ファイルをすべて削除してください。これらによって、.ql ファイルの変更を有効にできなくなる可能性があります。__