CodeQL CLI SARIF 出力

SARIF 出力について

SARIF は、さまざまな静的分析ツールの出力を表すように設計されており、SARIF 仕様には、"省略可能" と見なされる多くの機能があります。 このドキュメントでは、SARIF v2.1.0.csd1 仕様に対応する形式の種類 sarifv2.1.0を使用するときに生成される出力について詳しく説明します。 分析結果のファイル形式の選択について詳しくは、CodeQL ドキュメントの database analyze コマンドを参照してください。

SARIF の仕様とスキーマ

この記事は、詳しい SARIF 仕様と併せて読むことを目的としています。 仕様と SARIF スキーマについて詳しくは、SARIF 仕様のドキュメントを参照してください。

変更に関するメモ

バージョン間の変更

CodeQL バージョン	形式の種類	[変更点]
2.0.0	sarifv2.1.0	この形式の最初のバージョン。

出力に対する将来の変更

特定の形式の種類 (たとえば、sarifv2.1.0) に対して生成される出力は、CodeQL の将来のリリースで変更される可能性があります。 GitHub では、生成された SARIF のコンシューマーとの下位互換性を維持するために、次のことを保証するよう努めます。

• 常に生成されるとマークされているフィールドは決して削除されません。

• 常に生成されるわけではないとマークされているフィールドの場合、フィールドが生成される状況が変わる可能性があります。 CodeQL SARIF 出力のコンシューマーは、これらのフィールドの有無に対して堅牢である必要があります。

将来のリリースでは、新しい出力フィールドが同じ形式の種類で追加される可能性があります。これらは後方互換性を損なうとは見なされず、コンシューマーは新しく追加されたフィールドの存在に対して堅牢である必要があります。

CodeQL の将来のバージョンでは、新しい形式引数の種類が追加される可能性があります (たとえば、新しいバージョンの SARIF をサポートするため)。 これらについては、明示的に文書化されていない限り、下位互換性は保証されません。

生成される SARIF オブジェクト

ここでは、生成される可能性のある各 SARIF コンポーネントと、特定の状況について詳しく説明します。 生成されないプロパティは省略します。

sarifLog オブジェクト

JSON プロパティ名	常に生成されますか?	Notes
$schema		SARIF スキーマへのリンクを提供します。
version		出力の生成に使用される SARIF のバージョン。
runs		1 つの言語の単一の実行オブジェクトを含む配列。

run オブジェクト

JSON プロパティ名	常に生成されますか?	Notes
tool		なし
originalUriBaseIds		分析マシン上の元の場所を表す artifactLocations への uriBaseIds のディクショナリ。 これには少なくとも %SRCROOT% uriBaseId が含まれます。これは、分析されたプロジェクトのソース コードの分析マシン上にあるルートの場所を表します。 各 artifactLocation には、uri および description プロパティが含まれます。
artifacts		結果で参照されるすべてのファイルに対して少なくとも 1 つの成果物オブジェクトを含む配列。
results		なし
newLineSequences		なし
columnKind		なし
properties		プロパティ ディクショナリには、CodeQL CLI に渡される形式指定子を識別する semmle.formatSpecifier が含まれます。

tool オブジェクト

JSON プロパティ名	常に生成されますか?	Notes
driver		なし

toolComponent オブジェクト

JSON プロパティ名	常に生成されますか?	Notes
name		CodeQL CLI ツールからの出力については、"CodeQL command-line toolchain" に設定します。 出力が別のツールを使用して生成された場合、別の name が報告され、形式がここで説明されているものと異なる場合があることに注意してください。
organization		"GitHub" に設定します。
version		CodeQL リリース バージョン (たとえば、"2.0.0") に設定します。
rules		ルールを表す reportingDescriptor オブジェクトの配列。 この配列には、少なくとも、この分析中に実行されたすべてのルールが含まれますが、使用可能でも実行されなかったルールが含まれている可能性があります。 クエリの有効化について詳しくは、defaultConfiguration を参照してください。

reportingDescriptor オブジェクト (ルール用)

reportingDescriptor オブジェクトは、SARIF 仕様の複数の場所で使用できます。 reportingDescriptor が toolComponent オブジェクトのルール配列に含まれている場合、それには次のプロパティが含まれます。

JSON プロパティ名	常に生成されますか?	Notes
id		ルールを定義するクエリで指定された @id プロパティが含まれます。通常、形式は language/rule-name です (たとえば、cpp/unsafe-format-string)。 Organization によってクエリで @opaqueid プロパティが定義されている場合、代わりにそれが使用されます。
name		クエリで指定された @id プロパティが含まれます。 例については、上記の id プロパティを参照してください。
shortDescription		ルールを定義するクエリで指定された @name プロパティが含まれます。
fullDescription		ルールを定義するクエリで指定された @description プロパティが含まれます。
defaultConfiguration		reportingConfiguration オブジェクト。有効なプロパティは、true または false に設定され、レベル プロパティは、ルールを定義するクエリで指定された @severity プロパティに従って設定されます。 @severity プロパティが指定されていない場合は省略されます。

artifact オブジェクト

JSON プロパティ名	常に生成されますか?	Notes
location		artifactLocation オブジェクト。
index		artifact オブジェクトのインデックスです。
contents		--sarif-add-file-contents フラグを使用して結果が生成され、SARIF ファイルの生成時にソース コードが利用可能である場合、contents プロパティには、text プロパティが設定された artifactContent オブジェクトが設定されます。

artifactLocation オブジェクト

JSON プロパティ名	常に生成されますか?	Notes
uri		なし
index		なし
uriBaseId		ファイルが、分析マシン上のルート ソースの場所など、既知の抽象的な場所を基準とする場合は、これが設定されます。

result オブジェクト

結果の構成は、CodeQL に提供されるオプションによって異なります。 既定では、結果は、一意のメッセージ形式文字列とプライマリの場所別にグループ化されます。 したがって、同じ場所で発生し、同じ基になるメッセージを含む 2 つの結果は、出力では 1 つの結果として表示されます。 この動作は、フラグ --ungroup-results を使用して無効にすることができます。この場合、結果はグループ化されません。

JSON プロパティ名	常に生成されますか?	Notes
ruleId		「reportingDescriptor オブジェクト (ルール用)」の id プロパティの説明を参照してください。
ruleIndex		なし
message		この場所で発生した問題を説明するメッセージ。 このメッセージは SARIF "プレースホルダーを含むメッセージ" である可能性があり、これには、relatedLocations プロパティ内の場所を参照するリンクが含まれます。
locations		1 つの location オブジェクトを含む配列。
partialFingerprints		名前付き指紋の種類から指紋へのディクショナリ。 これには、少なくとも primaryLocationLineHash の値が含まれるので、プライマリの場所のコンテキストに基づいて指紋が提供されます。
codeFlows		この結果のルールを定義するクエリが @kind path-problem の場合、この配列には 1 つ以上の codeFlow オブジェクトが設定されることがあります。
relatedLocations		この結果のルールを定義するクエリにプレースホルダー オプションを含むメッセージがある場合、この配列が設定されます。 各一意の場所が 1 回ずつ含まれます。
suppressions		結果が抑制されている場合、これには @kind プロパティが IN_SOURCE に設定された 1 つの suppression オブジェクトが含まれます。 この結果が抑制されていないが、抑制を含む結果が少なくとも 1 つ存在する場合、これは空の配列に設定されます。それ以外の場合、設定されません。

location オブジェクト

JSON プロパティ名	常に生成されますか?	Notes
physicalLocation		なし
id		result オブジェクトの relatedLocations 配列内に出現する location オブジェクトには、id プロパティが含まれている場合があります。
message		次の場合、location オブジェクトに message プロパティが含まれている可能性があります。 - message プロパティを含む可能性がある result オブジェクトの relatedLocations 配列内に出現する。 - threadFlowLocation.location プロパティ内に出現する。

physicalLocation オブジェクト

JSON プロパティ名	常に生成されますか?	Notes
artifactLocation		なし
region		指定された physicalLocation がソース コード ファイルなどのテキスト ファイルに存在する場合、region プロパティが存在する可能性があります。
contextRegion		この場所に snippet が関連付けられている場合に存在する可能性があります。

region オブジェクト

CodeQL によって生成される region オブジェクトには次の 2 種類があります。

• 行または列のオフセットの領域

• 文字のオフセットと長さの領域

CodeQL によって生成された領域はいずれかの形式で指定でき、コンシューマーはどちらの種類も堅牢に処理する必要があります。

行または列のオフセット領域の場合、次のプロパティが設定されます。

JSON プロパティ名	常に生成されますか?	Notes
startLine		なし
startColumn		既定値の 1 に等しい場合は含まれません。
endLine		startLine と同じ場合は含まれません。
endColumn		なし
snippet		なし

文字のオフセットと長さの領域の場合、次のプロパティが設定されます。

JSON プロパティ名	常に生成されますか?	Notes
charOffset		startLine、startColumn、endLine、endColumn が設定されていない場合に指定されます。
charLength		startLine、startColumn、endLine、endColumn が設定されていない場合に指定されます。
snippet		なし

codeFlow オブジェクト

JSON プロパティ名	常に生成されますか?	Notes
threadFlows		なし

threadFlow オブジェクト

JSON プロパティ名	常に生成されますか?	Notes
locations		なし

threadFlowLocation オブジェクト

JSON プロパティ名	常に生成されますか?	Notes
location		なし