Verwenden von Artefaktnachweisen zur Ermittlung der Herkunft von Builds

Note

Artefaktenachweise befinden sich in der öffentlichen Betaversion und können geändert werden.

Informationen zu Nachweisartefakten

Mit Artefaktbescheinigungen können Sie fälschungssichere Herkunfts- und Integritätsgarantien für die von Ihnen entwickelte Software erstellen. Personen, die Ihre Software nutzen, können wiederum überprüfen, wo und wie Ihre Software erstellt wurde.

Wenn Sie Artefaktenachweise mit Ihrer Software generieren, erstellen Sie kryptografisch signierte Ansprüche, die die Provenienz Ihres Builds einrichten und die folgenden Informationen enthalten:

Eine Verknüpfung mit dem Workflow, der dem Artefakt zugeordnet ist.
Das Repository, die Organisation, die Umgebung, die SHA-Übertragung und das auslösende Ereignis für das Artefakt.
Andere Informationen aus dem OIDC-Token, die zur Feststellung der Herkunft verwendet werden. Weitere Informationen findest du unter Informationen zur Sicherheitshärtung mit OpenID Connect.

Sie können auch Artefaktnachweise generieren, die eine zugeordnete Software-Stückliste (SBOM) enthalten. Das Zuordnen Ihrer Builds zu einer Liste der darin verwendeten Open Source-Abhängigkeiten bietet Transparenz und ermöglicht es Verbrauchern, Datenschutzstandards einzuhalten.

Informationen zu SLSA-Ebenen für Artefaktnachweise

Das SLSA-Framework ist ein Industriestandard, der zur Bewertung der Lieferkettensicherheit verwendet wird. Es ist in Ebenen organisiert. Jede Ebene stellt einen zunehmenden Grad an Sicherheit und Vertrauenswürdigkeit für eine Software-Lieferkette dar. Artefaktnachweise stellen SLSA v1.0 Build Level 2 bereit.

Sie können Artefaktenachweise verwenden, um SLSA v1.0 Build Level 3 zu erreichen. Es wird jedoch dringend empfohlen, sich zunächst auf die breite Einführung von Build Level 2 in Ihrer Organisation zu konzentrieren. Es ist viel besser, wenn alle Builds durchweg Level 2 erreichen, als wenn nur ein kleiner Teil der Builds Level 3 erreicht. Um Build Level 3 zu erreichen, empfehlen wir, Ihren Buildprozess mit wiederverwendbaren Workflows zu standardisieren, die wiederverwendbaren Workflows zu überwachen, um sicherzustellen, dass sie die Anforderungen von Level 3 erfüllen, und dann Ihre Überprüfungsrichtlinie so aktualisieren, dass diese überwachten wiederverwendbaren Workflows erforderlich sind.

Weitere Informationen finden Sie im Abschnitt Herkunft der SLSA-Dokumentation.

Informationen zur Verwendung von Sigstore für Artefaktnachweise

Um Artefaktenachweise zu generieren, verwendet GitHub Sigstore, ein Open Source-Projekt, das eine umfassende Lösung für die Signierung und Verifizierung von Software-Artefakten über Nachweise bietet.

Öffentliche Repositorys, die Artefaktenachweise generieren, verwenden die Sigstore Public Good Instance. Eine Kopie des generierten Sigstore-Bundles wird mit GitHub gespeichert und auch in ein unveränderliches Transparenzprotokoll geschrieben, das im Internet öffentlich lesbar ist.

Private Repositorys, die Artefaktenachweise generieren, verwenden die Sigstore-Instance von GitHub. Die Sigstore-Instance von GitHub verwendet dieselbe Codebasis wie die Sigstore Public Good Instance, verfügt jedoch nicht über ein Transparenzprotokoll und verwendet nur GitHub Actions.

Informationen zur Überprüfung von Artefaktnachweisen

Wenn Sie Software verwenden, die Artefaktnachweise veröffentlicht, können Sie die GitHub CLI verwenden, um diese Nachweise zu überprüfen. Da die Nachweise Aufschluss darüber geben, wo und wie die Software erstellt wurde, können Sie diese Informationen nutzen, um Sicherheitsrichtlinien zu erstellen und durchzusetzen, die die Sicherheit Ihrer Lieferkette erhöhen. Weitere Informationen finden Sie unter „Überprüfung von Artefaktnachweisen mit der GitHub CLI.“

Warning

Es ist wichtig zu beachten, dass Artefaktnachweise keine Garantie dafür sind, dass ein Artefakt sicher ist. Stattdessen verknüpfen Sie Artefaktenachweise mit dem Quellcode und den Buildanweisungen, die sie erstellt haben. Es liegt an Ihnen, Ihre Richtlinienkriterien festzulegen, diese Richtlinien durch Bewertung des Inhalts zu bewerten und eine fundierte Risikoentscheidung zu treffen, wenn Sie Software nutzen.

Generieren von Artefaktnachweisen 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-build-provenance-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-build-provenance Repository.

Generieren der Build-Herkunft für Binärdateien

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
```
Fügen Sie nach dem Schritt, in dem die Binärdatei erstellt wurde, den folgenden Schritt hinzu.
```
- name: Generate artifact attestation
  uses: actions/attest-build-provenance@v1
  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

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
```
Fügen Sie nach dem Schritt, in dem das Image erstellt wurde, den folgenden Schritt hinzu.
```
- 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
```
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 zur Verwendung von Ausgaben finden Sie 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 einen Nachweis für ein SBOM zu generieren, müssen Sie:

Sicherstellen, dass Sie über die entsprechenden Berechtigungen verfügen, die in Ihrem Workflow konfiguriert sind.
Sie ein SBOM für Ihr Artefakt erstellen. Weitere Informationen finden Sie unter anchore-sbom-action im GitHub Marketplace.
Einen Schritt in Ihren Workflow einfügen, der die attest-sbom-Aktion 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 Repository attest-sbom Aktion.

Generierung eines SBOM-Nachweises für Binärdateien

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
```
Fügen Sie nach dem Schritt, in dem die Binärdatei erstellt wurde, den folgenden Schritt hinzu.
```
- name: Generate SBOM attestation
  uses: actions/attest-sbom@v1
  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

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
```
Fügen Sie nach dem Schritt, in dem das Image erstellt wurde, den folgenden Schritt hinzu.
```
- 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
```
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 zur Verwendung von Ausgaben finden Sie 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.

Überprüfung von Artefaktnachweisen mit der GitHub CLI

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

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

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. Sie können 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

docker login ghcr.io

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

Weitere Informationen finden Sie im attestation-Abschnitt des Handbuchs GitHub CLI.

Verwenden von Artefaktnachweisen zur Ermittlung der Herkunft von Builds

In diesem Artikel