关于 SARIF 输出
SARIF 旨在表示各种静态分析工具的输出，SARIF 规范中有许多被视为“可选”的功能。 本文档详细介绍使用格式类型 sarifv2.1.0 时生成的输出，该格式类型对应于 SARIF v2.1.0.csd1 规范。 有关为分析结果选择文件格式的详细信息，请参阅“数据库分析”。
SARIF 规范和架构
本文旨在与详细的 SARIF 规范一起阅读。 有关规范和 SARIF 架构的详细信息，请参阅 SARIF 规范文档。
更改注释
版本之间的更改
| CodeQL version | 格式类型 | 更改 |
|---|---|---|
| 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 对象的规则数组中时，它具有以下属性。
| JSON 属性名称 | 始终生成？ | 说明 |
|---|---|---|
id | 将包含定义规则的查询中指定的 @id 属性，该属性通常采用 language/rule-name 格式（例如 cpp/unsafe-format-string）。 如果组织在查询中定义了 @opaqueid 属性，则将改用该属性。 | |
name | 将包含查询中指定的 @id 属性。 有关示例，请参阅上面的 id 属性。 | |
shortDescription | 将包含定义规则的查询中指定的 @name 属性。 | |
fullDescription | 将包含定义规则的查询中指定的 @description 属性。 | |
defaultConfiguration | 一个 reportingConfiguration 对象，其 enabled 属性设置为 true 或 false，并根据定义规则的查询中指定的 @severity 属性设置级别属性。 如果未指定 @severity 属性，则省略。 |
（属于artifact 对象）的父级。
| JSON 属性名称 | 始终生成？ | 说明 |
|---|---|---|
location | 一个 artifactLocation 对象。 | |
index | artifact 对象的索引。 | |
contents | 如果使用 --sarif-add-file-contents 标志生成结果，并且源代码在生成 SARIF 文件时可用，则使用 artifactContent 对象填充 contents 属性，并设置 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 | 无 |