关于 SARIF 输出
SARIF 旨在表示各种静态分析工具的输出，并且 SARIF 规范中有很多功能被认为是“可选的”。本文档详细说明了使用格式类型 sarifv2.1.0（对应于 SARIF v2.1.0.csd1 规范）时生成的输出。有关为分析结果选择文件格式的更多信息，请参阅“database analyze”。
SARIF 规范和模式
建议您结合详细的 SARIF 规范阅读本文档。有关规范和 SARIF 模式的信息，请参阅 SARIF 规范文档。
更改说明
版本之间的更改
| CodeQL 版本 | 格式类型 | 更改 |
|---|---|---|
| 2.0.0 | sarifv2.1.0 | 此格式的第一个版本。 |
将来对输出的更改
对于给定的特定格式类型（例如，sarifv2.1.0）生成的输出可能会在将来的 CodeQL 版本中发生更改。我们将努力保持与生成的 SARIF 使用者的向后兼容性，以确保
-
标记为始终生成的字段将永远不会被删除。
-
对于标记为不总是生成的字段，生成这些字段的情况可能会发生变化。CodeQL SARIF 输出的用户应能够应对这些字段的存在或不存在。
在将来发布的同一格式类型下可能会添加新的输出字段，这些字段不被视为破坏向后兼容性，并且用户应能够应对新添加字段的存在。
在将来的 CodeQL 版本中可能会添加新的格式参数类型，例如，以支持 SARIF 的新版本。这些没有向后兼容性保证，除非有明确的文档说明。
生成的 SARIF 对象
这详细说明了可能生成的每个 SARIF 组件及其任何特定情况。我们省略了从不生成的任何属性。
sarifLog 对象
| JSON 属性名称 | 始终生成？ | 说明 |
|---|---|---|
$schema | 提供指向 SARIF 模式 的链接。 | |
version | 用于生成输出的 SARIF 版本。 | |
runs | 包含单个运行对象的数组，用于一种语言。 |
run 对象
| JSON 属性名称 | 始终生成？ | 说明 |
|---|---|---|
tool | 无 | |
artifacts | 包含至少一个工件对象的数组，用于结果中引用的每个文件。 | |
results | 无 | |
newLineSequences | 无 | |
columnKind | 无 | |
properties | 属性字典将包含 semmle.formatSpecifier，它标识传递给 CodeQL CLI 的格式说明符。 |
tool 对象
| JSON 属性名称 | 始终生成？ | 说明 |
|---|---|---|
driver | 无 |
toolComponent 对象
| JSON 属性名称 | 始终生成？ | 说明 |
|---|---|---|
name | 对于来自 CodeQL CLI 工具的输出，设置为“CodeQL 命令行工具链”。请注意，如果输出是使用其他工具生成的，则会报告不同的 name，并且格式可能与此处描述的不同。 | |
organization | 设置为“GitHub”。 | |
version | 设置为 CodeQL 版本，例如“2.0.0”。 | |
rules | 表示规则的 reportingDescriptor 对象的数组。此数组将至少包含在此分析期间运行的所有规则，但可能包含可用但未运行的规则。有关启用查询的更多详细信息，请参阅 defaultConfiguration。 |
reportingDescriptor 对象（用于规则）
reportingDescriptor 对象可用于 SARIF 规范中的多个位置。当 reportingDescriptor 包含在 toolComponent 对象的 rules 数组中时，它具有以下属性。
| JSON 属性名称 | 始终生成？ | 说明 |
|---|---|---|
id | 将包含定义规则的查询中指定的 @id 属性，该属性通常采用 language/rule-name 格式（例如 cpp/unsafe-format-string）。如果您的组织在查询中定义了 @opaqueid 属性，则将使用该属性。 | |
name | 将包含查询中指定的 @id 属性。有关示例，请参阅上面的 id 属性。 | |
shortDescription | 将包含定义规则的查询中指定的 @name 属性。 | |
fullDescription | 将包含定义规则的查询中指定的 @description 属性。 | |
defaultConfiguration | 一个 reportingConfiguration 对象，其 enabled 属性设置为 true 或 false，并且 level 属性根据定义规则的查询中指定的 @severity 属性设置。如果未指定 @severity 属性，则将其省略。 |
artifact 对象
| JSON 属性名称 | 始终生成？ | 说明 |
|---|---|---|
location | 一个 artifactLocation 对象。 | |
index | artifact 对象的索引。 | |
contents | 如果使用 --sarif-add-file-contents 标志生成结果，并且在生成 SARIF 文件时源代码可用，则 contents 属性将填充 artifactContent 对象，并设置 text 属性。 |
artifactLocation 对象
| JSON 属性名称 | 始终生成？ | 说明 |
|---|---|---|
uri | 无 | |
index | 无 | |
uriBaseId | 如果文件相对于某个已知的抽象位置（例如分析计算机上的根源代码位置），则将设置此属性。 |
result 对象
结果的构成取决于提供给 CodeQL 的选项。默认情况下，结果按唯一的错误消息格式字符串和主要位置进行分组。因此，在同一位置发生且具有相同底层消息的两个结果将在输出中显示为单个结果。可以通过使用标志--ungroup-results禁用此行为，在这种情况下，不会对任何结果进行分组。
| JSON 属性名称 | 始终生成？ | 说明 |
|---|---|---|
ruleId | 请参阅reportingDescriptor 对象（对于规则）中id 属性的说明。 | |
ruleIndex | 无 | |
message | 描述此位置发生的问题的消息。此消息可能是 SARIF“包含占位符的消息”，其中包含指向relatedLocations 属性中位置的链接。 | |
locations | 包含单个location 对象的数组。 | |
partialFingerprints | 一个从命名指纹类型到指纹的字典。这将至少包含primaryLocationLineHash的值，该值提供基于主要位置上下文生成的指纹。 | |
codeFlows | 如果定义此结果规则的查询为@kind path-problem，则此数组可能会填充一个或多个codeFlow 对象。 | |
relatedLocations | 如果定义此结果规则的查询的消息包含占位符选项，则此数组将被填充。每个唯一位置仅包含一次。 | |
suppressions | 如果结果被抑制，则此属性将包含单个suppression 对象，其@kind 属性设置为IN_SOURCE。如果此结果未被抑制，但至少有一个结果具有抑制，则此属性将设置为一个空数组，否则将不设置。 |
location 对象
| JSON 属性名称 | 始终生成？ | 说明 |
|---|---|---|
physicalLocation | 无 | |
id | 出现在result 对象的relatedLocations 数组中的location 对象可能包含id 属性。 | |
message | location 对象如果满足以下条件，则可能包含message 属性：- 它们出现在 result 对象的relatedLocations 数组中，可能包含message 属性。- 它们出现在 threadFlowLocation.location 属性中。 |
physicalLocation 对象
| JSON 属性名称 | 始终生成？ | 说明 |
|---|---|---|
artifactLocation | 无 | |
region | 如果给定的physicalLocation 存在于文本文件中（例如源代码文件），则region 属性可能存在。 | |
contextRegion | 如果此位置具有关联的snippet，则可能存在。 |
region 对象
CodeQL 生成的region 对象有两种类型
-
行/列偏移量区域
-
字符偏移量和长度区域
CodeQL 生成的任何区域都可以使用这两种格式中的任何一种指定，使用者应该稳健地处理这两种类型。
对于行/列偏移量区域，将设置以下属性：
| JSON 属性名称 | 始终生成？ | 说明 |
|---|---|---|
startLine | 无 | |
startColumn | 如果等于默认值 1，则不包含。 | |
endLine | 如果不与startLine相同，则不包含。 | |
endColumn | 无 | |
snippet | 无 |
对于字符偏移量和长度区域，将设置以下属性：
| JSON 属性名称 | 始终生成？ | 说明 |
|---|---|---|
charOffset | 如果startLine、startColumn、endLine 和endColumn 未填充，则提供。 | |
charLength | 如果startLine、startColumn、endLine 和endColumn 未填充，则提供。 | |
snippet | 无 |
codeFlow 对象
| JSON 属性名称 | 始终生成？ | 说明 |
|---|---|---|
threadFlows | 无 |
threadFlow 对象
| JSON 属性名称 | 始终生成？ | 说明 |
|---|---|---|
locations | 无 |
threadFlowLocation 对象
| JSON 属性名称 | 始终生成？ | 说明 |
|---|---|---|
location | 无 |