Verwenden von Artefaktnachweisen zur Ermittlung der Herkunft von Builds

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 selbst stellen SLSA v1.0 Build Level 2 bereit.

Dies stellt eine Verknüpfung zwischen Ihrem Artefakt und seinen Buildanweisungen bereit, aber Sie können noch einen Schritt weiter gehen, indem Sie fordern, dass die Builds bekannte, geprüfte Buildanweisungen verwenden. Eine gute Möglichkeit, dies zu erreichen, besteht darin, dass Ihr Build in einem wiederverwendbaren Workflow stattfindet, den viele Repositories in Ihrem Unternehmen gemeinsam nutzen. Wiederverwendbare Workflows können eine Isolation zwischen dem Buildprozess und dem aufrufenden Workflow bereitstellen, um SLSA v1.0 Buildebene 3 zu erfüllen. Weitere Informationen finden Sie unter Verwenden von Artefaktnachweisen und wiederverwendbaren Workflows zum Erreichen von SLSA v1 Build Level 3.

Weitere Informationen zu SLSA-Ebenen finden Sie unter SLSA-Sicherheitsstufen.

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.

Was nachgewiesen werden muss

Das Generieren von Nachweisen allein bietet keinen Sicherheitsvorteil, die Nachweise müssen überprüft werden, damit der Vorteil realisiert werden kann. Im Folgenden finden Sie einige Richtlinien dazu, was signiert werden soll und wie oft:

Folgendes sollte unterzeichnet werden:

Software, die Sie veröffentlichen, von der Sie erwarten, dass die Benutzer sie auf gh attestation verify ... ausführen.
Binärdateien, die Menschen ausführen, Pakete, die Menschen herunterladen, oder Manifeste, die Hashes der detaillierten Inhalte enthalten.

Folgendes sollte nicht unterzeichnet werden:

Häufige Builds, die nur für automatisierte Tests geeignet sind.
Einzelne Dateien wie Quellcode, Dokumentationsdateien oder eingebettete Bilder.

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 findest du unter Überprüfen 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@v2
  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@v2
  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 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 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.

Ü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. Du kannst den folgenden Befehl GitHub CLI verwenden.