Image attestation storage

Table of contents

Buildkit supports creating and attaching attestations to build artifacts. These attestations can provide valuable information from the build process, including, but not limited to: SBOMs, SLSA Provenance, build logs, etc.

This document describes the current custom format used to store attestations, which is designed to be compatible with current registry implementations today. In the future, we may support exporting attestations in additional formats.

Attestations are stored as manifest objects in the image index, similar in style to OCI artifacts.

Properties

Attestation Manifest

Attestation manifests are attached to the root image index object, under a separate OCI image manifest. Each attestation manifest can contain multiple attestation blobs, with all the of the attestations in a manifest applying to a single platform manifest. All properties of standard OCI and Docker manifests continue to apply.

The image config descriptor will point to a valid image config, however, it will not contain attestation-specific details, and should be ignored as it is only included for compatibility purposes.

Each image layer in layers will contain a descriptor for a single attestation blob. The mediaType of each layer will be set in accordance to its contents, one of:

application/vnd.in-toto+json (currently, the only supported option)
Indicates an in-toto attestation blob

Any unknown mediaTypes should be ignored.

To assist attestation traversal, the following annotations may be set on each layer descriptor:

in-toto.io/predicate-type
This annotation will be set if the enclosed attestation is an in-toto attestation (currently, the only supported option). The annotation will be set to contain the same value as the predicateType property present inside the attestation.
When present, this annotation may be used to find the specific attestation(s) they are looking for to avoid pulling the contents of the others.

Attestation Blob

The contents of each layer will be a blob dependent on its mediaType.

application/vnd.in-toto+json

The blob contents will contain a full in-toto attestation statement:

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

The subject of the attestation should be set to be the same digest as the target manifest described in the Attestation Manifest Descriptor, or some object within.

Attestation Manifest Descriptor

Attestation manifests are attached to the root image index, in the manifests key, after all the original runnable manifests. All properties of standard OCI and Docker manifest descriptors continue to apply.

To prevent container runtimes from accidentally pulling or running the image described in the manifest, the platform property of the attestation manifest will be set to unknown/unknown, as follows:

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

To assist index traversal, the following annotations will be set on the manifest descriptor descriptor:

vnd.docker.reference.type
This annotation describes the type of the artifact, and will be set to attestation-manifest. If any other value is specified, the entire manifest should be ignored.
vnd.docker.reference.digest
This annotation will contain the digest of the object in the image index that the attestation manifest refers to.
When present, this annotation can be used to find the matching attestation manifest for a selected image manifest.

Examples

Example showing an SBOM attestation attached to a linux/amd64 image

Image index (`sha256:94acc2ca70c40f3f6291681f37ce9c767e3d251ce01c7e4e9b98ccf148c26260`):

This image index defines two descriptors: an AMD64 image sha256:23678f31.. and an attestation manifest sha256:02cb9aa7.. for that image.

{
  "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"
      }
    }
  ]
}

Attestation manifest (`sha256:02cb9aa7600e73fcf41ee9f0f19cc03122b2d8be43d41ce4b21335118f5dd943`):

This attestation manifest contains one attestation that is an in-toto attestation that contains a "https://spdx.dev/Document" predicate, signifying that it is defining a SBOM for the image.

{
  "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"
      }
    }
  ]
}

Image config (`sha256:a781560066f20ec9c28f2115a95a886e5e71c7c7aa9d8fd680678498b82f3ea3`):

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

Layer content (`sha256:1ea07d5e55eb47ad0e6bbfa2ec180fb580974411e623814e519064c88f022f5c`):

Attestation body containing the SBOM data listing the packages used during the build in SPDX format.

{
  "_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",
    ...