attest build provenance

actions/attest-build-provenance

Generieren Sie signierte Build-Herkunftsnachweise für Workflow-Artefakte. Intern durch das @actions/attest-Paket unterstützt.

Attestierungen binden ein Subjekt (ein benanntes Artefakt zusammen mit seinem Digest) an ein SLSA-Build-Herkunftsprädikat unter Verwendung des In-toto-Formats.

Für die Beglaubigung wird eine überprüfbare Signatur mithilfe eines kurzlebigen, von Sigstore ausgestellten Signaturzertifikats generiert. Wenn das Repository, das den GitHub Actions-Workflow initiiert, öffentlich ist, wird die Public-Good-Instanz von Sigstore zum Generieren der Attestierungssignatur verwendet. Wenn das Repository privat/intern ist, wird die private Sigstore-Instanz von GitHub verwendet.

Sobald die Bescheinigung erstellt und signiert wurde, wird sie in die GH-Bescheinigungs-API hochgeladen und mit dem Repository verknüpft, von dem aus der Workflow initiiert wurde.

Attestierungen können mit dem attestation -Befehl in der GitHub-CLI überprüft werden.

Weitere Informationen zu Artefaktnachweisen finden Sie unter Verwenden von Artefaktnachweisen zum Ermitteln der Herkunft von Builds.

Verwendung

Innerhalb des GitHub Actions-Workflows, der ein Artefakt erstellt, das Sie bescheinigen möchten:

1. Stellen Sie sicher, dass die folgenden Berechtigungen festgelegt sind:

    permissions :
     id-token : write
     attestations : write

   Die id-token -Berechtigung gibt der Aktion die Möglichkeit, das OIDC-Token zu prägen, das zum Anfordern eines Sigstore-Signaturzertifikats erforderlich ist. Die attestations ist erforderlich, um die Bescheinigung beizubehalten.

2. Fügen Sie Ihrem Workflow Folgendes hinzu, nachdem Ihr Artefakt erstellt wurde:

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

   Der Parameter subject-path sollte das Artefakt identifizieren, für das Sie eine Bescheinigung generieren möchten.

Eingaben

Siehe 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 :

Ausgänge

Name	Beschreibung	Beispiel
bundle-path	Absoluter Pfad zur Datei, die die generierte Bescheinigung enthält	/tmp/attestation.jsonl

Attestierungen werden im JSON-serialisierten Sigstore-Bundle-Format gespeichert.

Wenn mehrere Subjekte gleichzeitig attestiert werden, wird jede Attestierung in einer separaten Zeile in die Ausgabedatei geschrieben (unter Verwendung des JSON-Zeilenformats).

Bescheinigungsgrenzen

Betreffbeschränkungen

Es können nicht mehr als 2500 Fächer gleichzeitig bescheinigt werden. Die Probanden werden in Stapeln von 50 verarbeitet. Nach der anfänglichen Gruppe von 50 kommt es bei jedem weiteren Stapel zu einer exponentiell zunehmenden Verzögerung (maximal 1 Minute Verzögerung pro Stapel), um eine Überlastung der Bescheinigungs-API zu vermeiden.

Beispiele

Betreff anhand des Pfads identifizieren

Für den grundlegenden Anwendungsfall fügen Sie einfach die Aktion attest-build-provenance zu Ihrem Workflow hinzu und geben den Pfad zu dem Artefakt an, für das Sie eine Bescheinigung generieren möchten.

 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 '

Identifizieren Sie mehrere Themen

Wenn Sie mehrere Artefakte generieren, können Sie für jedes eine Herkunftsbescheinigung generieren, indem Sie in der Eingabe „ subject-path einen Platzhalter verwenden.

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

Informationen zu unterstützten Platzhaltern sowie zum Verhalten und zur Dokumentation finden Sie unter @actions/glob, das intern zum Suchen nach Dateien verwendet wird.

Alternativ können Sie mehrere Themen explizit mit einer durch Kommas oder Zeilenumbrüche getrennten Liste auflisten:

- 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

Containerbild

Wenn Sie mit Containerbildern arbeiten, können Sie die Aktion mit den Eingaben subject-name und subject-digest aufrufen.

Wenn Sie die Bescheinigung mit der push-to-registry Option in der Container-Registrierung veröffentlichen möchten, ist es wichtig, dass der subject-name den vollständig qualifizierten Bildnamen angibt (z. B. „ghcr.io/user/app“ oder „acme. azurecr.io/user/app"). Fügen Sie KEIN Tag als Teil des Bildnamens ein – das bestimmte Bild, das attestiert wird, wird durch den bereitgestellten Digest identifiziert.

Attestierungspakete werden gemäß der Cosign-Bundle-Spezifikation in der OCI-Registrierung gespeichert.

HINWEIS : Verwenden Sie beim Pushen zum Docker Hub bitte „index.docker.io“ als Registrierungsteil des Image-Namens.

 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