Skip to main content

CodeQL CLI SARIF 出力

CodeQL CLI から SARIF を出力し、静的分析結果を他のシステムと共有できます。

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

GitHub CodeQL は、インストール時にユーザーごとにライセンスされます。 CodeQL は、ライセンスの制限の下で特定のタスクでのみ使用できます。 詳しくは、「CodeQL CLI について」を参照してください。

GitHub Advanced Security ライセンスがある場合は、CodeQL を使用して、自動分析、継続的インテグレーション、継続的デリバリーを行うことができます。 詳しくは、「GitHub Advanced Security について」を参照してください。

SARIF 出力について

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

SARIF の仕様とスキーマ

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

変更に関するメモ

バージョン間の変更

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

出力に対する将来の変更

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

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

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

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

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

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

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

sarifLog オブジェクト

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

run オブジェクト

JSON プロパティ名常に生成されますか?Notes
toolなし
artifacts結果で参照されるすべてのファイルに対して少なくとも 1 つの成果物オブジェクトを含む配列。
resultsなし
newLineSequencesなし
columnKindなし
propertiesプロパティ ディクショナリには、CodeQL CLI に渡される形式指定子を識別する semmle.formatSpecifier が含まれます。

tool オブジェクト

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

toolComponent オブジェクト

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

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

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

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

artifact オブジェクト

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

artifactLocation オブジェクト

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

result オブジェクト

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

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

location オブジェクト

JSON プロパティ名常に生成されますか?Notes
physicalLocationなし
idresult オブジェクトの 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 に等しい場合は含まれません。
endLinestartLine と同じ場合は含まれません。
endColumnなし
snippetなし

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

JSON プロパティ名常に生成されますか?Notes
charOffsetstartLinestartColumnendLineendColumn が設定されていない場合に指定されます。
charLengthstartLinestartColumnendLineendColumn が設定されていない場合に指定されます。
snippetなし

codeFlow オブジェクト

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

threadFlow オブジェクト

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

threadFlowLocation オブジェクト

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