Verwenden von Artefaktnachweisen zur Ermittlung der Herkunft von Builds

Artefaktnachweise ermöglichen es Ihnen, die Lieferkettensicherheit Ihrer Builds zu erhöhen, indem Sie nachweisen, wo und wie Ihre Software erstellt wurde.

Wer kann dieses Feature verwenden?

Artefaktnachweise sind für Repositorys in allen aktuellen GitHub-Plänen verfügbar. Sie sind nicht für Legacy-Pläne verfügbar, z. B. Bronze, Silber oder Gold. Wenn du über einen GitHub Free-, GitHub Pro- oder GitHub Team-Plan verfügst, sind Artefaktnachweise nur für öffentliche Repositorys verfügbar. Zur Verwendung von Artefaktnachweisen in privaten oder internen Repositorys benötigen Sie einen GitHub Enterprise Cloud-Plan.

In diesem Artikel

Voraussetzungen

Bevor du mit dem Generieren von Artefaktnachweisen beginnst, musst du wissen, worum es sich dabei handelt und wann du sie verwenden solltest. Weitere Informationen findest du unter Artefakt-Bestätigungen.

Generieren von Artefaktbescheinigungen für Ihre Builds

Sie können GitHub Actions verwenden, um Artefaktbescheinigungen zu generieren, die die Build-Herkunft für Artefakte wie Binärdateien und Containerimages festlegen.

Um einen Artefaktnachweis zu generieren, müssen Sie:

  • Sicherstellen, dass Sie über die entsprechenden Berechtigungen verfügen, die in Ihrem Workflow konfiguriert sind.
  • Einen Schritt in Ihren Workflow einfügen, der die attest-Aktion verwendet.

Wenn Sie ihre aktualisierten Workflows ausführen, erstellen sie Ihre Artefakte und generieren einen Artefaktnachweis, der die Build-Herkunft festlegt. Sie können Nachweise auf der Registerkarte Aktionen Ihres Repositorys anzeigen. Weitere Informationen finden Sie im attest Repository.

Erstellung der Build-Herkunft für Binärdateien

  1. Fügen Sie im Workflow, der die Binärdatei erstellt, die Sie bestätigen möchten, die folgenden Berechtigungen hinzu.

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

  2. Fügen Sie nach dem Schritt, in dem die Binärdatei erstellt wurde, den folgenden Schritt hinzu.

    - name: Generate artifact attestation
  uses: actions/attest@v4
  with:
    subject-path: 'PATH/TO/ARTIFACT'

    Der Wert des subject-path-Parameters sollte auf den Pfad zu der zu bescheinigenden Binärdatei gesetzt werden.

Generieren der Build-Herkunft für Containerimages

  1. Fügen Sie im Workflow, der das Containerimage erstellt, das Sie bestätigen möchten, die folgenden Berechtigungen hinzu.

    permissions:
  id-token: write
  contents: read
  attestations: write
  packages: write

  2. Fügen Sie nach dem Schritt, in dem das Image erstellt wurde, den folgenden Schritt hinzu.

    - name: Generate artifact attestation
  uses: actions/attest@v4
  with:
    subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
    subject-digest: 'sha256:fedcba0...'
    push-to-registry: true

    Der Wert des subject-name-Parameters sollte den vollqualifizierten Bildnamen angeben. Zum Beispiel: ghcr.io/user/app oder acme.azurecr.io/user/app. Fügen Sie kein Tag als Teil des Bildnamens ein.

    Der Wert des subject-digest-Parameters sollte auf den SHA256 Digest des Betreffs für den Nachweis in der Form sha256:HEX_DIGEST gesetzt werden. Wenn Ihr Workflow docker/build-push-action verwendet, können Sie die digest Ausgabe aus diesem Schritt verwenden, um den Wert zu liefern. Weitere Informationen zum Verwenden von Ausgaben findest du unter Workflowsyntax für GitHub Actions.

Generieren eines Nachweises für eine Software-Stückliste (SBOM)

Sie können signierte SBOM-Nachweise für Workflowartefakte generieren.

Um eine Bestätigung für ein SBOM zu generieren, müssen Sie:

  • Sicherstellen, dass Sie über die entsprechenden Berechtigungen verfügen, die in Ihrem Workflow konfiguriert sind.
  • Erstellen Sie ein SBOM für Ihr Artefakt. Weitere Informationen finden Sie unter anchore-sbom-action im GitHub Marketplace.
  • Fügen Sie einen Schritt in Ihren Workflow ein, der die attest Aktion mit der sbom-path Eingabe verwendet.

Wenn Sie Ihre aktualisierten Workflows ausführen, werden diese Ihre Artefakte erstellen und einen SBOM-Nachweis erzeugen. Sie können Nachweise auf der Registerkarte Aktionen Ihres Repositorys anzeigen. Weitere Informationen finden Sie im attest Repository.

Generierung eines SBOM-Nachweises für Binärdateien

  1. Fügen Sie im Workflow, der die Binärdatei erstellt, die Sie bestätigen möchten, die folgenden Berechtigungen hinzu.

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

  2. Fügen Sie nach dem Schritt, in dem die Binärdatei erstellt wurde, den folgenden Schritt hinzu.

    - name: Generate SBOM attestation
  uses: actions/attest@v4
  with:
    subject-path: 'PATH/TO/ARTIFACT'
    sbom-path: 'PATH/TO/SBOM'

    Der Wert des subject-path-Parameters sollte auf den Pfad der Binärdatei festgelegt werden, die das SBOM beschreibt. Der Wert des sbom-path-Parameters sollte auf den Pfad der von Ihnen generierten SBOM-Datei festgelegt werden.

Generieren eines SBOM-Nachweises für Containerimages

  1. Fügen Sie im Workflow, der das Containerimage erstellt, das Sie bestätigen möchten, die folgenden Berechtigungen hinzu.

    permissions:
  id-token: write
  contents: read
  attestations: write
  packages: write

  2. Fügen Sie nach dem Schritt, in dem das Image erstellt wurde, den folgenden Schritt hinzu.

    - name: Generate SBOM attestation
  uses: actions/attest@v4
  with:
    subject-name: ${{ env.REGISTRY }}/PATH/TO/IMAGE
    subject-digest: 'sha256:fedcba0...'
    sbom-path: 'sbom.json'
    push-to-registry: true

    Der Wert des subject-name-Parameters sollte den vollqualifizierten Bildnamen angeben. Zum Beispiel: ghcr.io/user/app oder acme.azurecr.io/user/app. Fügen Sie kein Tag als Teil des Bildnamens ein.

    Der Wert des subject-digest-Parameters sollte auf den SHA256 Digest des Betreffs für den Nachweis in der Form sha256:HEX_DIGEST gesetzt werden. Wenn Ihr Workflow docker/build-push-action verwendet, können Sie die digest Ausgabe aus diesem Schritt verwenden, um den Wert zu liefern. Weitere Informationen zum Verwenden von Ausgaben findest du unter Workflowsyntax für GitHub Actions.

    Der Wert des sbom-path-Parameters sollte auf den Pfad zu der JSON-formatierten SBOM-Datei gesetzt werden, die Sie bescheinigen möchten.

Hochladen von Artefakten in die linked artifacts page

Wir empfehlen dir, verifizierte Assets in die linked artifacts page deiner Organisation hochzuladen. Auf dieser Seite werden der Buildverlauf, die Bereitstellungsdatensätze und die Speicherdetails der Artefakte angezeigt. Sie können diese Daten verwenden, um Sicherheitswarnungen zu priorisieren oder anfällige Artefakte schnell mit ihrem eigenen Team, Quellcode und Buildausführung zu verbinden. Weitere Informationen finden Sie unter Informationen zu verknüpften Artefakten.

Die Nachweis erstellt automatisch Speicherdatensätze in der linked artifacts page, wenn beides zutrifft:

  • Die push-to-registry Einstellung ist auf true
  • Der Workflow, der die Aktion enthält, verfügt über die artifact-metadata: write Berechtigung

Einen Beispielworkflow findest du unter ** Speicher- und Bereitstellungsdaten in das linked artifacts page hochladen.

Überprüfung von Artefaktnachweisen mit der GitHub CLI

Du kannst Artefaktenachweise für Binärdateien und Containerimages validieren und SBOM-Nachweise mithilfe der GitHub CLI validieren. Weitere Informationen findest du im attestation-Abschnitt des Handbuchs GitHub CLI.

Hinweis

Bei diesen Befehlen wird davon ausgegangen, dass du dich in einer Onlineumgebung befindest. Wenn du dich in einer offline- oder einer Umgebung mit Air Gap befindest, findest du weitere Informationen unter Überprüfen von Nachweisen offline.

Verifizieren einer Artefaktbestätigung für Binärdateien

Verwenden Sie den folgenden GitHub CLI-Befehl, um Artefaktenachweise für Binärdateien zu überprüfen.

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

Verifizieren einer Artefaktbescheinigung für Container-Abbilder

Um Artefaktenachweise für Containerimages zu überprüfen, müssen Sie den FQDN des Images mit einem vorangestellten oci:// anstelle des Pfads zu einer Binärdatei angeben. Du kannst den folgenden Befehl GitHub CLI verwenden.

Bash
docker login ghcr.io

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

Verifizieren einer Bescheinigung für SBOMs

Um SBOM-Nachweise zu verifizieren, musst du das --predicate-type-Flag angeben, um auf ein nicht standardmäßiges Prädikat zu verweisen. Weitere Informationen findest du unter Vetted predicates im Repository in-toto/attestation.

Beispielsweise unterstützt die attest-Aktion derzeit SPDX- oder CycloneDX-SBOM-Prädikate. Um einen SBOM-Nachweis im SPDX-Format zu verifizieren, kannst du den folgenden GitHub CLI-Befehl verwenden.

Bash
gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY \
  -R ORGANIZATION_NAME/REPOSITORY_NAME \
  --predicate-type https://spdx.dev/Document/v2.3

Wenn du weitere Informationen zum Nachweis benötigst, verweise auf das --format json-Flag. Dies kann insbesondere bei der Überprüfung von SBOM-Nachweisen hilfreich sein.

Bash
gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY \
  -R ORGANIZATION_NAME/REPOSITORY_NAME \
  --predicate-type https://spdx.dev/Document/v2.3 \
  --format json \
  --jq '.[].verificationResult.statement.predicate'

Nächste Schritte

Damit deine Nachweise relevant und verwaltbar sind, solltest du Nachweise löschen, die nicht mehr benötigt werden. Weitere Informationen findest du unter Verwalten des Lebenszyklus von Artefaktnachweisen.

Du kannst außerdem Releasenachweise generieren, damit Benutzende die Integrität und den Ursprung deinen Releases überprüfen können. Weitere Informationen finden Sie unter Unveränderliche Releases.