CodeQL CLI SARIF 输出

关于 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 对象。

run 对象

JSON 属性名称	始终生成？	注意
tool (工具)		无
artifacts		一个数组，包含每个在结果中被引用的文件对应的至少一个 artifact 对象。
结果		无
newLineSequences		无
columnKind		无
properties		properties 字典将包含 semmle.formatSpecifier，它标识传递给 CodeQL CLI 的格式说明符。

tool 对象

JSON 属性名称	始终生成？	注意
driver		无

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 对象的 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 数组中。 - 它们出现在 threadFlowLocation.location 属性中。

physicalLocation 对象

JSON 属性名称	始终生成？	注意
artifactLocation		无
region		如果给定的 physicalLocation 位于文本文件（如源代码文件）中，则可能存在 region 属性。
contextRegion		如果此位置关联了 snippet，则可能出现此属性。

region 对象

CodeQL 生成的 region 对象有两种类型

• 行/列偏移区域

• 字符偏移和长度区域

CodeQL 生成的任何 region 都可以采用任一格式，消费者应能够稳健地处理这两种类型。

对于行/列偏移区域，将设置以下属性

JSON 属性名称	始终生成？	注意
startLine		无
startColumn		如果等于默认值 1，则不包括此属性。
结束行		如果与 startLine 相同，则不包括此属性。
结束列		无
snippet		无

对于字符偏移和长度区域，将设置以下属性

JSON 属性名称	始终生成？	注意
charOffset		如果未填充 startLine、startColumn、endLine 和 endColumn，则提供此属性。
charLength		如果未填充 startLine、startColumn、endLine 和 endColumn，则提供此属性。
snippet		无

codeFlow 对象

JSON 属性名称	始终生成？	注意
threadFlows		无

threadFlow 对象

JSON 属性名称	始终生成？	注意
locations		无

threadFlowLocation 对象

JSON 属性名称	始终生成？	注意
location		无