CodeQL CLI SARIF 输出

可以从 CodeQL CLI 输出 SARIF，并与其他系统共享静态分析结果。

谁可以使用此功能？

CodeQL 可用于以下存储库��型：

在本文中

关于 SARIF 输出

SARIF 旨在表示各种静态分析工具的输出，SARIF 规范中有许多被视为“可选”的功能。 本文档详细介绍使用格式类型 sarifv2.1.0 时生成的输出，该格式类型对应于 SARIF v2.1.0.csd1 规范。 有关为分析结果选择文件格式的详细信息，请参阅 数据库分析。

SARIF 规范和架构

本文旨在与详细的 SARIF 规范一��阅读。 有关规范和 SARIF 架构的详细信息，请参阅 SARIF 规范文档。

更改注释

版本之间的更改

CodeQL 版本格式类型Changes
2.0.0sarifv2.1.0此格式的第一个版本。

输出的未来更改

为给定的特定格式类型生成的输出（例如 sarifv2.1.0）在将来的 CodeQL 版本中可能会更改。 我们将通过确保以下各项，努力保持与生成的 SARIF 使用者的后向兼容性：

  • 永远不会删除标记为“始终生成”的字段。

  • 对于标记为“并非始终生成”的字段，生成字段时的情况可能会改变。 CodeQL SARIF 输出的使用者应能够可靠解决存在或缺少这些字段的情况。

将来的版本中可能会使用相同的格式类型添加新的输出字段，这些字段不被视为破坏后向兼容性，并且使用者应能够可靠解决存在新添加字段的情况。

将来的 CodeQL 版本中可能会添加新的格式参数类型，例如，为了支持新版本的 SARIF。 除非明确记录，否则它们不保证后向兼容性。

生成的 SARIF 对象

这会详细说明可能生成的每个 SARIF 组件，以及任何特定情况。 我们省略了任何从未生成过的属性。

          `sarifLog` 对象
JSON 属性名称始终生成？注释
$schema提供指向 SARIF 架构的链接。
version用于生成输出的 SARIF 版本。
runs包含一种语言的单个运行对象的数组。

          `run` 对象
JSON 属性名称始终生成？注释
toolNone
artifacts一个数组，其中包含在结果中引用的每个文件的至少一个工件对象。
resultsNone
newLineSequencesNone
columnKindNone
properties属性字典将包含 semmle.formatSpecifier，它标识传递给 CodeQL CLI 的格式说明符。

          `tool` 对象
JSON 属性名称始终生成？注释
driverNone

          `toolComponent` 对象
JSON 属性名称始终生成？注释
name对于 CodeQL 工具的输出，设置为“CodeQL CLI 命令行工具链”。 请注意，如果输出是使用其他工具生成的，则会报告不同的 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 文件时可用，则使用 contents 对象填充 artifactContent 属性，并设置 text 属性。|

          `artifactLocation` 对象
JSON 属性名称始终生成？注释
uriNone
indexNone
uriBaseId如果文件相对于某个已知的抽象位置（例如分析计算机上的根源位置），则将设置此属性。

          `result` 对象

结果的组成取决于提供给 CodeQL 的选项。 默认情况下，结果按唯一的消息格式字符串和主要位置分组。 因此，在具有相同基础消息的同一位置发生的两个结果将在输出中显示为单个结果。 可以使用 --ungroup-results 标志禁用此行为，在这种情况下，不会对结果进行分组。

JSON 属性名称始终生成？注释
ruleId请参阅 id 对象（对于规则）中的 reportingDescriptor 属性的说明。
ruleIndexNone
message描述此位置发生的问题的信息。 此消息可能是 SARIF “包含占位符的消息”，其中包含指向 relatedLocations 属性中某些位置的链接。
locations包含单个 location 对象的数组。
partialFingerprints从命名指纹类型到指纹的字典。 这将至少包含 primaryLocationLineHash 的值，该值根据主要位置的上下文提供指纹。
codeFlows如果为此结果定义规则的查询属于 codeFlow，则可以使用一个或多个 @kind path-problem 对象填充此数组。
relatedLocations如果为此结果定义规则的查询具有包含占位符选项的消息，则将填充此数组。 每个唯一位置包含一次。
suppressions如果禁止显示结果，则这将包含一个 suppression 对象，其 @kind 属性设置为 IN_SOURCE。 如果此结果未被屏蔽，但至少有一个结果被屏蔽，则将此结果设置为空数组，否则不会进行设置。

          `location` 对象
JSON 属性名称始终生成？注释
physicalLocationNone
id出现在 location 对象的 relatedLocations 数组中的 result 对象可能包含 id 属性。
message在以下情况下，location 对象可能包含 message 属性：

- 它们出现在 relatedLocations 对象的 result 数组中，可能包含 message 属性。

- 它们出现在 threadFlowLocation.location 属性中。

          `physicalLocation` 对象
JSON 属性名称始终生成？注释
artifactLocationNone
region如果给定 physicalLocation 存在于文本文件（如源代码文件）中，则可能存在 region 属性。
contextRegion如果此位置具有关联的 snippet，则可能存在。

          `region` 对象

CodeQL 生成了两种类型的 region 对象：

  • 行/列偏移量区域

  • 字符偏移和长度范围

CodeQL 生成的任何区域都可以以任一格式指定，并且使用者应可靠地处理任一类型。

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

JSON 属性名称始终生成？注释
startLineNone
startColumn如果等于默认值 1，则不包括。
endLine如果与 startLine 相同，则不包括。
endColumnNone
snippetNone

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

JSON 属性名称始终生成？注释
charOffset仅在 startLine、startColumn、endLine 和 endColumn 未填充时提供。
charLength仅在 startLine、startColumn、endLine 和 endColumn 未填充时提供。
snippetNone

          `codeFlow` 对象
JSON 属性名称始终生成？注释
threadFlowsNone

          `threadFlow` 对象
JSON 属性名称始终生成？注释
locationsNone

          `threadFlowLocation` 对象
JSON 属性名称始终生成？注释
locationNone