# 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:

```dockerfile
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)](https://www.openpolicyagent.org/).
El siguiente ejemplo muestra una política de compilación básica en Rego.

```rego {title="Dockerfile.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](/build/intro/) te
enseña todo lo necesario.

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

```text
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](/build/intro/)
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](/build/usage/).

Para ver ejemplos prácticos que puedes copiar y adaptar, consulta la biblioteca de
[Ejemplos de políticas](/build/examples/).