CodeQL クエリによるコード分析

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

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

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

  • GitHub.com のパブリック リポジトリについては、「GitHub CodeQL の使用条件」を参照してください
  • GitHub Code Security が有効になっている GitHub Team または GitHub Enterprise Cloud 上の organization 所有のリポジトリ

この記事で

データベースをCodeQL CLIを使用して分析することについて

コードベースを分析するには、コードから抽出された CodeQL データベースに対してクエリを実行します。 CodeQL 分析では、コード スキャン アラートを生成するために GitHub にアップロードできる結果が生成されます。

[前提条件]

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

  •         [
        CodeQL CLIをローカルでコマンドを実行するために設定する](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli)。

  • 分析するソース コード用のCodeQL データベースを作成します。

            `codeql database analyze`を実行する最も簡単な方法は、CodeQL CLI バンドルに含まれる標準クエリを使用することです。

実行中 codeql database analyze

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

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

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

メモ

1 つのコミットに対して複数の CodeQL データベースを分析する場合は、このコマンドによって生成される結果のセットごとに SARIF カテゴリを指定する必要があります。 結果を GitHubにアップロードすると、 code scanning は、このカテゴリを使用して各言語の結果を個別に格納します。 この操作を忘れた場合は、各アップロードで前の結果が上書きされます。

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>

          `<database>`、`--format`、`--output` を指定する必要があります。 目的の分析に合わせて追加のオプションを指定できます。
Option必須Usage
<database>分析する CodeQL データベースを含むディレクトリのパスを指定します。
<packs,queries>実行 CodeQL パックまたはクエリを指定します。
          code scanningに使用される標準クエリを実行するには、このパラメーターを省略します。 
          CodeQL CLI バンドルに含まれる他のクエリ スイートを表示するには、`codeql resolve queries`を実行します。 ここに一覧表示されているスイートは、`.qls` 拡張子の有無に関係なく提供できます。 独自のクエリ スイートの作成については、[](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites)のドキュメントの CodeQL CLI を参照してください。 |

| --format | | 分析中に生成される結果ファイルの形式を指定します。 CSV、SARIF、グラフ形式など、さまざまな形式がサポートされています。 GitHub にアップロードするには、次の形式でなければなりません: sarif-latest。 詳しくは、「Code scanningの SARIF サポート」をご覧ください。 | | --output | | SARIF 結果ファイルを保存する場所を、.sarif 拡張子と任意のファイル名を含めて指定します。 | | --sarif-category | | 単一データベースの分析の場合は省略可能です。 リポジトリ内の単一コミットに対して複数のデータベースを分析する場合に言語を定義するために必要です。

この分析の SARIF 結果ファイルに含めるカテゴリを指定します。 カテゴリは、同じツールとコミットに対する複数の分析を区別するために使用されますが、異なる言語またはコードの異なる部分で実行されます。 | | --sarif-add-baseline-file-info | | 推奨。 ファイル カバレッジ情報を ツールの状態ページに送信するために使用します。 詳しくは、「コード スキャンにツールの状態ページを使用する」をご覧ください。 | | --sarif-include-query-help | | SARIF 出力にクエリ ヘルプを含めるかどうかを指定します。 次のいずれかです: always: すべてのクエリにクエリ ヘルプを含めます。 custom_queries_only (デフォルト): カスタム クエリ (codeql/<lang>-queries 形式ではないクエリ パックのクエリ) にのみクエリ ヘルプを含めます。 never: どのクエリにもヘルプを含めません。 SARIF 出力に含まれるカスタム クエリのクエリ ヘルプは、クエリのコード スキャンのアラートで表示されます。 詳しくは、「CodeQL CLI のカスタム クエリの記述」をご覧ください。 | | <packs> | | CodeQLクエリ パックを分析に含める場合に使用します。 詳細については、「CodeQL パックのダウンロードと使用」を参照してください。 | | --download | | CodeQL クエリ パックの一部がまだディスク上になく、クエリを実行する前にダウンロードする必要がある場合に使用します。 | | --threads | | 複数のスレッドを使用してクエリを実行する場合に使用します。 既定値は 1 です。 クエリの実行を高速化するために、より多くのスレッドを指定できます。 スレッドの数を論理プロセッサの数に設定するには、0 を指定します。 | | --verbose | | データベース作成プロセスから分析プロセスと診断データに関する詳細情報を取得するために使用します。 | | --threat-model | | (パブリック プレビュー) 脅威モデルを追加して、 CodeQL 分析で追加のソースを構成するために使用します。 パブリック プレビュー中、脅威モデルは Java 分析によってのみサポートされます。 詳しくは、「データベース分析」をご覧ください。 |

メモ

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

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

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

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

          CodeQL データベースの分析の基本的な例

この例では、CodeQLに格納されている/codeql-dbs/example-repo データベースを分析し、結果を SARIF ファイル (/temp/example-repo-js.sarif) として保存します。 --sarif-category を使用して、結果を JavaScript として識別する追加の情報を SARIF ファイルに含めます。 これは、リポジトリ内の 1 つのコミットを分析するために複数の CodeQL データベースがある場合に不可欠です。

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript-typescript \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/codeql-javascript/AngularJS/DisablingSce.ql.
...
> Shutting down query evaluator.
> Interpreting results.

モニタリングのために結果にファイルカバレッジ情報を追加する

必要に応じて、GitHubのツールの状態ページに表示するためにcode scanningするファイル カバレッジ情報を送信できます。 ファイル カバレッジ情報の詳細については、「コード スキャンにツールの状態ページを使用する」を参照してください。

          code scanning結果にファイル カバレッジ情報を含めるには、CI システムの`--sarif-add-baseline-file-info`呼び出しに`codeql database analyze` フラグを追加します。次に例を示します。

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript-typescript \
    --sarif-add-baseline-file-info \ --format=sarif-latest \
    --output=/temp/example-repo-js.sarif

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

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

          CodeQL クエリ パックの実行

          CodeQL
          GitHubから既存のContainer registry クエリ パックを実行するには、1 つ以上のパック名を指定します。

codeql database analyze <database> microsoft/[email protected] github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download

このコマンドは、2 つの CodeQL クエリ パックの既定のクエリ スイート ( microsoft/coding-standards バージョン 1.0.0 と指定したデータベースの最新バージョンの github/security-queries ) を実行します。 既定のスイートの詳細については、「CodeQL パックを発行して使用する」を参照してください。

          `--download` フラグは省略できます。 これを使用すると、クエリ パックがまだローカルで使用できない場合に確実にダウンロードされます。

単一クエリの実行

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

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

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

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

または、 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で使用するクエリの準備の詳細については、「[AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/writing-and-sharing-custom-queries-for-the-codeql-cli)」を参照してください。

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

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

重要

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

たとえば、Functions クエリ パック内の codeql/python-queries ディレクトリに含まれるすべての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 仕様に従って結果が確実に書式設定されます。

          CodeQL パックでのクエリのサブセットの実行

v2.8.1 以降 CodeQL CLI 使用している場合は、パック仕様の最後にパスを含め、パック内のクエリのサブセットを実行できます。 これは、パック内でクエリを検索または実行するすべてのコマンドに適用されます。

クエリのセットを指定する完全な方法は、scope/name@range:path の形式です。各値は次のとおりです。

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

  •         `range` は [semver 範囲](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges)です。

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

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

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

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

パック。

          `experimental/Security`
          `codeql/cpp-queries` パック内の CodeQL フォルダー内のすべてのクエリを使用してデータベースを分析するには、次を使用できます。

codeql database analyze --format=sarif-latest --output=results <db> \
    codeql/cpp-queries:experimental/Security

          `RedundantNullCheckParam.ql`
          `codeql/cpp-queries` パックでCodeQL クエリを実行するには、次のコマンドを使用します。

codeql database analyze --format=sarif-latest --output=results <db> \
    'codeql/cpp-queries:experimental/Likely Bugs/RedundantNullCheckParam.ql'

= 0.0.3 および < 0.1.0 (互換性が最も高いバージョンが選択されます) のバージョンの cpp-security-and-quality.qls``codeql/cpp-queries パックのCodeQL クエリ スイートを使用してデータベースを分析するには、次の方法を使用できます。

codeql database analyze --format=sarif-latest --output=results <db> \
   'codeql/cpp-queries@~0.0.3:codeql-suites/cpp-security-and-quality.qls'

パスにリテラル @ または : が含まれるクエリ ファイル、ディレクトリ、またはスイートを参照する必要がある場合は、次のように、クエリ仕様の前に path: を付けることができます。

codeql database analyze --format=sarif-latest --output=results <db> \
    path:C:/Users/ci/workspace@2/security/query.ql

          CodeQL パックの詳細については、「[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs)」を参照してください。

クエリ スイートの実行

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-queriesCodeQL クエリ パックをダウンロードし、分析を実行し、 GitHubのすべてのバージョンでサポートされている SARIF バージョン 2.1.0 形式のファイルを生成します。 このファイルは、GitHubまたはコード スキャン API を実行して、codeql github upload-resultsにアップロードできます。 詳細については、「CodeQL 分析結果をGitHubにアップロードする」または「コード スキャン用の REST API エンドポイント」を参照してください。

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

詳しくは、「CodeQL クエリ スイートの作成」をご覧ください。

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

汚染されたデータの潜在的なソースを追加するモデル パックを含める

メモ

脅威モデルは現在 パブリック プレビュー 段階であり、変更される可能性があります。 パブリック プレビュー 期間中、脅威モデルは Java/Kotlin と C# 解析でのみサポートされます。

脅威モデルは、 code scanning 分析で構成できます。 詳細については、ドキュメントの「Java 用の脅威モデル」と「C# 用の Kotlin モデル」および「CodeQL」を参照してください。

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

この例では、標準クエリ パック codeql/java-queries の関連するクエリでは、脅威モデルと、local データフロー ソースのデフォルトの remote 脅威モデルが使用されます。 ローカル ソース (ファイル システム、コマンド ライン引数、データベース、環境変数など) のデータを、コードベースの汚染されたデータの潜在的なソースと見なす場合は、local 脅威モデルを使用する必要があります。

結果

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

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

結果の CSV 形式の詳細については、「CodeQL CLI の CSV 出力」を参照してください。

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

ログと診断情報を見る

          CodeQL クエリ スイートを使用してcode scanning データベースを分析すると、アラートに関する詳細情報の生成に加えて、CLI はデータベース生成ステップと概要メトリックから診断データを報告します。 SARIF 出力を生成することを選択した場合は、追加データが SARIF ファイルにも含まれます。 アラートが少ないリポジトリの場合、この情報は、コードに問題がまったくないかどうか、または CodeQL データベースの生成中にエラーが発生したかどうかを判断するのに役立つ場合があります。 
          `codeql database analyze` からさらに詳しい出力を得るには、`--verbose` オプションを使用します。

利用可能な診断情報の種類の詳細については、「コード スキャン ログ」を参照してください。

          GitHub分析が失敗した場合でも、診断情報をエクスポートしてCodeQLにアップロードすることができます。 詳しくは、「[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github#uploading-diagnostic-information-to-github-if-the-analysis-fails)」をご覧ください。

次のステップ

  •         CodeQL分析結果をGitHubにアップロードする方法については、[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github) を参照してください。