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

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

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

前提条件

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

コマンドをローカルで実行するように 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 AEにアップロードする際には、code scanningはこのカテゴリを使ってそれぞれの言語に対する結果を別々に保存します。この操作を忘れた場合は、各アップロードで前の結果が上書きされます。

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <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 へのアップロードの場合、これは `sarif-latest` である必要があります。詳しくは、「Code scanningの SARIF サポート」を参照してください。
`--output`		SARIF 結果ファイルを保存する場所を、`.sarif` 拡張子と任意のファイル名を含めて指定します。
`--sarif-category`		単一データベースの分析の場合は省略可能です。リポジトリ内の単一コミットに対して複数のデータベースを分析する場合に言語を定義するために必要です。この分析の SARIF 結果ファイルに含めるカテゴリを指定します。カテゴリは、同じツールとコミットに対する複数の分析を区別するために使用されますが、異なる言語またはコードの異なる部分で実行されます。
`--sarif-add-query-help`		分析で使用されるカスタムクエリに対して使用可能なマークダウンレンダリングクエリヘルプを含める場合に使用します。関連するクエリによってアラートが生成された場合は、SARIF 出力に含まれるカスタムクエリのクエリヘルプがすべてコードスキャン UI に表示されます。詳細については、「CodeQL CLI でのカスタムクエリの使用」を参照してください。
`--threads`		複数のスレッドを使用してクエリを実行する場合に使用します。既定値は `1` です。クエリの実行を高速化するために、より多くのスレッドを指定できます。スレッドの数を論理プロセッサの数に設定するには、`0` を指定します。
`--verbose`		データベース作成プロセスから分析プロセスと診断データに関する詳細情報を取得するために使用します。

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

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 \
    --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.

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

次の例は、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 にアップロードできます。詳細については、「CodeQL 分析結果を GitHub にアップロードする」または「Code Scanning」を参照してください。

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

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

結果

分析結果は、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 AE にエクスポートしてアップロードすることを選択できます。詳しくは、「CodeQL 分析結果を GitHub にアップロードする」を参照してください。

次のステップ

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

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

この記事の内容