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

CodeQL CLI でのデータベースの分析

コードベースから抽出された CodeQL データベースに対してクエリを実行できます。

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

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

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

CodeQL CLI でのデータベースの分析について

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

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

コードベースを分析するには、コードから抽出された CodeQL データベースに対してクエリを実行します。

CodeQL 分析では、ソース コードで警告またはパスとして表示できる解釈された結果 が生成されます。 database analyze で実行するクエリの記述について詳しくは、「CodeQL CLI でのカスタム クエリの使用」を参照してください。

その他のクエリ実行コマンド

database analyze で実行されるクエリには、厳密なメタデータ要件があります。 次のプラミング レベルのサブコマンドを使用してクエリを実行することもできます。

  • database run-queries を実行すると、解釈されていない結果を BQRS と呼ばれる中間バイナリ形式で出力します

  • クエリの実行 を実行すると、BQRS ファイルが出力されるか、結果テーブルがコマンド ラインに直接出力されます。 コマンド ラインで結果を直接表示すると、CLI を使用した反復クエリ開発に役立つ場合があります。

これらのコマンドを使用して実行されるクエリのメタデータ要件は同じではありません。 ただし、人間が判読できるデータを保存するには、bqrs decode プラミング サブコマンドを使って各 BQRS 結果ファイルを処理する必要があります。 そのため、ほとんどのユース ケースでは、database analyze を使用して、解釈された結果を直接生成するのが最も簡単です。

分析を開始する前に、次のことを行う必要があります。

codeql database analyze を実行する最も簡単な方法は、CodeQL パックを使用することです。 また、CodeQL リポジトリのローカル チェックアウトからのクエリを使用してコマンドを実行することもできます。これは、CodeQL コア クエリをカスタマイズする場合に実行することがあります。

実行中 codeql database analyze

database analyze を実行すると、次のようになります。

  1. 必要に応じて、ローカルで使用できない参照される CodeQL パッケージがダウンロードされます。
  2. CodeQL データベースで実行することで、1 つまたは複数のクエリ ファイルが実行されます。
  3. 特定のクエリ メタデータに基づいて結果が解釈され、ソース コード内の正しい場所に警告を表示できるようにします。
  4. 診断およびサマリー クエリの結果が標準出力に報告されます。

次のコマンドを実行して、データベースを分析できます。

codeql database analyze <database> --format=<format> --output=<output> <query-specifiers>...

ユーザーは次のものを指定する必要があります。

  • <database>: 分析する CodeQL データベースへのパス。
  • --format: 分析中に生成される結果ファイルの形式。 CSV、SARIF、グラフ形式など、さまざまな形式がサポートされています。 CSV と SARIF について詳しくは、「結果」を参照してください。 サポートされているその他の結果形式については、「database analyze」をご覧ください。
  • --output: 分析中に生成される結果ファイルの出力パス。

以下を指定することもできます。

  • <query-specifiers>...: データベースで実行するクエリのスペース区切りリスト。 これは引数のリストです。各引数には以下を指定することができます。

    • クエリ ファイルへのパス
    • クエリ ファイルを含むディレクトリへのパス
    • クエリ スイート ファイルへのパス
    • CodeQL クエリ パックの名前
      • 省略可能なバージョン範囲を指定
      • パック内のクエリ、ディレクトリ、またはクエリ スイートへの省略可能なパスを指定

    省略すると、分析されたデータベースの言語の既定のクエリ スイートが使用されます。 クエリ指定子の完全な構文については、「CodeQL パックで実行するクエリの指定」をご覧ください。

  • --sarif-category: 結果の識別カテゴリ。 コミットに複数の結果セットをアップロードする場合に使用します。 たとえば、github upload-results を使用して複数の言語の結果を GitHub コード スキャン API に送信する場合です。 このユース ケースについて詳しくは、「CI システムでの CodeQL CLI の構成」を参照してください。

  • --sarif-add-query-help: (バージョン 2.7.1 以降でサポートされている) Markdown で記述されたカスタム クエリ ヘルプを、分析によって生成された SARIF ファイル (v2.1.0 以降) に追加します。 分析を実行する前に、.qhelp ファイルに格納されているクエリ ヘルプを .md に変換する必要があります。 詳しくは、「SARIF ファイルにカスタム CodeQL クエリのクエリ ヘルプを含める」をご覧ください。

  • --download: ローカルで使用できない参照されている CodeQL パッケージを CLI でダウンロードできるようにするブール値フラグ。 このフラグが欠落していて、参照されている CodeQL パッケージがローカルで使用できない場合、コマンドは失敗します。

データベースのアップグレード

CodeQL CLI v2.3.3 以前で作成されたデータベースの場合は、新しいバージョンの CodeQL CLI で分析を実行する前に、データベースを明示的にアップグレードする必要があります。 この手順が必要な場合は、database analyze の実行時にデータベースをアップグレードする必要があることを示すメッセージが表示されます。

CodeQL CLI v2.3.4 以降によって作成されたデータベースの場合は、CLI で必要なアップグレードが暗黙的に実行されます。 アップグレード コマンドを明示的に実行する必要はありません。

データベースを分析するときに使うことができるすべてのオプションについて詳しくは、「database analyze」をご覧ください。

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

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

  • scope/name は、CodeQL パックの修飾名です。

  • rangesemver 範囲です。

  • path は、単一のクエリ、クエリを含むディレクトリ、またはクエリ スイート ファイルへのファイル システム パスです。

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

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

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

クエリ指定子の例

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

  • codeql/python-queries@1.2.3 - バージョン 1.2.3codeql/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 リポジトリで確認できます。 他の言語のクエリ スイートも同様です。

データベース分析の実行例

次の例は、CodeQL パックを使用して database analyze を実行する方法と、CodeQL リポジトリのローカル チェックアウトを使用する方法を示しています。 これらの例では、CodeQL リポジトリのローカル コピーの兄弟であるディレクトリに CodeQL データベースが作成されていることを前提としています。

単一クエリの実行

JavaScript コードベースの CodeQL データベースに対して単一のクエリを実行する場合は、データベースを含むディレクトリから次のコマンドを使用できます。

codeql database analyze --download <javascript-database> codeql/javascript-queries:Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv

このコマンドでは、未使用の変数、インポート、関数、またはクラスに関連する潜在的なバグを検出するシンプルなクエリを実行します。これは、CodeQL リポジトリに含まれる JavaScript クエリの 1 つです。 同様のパスのスペース区切りリストを指定することで、複数のクエリを実行できます。

分析により、新しいディレクトリ (js-analysis) に CSV ファイル (js-results.csv) が生成されます。

または、CodeQL リポジトリがチェックアウトされている場合は、クエリへのパスを直接指定することで、同じクエリを実行できます。

codeql database analyze <javascript-database> ../ql/javascript/ql/src/Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv

database analyze コマンドを使用して、独自のカスタム クエリを実行することもできます。 CodeQL CLI で使うクエリの準備について詳しくは、「CodeQL CLI でのカスタム クエリの使用」をご覧ください。

ディレクトリ内のすべてのクエリの実行

ディレクトリ内にあるすべてのクエリは、個々のクエリ ファイルをすべて一覧表示するのではなく、ディレクトリ パスを指定することで実行できます。 パスは再帰的に検索されるため、サブフォルダーに含まれるすべてのクエリも実行されます。

重要

database analyze の実行中にコア CodeQL クエリ パックのルートを指定することは避けてください。コマンドで使用するように設計されていない特殊ないくつかのクエリが含まれている可能性があるためです。 代わりに、クエリ パックを実行して、パックの既定のクエリを分析に含めるか、コード スキャン クエリ スイートのいずれかを実行します。

たとえば、codeql/python-queries クエリ パック内の Functions ディレクトリに含まれるすべての Python クエリを実行するには、次のように実行します。

codeql database analyze <python-database> codeql/python-queries:Functions --format=sarif-latest --output=python-analysis/python-results.sarif --download

または、CodeQL リポジトリがチェックアウトされている場合は、ディレクトリへのパスを直接指定して、同じクエリを実行できます。

codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif

分析が完了すると、SARIF 結果ファイルが生成されます。 --format=sarif-latest を指定すると、CodeQL でサポートされている最新の SARIF 仕様に従って結果が確実に書式設定されます。

クエリ スイートの実行

C/C++ コードベースの CodeQL データベースに対してクエリ スイートを実行する場合は、データベースを含むディレクトリから次のコマンドを使用できます。

codeql database analyze <cpp-database> codeql/cpp-queries:codeql-suites/cpp-code-scanning.qls --format=sarifv2.1.0 --output=cpp-results.sarif --download

このコマンドでは、codeql/cpp-queries CodeQL クエリ パックをダウンロードし、分析を実行し、すべてのバージョンの GitHub でサポートされている SARIF バージョン 2.1.0 形式のファイルを生成します。 このファイルは、codeql github upload-results またはコード スキャン API を実行して、GitHub にアップロードできます。 詳細については、「CIシステムでのCodeQL CLIの設定」または「Code Scanning」を参照してください。

CodeQL クエリ スイートは、ディレクティブを使用して、特定のメタデータ プロパティに基づいて実行するクエリを選択する .qls ファイルです。 標準の CodeQL パックには、コード スキャンで使用されるクエリ スイートの場所を指定するメタデータがあるため、CodeQL CLI でこれらのスイート ファイルを自動的に検索する場所が認識されており、ユーザーがコマンド ラインで完全なパスを指定する必要はありません。 詳しくは、「CodeQL クエリ スイートの作成」をご覧ください。

カスタム クエリ スイートの作成の詳細については「CodeQL クエリ スイートの作成」を参照してください。

診断およびサマリー情報

CodeQL データベースを作成すると、エクストラクターにより診断データがデータベースに格納されます。 コード スキャン クエリ スイートには、この診断データをレポートし、サマリー メトリックを計算するための追加のクエリが含まれています。 database analyze コマンドが完了すると、CLI によって結果ファイルが生成され、診断およびサマリー データが標準出力に報告されます。 SARIF 出力を生成することを選択した場合は、追加データが SARIF ファイルにも含まれます。

分析で予想よりも少ない標準クエリの結果が見つかった場合は、診断およびサマリー クエリの結果を確認して、CodeQL データベースが、分析するコードベースの適切な表現である可能性があるかどうかを確認します。

GitHub のコード スキャン ワークフローへの CodeQL パックの統合

コード スキャンのセットアップでは、CodeQL クエリ パックを使用できます。 これにより、さまざまなソースによって発行されたクエリ パックを選択し、それらを使用してコードを分析できます。 詳しくは、CodeQL アクションでの CodeQL クエリ パックの使用に関するページ、または CI システムでの CodeQL クエリ パックのダウンロードと使用に関するページをご覧ください。

SARIF ファイルにカスタム CodeQL クエリのクエリ ヘルプを含める

CodeQL CLI を使用してサードパーティの CI/CD システムでコード スキャン分析を実行する場合は、分析中に生成された SARIF ファイルにカスタム クエリのクエリ ヘルプを含めることができます。 SARIF ファイルを GitHub にアップロードした後、カスタム クエリによって生成された警告のコード スキャン UI にクエリ ヘルプが表示されます。

CodeQL CLI v2.7.1 以降では、codeql database analyze の実行時に --sarif-add-query-help オプションを指定することで、SARIF ファイルに Markdown レンダリング クエリ ヘルプを含めることができます。 詳しくは、「CI システムでの CodeQL CLI の構成」を参照してください。

カスタム クエリのクエリ ヘルプを Markdown ファイルに直接記述し、対応するクエリと共に保存できます。 または、標準の CodeQL クエリとの一貫性を保つために、クエリ ヘルプを .qhelp 形式で記述することもできます。 .qhelp ファイルに書き込まれたクエリ ヘルプは SARIF ファイルに含めることはできません。また、コード スキャンでは処理できないため、分析を実行する前に Markdown に変換する必要があります。 詳しくは、「クエリ ヘルプ ファイル」と「クエリ ヘルプ ファイルのテスト」をご覧ください。

結果

分析結果は、SARIF や CSV など、さまざまな形式で保存できます。

SARIF 形式は、さまざまな種類の静的分析ツールの出力を表すように設計されています。 詳しくは、「SARIF 出力」を参照してください。

結果を CSV 形式で生成することを選択した場合、出力ファイル内の各行は警告に対応します。 各行は、次の情報を含むコンマ区切りリストです。

プロパティ説明
名前結果を識別したクエリの名前。Inefficient regular expression
説明クエリの説明。A regular expression that requires exponential time to match certain inputs can be a performance bottleneck, and may be vulnerable to denial-of-service attacks.
重大度クエリの重大度。error
Message警告メッセージ。This part of the regular expression may cause exponential backtracking on strings containing many repetitions of '\\\\'.
パス警告を含むファイルのパス。/vendor/codemirror/markdown.js
開始行警告をトリガーしたコードが開始されるファイルの行。617
開始列警告コードの開始を示す開始行の列。 1 に等しい場合は含まれません。32
終了行警告をトリガーしたコードが終了するファイルの行。 開始行と同じ値の場合は含まれません。64
終了列使用可能な場合は、警告コードの終了を示す終了行の列。 それ以外の場合は、終了行が繰り返されます。617

結果ファイルは、独自のコード レビューまたはデバッグ インフラストラクチャに統合できます。 たとえば、SARIF ファイル出力を使用すると、IDE 用の SARIF ビューアー プラグインを使って、ソース コード内の正しい場所にある警告を強調表示できます。

参考資料