Cómo usar el comando docker scout attestation add para adjuntar atestados a una imagen

Introducción

En este laboratorio, aprenderá cómo adjuntar atestados a una imagen de Docker utilizando el comando docker scout attestation add. Los atestados son metadatos valiosos que pueden proporcionar información crucial sobre el origen de una imagen, el proceso de construcción, los resultados de análisis de seguridad y más.

Comenzará preparando una imagen de Docker y un archivo de atestado simple. Luego, utilizará el comando docker scout attestation add con la bandera --file para adjuntar el atestado a la imagen. También explorará cómo especificar un tipo de predicado particular para el atestado utilizando la bandera --predicate-type. Finalmente, verificará que los atestados se hayan agregado correctamente a la imagen.

Skills Graph

Preparar una imagen y un archivo de atestado

En este paso, prepararemos una imagen de Docker y un archivo de atestado. Un atestado es un fragmento de metadatos que proporciona información sobre una imagen, como cómo se construyó, se analizó en busca de vulnerabilidades o se firmó. Utilizaremos un archivo de texto simple como nuestro archivo de atestado para este ejemplo.

Primero, descarguemos una imagen básica de Docker que utilizaremos. Utilizaremos la imagen alpine, que es una distribución Linux ligera.

docker pull alpine:latest

Debería ver una salida que indique que la imagen se está descargando.

latest: Pulling from library/alpine
...
Status: Downloaded newer image for alpine:latest
docker.io/library/alpine:latest

A continuación, crearemos un archivo de atestado simple. Este archivo contendrá algunos datos JSON arbitrarios. En un escenario del mundo real, este archivo contendría datos estructurados sobre la imagen, como información de construcción, resultados de análisis o detalles de firma.

Crearemos un archivo llamado attestation.json en el directorio ~/project.

nano ~/project/attestation.json

Dentro del editor nano, pegue el siguiente contenido JSON:

{
  "predicateType": "https://example.com/attestation/v1",
  "data": {
    "key": "value",
    "another_key": 123
  }
}

Presione Ctrl + X, luego Y y Enter para guardar el archivo.

Puede verificar el contenido del archivo utilizando el comando cat:

cat ~/project/attestation.json

La salida debe ser el contenido JSON que acaba de pegar.

Ahora tiene tanto la imagen de Docker (alpine:latest) como el archivo de atestado (~/project/attestation.json) listos para los siguientes pasos.

Agregar un atestado a la imagen utilizando --file

En este paso, agregaremos el archivo de atestado que creamos en el paso anterior a la imagen alpine:latest. Utilizaremos el comando docker buildx imagetools create con la bandera --attestation-file. Este comando nos permite crear un nuevo manifiesto de imagen con metadatos adicionales, incluyendo atestados.

La sintaxis básica para agregar un archivo de atestado es:

docker buildx imagetools create <source_image> --attestation-file <attestation_file_path> --tag <new_image_tag>

Aquí, <source_image> es la imagen a la que desea agregar el atestado, <attestation_file_path> es la ruta a su archivo de atestado y <new_image_tag> es la etiqueta para el nuevo manifiesto de imagen que incluirá el atestado.

Agreguemos el archivo ~/project/attestation.json a la imagen alpine:latest y etiquetemos la nueva imagen como alpine:attested.

docker buildx imagetools create alpine:latest --attestation-file ~/project/attestation.json --tag alpine:attested

Debería ver una salida que indique que se está creando y enviando el nuevo manifiesto de imagen.

...
unpacking to docker.io/library/alpine:attested done

Este comando crea un nuevo manifiesto de imagen con la etiqueta alpine:attested que incluye los datos de atestado de ~/project/attestation.json. La imagen original alpine:latest permanece sin cambios.

Ahora puede listar sus imágenes de Docker para ver la recién creada imagen alpine:attested.

docker images

Debería ver tanto alpine:latest como alpine:attested en la lista.

REPOSITORY   TAG       IMAGE ID       CREATED        SIZE
alpine       attested  <image_id>     ...            ...
alpine       latest    <image_id>     ...            ...
...

Tenga en cuenta que el IMAGE ID puede ser el mismo para ambas imágenes, ya que imagetools create a menudo reutiliza las capas de imagen subyacentes y solo crea un nuevo manifiesto.

Agregar un atestado con un tipo de predicado específico utilizando --predicate-type

En el paso anterior, agregamos un atestado utilizando la bandera --attestation-file. Docker infirió automáticamente el tipo de predicado del campo predicateType dentro del archivo JSON. Sin embargo, también puede especificar explícitamente el tipo de predicado utilizando la bandera --predicate-type. Esto es útil si sus datos de atestado no incluyen el campo predicateType o si desea anular el que está en el archivo.

La sintaxis básica para agregar un atestado con un tipo de predicado específico es:

docker buildx imagetools create <source_image> --attestation-file <attestation_file_path> --predicate-type <predicate_type_url> --tag <new_image_tag>

Aquí, <predicate_type_url> es la URL que representa el tipo de atestado.

Vamos a agregar de nuevo el mismo archivo ~/project/attestation.json a la imagen alpine:latest, pero esta vez estableceremos explícitamente el tipo de predicado en https://example.com/another-attestation/v2 y etiquetaremos la nueva imagen como alpine:attested-v2.

docker buildx imagetools create alpine:latest --attestation-file ~/project/attestation.json --predicate-type https://example.com/another-attestation/v2 --tag alpine:attested-v2

Debería ver una salida similar al paso anterior, que indique la creación de un nuevo manifiesto de imagen.

...
unpacking to docker.io/library/alpine:attested-v2 done

Este comando crea un nuevo manifiesto de imagen con la etiqueta alpine:attested-v2. Aunque el archivo attestation.json contiene "predicateType": "https://example.com/attestation/v1", la bandera --predicate-type anula esto, y el atestado en el nuevo manifiesto tendrá el tipo de predicado https://example.com/another-attestation/v2.

Vamos a listar las imágenes de nuevo para ver la nueva etiqueta.

docker images

Ahora debería ver alpine:latest, alpine:attested y alpine:attested-v2.

REPOSITORY   TAG           IMAGE ID       CREATED        SIZE
alpine       attested-v2   <image_id>     ...            ...
alpine       attested      <image_id>     ...            ...
alpine       latest        <image_id>     ...            ...
...

En el siguiente paso, verificaremos que los atestados se hayan agregado correctamente e inspeccionaremos su contenido.

Verificar los atestados agregados

En este último paso, verificaremos que los atestados se hayan agregado correctamente a las imágenes e inspeccionaremos su contenido. Podemos utilizar el comando docker buildx imagetools inspect para ver el manifiesto de una imagen, que incluye información sobre cualquier atestado asociado.

La sintaxis básica para inspeccionar un manifiesto de imagen es:

docker buildx imagetools inspect <image_tag>

Primero, inspeccionemos la imagen alpine:attested, que creamos utilizando la bandera --attestation-file.

docker buildx imagetools inspect alpine:attested

Debería ver una salida detallada sobre el manifiesto de la imagen. Busque una sección relacionada con "attestations" (atestados). Debería encontrar una entrada con el tipo de predicado https://example.com/attestation/v1 y los datos de su archivo attestation.json.

...
  "attestations": [
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "payload": "...",
      "predicateType": "https://example.com/attestation/v1"
    }
  ],
...

Ahora, inspeccionemos la imagen alpine:attested-v2, que creamos utilizando la bandera --predicate-type para anular el tipo de predicado.

docker buildx imagetools inspect alpine:attested-v2

Nuevamente, busque la sección "attestations". Esta vez, debería ver una entrada con el tipo de predicado https://example.com/another-attestation/v2, aunque el contenido de los datos de atestación sea el mismo que antes.

...
  "attestations": [
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "payload": "...",
      "predicateType": "https://example.com/another-attestation/v2"
    }
  ],
...

Esto confirma que hemos agregado con éxito atestados a las imágenes de Docker y que la bandera --predicate-type se puede utilizar para establecer explícitamente el tipo de predicado.

Ahora ha aprendido cómo preparar una imagen y un archivo de atestación, agregar atestados a una imagen utilizando tanto la bandera --attestation-file como la bandera --predicate-type, y verificar los atestados agregados utilizando docker buildx imagetools inspect.

Resumen

En este laboratorio, aprendimos cómo adjuntar atestados a una imagen de Docker utilizando el comando docker scout attestation add. Comenzamos preparando una imagen de Docker (alpine:latest) y creando un archivo de atestación JSON simple. Luego, utilizamos el comando docker scout attestation add con la bandera --file para adjuntar el archivo de atestación a la imagen. También exploramos cómo especificar un tipo de predicado personalizado para el atestado utilizando la bandera --predicate-type. Finalmente, verificamos que los atestados se hayan agregado correctamente a la imagen.