Referencia de inputs

Tabla de contenidos

Cuando Buildx evalúa las políticas, proporciona información sobre las entradas de compilación a través del objeto input. La estructura de input depende del tipo de recurso al que haga referencia tu Dockerfile.

Tipos de entrada

Las entradas de compilación corresponden a instrucciones de Dockerfile:

Instrucción de Dockerfile	Tipo de entrada	Patrón de acceso
`FROM alpine:latest`	Imagen	`input.image`
`COPY --from=builder /app /app`	Imagen	`input.image`
`ADD https://example.com/file.tar.gz /`	HTTP	`input.http`
`ADD [email protected]:user/repo.git /src`	Git	`input.git`
Contexto de compilación (`.`)	Local	`input.local`

Cada tipo de entrada tiene campos específicos disponibles para la evaluación de la política.

Entradas HTTP

Las entradas HTTP representan archivos descargados a través de HTTP o HTTPS utilizando la instrucción ADD.

Ejemplo de Dockerfile

FROM alpine
ADD --checksum=sha256:abc123... https://example.com/app.tar.gz /app.tar.gz

Campos disponibles

`input.http.url`

La URL completa del recurso.

allow if {
    input.http.url == "https://example.com/app.tar.gz"
}

`input.http.schema`

El esquema de la URL (http o https).

# Requerir HTTPS para todas las descargas
allow if {
    input.http.schema == "https"
}

`input.http.host`

El nombre de host de la URL.

# Permitir descargas desde dominios aprobados
allow if {
    input.http.host == "cdn.example.com"
}

`input.http.path`

El componente de la ruta de la URL.

allow if {
    startswith(input.http.path, "/releases/")
}

`input.http.checksum`

La suma de comprobación (checksum) especificada con ADD --checksum=..., si está presente. Una cadena vacía si no se proporcionó ninguna suma de comprobación.

# Requerir sumas de comprobación para todas las descargas
allow if {
    input.http.checksum != ""
}

`input.http.hasAuth`

Booleano que indica si la solicitud incluye autenticación (autenticación básica HTTP o token de portador / bearer token).

# Requerir autenticación para servidores internos
allow if {
    input.http.host == "internal.company.com"
    input.http.hasAuth
}

Entradas de imagen

Las entradas de imagen representan imágenes de contenedor provenientes de instrucciones FROM o referencias COPY --from.

Ejemplo de Dockerfile

FROM alpine:3.19@sha256:abc123...
COPY --from=builder:latest /app /app

Campos disponibles

`input.image.ref`

La referencia completa de la imagen tal como está escrita en el Dockerfile.

allow if {
    input.image.ref == "alpine:3.19@sha256:abc123..."
}

`input.image.host`

El nombre de host del registro. Las imágenes de Docker Hub usan "docker.io".

# Solo permitir imágenes de Docker Hub
allow if {
    input.image.host == "docker.io"
}

# Solo permitir imágenes de GitHub Container Registry
allow if {
    input.image.host == "ghcr.io"
}

`input.image.repo`

El nombre del repositorio sin el host del registro.

allow if {
    input.image.repo == "library/alpine"
}

`input.image.fullRepo`

La ruta completa del repositorio, incluyendo el host del registro.

allow if {
    input.image.fullRepo == "docker.io/library/alpine"
}

`input.image.tag`

La parte de la etiqueta (tag) de la referencia. Vacío si se usa una referencia por digest.

# Permitir solo etiquetas específicas
allow if {
    input.image.tag == "3.19"
}

`input.image.isCanonical`

Booleano que indica si la referencia utiliza un digest (@sha256:...).

# Requerir referencias por digest
allow if {
    input.image.isCanonical
}

`input.image.checksum`

El digest SHA256 del manifiesto de la imagen.

allow if {
    input.image.checksum == "sha256:abc123..."
}

`input.image.platform`

La plataforma de destino para imágenes multiplataforma.

allow if {
    input.image.platform == "linux/amd64"
}

`input.image.os`

El sistema operativo a partir de la configuración de la imagen.

allow if {
    input.image.os == "linux"
}

`input.image.arch`

La arquitectura de CPU a partir de la configuración de la imagen.

allow if {
    input.image.arch == "amd64"
}

`input.image.hasProvenance`

Booleano que indica si la imagen tiene atestaciones de procedencia.

# Requerir procedencia para imágenes de producción
allow if {
    input.image.hasProvenance
}

`input.image.labels`

Un mapa de etiquetas de imagen provenientes de la configuración de la imagen.

# Verificar etiquetas específicas
allow if {
    input.image.labels["org.opencontainers.image.vendor"] == "Example Corp"
}

`input.image.signatures`

Array de firmas de atestación. Cada firma en el array cuenta con los siguientes campos:

kind: Tipo de firma (ej. "docker-github-builder", "self-signed")
type: Tipo de estructura de la firma (ej. "bundle-v0.3", "simplesigning-v1")
timestamps: Marcas de tiempo de confianza de los registros de transparencia
dockerReference: Referencia de la imagen de Docker
isDHI: Booleano que indica si se trata de una Docker Hardened Image
signer: Detalles del certificado de Sigstore

# Requerir al menos una firma
allow if {
    count(input.image.signatures) > 0
}

Para las firmas de Sigstore, el objeto signer proporciona información detallada del certificado del flujo de firma:

certificateIssuer: Emisor del certificado
subjectAlternativeName: Nombre alternativo del sujeto del certificado (Subject Alternative Name)
buildSignerURI: URI del firmante de la compilación
buildSignerDigest: Digest del firmante de la compilación
runnerEnvironment: Entorno del ejecutor de CI/CD (runner environment)
sourceRepositoryURI: URL del repositorio de origen
sourceRepositoryDigest: Digest del repositorio de origen
sourceRepositoryRef: Referencia del repositorio de origen (rama/etiqueta)
sourceRepositoryIdentifier: Identificador del repositorio de origen
sourceRepositoryOwnerURI: URI del propietario del repositorio
buildConfigURI: URI de la configuración de compilación
buildTrigger: Qué desencadenó la compilación
runInvocationURI: URI de invocación de la ejecución de CI/CD

# Requerir firmas de GitHub Actions
allow if {
    some sig in input.image.signatures
    sig.signer.runnerEnvironment == "github-hosted"
    startswith(sig.signer.sourceRepositoryURI, "https://github.com/myorg/")
}

Entradas de Git

Las entradas de Git representan repositorios de Git referenciados en instrucciones ADD o utilizados como contexto de compilación.

Ejemplo de Dockerfile

ADD [email protected]:moby/buildkit.git#v0.12.0 /src

Campos disponibles

`input.git.schema`

El esquema de la URL (https, http, git o ssh).

# Requerir HTTPS para clonaciones de Git
allow if {
    input.git.schema == "https"
}

`input.git.host`

El servidor host de Git (ej. github.com, gitlab.com).

allow if {
    input.git.host == "github.com"
}

`input.git.remote`

La URL completa de Git.

allow if {
    input.git.remote == "https://github.com/moby/buildkit.git"
}

`input.git.ref`

La referencia de Git.

allow if {
    input.git.ref == "refs/heads/master"
}

`input.git.tagName`

El nombre de la etiqueta si la referencia es una etiqueta (tag).

# Solo permitir etiquetas de versión
allow if {
    regex.match(`^v[0-9]+\.[0-9]+\.[0-9]+$`, input.git.tagName)
}

`input.git.branch`

El nombre de la rama si la referencia es una rama.

allow if {
    input.git.branch == "main"
}

`input.git.subDir`

La ruta del subdirectorio dentro del repositorio, si se especifica.

# Asegurar que las clonaciones se realicen desde la raíz
allow if {
    input.git.subDir == ""
}

`input.git.isCommitRef`

Booleano que indica si la referencia es un SHA de commit (en lugar del nombre de una rama o etiqueta).

# Requerir SHAs de commit para producción
allow if {
    input.env.target == "production"
    input.git.isCommitRef
}

`input.git.checksum`

La suma de comprobación de la referencia de Git. Para referencias de commit y ramas, este es el hash del commit. Para etiquetas anotadas, este es el hash del objeto de la etiqueta.

allow if {
    input.git.checksum == "abc123..."
}

`input.git.commitChecksum`

El hash del commit al que apunta la referencia. Para etiquetas anotadas, difiere de checksum (que es el hash del objeto de la etiqueta). Para referencias de commit y ramas, es el mismo que checksum.

allow if {
    input.git.commitChecksum == "abc123..."
}

`input.git.isAnnotatedTag`

Booleano que indica si la referencia es una etiqueta anotada (en contraposición a una etiqueta ligera).

# Requerir etiquetas anotadas
allow if {
    input.git.tagName != ""
    input.git.isAnnotatedTag
}

`input.git.commit`

Objeto que contiene metadatos del commit:

author: Nombre, correo electrónico y cuándo firmó el autor
committer: Nombre, correo electrónico y cuándo firmó el committer
message: Mensaje de commit
pgpSignature: Detalles de la firma PGP si está firmado
sshSignature: Detalles de la firma SSH si está firmado

# Verificar el correo electrónico del autor del commit
allow if {
    input.git.commit.author.email == "[email protected]"
}

`input.git.tag`

Objeto que contiene metadatos de la etiqueta para etiquetas anotadas:

tagger: Nombre, correo electrónico y cuándo firmó el etiquetador
message: Mensaje de la etiqueta
pgpSignature: Detalles de la firma PGP si está firmada
sshSignature: Detalles de la firma SSH si está firmada

# Requerir etiquetas firmadas
allow if {
    input.git.tag.pgpSignature != null
}

Entradas locales

Las entradas locales representan el directorio del contexto de compilación.

Campos disponibles

`input.local.name`

El nombre o la ruta del contexto local.

allow if {
    input.local.name == "."
}

Las entradas locales suelen estar menos restringidas que las remotas, pero de todos modos puedes escribir políticas para imponer requisitos sobre el contexto.

# Reglas más estrictas para el Dockerfile de producción
allow if {
    input.env.filename == "Dockerfile"
    input.image.isCanonical
}

# Reglas más flexibles para desarrollo
allow if {
    input.env.filename == "Dockerfile.dev"
}

`input.env.target`

El objetivo de compilación (target) en compilaciones multi-stage.

# Requerir firma solo para compilaciones de lanzamiento (release)
allow if {
    input.env.target == "release"
    input.git.tagName != ""
    verify_git_signature(input.git.tag, "maintainer.asc")
}

`input.env.args`

Argumentos de compilación pasados con --build-arg. Accede a argumentos específicos por su clave.

# Verificar los valores de los argumentos de compilación
allow if {
    input.env.args.ENVIRONMENT == "production"
    input.image.hasProvenance
}

Siguientes pasos

Consulta las Funciones integradas para conocer las funciones auxiliares integradas que permiten comprobar y validar propiedades de entrada.
Explora los Ejemplos de políticas para conocer patrones comunes.
Lee acerca de Rego para lógica de políticas avanzada.

¿En qué te puedo ayudar?

Referencia de inputs