# Uso de atestaciones de artefactos para establecer la procedencia de las compilaciones

Las atestaciones de artefactos te permiten aumentar la seguridad de la cadena de suministro de las compilaciones estableciendo dónde y cómo se compiló el software.

## Requisitos previos

Antes de empezar a generar atestaciones de artefactos, debes comprender qué son y cuándo debes usarlas. Consulta [Atestaciones de artefactos](/es/actions/concepts/security/artifact-attestations).

## Generación de atestaciones de artefactos para las compilaciones

Puede usar GitHub Actions para generar atestaciones de artefactos que establecen la procedencia de compilación para artefactos como archivos binarios e imágenes de contenedor.

Para generar una atestación de artefacto, debe:

* Asegurarse de que tiene los permisos adecuados configurados en el flujo de trabajo.
* Incluye un paso en tu flujo de trabajo que utilice la acción [`attest`](https://github.com/actions/attest).

Al ejecutar los flujos de trabajo actualizados, compilarán los artefactos y generarán una atestación de artefactos que establezca la procedencia de la compilación. Puede ver las atestaciones en la pestaña\*\* Acciones \*\*del repositorio. Para obtener más información, consulte el repositorio [`attest`](https://github.com/actions/attest).

### Generación de la procedencia de compilación para archivos binarios

1. En el flujo de trabajo que compila el archivo binario que desea atestiguar, agregue los permisos siguientes.

   ```yaml
   permissions:
     id-token: write
     contents: read
     attestations: write
   ```

2. Después del paso en el que se ha compilado el archivo binario, agregue el paso siguiente.

   ```yaml
   - name: Generate artifact attestation
     uses: actions/attest@v4
     with:
       subject-path: 'PATH/TO/ARTIFACT'
   ```

   El valor del parámetro `subject-path` debe establecerse en la ruta de acceso al archivo binario que desea atestiguar.

### Generación de la procedencia de compilación para imágenes de contenedor

1. En el flujo de trabajo que compila la imagen de contenedor que desea atestiguar, agregue los permisos siguientes.

   ```yaml
   permissions:
     id-token: write
     contents: read
     attestations: write
     packages: write
   ```

2. Después del paso en el que se ha compilado la imagen, agregue el paso siguiente.

   ```yaml
   - name: Generate artifact attestation
     uses: actions/attest@v4
     with:
       subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
       subject-digest: 'sha256:fedcba0...'
       push-to-registry: true
   ```

   El valor del parámetro `subject-name` debe especificar el nombre de imagen totalmente calificado. Por ejemplo, `ghcr.io/user/app` o `acme.azurecr.io/user/app`. No incluya una etiqueta como parte del nombre de la imagen.

   El valor del parámetro `subject-digest` debe establecerse en el resumen SHA256 del asunto para la atestación, con el formato `sha256:HEX_DIGEST`. Si el flujo de trabajo usa `docker/build-push-action`, puede usar la salida [`digest`](https://github.com/docker/build-push-action?tab=readme-ov-file#outputs) de ese paso para proporcionar el valor. Para obtener más información sobre el uso de salidas, consulta [Sintaxis del flujo de trabajo para Acciones de GitHub](/es/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idoutputs).

## Generación de una atestación para una lista de materiales de software (SBOM)

Puede generar atestaciones SBOM firmadas para artefactos de flujo de trabajo.

Para generar una atestación para un SBOM, debe:

* Asegurarse de que tiene los permisos adecuados configurados en el flujo de trabajo.
* Crear un SBOM para el artefacto. Para obtener más información, consulte [`anchore-sbom-action`](https://github.com/marketplace/actions/anchore-sbom-action) en el GitHub Marketplace.
* Incluya un paso en su flujo de trabajo que utilice la acción [`attest`](https://github.com/actions/attest) con la entrada `sbom-path`.

Al ejecutar los flujos de trabajo actualizados, compilarán los artefactos y generarán una atestación SBOM. Puede ver las atestaciones en la pestaña\*\* Acciones \*\*del repositorio. Para obtener más información, consulte el repositorio [`attest`](https://github.com/actions/attest).

### Generación de una atestación SBOM para archivos binarios

1. En el flujo de trabajo que compila el archivo binario que desea atestiguar, agregue los permisos siguientes.

   ```yaml
   permissions:
     id-token: write
     contents: read
     attestations: write
   ```

2. Después del paso en el que se ha compilado el archivo binario, agregue el paso siguiente.

   ```yaml
   - name: Generate SBOM attestation
     uses: actions/attest@v4
     with:
       subject-path: 'PATH/TO/ARTIFACT'
       sbom-path: 'PATH/TO/SBOM'
   ```

   El valor del parámetro `subject-path` debe establecerse en la ruta de acceso del archivo binario que describe SBOM. El valor del parámetro `sbom-path` debe establecerse en la ruta de acceso del archivo SBOM que generó.

### Generación de una atestación SBOM para imágenes de contenedor

1. En el flujo de trabajo que compila la imagen de contenedor que desea atestiguar, agregue los permisos siguientes.

   ```yaml
   permissions:
     id-token: write
     contents: read
     attestations: write
     packages: write
   ```

2. Después del paso en el que se ha compilado la imagen, agregue el paso siguiente.

   ```yaml
   - name: Generate SBOM attestation
     uses: actions/attest@v4
     with:
       subject-name: ${{ env.REGISTRY }}/PATH/TO/IMAGE
       subject-digest: 'sha256:fedcba0...'
       sbom-path: 'sbom.json'
       push-to-registry: true
   ```

   El valor del parámetro `subject-name` debe especificar el nombre de imagen totalmente calificado. Por ejemplo, `ghcr.io/user/app` o `acme.azurecr.io/user/app`. No incluya una etiqueta como parte del nombre de la imagen.

   El valor del parámetro `subject-digest` debe establecerse en el resumen SHA256 del asunto para la atestación, con el formato `sha256:HEX_DIGEST`. Si el flujo de trabajo usa `docker/build-push-action`, puede usar la salida [`digest`](https://github.com/docker/build-push-action?tab=readme-ov-file#outputs) de ese paso para proporcionar el valor. Para obtener más información sobre el uso de salidas, consulta [Sintaxis del flujo de trabajo para Acciones de GitHub](/es/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idoutputs).

   El valor del parámetro `sbom-path` debe establecerse en la ruta de acceso al archivo SBOM con formato JSON que desea atestiguar.

## Carga de artefactos en linked artifacts page

Recomendamos subir los activos verificados al linked artifacts page
de su organización. En esta página se muestran los detalles del historial de compilación, los registros de implementación y el almacenamiento de los artefactos. Puede usar estos datos para priorizar las alertas de seguridad o conectar rápidamente artefactos vulnerables a su equipo responsable, código fuente y proceso de compilación. Para más información, consulta [Acerca de los artefactos vinculados](/es/code-security/concepts/supply-chain-security/linked-artifacts).

La acción [attest](https://github.com/actions/attest) crea automáticamente registros de almacenamiento en el linked artifacts page si ambos:

* La `push-to-registry` opción se establece en `true`
* El flujo de trabajo que incluye la acción tiene el `artifact-metadata: write` permiso.

Para obtener un flujo de trabajo de ejemplo, consulta [Carga de datos de almacenamiento e implementación en linked artifacts page](/es/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/upload-linked-artifacts#generating-an-attestation).

## Verificación de atestaciones de artefactos con GitHub CLI

Puede validar las atestaciones de artefactos para archivos binarios e imágenes de contenedor, y validar las atestaciones de SBOM mediante GitHub CLI. Para obtener más información, consulte la [`attestation`](https://cli.github.com/manual/gh_attestation) sección del GitHub CLI manual.

> \[!NOTE] Estos comandos asumen que se encuentra en un entorno en línea. Si está en un entorno sin conexión o aislado, consulta [Comprobación de atestaciones sin conexión](/es/actions/how-tos/secure-your-work/use-artifact-attestations/verify-attestations-offline).

### Comprobación de una atestación de artefactos para archivos binarios

Para verificar las atestaciones de artefactos para **binarios**, use el siguiente comando GitHub CLI.

```bash copy
gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY -R ORGANIZATION_NAME/REPOSITORY_NAME
```

### Comprobación de una atestación de artefactos para imágenes de contenedor

Para comprobar las atestaciones de artefactos para las **imágenes de contenedor**, debe proporcionar el FQDN de la imagen `oci://` con prefijo en lugar de la ruta de acceso a un archivo binario. Puede usar el siguiente GitHub CLI comando.

```bash copy
docker login ghcr.io

gh attestation verify oci://ghcr.io/ORGANIZATION_NAME/IMAGE_NAME:test -R ORGANIZATION_NAME/REPOSITORY_NAME
```

### Comprobación de una atestación para SBOM

Para comprobar las atestaciones de SBOM, debes proporcionar la marca `--predicate-type` para hacer referencia a un predicado no predeterminado. Para obtener más información, consulta [Predicados verificados](https://github.com/in-toto/attestation/tree/main/spec/predicates#vetted-predicates) en el repositorio `in-toto/attestation`.

Por ejemplo, la [acción `attest`](https://github.com/actions/attest) admite actualmente predicados SBOM de SPDX o CycloneDX. Para comprobar una atestación SBOM en el formato SPDX, puede usar el siguiente GitHub CLI comando.

```bash copy
gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY \
  -R ORGANIZATION_NAME/REPOSITORY_NAME \
  --predicate-type https://spdx.dev/Document/v2.3
```

Para ver más información sobre la atestación, haz referencia a la marca `--format json`. Esto puede ser especialmente útil al revisar las atestaciones SBOM.

```bash copy
gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY \
  -R ORGANIZATION_NAME/REPOSITORY_NAME \
  --predicate-type https://spdx.dev/Document/v2.3 \
  --format json \
  --jq '.[].verificationResult.statement.predicate'
```

## Pasos siguientes

Para que las atestaciones sean relevantes y administrables, debes eliminar las que ya no sean necesarias. Consulta [Administración del ciclo de vida de las atestaciones de artefactos](/es/actions/how-tos/secure-your-work/use-artifact-attestations/manage-attestations).

También puedes generar atestaciones de versión para ayudar a los consumidores a comprobar la integridad y el origen de las versiones. Para más información, consulta [Versiones inmutables](/es/code-security/concepts/supply-chain-security/immutable-releases).