Admin-Sistemas ·

Implementación paso a paso de Docker Content Trust (DCT) en producción

Introducción

Docker Content Trust (DCT) es la solución oficial de Docker para firmar y verificar la integridad de imágenes mediante Notary, una implementación de The Update Framework (TUF). En entornos de producción, DCT permite garantizar que solo se desplieguen imágenes aprobadas y que no hayan sido modificadas maliciosamente. Este artículo muestra, paso a paso, cómo habilitar DCT, gestionar el ciclo de vida de las claves, aplicar políticas de firma y automatizar todo el proceso dentro de pipelines CI/CD.

1. Preparación del entorno

1.1 Requisitos previos

  • Docker Engine ≥ 1.8 (aunque se recomienda la versión 20.x o superior).
  • Acceso a un registro Docker (Docker Hub, Azure Container Registry, Amazon ECR, etc.).
  • Herramientas: docker, notary (se instala con Docker), jq para manipular JSON y git para CI.
  • Un repositorio Git con permisos de escritura en el registro.

1.2 Instalación de Notary (si no viene con Docker)

# En Debian/Ubuntu
sudo apt-get update
sudo apt-get install -y notary

En RHEL/CentOS

sudo yum install -y notary

Verifique la versión:

notary version
# Output esperado: notary version 0.6.x

2. Gestión de claves

2.1 Creación del repositorio Notary

Docker crea automáticamente un repositorio Notary en el registro cuando se firma la primera imagen. Sin embargo, es buena práctica inicializarlo explícitamente para controlar las claves raíz y de firma.

# Exportar variables para evitar prompts interactivos
export DOCKER_CONTENT_TRUST=1
export DOCKER_CONTENT_TRUST_ROOT_PASSPHRASE=miRootPass
export DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE=miRepoPass

Push de una imagen dummy para iniciar el repositorio Notary

docker pull alpine:3.18 docker tag alpine:3.18 myregistry.example.com/miapp:1.0.0 docker push myregistry.example.com/miapp:1.0.0

Al ejecutar el push con DOCKER_CONTENT_TRUST=1, Docker genera las claves root y tuf (también llamadas repository). Estas se almacenan en ~/.docker/trust:

tree ~/.docker/trust
~/.docker/trust
├── private
│   ├── root_key
│   └── repository_key
└── metadata
    ├── root.json
    └── repository
        └── 1.json

2.2 Rotación y respaldo de claves

Es fundamental respaldar root_key y repository_key en un almacén seguro (Vault, AWS KMS, HSM). Para rotar la clave de firma:

# Generar una nueva clave de firma (tuf)
notary key generate --role targets

Publicar la nueva clave en el servidor Notary

notary key rotate myregistry.example.com/miapp

Para rotar la clave raíz (operación delicada):

notary key change-password --role root
# Luego, actualizar los archivos de metadata:
notary -s https://notary.myregistry.example.com:4443 \
       -d ~/.docker/trust \
       key rotate --role root

Recuerde que la rotación de la raíz invalida todas las firmas previas, así que planifique una ventana de mantenimiento.

3. Política de firmas

3.1 Definir roles y delegaciones

Notary permite delegar firmas a diferentes roles (por ejemplo, release, staging). Esto facilita flujos de trabajo con varios equipos.

# Crear una delegación llamada "release"
notary delegation add myregistry.example.com/miapp release \
    --key /path/to/release.pub \
    --threshold 1

Listar delegaciones

notary delegation list myregistry.example.com/miapp

3.2 Configurar políticas de firma en Docker

Docker no expone directamente una política de firma; en su lugar, usamos Docker Content Trust junto con políticas de CI para decidir cuándo se debe firmar.

  • Política de rama: Sólo las ramas main y release/* pueden firmar.
  • Umbral de firmas: Se requiere al menos 2 firmas en la delegación release antes de que la imagen sea considerada “aprobada”.

Implementamos esta lógica en el pipeline (ver sección 4).

4. Automatización en pipelines CI/CD

4.1 Integración con GitHub Actions

A continuación se muestra un workflow básico que construye, firma y publica una imagen sólo si la rama cumple la política.

name: Build & Publish Docker Image

on: push: branches: - main - ‘release/**’

jobs: build: runs-on: ubuntu-latest env: DOCKER_CONTENT_TRUST: 1 DOCKER_CONTENT_TRUST_ROOT_PASSPHRASE: ${{ secrets.ROOT_PASSPHRASE }} DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE: ${{ secrets.REPO_PASSPHRASE }}

steps:
  - name: Checkout code
    uses: actions/checkout@v3

  - name: Set up Docker Buildx
    uses: docker/setup-buildx-action@v2

  - name: Log in to registry
    uses: docker/login-action@v2
    with:
      registry: myregistry.example.com
      username: ${{ secrets.REGISTRY_USER }}
      password: ${{ secrets.REGISTRY_PASS }}

  - name: Build image
    run: |
      docker build -t myregistry.example.com/miapp:${{ github.sha }} .
  
  - name: Sign & Push
    run: |
      docker push myregistry.example.com/miapp:${{ github.sha }}

En este workflow, las variables DOCKER_CONTENT_TRUST_ROOT_PASSPHRASE y DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE provienen de GitHub Secrets, garantizando que las claves nunca se imprimen en logs.

4.2 Verificación en entornos de despliegue (Kubernetes)

Para que los nodos de Kubernetes sólo acepten imágenes firmadas, configure imagePolicyWebhook con gatekeeper o OPA. Un ejemplo sencillo con openpolicyagent/opa:

# policy.rego
package kubernetes.admission

deny[msg] { input.request.kind.kind == “Pod” not signed_image(input.request.object.spec.containers[_].image) }

signed_image(img) { startswith(img, “myregistry.example.com/”)

Asumimos que la firma se valida externamente; aquí solo comprobamos prefijo

}

Despliegue:

kubectl apply -f policy.rego
kubectl apply -f https://raw.githubusercontent.com/open-policy-agent/gatekeeper/master/deploy/gatekeeper.yaml

4.3 Rotación automática de claves en CI

Puede programar un job periódico que genere una nueva repository key y actualice la metadata. Un ejemplo con GitLab CI:

rotate_keys:
  stage: maintenance
  script:
    - export DOCKER_CONTENT_TRUST=1
    - export DOCKER_CONTENT_TRUST_ROOT_PASSPHRASE=$ROOT_PASS
    - export DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE=$REPO_PASS
    - notary key generate --role targets
    - notary key rotate myregistry.example.com/miapp
  only:
    - schedules

5. Troubleshooting y errores comunes

5.1 Error: docker: Error response from daemon: repository name not known

Este mensaje indica que el registro no tiene habilitado Notary o que la URL del servidor Notary es incorrecta. Solución:

  1. Verifique que DOCKER_CONTENT_TRUST_SERVER apunte al endpoint correcto (p.ej. https://notary.myregistry.example.com:4443).
  2. Asegúrese de que el registro soporte Notary (consultar la documentación del proveedor).

5.2 Error: signature verification failed for repository

Causas típicas:

  • Clave de firma no coincide con la almacenada en ~/.docker/trust. Revise que los archivos root_key y repository_key no estén corruptos.
  • La imagen que intenta pull no está firmada. Use docker trust inspect --pretty REGISTRY/IMAGE:TAG para confirmar.

5.3 Error al rotar la clave raíz: cannot rotate root key: metadata verification failed

Este error ocurre cuando la metadata local está desincronizada con el servidor Notary. Solución:

# Forzar una descarga fresca de la metadata
notary -d ~/.docker/trust -s https://notary.myregistry.example.com:4443 \
       key list

Después, vuelva a intentar la rotación.

5.4 Problemas en CI: variables de entorno no disponibles

En muchas plataformas CI, las variables que contienen contraseñas no se exportan automáticamente a los contenedores Docker. Asegúrese de usar la sintaxis propia de cada CI (${{ secrets.X }} en GitHub, $CI_VARIABLE en GitLab) y de marcar los pasos como env: en el job.

Conclusión

Docker Content Trust brinda un mecanismo robusto y estándar para garantizar que solo se desplieguen imágenes verificadas, reduciendo el riesgo de ataques de supply‑chain. La correcta gestión de claves, la definición de políticas de firma y la integración en pipelines CI/CD son los pilares de una implementación segura.

Recuerde siempre:

  • Respaldar y rotar las claves de forma planificada.
  • Aplicar delegaciones y umbrales que reflejen la estructura organizacional.
  • Validar la firma tanto en la fase de build como en el momento del despliegue (Kubernetes, Docker Swarm, etc.).
  • Mantener la documentación actualizada y entrenar a los equipos en el uso de DCT.

Con estos pasos, su infraestructura de contenedores estará preparada para enfrentar los desafíos de seguridad modernos, asegurando la integridad y autenticidad de cada imagen que atraviesa el pipeline de producción.