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

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

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

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

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

前提条件

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

コマンドをローカルで実行するように CodeQL CLI を設定する。
分析するソースコードの CodeQL データベースを作成する。

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

実行中 `codeql database analyze`

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

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

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

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

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

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

<database>、--format、--output を指定する必要があります。目的の分析に合わせて追加のオプションを指定できます。

オプション	必須	使用法
`<database>`		分析するCodeQLデータベースを含むディレクトリのパスを指定します。
`<packs,queries>`		実行する CodeQL パックまたはクエリを指定します。 code scanning に使用される標準クエリを実行するには、このパラメーターを省略します。 CodeQL CLI バンドルに含まれている他のクエリスイートを確認する場合は、`/<extraction-root>/qlpacks/codeql/<language>-queries/codeql-suites` を参照してください。独自のクエリスイートの作成については、CodeQL CLI 用ドキュメントの「CodeQL クエリスイートの作成」をご覧ください。
`--format`		分析中に生成される結果ファイルの形式を指定します。 CSV、SARIF、グラフ形式など、さまざまな形式がサポートされています。 GitHubにアップロードする場合、これは`sarifv2.1.0`である必要があります。詳しくは、「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 分析でのみサポートされます。詳しくは、「database analyze」を参照してください。

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

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

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

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

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

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

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript-typescript \
    --format=sarifv2.1.0 --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 Enterprise Server にファイルカバレッジ情報を送信して、code scanning のツールの状態ページページに表示できます。ファイルカバレッジ情報の詳細については、「コードスキャンのツール状態ページについて」を参照してください。

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

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

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

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

CodeQL クエリパックの実行

GitHub Container registry の既存の CodeQL クエリパックを実行する場合は、1 つまたは複数のパック名を指定できます。

codeql database analyze <database> microsoft/coding-standards@1.0.0 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 データベースに対して単一のクエリを実行する場合は、データベースを含むディレクトリから次のコマンドを使用できます。

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 仕様に従って結果が確実に書式設定されます。

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

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

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

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

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

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

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

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

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

codeql/cpp-queries CodeQL パックの RedundantNullCheckParam.ql クエリを実行するには、以下を使用します。

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

0.0.3 以上、0.1.0 未満 (互換性が最も高いバージョンが選択される) のバージョンの codeql/cpp-queries CodeQL パックの cpp-security-and-quality.qls クエリスイートを使用してデータベースを分析する場合は、以下を使用できます。

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 パックについて詳しくは、「CodeQL パックを使った分析のカスタマイズ」をご覧ください。

クエリスイートの実行

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 にアップロードできます。詳細については、「CodeQL 分析結果を GitHub にアップロードする」または「コードスキャン用の REST API エンドポイント」を参照してください。

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

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

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

注: 脅威モデルは現在ベータ段階であり、変更される可能性があります。ベータ期間中、脅威モデルは Java/Kotlin および C# 解析でのみサポートされます。

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

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

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

結果

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

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

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

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

ログと診断情報を見る

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

利用可能な診断情報の種類について詳しくは、「Code scanningログの表示」を参照してください。

CodeQL の分析が失敗した場合でも、診断情報を GitHub Enterprise Server にエクスポートしてアップロードすることを選択できます。詳しくは、「CodeQL 分析結果を GitHub にアップロードする」を参照してください。

次のステップ

CodeQL 分析結果を GitHub Enterprise Server にアップロードする方法については、「CodeQL 分析結果を GitHub にアップロードする」を参照してください。