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),jqpara manipular JSON ygitpara 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 notaryEn 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=miRepoPassPush 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 targetsPublicar 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 1Listar 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
mainyrelease/*pueden firmar. - Umbral de firmas: Se requiere al menos 2 firmas en la delegación
releaseantes 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 Imageon: 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.admissiondeny[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:
- Verifique que
DOCKER_CONTENT_TRUST_SERVERapunte al endpoint correcto (p.ej.https://notary.myregistry.example.com:4443). - 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 archivosroot_keyyrepository_keyno estén corruptos. - La imagen que intenta pull no está firmada. Use
docker trust inspect --pretty REGISTRY/IMAGE:TAGpara 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.