構文

codeql database interpret-results --format=<format> --output=<output> [--threads=<num>] <options>... -- <database> <file|dir|suite>...

codeql database interpret-results --format=<format> --output=<output> [--threads=<num>] <options>... -- <database> <file|dir|suite>...

説明

[プラミング] 計算されたクエリ結果を SARIF や CSV などの意味のある形式に解釈します。

結果は計算し終わっていて、codeql database run-queries を使用して CodeQL データベース ディレクトリに保存済みである必要があります (通常は、codeql database analyze を使用して、これらの手順を一緒に実行します)。

[オプション]

主なオプション

<database>

[必須] クエリが実行された CodeQL データベースのパス。

<file|dir|suite>...

ここで実行されたクエリの指定を繰り返します。

省略すると、CLI で codeql database run-queries と同じロジックを使用して、適切なクエリ セットが決定されます。

(将来のバージョンでは、これを省略し、代わりにデータベースで見つかったすべての結果を解釈できるようにする必要があります。 その輝かしい未来はまだありません。 申し訳ありません。)

--format=<format>

[必須] 結果を書き込む形式。 つぎのいずれかです。

csv: ルールとアラート メタデータの両方がある列を含む、書式設定されたコンマ区切りの値。

sarif-latest: Static Analysis Results Interchange Format (SARIF)。静的な分析結果を記述するための JSON ベースの形式。 この形式オプションでは、サポートされている最新バージョン (v2.1.0) が使用されます。 このオプションは、異なる CodeQL バージョン間で異なるバージョンの SARIF が生成されるため、自動化での使用には適していません。

sarifv2.1.0: SARIF v2.1.0。

graphtext: グラフを表すテキスト形式。 @kind グラフを使用するクエリとのみ互換性があります。

dgml: Directed Graph Markup Language。グラフを記述するための XML ベースの形式。 @kind グラフを使用するクエリとのみ互換性があります。

dot: Graphviz DOT 言語。グラフを記述するためのテキストベースの形式。 @kind グラフを使用するクエリとのみ互換性があります。

-o, --output=<output>

[必須] 結果を書き込む出力パス。 グラフ形式の場合、これはディレクトリである必要があり、結果 (このコマンドで複数のクエリの解釈がサポートされている場合は複数の結果) がそのディレクトリ内に書き込まれます。

--max-paths=<maxPaths>

パスを含むアラートごとに生成するパスの最大数。 (デフォルト値: 4)

--[no-]sarif-add-file-contents

[SARIF 形式のみ] 少なくとも 1 つの結果で参照されるすべてのファイルの完全なファイル コンテンツを含めます。

--[no-]sarif-add-snippets

[SARIF 形式のみ] 結果に示されている各場所のコード スニペットを含めます。報告された場所の前後に 2 行のコンテキストがあります。

--[no-]sarif-add-query-help

[SARIF 形式のみ] [非推奨] すべてのクエリの Markdown クエリ ヘルプを含めます。 /path/to/query.md ファイルから /path/to/query.ql のクエリ ヘルプが読み込まれます。 このフラグが指定されていない場合のデフォルトの動作では、カスタム クエリ (`codeql/<lang&rt;-queries` 形式ではないクエリ パック内のクエリ) に対してのみヘルプを含めます。 このオプションは、codeql bqrs interpret に渡しても効果はありません。

--sarif-include-query-help=<mode>

[SARIF 形式のみ] SARIF 出力にクエリ ヘルプを含めるかどうかを指定します。 次のいずれか:

always: すべてのクエリにクエリ ヘルプを含めます。

custom_queries_only(デフォルト値): カスタム クエリ (`codeql/<lang&rt;-queries` 形式ではないクエリ) にのみクエリ ヘルプを含めます。

never: どのクエリにもヘルプを含めません。

このオプションは、codeql bqrs interpret に渡しても効果はありません。

v2.15.2 以降で使用できます。

--no-sarif-include-alert-provenance

[詳細設定] [SARIF 形式のみ] SARIF 出力にアラートの実績情報を含めないでください。

v2.18.1 以降で使用できます。

--[no-]sarif-group-rules-by-pack

[SARIF 形式のみ] <run>.tool.extensions プロパティの対応する QL パックの下に、各クエリのルール オブジェクトを配置します。 このオプションは、codeql bqrs interpret に渡しても効果はありません。

--[no-]sarif-multicause-markdown

[SARIF 形式のみ] 複数の原因があるアラートの場合は、プレーン文字列に加え、マークダウン形式の明細化されたリストとして出力に含めます。

--no-sarif-minify

[SARIF 形式のみ] 再フォーマットされた SARIF 出力を生成します。 既定では、SARIF 出力はミニファイ処理され、出力ファイルのサイズが小さくなります。

--sarif-run-property=<String=String>

[SARIF 形式のみ] 生成された SARIF 'run' プロパティ バッグに追加するキーと値のペア。 繰り返すことができます。

--no-group-results

[SARIF 形式のみ] 一意の場所ごとに 1 つの結果ではなく、メッセージごとに 1 つの結果を生成します。

--csv-location-format=<csvLocationFormat>

CSV 出力で場所を生成する形式。 次のいずれか: uri、行列、オフセット長。 (デフォルト値: 行列)

--dot-location-url-format=<dotLocationUrlFormat>

DOT 出力でファイルの場所 URL を生成する形式を定義する書式設定文字列。 プレース ホルダーとして、{path} {start:line} {start:column} {end:line} {end:column}、{offset}、{length} を使用できます

--[no-]sublanguage-file-coverage

[GitHub.com および GitHub Enterprise Server v3.12.0 以降のみ] サブ言語のファイル カバレッジ情報を使用します。 これにより、C と C++、Java と Kotlin、JavaScript、TypeScript などの CodeQL エクストラクターを共有する言語の個別のファイル カバレッジ情報を計算、表示、エクスポートします。

v2.15.2 以降で使用できます。

--sarif-category=<category>

[SARIF 形式のみ] [推奨] SARIF 出力に含めるこの分析のカテゴリを指定します。 カテゴリを使用して、同じコミットとリポジトリ (ただし、異なる言語またはコードの異なる部分) で実行される複数の分析を区別できます。

同じバージョンのコード ベースを複数の異なる方法で分析し (たとえば、言語が異なる場合)、コード スキャンでプレゼンテーションするために GitHub に結果をアップロードする場合、この値は各分析間で異なる必要があります。これにより、コード スキャンに対して、分析では互いに ''置き換える'' のではなく ''補足する'' ことが示されます __ __ (コード ベースの ''異なる'' バージョンに対して同じ分析の実行間で値の一貫性を保つ必要があります)。__

この値は <run>.automationDetails.id プロパティとして表示されます (存在しない場合は末尾にスラッシュが追加される)。

-j, --threads=<num>

パスの計算に使用されるスレッドの数。

デフォルト値は 1 です。 0 を渡して、コンピューター上のコアごとに 1 つのスレッドを使用したり、N を渡して、N 個のコアを未使用のままにしたりすることができます (ただし、その場合でも、少なくとも 1 つのスレッドが使用されます)。

--no-database-extension-packs

[詳細設定] コード スキャン構成ファイルから、または分析されたコードベースの 'extensions' ディレクトリに格納されている拡張ファイルからデータベースを作成する際に、データベースに格納されている拡張パックを省略します。

--[no-]print-diagnostics-summary

分析した診断の概要を標準出力に出力します。

--[no-]print-metrics-summary

分析したメトリックの概要を標準出力に出力します。

--[no-]print-baseline-loc

カウントされたベースライン コード行を標準出力に出力します。

CodeQL パッケージ マネージャーを構成するためのオプション

--registries-auth-stdin

<registry_url>=<token> ペアのコンマ区切りのリストを渡して、GitHub Enterprise Server コンテナー レジストリに対して認証を行います。

たとえば、https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 を渡して、 2 つの GitHub Enterprise Server インスタンスに対して認証を行うことができます。

これを使って、CODEQL_REGISTRIES_AUTH および GITHUB_TOKEN 環境変数をオーバーライドします。 github.com コンテナー レジストリに対する認証のみが必要な場合は、代わりに、より単純な --github-auth-stdin オプションを使って認証できます。

--github-auth-stdin

標準入力を介して github.com GitHub Apps トークンまたは個人用アクセス トークンを渡して、github.com コンテナー レジストリに対して認証を行います。

GitHub Enterprise Server コンテナー レジストリに対して認証を行うには、--registries-auth-stdin を渡すか、CODEQL_REGISTRIES_AUTH 環境変数を使います。

これを使って、GITHUB_TOKEN 環境変数をオーバーライドします。

結果の解釈に使用する拡張子を指定するオプション

--model-packs=<name@range>...

評価するクエリをカスタマイズするためにモデル パックとして使用する CodeQL パック名のリスト (それぞれがオプションのバージョン範囲を含む)。

QL パックを検索するためのオプション (クエリ スイートを解釈するために必要な場合がある)

--search-path=<dir>[:<dir>...]

QL パックが見つかる可能性があるディレクトリの一覧。 各ディレクトリは、QL パック (またはルートに .codeqlmanifest.json ファイルを含むパックのバンドル)、または 1 つ以上のこのようなディレクトリの直接の親ディレクトリのいずれかです。

パスに複数のディレクトリを含める場合は、それらの順序で、それらの間の優先順位を定義します。解決する必要があるパック名が複数のディレクトリ ツリーで一致する場合は、最初に指定したものが優先されます。

オープンソースの CodeQL リポジトリのチェックアウトでこれを指定すると、そこにある言語の 1 つを照会するときに機能するはずです。

CodeQL リポジトリを、アンパックされた CodeQL ツールチェーンの兄弟としてチェックアウトしている場合、このオプションを指定する必要はありません。このような兄弟ディレクトリは、他の方法では見つからない QL パックについて常に検索されます (このデフォルトが機能しない場合は、ユーザーごとの構成ファイルで --search-path を一度だけ設定することを強くお勧めします)。

(注: Windows では、パスの区切り記号は ; です)。

--additional-packs=<dir>[:<dir>...]

このディレクトリ リストを指定した場合、ディレクトリは、--search-path で指定したものより前に、パックについて検索されます。 これらの間の順序は重要ではありません。このリストの 2 か所でパック名が見つかった場合は、エラーです。

これは、デフォルトのパスにも表示される新しいバージョンのパックを一時的に開発している場合に役立ちます。 一方、構成ファイルでこのオプションをオーバーライドすることは "お勧めしません"。内部アクションによっては、このオプションがオンザフライで追加され、構成済みの値がオーバーライドされます。__

(注: Windows では、パスの区切り記号は ; です)。

共通オプション

-h, --help

このヘルプ テキストを表示します。

-J=<opt>

[詳細設定] コマンドを実行している JVM にオプションを指定します

(スペースを含むオプションは正しく処理されないことに注意してください)。

-v, --verbose

出力される進行状況メッセージの数を段階的に増やします。

-q, --quiet

出力される進行状況メッセージの数を段階的に減らします。

--verbosity=<level>

[詳細設定] 詳細レベルを、errors、warnings、progress、progress+、progress++、progress+++ のいずれかに明示的に設定します。 -v と -q がオーバーライドされます。

--logdir=<dir>

[詳細設定] タイムスタンプと実行中のサブコマンドの名前を含む生成された名前を使用して、指定されたディレクトリ内の 1 つまたは複数のファイルに詳細なログを書き込みます

(完全に制御できる名前でログ ファイルを書き込むには、代わりに --log-to-stderr を指定し、必要に応じて stderr をリダイレクトします)。

--common-caches=<dir>

[[詳細設定] ダウンロードした QL パックやコンパイル済みクエリ プランなど、CLI の複数の実行間に保持される、ディスク上でキャッシュされたデータの場所を制御します。 明示的に設定されない場合、デフォルトではユーザーのホーム ディレクトリに名前が付けられた .codeql ディレクトリになります。まだ存在しない場合は作成されます。

v2.15.2 以降で使用できます。