映象證明儲存

Buildkit 支援建立證明並將其附加到構建工件。這些證明可以提供構建過程中的寶貴資訊,包括但不限於:軟體供應鏈清單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而有所不同。

  • 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",
    ...