# Referencia de inputs


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 git@github.com: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

```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.

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

#### `input.http.schema`

El esquema de la URL (`http` o `https`).

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

#### `input.http.host`

El nombre de host de la URL.

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

#### `input.http.path`

El componente de la ruta de la URL.

```rego
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.

```rego
# 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).

```rego
# 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

```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.

```rego
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"`.

```rego
# 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.

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

#### `input.image.fullRepo`

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

```rego
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.

```rego
# 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:...`).

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

#### `input.image.checksum`

El digest SHA256 del manifiesto de la imagen.

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

#### `input.image.platform`

La plataforma de destino para imágenes multiplataforma.

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

#### `input.image.os`

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

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

#### `input.image.arch`

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

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

#### `input.image.hasProvenance`

Booleano que indica si la imagen tiene atestaciones de procedencia.

```rego
# 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.

```rego
# 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

```rego
# 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

```rego
# 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

```dockerfile
ADD git@github.com:moby/buildkit.git#v0.12.0 /src
```

### Campos disponibles

#### `input.git.schema`

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

```rego
# 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`).

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

#### `input.git.remote`

La URL completa de Git.

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

#### `input.git.ref`

La referencia de Git.

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

#### `input.git.tagName`

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

```rego
# 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.

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

#### `input.git.subDir`

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

```rego
# 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).

```rego
# 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.

```rego
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`.

```rego
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).

```rego
# 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

```rego
# Verificar el correo electrónico del autor del commit
allow if {
    input.git.commit.author.email == "maintainer@example.com"
}
```

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

```rego
# 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.

```rego
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.

## Campos de entorno

El objeto `input.env` proporciona información de la configuración de
compilación establecida por el usuario al invocar la compilación, y no es
específica de un tipo de recurso.

### Campos disponibles

#### `input.env.filename`

El nombre del Dockerfile que se está compilando.

```rego
# 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.

```rego
# 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.

```rego
# 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](/build/policies/built-ins/) para conocer las funciones
  auxiliares integradas que permiten comprobar y validar propiedades de entrada.
- Explora los [Ejemplos de políticas](/build/policies/examples/) para conocer patrones comunes.
- Lee acerca de [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/)
  para lógica de políticas avanzada.