镜像证明存储

目录

Buildkit 支持创建证明并将其附加到构建工件。这些证明可以提供构建过程中的有价值信息，包括但不限于：SBOMs、SLSA 出处、构建日志等。

本文档描述了当前用于存储证明的自定义格式，该格式旨在与当前的注册表实现兼容。未来，我们可能支持导出其他格式的证明。

证明作为清单对象存储在镜像索引中，其风格类似于 OCI 工件。

属性

证明清单

证明清单附加到根镜像索引对象，位于单独的 OCI 镜像清单下。每个证明清单可以包含多个 证明 Blob，其中一个清单中的所有证明适用于一个平台清单。标准 OCI 和 Docker 清单的所有属性仍然适用。

镜像 config 描述符将指向有效的 镜像配置，但是，它不会包含证明特定的详细信息，并且由于仅为兼容性目的而包含，因此应被忽略。

layers 中的每个镜像层将包含一个针对单个 证明 Blob 的描述符。每个层的 mediaType 将根据其内容进行设置，可以是以下之一：

  • application/vnd.in-toto+json（目前唯一支持的选项）

    表示一个 in-toto 证明 Blob

应忽略任何未知的 mediaType。

为了方便证明遍历，可以在每个层描述符上设置以下注解

  • in-toto.io/predicate-type

    如果包含的证明是 in-toto 证明（目前唯一支持的选项），将设置此注解。该注解将包含与证明内部存在的 predicateType 属性相同的值。

    如果存在，此注解可用于查找他们正在寻找的特定证明，以避免拉取其他证明的内容。

证明 Blob

每层的内容将是一个取决于其 mediaType 的 Blob。

  • application/vnd.in-toto+json

    Blob 内容将包含完整的 in-toto 证明语句

    {
  "_type": "https://in-toto.io/Statement/v0.1",
  "subject": [
    {
      "name": "<NAME>",
      "digest": {"<ALGORITHM>": "<HEX_VALUE>"}
    },
    ...
  ],
  "predicateType": "<URI>",
  "predicate": { ... }
}

    证明的主体应设置为与 证明清单描述符 中描述的目标清单的摘要相同，或其中的某个对象。

证明清单描述符

证明清单附加到根 镜像索引的 manifests 键中，位于所有原始可运行清单之后。标准 OCI 和 Docker 清单描述符的所有属性仍然适用。

为防止容器运行时意外拉取或运行清单中描述的镜像，证明清单的 platform 属性将设置为 unknown/unknown，如下所示

"platform": {
  "architecture": "unknown",
  "os": "unknown"
}

为了方便索引遍历，清单描述符将设置以下注解

  • vnd.docker.reference.type

    此注解描述工件的类型，将设置为 attestation-manifest。如果指定了任何其他值，则应忽略整个清单。

  • vnd.docker.reference.digest

    此注解将包含证明清单引用的镜像索引中对象的摘要。

    如果存在，此注解可用于查找与所选镜像清单匹配的证明清单。

示例

示例：显示附加到 linux/amd64 镜像的 SBOM 证明

镜像索引 (sha256:94acc2ca70c40f3f6291681f37ce9c767e3d251ce01c7e4e9b98ccf148c26260)

此镜像索引定义了两个描述符：一个 AMD64 镜像 sha256:23678f31.. 和该镜像的证明清单 sha256:02cb9aa7..。

{
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "schemaVersion": 2,
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:23678f31b3b3586c4fb318aecfe64a96a1f0916ba8faf9b2be2abee63fa9e827",
      "size": 1234,
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:02cb9aa7600e73fcf41ee9f0f19cc03122b2d8be43d41ce4b21335118f5dd943",
      "size": 1234,
      "annotations": {
        "vnd.docker.reference.digest": "sha256:23678f31b3b3586c4fb318aecfe64a96a1f0916ba8faf9b2be2abee63fa9e827",
        "vnd.docker.reference.type": "attestation-manifest"
      },
      "platform": {
         "architecture": "unknown",
         "os": "unknown"
      }
    }
  ]
}

证明清单 (sha256:02cb9aa7600e73fcf41ee9f0f19cc03122b2d8be43d41ce4b21335118f5dd943)

此证明清单包含一个 in-toto 证明，该证明包含 "https://spdx.dev/Document" 谓词，表明它正在定义该镜像的 SBOM。

{
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "schemaVersion": 2,
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:a781560066f20ec9c28f2115a95a886e5e71c7c7aa9d8fd680678498b82f3ea3",
    "size": 123
  },
  "layers": [
    {
      "mediaType": "application/vnd.in-toto+json",
      "digest": "sha256:133ae3f9bcc385295b66c2d83b28c25a9f294ce20954d5cf922dda860429734a",
      "size": 1234,
      "annotations": {
        "in-toto.io/predicate-type": "https://spdx.dev/Document"
      }
    }
  ]
}

镜像配置 (sha256:a781560066f20ec9c28f2115a95a886e5e71c7c7aa9d8fd680678498b82f3ea3)

{
  "architecture": "unknown",
  "os": "unknown",
  "config": {},
  "rootfs": {
    "type": "layers",
    "diff_ids": [
      "sha256:133ae3f9bcc385295b66c2d83b28c25a9f294ce20954d5cf922dda860429734a"
    ]
  }
}

层内容 (sha256:1ea07d5e55eb47ad0e6bbfa2ec180fb580974411e623814e519064c88f022f5c)

包含 SBOM 数据的证明主体，列出了构建过程中使用的 SPDX 格式的软件包。

{
  "_type": "https://in-toto.io/Statement/v0.1",
  "predicateType": "https://spdx.dev/Document",
  "subject": [
    {
      "name": "_",
      "digest": {
        "sha256": "23678f31b3b3586c4fb318aecfe64a96a1f0916ba8faf9b2be2abee63fa9e827"
      }
    }
  ],
  "predicate": {
    "SPDXID": "SPDXRef-DOCUMENT",
    "spdxVersion": "SPDX-2.2",
    ...
页面选项