注: CodeQL パッケージ管理機能 (CodeQL パックを含む) は現在ベータ版として利用でき、変更される可能性があります。 ベータ版リリース中、CodeQL パックは GitHub パッケージ (Container registry) を使用してのみ利用できます。 このベータ機能を使用するには、 https://github.com/github/codeql-action/releases から最新バージョンの CodeQL CLI バンドルをインストールします。
CodeQL パックについて
CodeQL パックを使用して、CodeQL クエリとライブラリを作成、共有、実行したり、これらに依存したりすることができます。 CodeQL パックには、クエリ、ライブラリ ファイル、クエリ スイート、メタデータが含まれます。 他のユーザーが作成したパックをダウンロードし、コードベースで実行することで、CodeQL 分析をカスタマイズできます。
CodeQL パックの 、三つの タイプがあります。クエリ パック、ライブラリ パック、およびモデル パック。
-
クエリ パックには、CodeQL データベースで評価できる事前コンパイル済みクエリのセットが含まれています。 クエリ パックは、実行するように設計されています。 クエリ パックが発行されると、バンドルにはすべての推移的な依存関係と各クエリのプリコンパイル済み表現、およびクエリ ソースが含まれます。 これにより、パック内のクエリの一貫した効率的な実行が保証されます。
-
ライブラリ パックは、クエリ パック (またはその他のライブラリ パック) で使用するように設計されており、クエリ自体は含まれません。 ライブラリはseparately発行されたときにコンパイル キャッシュが含まれません。
-
モデル パックを使用すると、code scanning 分析を展開して、既定でサポートされていないライブラリとフレームワークを認識できます。 モデル パックは現在ベータ版で、変更される可能性があります。 ベータ期間中、モデル パックは Java/Kotlin と C# 分析に使用できます。 独自のモデル パックの作成の詳細については、「CodeQL パックの作成と操作」を参照してください。
サポートされているすべての言語の標準 CodeQL パックは、Container registry で公開されています。 CodeQL CLI バンドルを使用して、標準的な方法で CodeQL CLI をインストールした場合、コア クエリ パックはすでにダウンロードされており、使用できるようになります。 これらは次のとおりです。
codeql/cpp-queriescodeql/csharp-queriescodeql/go-queriescodeql/java-queriescodeql/javascript-queriescodeql/python-queriescodeql/ruby-queriescodeql/swift-queries
CodeQL CLI を使用して、独自の CodeQL パックを作成したり、パックに依存関係を追加したり、依存関係をインストールまたは更新したりできます。 詳しくは、「CodeQL パックの作成と操作」を参照してください。
CodeQL CLI を使用して作成した CodeQL パックを発行できます。 CodeQL パックの公開とダウンロードの詳細については、「CodeQL パックを発行して使用する」をご覧ください。
CodeQL クエリ パックのダウンロードと使用
CodeQL CLI バンドルには、GitHub の専門家、セキュリティ研究者、コミュニティの共同作成者によって管理されるクエリが含まれます。 他の組織によって開発されたクエリを実行する場合、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 ファイルの変更を有効にできなくなる可能性があります。__