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