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

Acerca de las atestaciones de artefactos

Las atestaciones de artefactos permiten crear garantías de integridad y procedencia no verificables para el software que compile. A su vez, las personas que consumen el software pueden comprobar dónde y cómo se compiló el software.

Al generar atestaciones de artefactos con el software, se crean notificaciones firmadas criptográficamente que establecen la procedencia de la compilación e incluyen la siguiente información:

Vínculo al flujo de trabajo asociado al artefacto.
El repositorio, la organización, el entorno, la confirmación de SHA y el evento desencadenante para el artefacto.
Otra información del token de OIDC que se usa para establecer la procedencia. Para obtener más información, vea «Acerca del fortalecimiento de seguridad con OpenID Connect».

También puede generar atestaciones de artefactos que incluyan una lista de materiales de software asociada (SBOM). Asociar las compilaciones con una lista de las dependencias de código abierto usadas en ellas proporciona transparencia y permite a los consumidores cumplir con los estándares de protección de datos.

Acerca de los niveles de SLSA para atestaciones de artefactos

El marco SLSA es un estándar del sector que se usa para evaluar la seguridad de la cadena de suministro. Se organiza en niveles. Cada nivel representa un mayor grado de seguridad y fiabilidad para una cadena de suministro de software. Las atestaciones de artefactos proporcionan por sí solas el nivel de compilación 2 de SLSA v1.0.

Esto ofrece un vínculo entre el artefacto y sus instrucciones de compilación, pero puede ir un paso más allá y exigir que las compilaciones usen instrucciones de compilación conocidas y examinadas. Una excelente manera de hacerlo es hacer que la compilación tenga lugar en un flujo de trabajo reutilizable que muchos repositorios de toda la organización comparten. Los flujos de trabajo reutilizables pueden proporcionar aislamiento entre el proceso de compilación y el flujo de trabajo de llamada para satisfacer el nivel de compilación 3 de SLSA v1.0. Para más información, consulta Uso de atestaciones de artefactos y flujos de trabajo reutilizables para lograr el nivel de compilación 3 de SLSA v1.

Para obtener más información sobre los niveles de SLSA, consulte Niveles de seguridad de SLSA.

Acerca del uso de Sigstore para atestaciones de artefactos

Para generar atestaciones de artefactos, GitHub usa Sigstore, que es un proyecto de código abierto que ofrece una solución completa para firmar y comprobar artefactos de software mediante atestaciones.

Los repositorios públicos que generan atestaciones de artefactos usan la instancia correcta pública de Sigstore. Una copia del paquete Sigstore generado se almacena con GitHub y también se escribe en un registro de transparencia inmutable que se puede leer públicamente en Internet.

Los repositorios privados que generan atestaciones de artefactos usan la instancia de Sigstore de GitHub. La instancia de Sigstore de GitHub usa el mismo código base que la instancia pública de Sigstore, pero no tiene un registro de transparencia y solo se federa con GitHub Actions.

Qué elementos se atestiguan

La generación de atestaciones por sí sola no proporciona ninguna ventaja de seguridad, las atestaciones deben comprobarse para que las ventajas se materialicen. Estas son algunas instrucciones para saber qué firmar y con qué frecuencia:

Debería firmar:

Software en el que está lanzando con el que espera que las personas ejecuten gh attestation verify ....
Archivos binarios que las personas ejecutarán, paquetes que los usuarios descargarán o manifiestos que incluyen hashes de contenido detallado.

No debería firmar:

Compilaciones frecuentes que son solo para pruebas automatizadas.
Archivos individuales, como código fuente, archivos de documentación o imágenes incrustadas.

Acerca de la comprobación de atestaciones de artefactos

Si consume software que publica atestaciones de artefactos, puede usar GitHub CLI para comprobar esas atestaciones. Dado que las atestaciones proporcionan información sobre dónde y cómo se compiló el software, puede usar esa información para crear y aplicar directivas de seguridad que elevan la seguridad de la cadena de suministro. Para obtener más información, consulte “Comprobación de atestaciones de artefactos con GitHub CLI”.

Warning

Es importante recordar que las atestaciones de artefactos no son una garantía de que un artefacto sea seguro. En su lugar, las atestaciones de artefactos le vinculan al código fuente y las instrucciones de compilación que las generaron. Es su responsabilidad definir los criterios de la directiva, evaluar esa directiva mediante la evaluación del contenido y tomar una decisión de riesgo fundamentada al consumir software.

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.
Incluir un paso en el flujo de trabajo que use la acción attest-build-provenance.

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-build-provenance.

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

En el flujo de trabajo que compila el archivo binario que desea atestiguar, agregue los permisos siguientes.
```
permissions:
  id-token: write
  contents: read
  attestations: write
```
Después del paso en el que se ha compilado el archivo binario, agregue el paso siguiente.
```
- name: Generate artifact attestation
  uses: actions/attest-build-provenance@v1
  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

En el flujo de trabajo que compila la imagen de contenedor que desea atestiguar, agregue los permisos siguientes.
```
permissions:
  id-token: write
  contents: read
  attestations: write
  packages: write
```
Después del paso en el que se ha compilado la imagen, agregue el paso siguiente.
```
- name: Generate artifact attestation
  uses: actions/attest-build-provenance@v1
  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 completo. 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 de ese paso para proporcionar el valor. Para obtener más información sobre el uso de salidas, consulte "Sintaxis del flujo de trabajo para Acciones de GitHub".

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 en GitHub Marketplace.
Incluir un paso en el flujo de trabajo que use la acción attest-sbom.

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 de acciones attest-sbom.

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

En el flujo de trabajo que compila el archivo binario que desea atestiguar, agregue los permisos siguientes.
```
permissions:
  id-token: write
  contents: read
  attestations: write
```
Después del paso en el que se ha compilado el archivo binario, agregue el paso siguiente.
```
- name: Generate SBOM attestation
  uses: actions/attest-sbom@v1
  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

En el flujo de trabajo que compila la imagen de contenedor que desea atestiguar, agregue los permisos siguientes.
```
permissions:
  id-token: write
  contents: read
  attestations: write
  packages: write
```
Después del paso en el que se ha compilado la imagen, agregue el paso siguiente.
```
- name: Generate SBOM attestation
  uses: actions/attest-sbom@v1
  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 completo. 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 de ese paso para proporcionar el valor. Para obtener más información sobre el uso de salidas, consulte "Sintaxis del flujo de trabajo para Acciones de GitHub".

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

Comprobación de atestaciones de artefactos con GitHub CLI

Para comprobar las atestaciones de artefactos para los archivos binarios, use el siguiente comando de la GitHub CLI.

Bash

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

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

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 comando de GitHub CLI.