# CodeQL CLI SARIF 出力
CodeQL CLI から SARIF を出力し、静的分析結果を他のシステムと共有できます。
## SARIF 出力について
SARIF は、さまざまな静的分析ツールの出力を表すように設計されており、SARIF 仕様には、"省略可能" と見なされる多くの機能があります。 このドキュメントでは、SARIF v2.1.0.csd1 仕様に対応する形式の種類 `sarifv2.1.0`を使用するときに生成される出力について詳しく説明します。 分析結果のファイル形式の選択について詳しくは、「[データベース分析](/ja/enterprise-cloud@latest/code-security/codeql-cli/codeql-cli-manual/database-analyze)」を参照してください。
## SARIF の仕様とスキーマ
この記事は、詳しい SARIF 仕様と併せて読むことを目的としています。 仕様と SARIF スキーマについて詳しくは、[SARIF 仕様のドキュメント](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html)を参照してください。
## 変更に関するメモ
### バージョン間の変更
| CodeQL バージョン | 書式の種類 | Changes |
| ------------ | ------------- | -------------- |
| 2.0.0 | `sarifv2.1.0` | この形式の最初のバージョン。 |
### 出力に対する将来の変更
特定の形式の種類 (たとえば、`sarifv2.1.0`) に対して生成される出力は、CodeQL の将来のリリースで変更される可能性があります。 GitHub では、生成された SARIF のコンシューマーとの下位互換性を維持するために、次のことを保証するよう努めます。
* 常に生成されるとマークされているフィールドは決して削除されません。
* 常に生成されるわけではないとマークされているフィールドの場合、フィールドが生成される状況が変わる可能性があります。 CodeQL SARIF 出力の利用者は、これらのフィールドの有無に対応できる必要があります。
将来のリリースでは、新しい出力フィールドが同じ形式の種類で追加される可能性があります。これらは後方互換性を損なうとは見なされず、コンシューマーは新しく追加されたフィールドの存在に対して堅牢である必要があります。
CodeQL の将来のバージョンでは、新しい形式引数の種類が追加される可能性があります (たとえば、新しいバージョンの SARIF をサポートするため)。 これらについては、明示的に文書化されていない限り、下位互換性は保証されません。
## 生成される SARIF オブジェクト
ここでは、生成される可能性のある各 SARIF コンポーネントと、特定の状況について詳しく説明します。 生成されないプロパティは省略します。
###
```
`sarifLog` オブジェクト
```
| JSON プロパティ名 | 常に生成されますか? | 注記 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `$schema` | | |
```
[SARIF スキーマ](https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json)へのリンクを提供します。|
```
\| `version`| | 出力の生成に使用される SARIF のバージョン。|
\| `runs`| | 1 つの言語の単一の実行オブジェクトを含む配列。|
###
```
`run` オブジェクト
```
| JSON プロパティ名 | 常に生成されますか? | 注記 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `tool` | | None |
| `artifacts` | | 結果で参照されるすべてのファイルに対して少なくとも 1 つの成果物オブジェクトを含む配列。 |
| `results` | | None |
| `newLineSequences` | | None |
| `columnKind` | | None |
| `properties` | | プロパティ ディクショナリには、CodeQL CLI に渡される形式指定子を識別する `semmle.formatSpecifier` が含まれます。 |
###
```
`tool` オブジェクト
```
| JSON プロパティ名 | 常に生成されますか? | 注記 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `driver` | | None |
###
```
`toolComponent` オブジェクト
```
| JSON プロパティ名 | 常に生成されますか? | 注記 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` | | CodeQL CLI ツールからの出力については、"CodeQL command-line toolchain" に設定します。 出力が別のツールを使用して生成された場合、別の `name` が報告され、形式がここで説明されているものと異なる場合があることに注意してください。 |
| `organization` | | "GitHub" に設定します。 |
| `version` | | CodeQL リリース バージョン (たとえば、"2.0.0") に設定します。 |
| `rules` | | ルールを表す `reportingDescriptor` オブジェクトの配列。 この配列には、少なくとも、この分析中に実行されたすべてのルールが含まれますが、使用可能でも実行されなかったルールが含まれている可能性があります。 クエリの有効化について詳しくは、`defaultConfiguration` を参照してください。 |
###
```
`reportingDescriptor` オブジェクト (ルール用)
`reportingDescriptor` オブジェクトは、SARIF 仕様の複数の場所で使用できます。
`reportingDescriptor` が `toolComponent` オブジェクトのルール配列に含まれている場合、それには次のプロパティが含まれます。
```
| JSON プロパティ名 | 常に生成されますか? | 注記 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | | ルールを定義するクエリで指定された `@id` プロパティが含まれます。通常、形式は `language/rule-name` です (たとえば、`cpp/unsafe-format-string`)。 組織によってクエリ内で`@opaqueid` プロパティが定義されている場合は、そちらが使用されます。 |
| `name` | | クエリで指定された `@id` プロパティが含まれます。 例については、上記の `id` プロパティを参照してください。 |
| `shortDescription` | | ルールを定義するクエリで指定された `@name` プロパティが含まれます。 |
| `fullDescription` | | ルールを定義するクエリで指定された `@description` プロパティが含まれます。 |
| `defaultConfiguration` | | |
```
`reportingConfiguration` オブジェクト。有効なプロパティは、true または false に設定され、レベル プロパティは、ルールを定義するクエリで指定された `@severity` プロパティに従って設定されます。
`@severity` プロパティが指定されていない場合は省略されます。|
```
###
```
`artifact` オブジェクト
```
| JSON プロパティ名 | 常に生成されますか? | 注記 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `location` | | |
```
`artifactLocation` オブジェクト。|
```
\| `index`| |
`artifact` オブジェクトのインデックスです。|
\| `contents`| |
`--sarif-add-file-contents` フラグを使用して結果が生成され、SARIF ファイルの生成時にソース コードが利用可能である場合、`contents` プロパティには、`artifactContent` プロパティが設定された `text` オブジェクトが設定されます。|
###
```
`artifactLocation` オブジェクト
```
| JSON プロパティ名 | 常に生成されますか? | 注記 |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `uri` | | None |
| `index` | | None |
| `uriBaseId` | | ファイルが、分析マシン上のルート ソースの場所など、既知の抽象的な場所を基準とする場合は、これが設定されます。 |
###
```
`result` オブジェクト
```
結果の構成は、CodeQL に提供されるオプションによって異なります。 既定では、結果は、一意のメッセージ形式文字列とプライマリの場所別にグループ化されます。 したがって、同じ場所で発生し、同じ基になるメッセージを含む 2 つの結果は、出力では 1 つの結果として表示されます。 この動作は、フラグ `--ungroup-results` を使用して無効にすることができます。この場合、結果はグループ化されません。
| JSON プロパティ名 | 常に生成されますか? | 注記 |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ruleId` | | 「`id` オブジェクト (ルール用)」の `reportingDescriptor` プロパティの説明を参照してください。 |
| `ruleIndex` | | None |
| `message` | | この場所で発生した問題を説明するメッセージ。 このメッセージは SARIF "プレースホルダーを含むメッセージ" である可能性があり、これには、`relatedLocations` プロパティ内の場所を参照するリンクが含まれます。 |
| `locations` | | 1 つの `location` オブジェクトを含む配列。 |
| `partialFingerprints` | | 名前付きの指紋タイプから指紋への辞書。 これには、少なくとも `primaryLocationLineHash` の値が含まれるので、プライマリの場所のコンテキストに基づいて指紋が提供されます。 |
| `codeFlows` | | この結果のルールを定義するクエリが `codeFlow`、この配列には 1 つ以上の `@kind path-problem` オブジェクトが設定されることがあります。 |
| `relatedLocations` | | この結果のルールを定義するクエリにプレースホルダー オプションを含むメッセージがある場合、この配列が設定されます。 ユニークな場所がそれぞれ1回ずつ含まれます。 |
| `suppressions` | | 結果が抑制されている場合、これには `suppression` プロパティが `@kind` に設定された 1 つの `IN_SOURCE` オブジェクトが含まれます。 この結果が抑制されていないが、抑制を含む結果が少なくとも 1 つ存在する場合、これは空の配列に設定されます。それ以外の場合、設定されません。 |
###
```
`location` オブジェクト
```
| JSON プロパティ名 | 常に生成されますか? | 注記 |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `physicalLocation` | | None |
| `id` | | |
```
`location` オブジェクトの `relatedLocations` 配列内に出現する `result` オブジェクトには、`id` プロパティが含まれている場合があります。|
```
\| `message`| | 次の場合、`location` オブジェクトに `message` プロパティが含まれている可能性があります。- `relatedLocations` プロパティを含む可能性がある `result` オブジェクトの `message` 配列内に出現する。- `threadFlowLocation.location` プロパティ内に出現する。|
###
```
`physicalLocation` オブジェクト
```
| JSON プロパティ名 | 常に生成されますか? | 注記 |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `artifactLocation` | | None |
| `region` | | 指定された `physicalLocation` がソース コード ファイルなどのテキスト ファイルに存在する場合、`region` プロパティが存在する可能性があります。 |
| `contextRegion` | | この場所に `snippet` が関連付けられている場合に存在する可能性があります。 |
###
```
`region` オブジェクト
```
CodeQL によって生成される `region` オブジェクトには次の 2 種類があります。
* 行または列のオフセットの領域
* 文字のオフセットと長さの領域
CodeQL によって生成された領域はいずれかの形式で指定でき、コンシューマーはどちらの種類も堅牢に処理する必要があります。
行または列のオフセット領域の場合、次のプロパティが設定されます。
| JSON プロパティ名 | 常に生成されますか? | 注記 |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `startLine` | | None |
| `startColumn` | | 既定値の 1 に等しい場合は含まれません。 |
| `endLine` | | |
```
`startLine` と同じ場合は含まれません。|
```
\| `endColumn`| | None |
\| `snippet`| | None |
文字のオフセットと長さの領域の場合、次のプロパティが設定されます。
| JSON プロパティ名 | 常に生成されますか? | 注記 |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `charOffset` | | |
```
`startLine`、`startColumn`、`endLine`、`endColumn` が設定されていない場合に指定されます。|
```
\| `charLength`| |
`startLine`、`startColumn`、`endLine`、`endColumn` が設定されていない場合に指定されます。|
\| `snippet`| | None |
###
```
`codeFlow` オブジェクト
```
| JSON プロパティ名 | 常に生成されますか? | 注記 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `threadFlows` | | None |
###
```
`threadFlow` オブジェクト
```
| JSON プロパティ名 | 常に生成されますか? | 注記 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `locations` | | None |
###
```
`threadFlowLocation` オブジェクト
```
| JSON プロパティ名 | 常に生成されますか? | 注記 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `location` | | None |