attest build provenance

actions/attest-build-provenance

Genere certificaciones de procedencia de compilación firmadas para artefactos de flujo de trabajo. Desarrollado internamente por el paquete @actions/attest.

Las certificaciones vinculan algún sujeto (un artefacto con nombre junto con su resumen) a un predicado de procedencia de compilación SLSA utilizando el formato in-toto.

Se genera una firma verificable para la atestación mediante un certificado de firma de corta duración emitido por Sigstore. Si el repositorio que inicia el flujo de trabajo de GitHub Actions es público, se utilizará la instancia de bien público de Sigstore para generar la firma de certificación. Si el repositorio es privado/interno, utilizará la instancia privada de Sigstore de GitHub.

Una vez que se haya creado y firmado la certificación, se cargará en la API de certificaciones de GH y se asociará con el repositorio desde el que se inició el flujo de trabajo.

Las certificaciones se pueden verificar utilizando el comando attestation en la CLI de GitHub.

Consulte Uso de certificaciones de artefactos para establecer la procedencia de las compilaciones para obtener más información sobre las certificaciones de artefactos.

Uso

Dentro del flujo de trabajo de GitHub Actions que crea algún artefacto que le gustaría certificar:

1. Asegúrese de que estén establecidos los siguientes permisos:

    permissions :
     id-token : write
     attestations : write

   El permiso id-token le da a la acción la capacidad de acuñar el token OIDC necesario para solicitar un certificado de firma de Sigstore. El permiso attestations es necesario para conservar la atestación.

2. Agregue lo siguiente a su flujo de trabajo después de que se haya creado su artefacto:

   - uses : actions/attest-build-provenance@v1
     with :
       subject-path : ' <PATH TO ARTIFACT> '

   El parámetro subject-path debe identificar el artefacto para el cual desea generar una certificación.

Entradas

Ver acción.yml

- uses : actions/attest-build-provenance@v1
  with :
    # Path to the artifact serving as the subject of the attestation. Must
    # specify exactly one of "subject-path" or "subject-digest". May contain a
    # glob pattern or list of paths (total subject count cannot exceed 2500).
    subject-path :

    # SHA256 digest of the subject for the attestation. Must be in the form
    # "sha256:hex_digest" (e.g. "sha256:abc123..."). Must specify exactly one
    # of "subject-path" or "subject-digest".
    subject-digest :

    # Subject name as it should appear in the attestation. Required unless
    # "subject-path" is specified, in which case it will be inferred from the
    # path.
    subject-name :

    # Whether to push the attestation to the image registry. Requires that the
    # "subject-name" parameter specify the fully-qualified image name and that
    # the "subject-digest" parameter be specified. Defaults to false.
    push-to-registry :

    # Whether to attach a list of generated attestations to the workflow run
    # summary page. Defaults to true.
    show-summary :

    # The GitHub token used to make authenticated API requests. Default is
    # ${{ github.token }}
    github-token :

Salidas

Nombre	Descripción	Ejemplo
bundle-path	Ruta absoluta al archivo que contiene la certificación generada.	/tmp/attestation.jsonl

Las certificaciones se guardan en el formato de paquete Sigstore serializado JSON.

Si se certifican varios sujetos al mismo tiempo, cada certificación se escribirá en el archivo de salida en una línea separada (usando el formato de líneas JSON).

Límites de certificación

Límites de materia

No se podrán certificar más de 2500 materias al mismo tiempo. Los sujetos se procesarán en lotes de 50. Después del grupo inicial de 50, cada lote posterior incurrirá en una cantidad de retraso exponencialmente creciente (con un límite de 1 minuto de retraso por lote) para evitar abrumar la API de certificación.

Ejemplos

Identificar sujeto por ruta

Para el caso de uso básico, simplemente agregue la acción attest-build-provenance a su flujo de trabajo y proporcione la ruta al artefacto para el cual desea generar la certificación.

 name : build-attest

on :
  workflow_dispatch :

jobs :
  build :
    permissions :
      id-token : write
      contents : read
      attestations : write

    steps :
      - name : Checkout
        uses : actions/checkout@v4
      - name : Build artifact
        run : make my-app
      - name : Attest
        uses : actions/attest-build-provenance@v1
        with :
          subject-path : ' ${{ github.workspace }}/my-app '

Identificar múltiples sujetos

Si está generando varios artefactos, puede generar una certificación de procedencia para cada uno utilizando un comodín en la entrada de subject-path .

- uses : actions/attest-build-provenance@v1
  with :
    subject-path : ' dist/**/my-bin-* '

Para conocer los comodines admitidos junto con el comportamiento y la documentación, consulte @actions/glob, que se utiliza internamente para buscar archivos.

Alternativamente, puede enumerar explícitamente varios temas con una lista delimitada por comas o por nueva línea:

- uses : actions/attest-build-provenance@v1
  with :
    subject-path : ' dist/foo, dist/bar ' 

- uses : actions/attest-build-provenance@v1
  with :
    subject-path : |
      dist/foo
      dist/bar

Imagen del contenedor

Cuando trabaje con imágenes de contenedor, puede invocar la acción con las entradas de subject-name y subject-digest .

Si desea publicar la certificación en el registro de contenedor con la opción push-to-registry , es importante que el subject-name especifique el nombre completo de la imagen (por ejemplo, "ghcr.io/user/app" o "acme. azurecr.io/user/app"). NO incluya una etiqueta como parte del nombre de la imagen: la imagen específica que se está certificando se identifica en el resumen proporcionado.

Los paquetes de atestación se almacenan en el registro OCI de acuerdo con la Especificación del paquete Cosign.

NOTA : Al enviar a Docker Hub, utilice "index.docker.io" como parte del registro del nombre de la imagen.

 name : build-attested-image

on :
  push :
    branches : [main]

jobs :
  build :
    runs-on : ubuntu-latest
    permissions :
      id-token : write
      packages : write
      contents : read
      attestations : write
    env :
      REGISTRY : ghcr.io
      IMAGE_NAME : ${{ github.repository }}

    steps :
      - name : Checkout
        uses : actions/checkout@v4
      - name : Login to GitHub Container Registry
        uses : docker/login-action@v3
        with :
          registry : ${{ env.REGISTRY }}
          username : ${{ github.actor }}
          password : ${{ secrets.GITHUB_TOKEN }}
      - name : Build and push image
        id : push
        uses : docker/[email protected]
        with :
          context : .
          push : true
          tags : ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
      - name : Attest
        uses : actions/attest-build-provenance@v1
        id : attest
        with :
          subject-name : ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          subject-digest : ${{ steps.push.outputs.digest }}
          push-to-registry : true