attest build provenance

actions/attest-build-provenance

Générez des attestations de provenance de build signées pour les artefacts de flux de travail. Propulsé en interne par le package @actions/attest.

Les attestations lient un sujet (un artefact nommé avec son résumé) à un prédicat de provenance de construction SLSA en utilisant le format in-toto.

Une signature vérifiable est générée pour l'attestation à l'aide d'un certificat de signature de courte durée émis par Sigstore. Si le référentiel qui lance le workflow GitHub Actions est public, l'instance de bien public de Sigstore sera utilisée pour générer la signature d'attestation. Si le référentiel est privé/interne, il utilisera l'instance Sigstore privée GitHub.

Une fois l'attestation créée et signée, elle sera téléchargée sur l'API des attestations GH et associée au référentiel à partir duquel le flux de travail a été lancé.

Les attestations peuvent être vérifiées à l'aide de la commande attestation dans la CLI GitHub.

Voir Utilisation des attestations d'artefacts pour établir la provenance des builds pour plus d'informations sur les attestations d'artefacts.

Usage

Dans le workflow GitHub Actions qui crée un artefact que vous souhaitez attester :

1. Assurez-vous que les autorisations suivantes sont définies :

    permissions :
     id-token : write
     attestations : write

   L'autorisation id-token donne à l'action la possibilité de créer le jeton OIDC nécessaire pour demander un certificat de signature Sigstore. L'autorisation attestations est nécessaire pour conserver l'attestation.

2. Ajoutez les éléments suivants à votre flux de travail une fois votre artefact créé :

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

   Le paramètre subject-path doit identifier l'artefact pour lequel vous souhaitez générer une attestation.

Entrées

Voir action.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 :

Sorties

Nom	Description	Exemple
bundle-path	Chemin absolu vers le fichier contenant l'attestation générée	/tmp/attestation.jsonl

Les attestations sont enregistrées au format de bundle Sigstore sérialisé JSON.

Si plusieurs sujets sont attestés en même temps, chaque attestation sera écrite dans le fichier de sortie sur une ligne distincte (en utilisant le format JSON Lines).

Limites des attestations

Limites du sujet

Pas plus de 2 500 sujets peuvent être attestés en même temps. Les sujets seront traités par lots de 50. Après le groupe initial de 50, chaque lot suivant subira un délai croissant de façon exponentielle (plafonné à 1 minute de délai par lot) pour éviter de surcharger l'API d'attestation.

Exemples

Identifier le sujet par chemin

Pour le cas d'utilisation de base, ajoutez simplement l'action attest-build-provenance à votre flux de travail et fournissez le chemin d'accès à l'artefact pour lequel vous souhaitez générer une attestation.

 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 '

Identifier plusieurs sujets

Si vous générez plusieurs artefacts, vous pouvez générer une attestation de provenance pour chacun en utilisant un caractère générique dans l'entrée subject-path .

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

Pour les caractères génériques pris en charge ainsi que le comportement et la documentation, voir @actions/glob qui est utilisé en interne pour rechercher des fichiers.

Alternativement, vous pouvez répertorier explicitement plusieurs sujets avec une liste délimitée par des virgules ou des sauts de ligne :

- 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

Image du conteneur

Lorsque vous travaillez avec des images de conteneur, vous pouvez appeler l'action avec les entrées subject-name et subject-digest .

Si vous souhaitez publier l'attestation dans le registre de conteneurs avec l'option push-to-registry , il est important que le subject-name spécifie le nom complet de l'image (par exemple « ghcr.io/user/app » ou « acme. azurecr.io/user/app"). N'incluez PAS de balise dans le nom de l'image : l'image spécifique attestée est identifiée par le résumé fourni.

Les bundles d'attestations sont stockés dans le registre OCI conformément à la spécification Cosign Bundle.

REMARQUE : lors de la transmission vers Docker Hub, veuillez utiliser "index.docker.io" comme partie de registre du nom de l'image.

 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