Compartir comentarios
Las respuestas se generan en base a la documentación.

Verificar una imagen o chart de Docker Hardened Images

Tabla de contenidos

Las Docker Hardened Images (DHI) y los charts incluyen atestaciones firmadas que verifican el proceso de compilación, el contenido y la postura de seguridad.

La clave pública de Docker para las imágenes y charts de DHI se publica en:

Docker recomienda usar Docker Scout, pero puedes usar regctl y cosign para recuperar y verificar las atestaciones. Docker Scout ofrece varias ventajas clave: comprende las estructuras de atestación de DHI, resuelve automáticamente las plataformas, proporciona resúmenes legibles por humanos, valida en un solo paso con --verify y se integra estrechamente con la infraestructura de atestación de Docker.

Important

Debes autenticarte en el registro de Docker Hardened Images (dhi.io) para descargar las imágenes. Usa tus credenciales de Docker ID (el mismo usuario y contraseña que usas para Docker Hub) al iniciar sesión. Si no tienes una cuenta de Docker, crea una de forma gratuita.

Ejecuta docker login dhi.io para autenticarte.

Verificar atestaciones de imágenes

Note

Antes de ejecutar comandos de docker scout attest, asegúrate de que cualquier imagen que hayas descargado localmente esté actualizada con respecto a la imagen remota. Puedes hacerlo ejecutando docker pull. Si no lo haces, es posible que veas el mensaje No attestation found.

Listar las atestaciones disponibles

Para listar las atestaciones de una imagen de DHI replicada:

Note

Si la imagen existe localmente en tu dispositivo, debes anteponer al nombre de la imagen el prefijo registry://. Por ejemplo, usa registry://dhi.io/python:3.13 en lugar de dhi.io/python:3.13.

$ docker scout attest list dhi.io/<image>:<tag>

Este comando muestra todas las atestaciones disponibles, incluyendo SBOM, procedencia, informes de vulnerabilidades y más.

Primero, autentícate en ambos registros. Prepara un token de acceso personal (PAT) para tu usuario con acceso read only:

Warning

Los siguientes ejemplos exportan las credenciales directamente en la línea de comandos con fines de demostración. Esto expone tokens sensibles en el historial de la shell y en la lista de procesos. En entornos de producción, utiliza métodos seguros como leer desde archivos con permisos restringidos, archivos de entorno cargados en tiempo de ejecución o herramientas de gestión de secretos.

$ export DOCKER_USERNAME="YOUR_DOCKER_USERNAME"
$ export DOCKER_PAT="YOUR_DOCKER_PAT"
$ export DOCKER_ORG="YOUR_DOCKER_ORG"
$ echo $DOCKER_PAT | regctl registry login -u "$DOCKER_USERNAME" --pass-stdin docker.io
$ echo $DOCKER_PAT | regctl registry login -u "$DOCKER_USERNAME" --pass-stdin registry.scout.docker.com

Luego, lista las atestaciones utilizando la opción --external. Los repositorios de DHI almacenan las capas de las imágenes en dhi.io (o docker.io para imágenes replicadas) y las atestaciones firmadas en registry.scout.docker.com:

$ regctl artifact list docker.io/${DOCKER_ORG}/<image>:<tag> \
  --external registry.scout.docker.com/${DOCKER_ORG}/<image> \
  --platform linux/amd64

Por ejemplo:

$ regctl artifact list docker.io/${DOCKER_ORG}/dhi-node:22 \
  --external registry.scout.docker.com/${DOCKER_ORG}/dhi-node \
  --platform linux/amd64

Recuperar una atestación específica

Para recuperar una atestación específica, usa la opción --predicate-type con la URI completa del tipo de predicado:

$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  dhi.io/<image>:<tag>
Note

Si la imagen existe localmente en tu dispositivo, debes anteponer al nombre de la imagen el prefijo registry://. Por ejemplo, usa registry://dhi.io/python:3.13 en lugar de dhi.io/python:3.13.

Por ejemplo:

$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  dhi.io/python:3.13

Para recuperar únicamente el cuerpo del predicado:

$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  --predicate \
  dhi.io/<image>:<tag>

Una vez que hayas listado las atestaciones, descarga el artefacto de atestación completo utilizando el resumen del campo Name:

$ regctl artifact get <attestation-digest> > attestation.json

Por ejemplo, para guardar una atestación de procedencia SLSA:

$ regctl artifact get registry.scout.docker.com/${DOCKER_ORG}/dhi-node@sha256:6cbf803796e281e535f2681de7cd33a1012202610322a50ee745d1bb02ac3c18 > slsa_provenance.json

Validar la atestación

Para validar la atestación utilizando Docker Scout, puedes usar la opción --verify:

$ docker scout attest get dhi.io/<image>:<tag> \
   --predicate-type https://scout.docker.com/sbom/v0.1 --verify
Note

Si la imagen existe localmente en tu dispositivo, debes anteponer al nombre de la imagen el prefijo registry://. Por ejemplo, usa registry://dhi.io/node:20.19-debian12 en lugar de dhi.io/node:20.19-debian12.

Por ejemplo, para verificar la atestación SBOM para la imagen dhi.io/node:20.19-debian12:

$ docker scout attest get dhi.io/node:20.19-debian12 \
   --predicate-type https://scout.docker.com/sbom/v0.1 --verify

Una vez que hayas listado las atestaciones y obtenido el resumen del campo Name, verifícalas usando cosign:

$ cosign verify \
  <attestation-digest-from-name-field> \
  --key https://registry.scout.docker.com/keyring/dhi/latest.pub \
  --insecure-ignore-tlog=true

Por ejemplo:

$ cosign verify \
  registry.scout.docker.com/${DOCKER_ORG}/dhi-node@sha256:6cbf803796e281e535f2681de7cd33a1012202610322a50ee745d1bb02ac3c18 \
  --key https://registry.scout.docker.com/keyring/dhi/latest.pub \
  --insecure-ignore-tlog=true
Note

La opción --insecure-ignore-tlog=true es necesaria porque las atestaciones de DHI pueden no registrarse en el registro de transparencia público de Rekor para proteger la información privada del cliente. La firma de la atestación se sigue verificando con la clave pública de Docker.

Gestionar la falta de entradas en el registro de transparencia

Al usar --verify con Docker Scout o cosign verify, a veces puedes ver un error como:

ERROR no matching signatures: signature not found in transparency log

Esto ocurre porque las Docker Hardened Images no siempre registran las atestaciones en el registro de transparencia público de Rekor. En los casos en que una atestación contendría información privada del usuario (por ejemplo, el espacio de nombres de tu organización en la referencia de la imagen), escribirla en Rekor expondría esa información públicamente.

Incluso si falta la entrada en Rekor, la atestación sigue estando firmada con la clave pública de Docker y puede verificarse sin conexión omitiendo la comprobación del registro de transparencia de Rekor.

Para omitir la comprobación del registro de transparencia y validar con la clave de Docker, usa la opción --skip-tlog:

$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  dhi.io/<image>:<tag> \
  --verify --skip-tlog
Note

La opción --skip-tlog solo está disponible en la versión 1.18.2 y posteriores de la CLI de Docker Scout.

Si la imagen existe localmente en tu dispositivo, debes anteponer al nombre de la imagen el prefijo registry://. Por ejemplo, usa registry://dhi.io/python:3.13 en lugar de dhi.io/python:3.13.

Esto equivale a usar cosign con la opción --insecure-ignore-tlog=true, que valida la firma con la clave pública publicada de Docker pero ignora la comprobación del registro de transparencia.

Mostrar el comando cosign equivalente

Al usar la opción --verify, también se imprime el comando cosign correspondiente para verificar la firma de la imagen:

$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  --verify \
  dhi.io/<image>:<tag>
Note

Si la imagen existe localmente en tu dispositivo, debes anteponer al nombre de la imagen el prefijo registry://. Por ejemplo, usa registry://dhi.io/python:3.13 en lugar de dhi.io/python:3.13.

Por ejemplo:

$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  --verify \
  dhi.io/python:3.13

Si la verificación tiene éxito, Docker Scout imprime el comando cosign verify completo.

Ejemplo de salida:

     SBOM obtenido de la atestación, se encontraron 101 paquetes
     Procedencia obtenida de la atestación
     cosign verify ...
Important

Al usar cosign, primero debes autenticarte tanto en el registro de DHI como en el registro de Docker Scout.

Por ejemplo:

$ docker login dhi.io
$ docker login registry.scout.docker.com
$ cosign verify ...

Verificar atestaciones de paquetes

Además de las atestaciones de imágenes, los paquetes securizados individuales tienen sus propias atestaciones. Estas atestaciones a nivel de paquete te dejan verificar la procedencia y la información de compilación de paquetes específicos dentro de una imagen.

Para obtener instrucciones sobre cómo extraer información de paquetes de las atestaciones de imágenes y recuperar atestaciones a nivel de paquete, consulta Atestaciones de paquetes.

Verificar las atestaciones de Helm charts con Docker Scout

Los charts de Helm de Docker Hardened Image incluyen las mismas atestaciones completas que las imágenes de contenedor. El proceso de verificación para los charts es idéntico al de las imágenes, utilizando los mismos comandos de la CLI de Docker Scout.

Listar las atestaciones de charts disponibles

Para listar las atestaciones de un Helm chart de DHI:

$ docker scout attest list dhi.io/<chart>:<version>

Por ejemplo, para listar las atestaciones del chart external-dns:

$ docker scout attest list dhi.io/external-dns-chart:1.20.0

Este comando muestra todas las atestaciones de charts disponibles, incluyendo SBOM, procedencia, informes de vulnerabilidades y más.

Recuperar una atestación de chart específica

Para recuperar una atestación específica de un Helm chart, usa la opción --predicate-type con la URI completa del tipo de predicado:

$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  dhi.io/<chart>:<version>

Por ejemplo:

$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  dhi.io/external-dns-chart:1.20.0

Para recuperar únicamente el cuerpo del predicado:

$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  --predicate \
  dhi.io/<chart>:<version>

Validar atestaciones de charts con Docker Scout

Para validar una atestación de chart utilizando Docker Scout, usa la opción --verify:

$ docker scout attest get dhi.io/<chart>:<version> \
   --predicate-type https://scout.docker.com/sbom/v0.1 --verify

Por ejemplo, para verificar la atestación SBOM del chart external-dns:

$ docker scout attest get dhi.io/external-dns-chart:1.20.0 \
   --predicate-type https://scout.docker.com/sbom/v0.1 --verify

La misma opción --skip-tlog descrita en Gestionar la falta de entradas en el registro de transparencia también se puede usar con las atestaciones de charts cuando sea necesario.

Atestaciones de DHI disponibles

Consulta las atestaciones disponibles para ver una lista de las atestaciones disponibles para cada imagen de DHI, y las atestaciones de Helm charts para ver una lista de las atestaciones disponibles para cada chart de DHI.

Explorar atestaciones en Docker Hub

También puedes explorar las atestaciones visualmente al examinar una variante de imagen. La sección Attestations muestra cada atestación disponible con su:

  • Tipo (por ejemplo, SBOM, VEX)
  • URI del tipo de predicado
  • Referencia del resumen (digest) para usar con cosign

Estas atestaciones se generan y firman automáticamente como parte del proceso de compilación del chart o de la Docker Hardened Image.