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

Las atestaciones de artefactos le permiten aumentar la seguridad de la cadena de suministro de las compilaciones estableciendo públicamente dónde y cómo se compiló el software y asociarlo con una compilación de software firmada de materiales (SBOM).

En este artículo

Note

Las atestaciones de artefactos están en versión beta pública y están sujetas a cambios.

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 el nivel de compilación 2 de SLSA v1.0.

Puede usar atestaciones de artefactos para lograr el nivel de compilación 3 de SLSA v1.0; sin embargo, se recomienda encarecidamente centrarse en la adopción amplia del nivel 2 de compilación en toda la organización. Es mucho mejor alcanzar de forma coherente el nivel 2 en las compilaciones que tener una pequeña parte de compilaciones que alcancen el nivel 3. Para lograr el nivel de compilación 3, se recomienda estandarizar el proceso de compilación con flujos de trabajo reutilizables, auditar los flujos de trabajo reutilizables para asegurarse de que cumplen los requisitos de nivel 3 y, a continuación, actualizar la política de comprobación para requerir esos flujos de trabajo reutilizables auditados.

Para más información, consulte la sección Procedencia de la documentación 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.

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

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

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

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

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

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

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

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

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

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.

Bash
docker login ghcr.io

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

Para obtener más información, consulte la sección attestation en el manual de la GitHub CLI.