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

CodeQL パックについて

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

サイト管理者が CodeQL CLI のバージョンをより新しいリリースに更新している場合は、この記事の GitHub Enterprise Cloud バージョンで最新の機能に関する情報を参照してください。

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-stdin`		GitHub の REST API での認証用に作成された GitHub App または personal access token を標準入力でシークレットストアから CLI に渡します。このトークンを使用して設定された `GITHUB_TOKEN` 環境変数にコマンドがアクセスできる場合、これは必要ありません。

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

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

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

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

最新バージョンの octo-org/security-queries パックをダウンロードします。
バージョン 1.0.1 とocto-org/optional-security-queries互換性のある_バージョンの_パックをダウンロードします (この場合はバージョン 1.0.2 です)。 semver の互換性については、npm のセマンティックバージョンの範囲に関するドキュメントを参照してください。
octo-org/security-queries の既定のクエリをすべて実行します。
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 ファイルの変更を有効にできなくなる可能性があります。__