Validación de entradas de compilación con políticas

Compilar con Docker a menudo implica descargar recursos remotos. Estas dependencias externas, como imágenes de Docker, repositorios Git, archivos remotos y otros artefactos, se denominan entradas de compilación (build inputs).

Por ejemplo:

• Descargar (pull) imágenes desde un registro
• Clonar un repositorio de código fuente
• Obtener archivos de un servidor a través de HTTPS

Al consumir entradas de compilación, es recomendable verificar que el contenido sea el esperado. Una forma de hacerlo es usar la opción --checksum en la instrucción ADD del Dockerfile. Esto te permite verificar la suma de comprobación (checksum) SHA256 de un recurso remoto al descargarlo en una compilación:

ADD --checksum=sha256:c0ff3312345… https://example.com/archive.tar.gz /

Si el archivo remoto archive.tar.gz no coincide con la suma de comprobación que espera el Dockerfile, la compilación falla.

Las sumas de comprobación verifican que el contenido coincida con lo esperado, pero solo para la instrucción ADD. No brindan información sobre el origen del contenido ni sobre cómo se produjo. No puedes usar sumas de comprobación para imponer restricciones como "las imágenes deben estar firmadas" o "las dependencias deben provenir de fuentes aprobadas".

Las políticas de compilación resuelven este problema. Te permiten definir reglas que validan todas tus entradas de compilación, aplicando requisitos como atestaciones de procedencia, registros aprobados y etiquetas Git firmadas en todo el proceso de compilación.

Requisitos previos

Las políticas de compilación son actualmente una característica experimental. Para probarlas, necesitas:

• Buildx 0.31.0 o posterior - Verifica tu versión con: docker buildx version
• BuildKit 0.27.0 o posterior - Verifícalo con: docker buildx inspect --bootstrap

Si usas Docker Desktop, asegúrate de estar en una versión que incluya estas actualizaciones.

Políticas de compilación

La versión 0.31.0 de Buildx añadió soporte para las políticas de compilación. Las políticas de compilación son reglas para asegurar la cadena de suministro de tus compilaciones de Docker y ayudan a proteger contra vulnerabilidades de origen (upstream), dependencias maliciosas y modificaciones no autorizadas en tus entradas de compilación.

Las políticas de compilación te permiten aplicar verificaciones extendidas en las entradas utilizadas para compilar tus proyectos, tales como:

• Las imágenes de Docker deben usar referencias por digest (no solo etiquetas)
• Las imágenes deben tener atestaciones de procedencia y firmas cosign
• Las etiquetas de Git deben estar firmadas por los mantenedores con una clave pública PGP
• Todos los artefactos remotos deben usar HTTPS e incluir una suma de comprobación para su verificación

Las políticas de compilación se definen en un lenguaje de políticas declarativo, llamado Rego, creado para el Open Policy Agent (OPA). El siguiente ejemplo muestra una política de compilación básica en Rego.

package docker

default allow := false

# Permitir cualquier entrada local para esta compilación
# Por ejemplo: un contexto de compilación local o un Dockerfile local
allow if input.local

# Permitir imágenes, pero solo si tienen atestaciones de procedencia
allow if {
    input.image.hasProvenance
}

decision := {"allow": allow}

Si el Dockerfile asociado a esta política hace referencia a una imagen sin atestación de procedencia en una instrucción FROM, se violaría la política y la compilación fallaría.

Cómo funcionan las políticas

Cuando ejecutas docker buildx build, Buildx:

1. Resuelve todas las entradas de compilación (imágenes, repositorios Git, descargas HTTP)
2. Busca un archivo de política que coincida con el nombre de tu Dockerfile (por ejemplo, Dockerfile.rego)
3. Evalúa cada entrada frente a la política antes de que comience la compilación
4. Permite que la compilación continúe solo si todas las entradas cumplen con la política

Las políticas se escriben en Rego (el lenguaje de políticas de Open Policy Agent). No necesitas ser un experto en Rego; el tutorial de Introducción te enseña todo lo necesario.

Los archivos de políticas se ubican junto a tu Dockerfile:

project/
├── Dockerfile
├── Dockerfile.rego
└── src/

No se requiere configuración adicional; Buildx busca y carga automáticamente la política cuando compilas.

Casos de uso

Las políticas de compilación te ayudan a aplicar requisitos de seguridad y cumplimiento normativo en tus compilaciones de Docker. Escenarios comunes donde las políticas resultan útiles:

Aplicar estándares de imagen base

Exige que todos los Dockerfiles de producción utilicen imágenes base específicas y aprobadas con referencias por digest. Evita que los desarrolladores usen imágenes arbitrarias que no hayan sido revisadas por tu equipo de seguridad.

Validar dependencias de terceros

Cuando tu compilación descarga archivos, librerías o herramientas de internet, verifica que provengan de fuentes de confianza y coincidan con las sumas de comprobación o firmas esperadas. Esto protege contra ataques a la cadena de suministro donde una dependencia ascendente (upstream) se ve comprometida.

Garantizar lanzamientos firmados

Requiere que todas las dependencias tengan firmas válidas de partes de confianza.

• Verifica las firmas GPG de los repositorios Git que clonas en tus compilaciones
• Verifica las firmas de atestaciones de procedencia con Sigstore

Cumplir con requisitos de cumplimiento normativo

Algunos marcos regulatorios exigen pruebas de que validas tus entradas de compilación. Las políticas de compilación te ofrecen una forma declarativa y auditable de demostrar que estás verificando las dependencias frente a estándares de seguridad.

Separar reglas de desarrollo y producción

Aplica una validación más estricta para las compilaciones de producción mientras permites mayor flexibilidad durante el desarrollo. El mismo archivo de política puede contener reglas condicionales basadas en el contexto o el objetivo (target) de la compilación.

Comenzar

¿Listo para comenzar a escribir políticas? El tutorial de Introducción te guiará en la creación de tu primera política y te enseñará los conceptos básicos de Rego que necesitas.

Para obtener orientación sobre el uso práctico, consulta Uso de políticas de compilación.

Para ver ejemplos prácticos que puedes copiar y adaptar, consulta la biblioteca de Ejemplos de políticas.