{"meta":{"title":"CodeQL CLI SARIF 输出","intro":"可以从 CodeQL CLI 输出 SARIF，并与其他系统共享静态分析结果。","product":"安全性和代码质量","breadcrumbs":[{"href":"/zh/enterprise-cloud@latest/code-security","title":"安全性和代码质量"},{"href":"/zh/enterprise-cloud@latest/code-security/reference","title":"Reference"},{"href":"/zh/enterprise-cloud@latest/code-security/reference/code-scanning","title":"代码扫描"},{"href":"/zh/enterprise-cloud@latest/code-security/reference/code-scanning/codeql","title":"CodeQL"},{"href":"/zh/enterprise-cloud@latest/code-security/reference/code-scanning/codeql/codeql-cli","title":"CodeQL命令行界面 (CLI)"},{"href":"/zh/enterprise-cloud@latest/code-security/reference/code-scanning/codeql/codeql-cli/sarif-output","title":"CodeQL CLI SARIF 输出"}],"documentType":"article"},"body":"# CodeQL CLI SARIF 输出\n\n可以从 CodeQL CLI 输出 SARIF，并与其他系统共享静态分析结果。\n\n## 关于 SARIF 输出\n\nSARIF 旨在表示各种静态分析工具的输出，SARIF 规范中有许多被视为“可选”的功能。本文档详细介绍使用格式类型 `sarifv2.1.0` 时生成的输出，该格式类型对应于 SARIF v2.1.0.csd1 规范。有关为分析结果选择文件格式的详细信息，请参阅 [数据库分析](/zh/enterprise-cloud@latest/code-security/codeql-cli/codeql-cli-manual/database-analyze)。\n\n## SARIF 规范和架构\n\n本文旨在与详细的 SARIF 规范一起阅读。有关规范和 SARIF 架构的详细信息，请参阅 [SARIF 规范文档](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html)。\n\n## 更改注释\n\n### 版本之间的更改\n\n| CodeQL 版本 | 格式类型 | Changes |\n| --------- | ------------- | ---------- |\n| 2.0.0 | `sarifv2.1.0` | 此格式的第一个版本。 |\n\n### 输出的未来更改\n\n为给定的特定格式类型生成的输出（例如 `sarifv2.1.0`）在将来的 CodeQL 版本中可能会更改。我们将通过确保以下各项，努力保持与生成的 SARIF 使用者的后向兼容性：\n\n* 永远不会删除标记为“始终生成”的字段。\n\n* 对于标记为“并非始终生成”的字段，生成字段时的情况可能会改变。 CodeQL SARIF 输出的使用者应能够可靠解决存在或缺少这些字段的情况。\n\n将来的版本中可能会使用相同的格式类型添加新的输出字段，这些字段不被视为破坏后向兼容性，并且使用者应能够可靠解决存在新添加字段的情况。\n\n将来的 CodeQL 版本中可能会添加新的格式参数类型，例如，为了支持新版本的 SARIF。除非明确记录，否则它们不保证后向兼容性。\n\n## 生成的 SARIF 对象\n\n这会详细说明可能生成的每个 SARIF 组件，以及任何特定情况。我们省略了任何从未生成过的属性。\n\n###\n\n```\n `sarifLog` 对象\n```\n\n| JSON 属性名称 | 始终生成？ | 注释 |\n| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n| `$schema` | | 提供指向 [SARIF 架构](https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json)的链接。 |\n| `version` | | 用于生成输出的 SARIF 版本。 |\n| `runs` | | 包含一种语言的单个运行对象的数组。 |\n\n###\n\n```\n `run` 对象\n```\n\n| JSON 属性名称 | 始终生成？ | 注释 |\n| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |\n| `tool` | | None |\n| `artifacts` | | 一个数组，其中包含在结果中引用的每个文件的至少一个工件对象。 |\n| `results` | | None |\n| `newLineSequences` | | None |\n| `columnKind` | | None |\n| `properties` | | 属性字典将包含 `semmle.formatSpecifier`，它标识传递给 CodeQL CLI 的格式说明符。 |\n\n###\n\n```\n `tool` 对象\n```\n\n| JSON 属性名称 | 始终生成？ | 注释 |\n| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |\n| `driver` | | None |\n\n###\n\n```\n `toolComponent` 对象\n```\n\n| JSON 属性名称 | 始终生成？ | 注释 |\n| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| `name` | | 对于 CodeQL 工具的输出，设置为“CodeQL CLI 命令行工具链”。请注意，如果输出是使用其他工具生成的，则会报告不同的 `name` 输出，并且格式可能不同于此处所述。 |\n| `organization` | | 设置为“GitHub”。 |\n| `version` | | 将其设置为 CodeQL 发布版本，例如“2.0.0”。 |\n| `rules` | | 表示规则的 `reportingDescriptor` 对象数组。此数组将至少包含在此分析期间运行的所有规则，还可能包含可用但未运行的规则。有关启用查询的更多详细信息，请参阅 `defaultConfiguration`。 |\n\n###\n\n```\n `reportingDescriptor` 对象（对于规则）\n\n `reportingDescriptor` 对象可能用于 SARIF 规范中的多个位置。当 `reportingDescriptor` 包含在 `toolComponent` 对象的规则数组中时，它具有以下属性。\n```\n\n| JSON 属性名称 | 始终生成？ | 注释 |\n| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| `id` | | 将包含定义规则的查询中指定的 `@id` 属性，该属性通常采用 `language/rule-name` 格式（例如 `cpp/unsafe-format-string`）。如果组织在查询中定义了 `@opaqueid` 属性，则将改用该属性。 |\n| `name` | | 将包含查询中指定的 `@id` 属性。有关示例，请参阅上面的 `id` 属性。 |\n| `shortDescription` | | 将包含定义规则的查询中指定的 `@name` 属性。 |\n| `fullDescription` | | 将包含定义规则的查询中指定的 `@description` 属性。 |\n| `defaultConfiguration` | | 一个 `reportingConfiguration` 对象，其 enabled 属性设置为 true 或 false，并根据定义规则的查询中指定的 `@severity` 属性设置级别属性。如果未指定 `@severity` 属性，则省略。 |\n\n###\n\n```\n `artifact` 对象\n```\n\n| JSON 属性名称 | 始终生成？ | 注释 |\n| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |\n| `location` | | 对象 `artifactLocation` 。 |\n| `index` | | |\n\n```\n `artifact` 对象的索引。|\n```\n\n\\| `contents`| | 如果使用 `--sarif-add-file-contents` 标志生成结果，并且源代码在生成 SARIF 文件时可用，则使用 `contents` 对象填充 `artifactContent` 属性，并设置 `text` 属性。|\n\n###\n\n```\n `artifactLocation` 对象\n```\n\n| JSON 属性名称 | 始终生成？ | 注释 |\n| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |\n| `uri` | | None |\n| `index` | | None |\n| `uriBaseId` | | 如果文件相对于某个已知的抽象位置（例如分析计算机上的根源位置），则将设置此属性。 |\n\n###\n\n```\n `result` 对象\n```\n\n结果的组成取决于提供给 CodeQL 的选项。默认情况下，结果按唯一的消息格式字符串和主要位置分组。因此，在具有相同基础消息的同一位置发生的两个结果将在输出中显示为单个结果。可以使用 `--ungroup-results` 标志禁用此行为，在这种情况下，不会对结果进行分组。\n\n| JSON 属性名称 | 始终生成？ | 注释 |\n| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |\n| `ruleId` | | 请参阅 `id` 对象（对于规则）中的 `reportingDescriptor` 属性的说明。 |\n| `ruleIndex` | | None |\n| `message` | | 描述此位置发生的问题的信息。此消息可能是 SARIF “包含占位符的消息”，其中包含指向 `relatedLocations` 属性中某些位置的链接。 |\n| `locations` | | 包含单个 `location` 对象的数组。 |\n| `partialFingerprints` | | 从命名指纹类型到指纹的字典。这将至少包含 `primaryLocationLineHash` 的值，该值根据主要位置的上下文提供指纹。 |\n| `codeFlows` | | 如果为此结果定义规则的查询属于 `codeFlow`，则可以使用一个或多个 `@kind path-problem` 对象填充此数组。 |\n| `relatedLocations` | | 如果为此结果定义规则的查询具有包含占位符选项的消息，则将填充此数组。每个唯一位置包含一次。 |\n| `suppressions` | | 如果禁止显示结果，则这将包含一个 `suppression` 对象，其 `@kind` 属性设置为 `IN_SOURCE`。如果此结果未被屏蔽，但至少有一个结果被屏蔽，则将此结果设置为空数组，否则不会进行设置。 |\n\n###\n\n```\n `location` 对象\n```\n\n| JSON 属性名称 | 始终生成？ | 注释 |\n| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `physicalLocation` | | None |\n| `id` | | 出现在 `location` 对象的 `relatedLocations` 数组中的 `result` 对象可能包含 `id` 属性。 |\n| `message` | | 在以下情况下，`location` 对象可能包含 `message` 属性：

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

- 它们出现在 `threadFlowLocation.location` 属性中。 |\n\n###\n\n```\n `physicalLocation` 对象\n```\n\n| JSON 属性名称 | 始终生成？ | 注释 |\n| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |\n| `artifactLocation` | | None |\n| `region` | | 如果给定 `physicalLocation` 存在于文本文件（如源代码文件）中，则可能存在 `region` 属性。 |\n| `contextRegion` | | 如果此位置具有关联的 `snippet`，则可能存在。 |\n\n###\n\n```\n `region` 对象\n```\n\nCodeQL 生成了两种类型的 `region` 对象：\n\n* 行/列偏移量区域\n\n* 字符偏移和长度范围\n\nCodeQL 生成的任何区域都可以以任一格式指定，并且使用者应可靠地处理任一类型。\n\n对于行/列偏移量区域，将设置以下属性：\n\n| JSON 属性名称 | 始终生成？ | 注释 |\n| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |\n| `startLine` | | None |\n| `startColumn` | | 如果等于默认值 1，则不包括。 |\n| `endLine` | | 如果与 `startLine` 相同，则不包括。 |\n| `endColumn` | | None |\n| `snippet` | | None |\n\n对于字符偏移量和长度区域，将设置以下属性：\n\n| JSON 属性名称 | 始终生成？ | 注释 |\n| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |\n| `charOffset` | | 仅在 `startLine`、`startColumn`、`endLine` 和 `endColumn` 未填充时提供。 |\n| `charLength` | | 仅在 `startLine`、`startColumn`、`endLine` 和 `endColumn` 未填充时提供。 |\n| `snippet` | | None |\n\n###\n\n```\n `codeFlow` 对象\n```\n\n| JSON 属性名称 | 始终生成？ | 注释 |\n| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |\n| `threadFlows` | | None |\n\n###\n\n```\n `threadFlow` 对象\n```\n\n| JSON 属性名称 | 始终生成？ | 注释 |\n| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |\n| `locations` | | None |\n\n###\n\n```\n `threadFlowLocation` 对象\n```\n\n| JSON 属性名称 | 始终生成？ | 注释 |\n| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |\n| `location` | | None |"}