Attestations de build

Table des matières

Les attestations de build décrivent comment une image a été construite, et ce qu'elle contient. Les attestations sont créées au moment du build par BuildKit, et deviennent attachées à l'image finale comme métadonnées.

Le but des attestations est de rendre possible l'inspection d'une image et de voir d'où elle vient, qui l'a créée et comment, et ce qu'elle contient. Cela vous permet de prendre des décisions éclairées sur comment une image impacte la sécurité de la chaîne d'approvisionnement de votre application. Cela permet aussi l'utilisation de moteurs de politique pour valider les images basées sur des règles de politique que vous avez définies.

Deux types d'annotations de build sont disponibles :

Software Bill of Material (SBOM) : liste des artefacts logiciels qu'une image contient, ou qui ont été utilisés pour construire l'image.
Provenance : comment une image a été construite.

Objectif des attestations

L'utilisation de packages open source et tiers est plus répandue que jamais. Les développeurs partagent et réutilisent le code parce que cela aide à augmenter la productivité, permettant aux équipes de créer de meilleurs produits, plus rapidement.

Importer et utiliser du code créé ailleurs sans le vérifier introduit un risque de sécurité sévère. Même si vous révisez le logiciel que vous consommez, de nouvelles vulnérabilités zero-day sont fréquemment découvertes, nécessitant que les équipes de développement prennent des mesures pour les corriger.

Les attestations de build rendent plus facile de voir le contenu d'une image, et d'où elle vient. Utilisez les attestations pour analyser et décider s'il faut utiliser une image, ou pour voir si des images que vous utilisez déjà sont exposées à des vulnérabilités.

Créer des attestations

Lorsque vous construisez une image avec docker buildx build, vous pouvez ajouter des enregistrements d'attestation à l'image résultante en utilisant les options --provenance et --sbom. Vous pouvez choisir d'ajouter soit le type d'attestation SBOM ou provenance, ou les deux.

$ docker buildx build --sbom=true --provenance=true .

Note

Le magasin d'images par défaut ne prend pas en charge les attestations. Si vous utilisez le magasin d'images par défaut et que vous construisez une image en utilisant le driver docker par défaut, ou en utilisant un driver différent avec le flag --load, les attestations sont perdues.

Pour vous assurer que les attestations sont préservées, vous pouvez :

Utiliser un driver docker-container avec le flag --push pour pousser l'image vers un registre directement.

Activer le magasin d'images containerd.

Note

Les attestations de provenance sont activées par défaut, avec l'option mode=min. Vous pouvez désactiver les attestations de provenance en utilisant le flag --provenance=false, ou en définissant la variable d'environnement BUILDX_NO_DEFAULT_ATTESTATIONS.

Utiliser le flag --provenance=true attache des attestations de provenance avec mode=min par défaut. Voir Attestation de provenance pour plus de détails.

BuildKit génère les attestations lors de la construction de l'image. Les enregistrements d'attestation sont enveloppés dans le format JSON in-toto et attachés à l'index d'image dans un manifeste pour l'image finale.

Stockage

BuildKit produit des attestations dans le format in-toto, tel que défini par le framework in-toto, un standard supporté par la Linux Foundation.

Les attestations s'attachent aux images comme un manifeste dans l'index d'image. Les enregistrements de données des attestations sont stockés comme des blobs JSON.

Parce que les attestations s'attachent aux images comme un manifeste, cela signifie que vous pouvez inspecter les attestations pour n'importe quelle image dans un registre sans avoir à tirer l'image entière.

Tous les exportateurs BuildKit prennent en charge les attestations. Les exportateurs local et tar ne peuvent pas sauvegarder les attestations dans un manifeste d'image, puisqu'ils sortent un répertoire de fichiers ou une archive tar, pas une image. Au lieu de cela, ces exportateurs écrivent les attestations dans un ou plusieurs fichiers JSON dans le répertoire racine de l'export.

Exemple

L'exemple suivant montre une représentation JSON in-toto tronquée d'une attestation SBOM.

{
  "_type": "https://in-toto.io/Statement/v0.1",
  "predicateType": "https://spdx.dev/Document",
  "subject": [
    {
      "name": "pkg:docker/<registry>/<image>@<tag/digest>?platform=<platform>",
      "digest": {
        "sha256": "e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862"
      }
    }
  ],
  "predicate": {
    "SPDXID": "SPDXRef-DOCUMENT",
    "creationInfo": {
      "created": "2022-12-15T11:47:54.546747383Z",
      "creators": ["Organization: Anchore, Inc", "Tool: syft-v0.60.3"],
      "licenseListVersion": "3.18"
    },
    "dataLicense": "CC0-1.0",
    "documentNamespace": "https://anchore.com/syft/dir/run/src/core-da0f600b-7f0a-4de0-8432-f83703e6bc4f",
    "name": "/run/src/core",
    // liste des fichiers que l'image contient, par ex.:
    "files": [
      {
        "SPDXID": "SPDXRef-1ac501c94e2f9f81",
        "comment": "layerID: sha256:9b18e9b68314027565b90ff6189d65942c0f7986da80df008b8431276885218e",
        "fileName": "/bin/busybox",
        "licenseConcluded": "NOASSERTION"
      }
    ],
    // liste des packages qui ont été identifiés pour cette image:
    "packages": [
      {
        "name": "busybox",
        "originator": "Person: Sören Tempel <[email protected]>",
        "sourceInfo": "acquired package info from APK DB: lib/apk/db/installed",
        "versionInfo": "1.35.0-r17",
        "SPDXID": "SPDXRef-980737451f148c56",
        "description": "Size optimized toolbox of many common UNIX utilities",
        "downloadLocation": "https://busybox.net/",
        "licenseConcluded": "GPL-2.0-only",
        "licenseDeclared": "GPL-2.0-only"
        // ...
      }
    ],
    // relation fichiers-packages
    "relationships": [
      {
        "relatedSpdxElement": "SPDXRef-1ac501c94e2f9f81",
        "relationshipType": "CONTAINS",
        "spdxElementId": "SPDXRef-980737451f148c56"
      },
      ...
    ],
    "spdxVersion": "SPDX-2.2"
  }
}

Pour approfondir les spécificités sur comment les attestations sont stockées, voir Stockage d'attestation d'image (BuildKit).

Format de manifeste d'attestation

Les attestations sont stockées comme des manifestes, référencés par l'index de l'image. Chaque manifeste d'attestation fait référence à un seul manifeste d'image (une variante de plateforme de l'image). Les manifestes d'attestation contiennent une seule couche, la "valeur" de l'attestation.

L'exemple suivant montre la structure d'un manifeste d'attestation :

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "size": 167,
    "digest": "sha256:916d7437a36dd0e258e64d9c5a373ca5c9618eeb1555e79bd82066e593f9afae"
  },
  "layers": [
    {
      "mediaType": "application/vnd.in-toto+json",
      "size": 1833349,
      "digest": "sha256:3138024b98ed5aa8e3008285a458cd25a987202f2500ce1a9d07d8e1420f5491",
      "annotations": {
        "in-toto.io/predicate-type": "https://spdx.dev/Document"
      }
    }
  ]
}

Attestations comme artefacts OCI

Vous pouvez configurer le format du manifeste d'attestation en utilisant l' option oci-artifact pour les exportateurs image et registry. Si défini à true, la structure du manifeste d'attestation change comme suit :

Un champ artifactType est ajouté au manifeste d'attestation, avec une valeur de application/vnd.docker.attestation.manifest.v1+json.
Le champ config est un descripteur vide au lieu d'une config "factice".
Un champ subject est aussi ajouté, pointant vers le manifeste d'image auquel l'attestation fait référence.

L'exemple suivant montre une attestation avec le format d'artefact OCI :

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "artifactType": "application/vnd.docker.attestation.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.empty.v1+json",
    "size": 2,
    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
    "data": "e30="
  },
  "layers": [
    {
      "mediaType": "application/vnd.in-toto+json",
      "size": 2208,
      "digest": "sha256:6d2f2c714a6bee3cf9e4d3cb9a966b629efea2dd8556ed81f19bd597b3325286",
      "annotations": {
        "in-toto.io/predicate-type": "https://slsa.dev/provenance/v0.2"
      }
    }
  ],
  "subject": {
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "size": 1054,
    "digest": "sha256:bc2046336420a2852ecf915786c20f73c4c1b50d7803aae1fd30c971a7d1cead",
    "platform": {
      "architecture": "amd64",
      "os": "linux"
    }
  }
}

Prochaines étapes

Apprenez-en plus sur les types d'attestation disponibles et comment les utiliser :