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

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

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

[前提条件]

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

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

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

実行中 `codeql database analyze`

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

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

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

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` 拡張子の有無に関係なく提供できます。独自のクエリスイートの作成については、のドキュメントの 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-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/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 データベースに対して 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で使用するクエリの準備の詳細については、「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 範囲です。
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 パックの詳細については、「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-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にアップロードすることができます。詳しくは、「CodeQL 分析結果をGitHubにアップロードする」をご覧ください。

次のステップ

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

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

この記事で