database interpret-results

This content describes the most recent release of the CodeQL CLI. For more information about this release, see https://github.com/github/codeql-cli-binaries/releases.

To see details of the options available for this command in an earlier release, run the command with the --help option in your terminal.

構文

Shell

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 データベースのパス。

`<filesuite>...`

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

省略すると、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 bqrs interpret に渡しても効果はありません。

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

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

`--[no-]sarif-multicause-markdown`

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

`--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} を使用できます

`--sarif-category=<category>`

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

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

この値は、SARIF v1 では <run>.automationId プロパティ、SARIF v2 では <run>.automationLogicalId プロパティ、SARIF v 2.1.0 では <run>.automationDetails.id プロパティとして表示されます (まだ存在しない場合は末尾にスラッシュが付加される)。

`-j, --threads=<num>`

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

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

`--[no-]print-diagnostics-summary`

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

`--[no-]print-metrics-summary`

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

`--[no-]print-baseline-loc`

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

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

`--registries-auth-stdin`

\<registry_url>=\ ペアのコンマ区切りリストを渡すことで、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 環境変数をオーバーライドします。

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 つの異なる場所でパック名が見つかった場合はエラーです。

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