Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Build-Herkunft generieren und validieren

Auf dieser Seite finden Sie eine Anleitung zum Generieren der Build-Herkunft, zum Ansehen der Ausgabe und zum Validieren der Provenienz.

Die Build-Herkunft ist eine Sammlung überprüfbarer Daten zu einem Build. Herkunftsmetadaten enthalten Details wie die Digests der erstellten Images, die Speicherorte der Eingabequellen, die Build-Argumente und die Build-Dauer. Anhand dieser Informationen können Sie sicherstellen, dass die verwendeten Artefakte korrekt und zuverlässig sind und von vertrauenswürdigen Quellen und Buildern erstellt wurden.

Cloud Build unterstützt die Generierung von Build-Herkunft, die die SLSA-Sicherheitsstufe 3 (Supply-chain Levels for Software Artifacts) gemäß den Spezifikationen für SLSA-Version 0.1 und 1.0 erfüllt.

Im Rahmen der Unterstützung der SLSA v1.0-Spezifikation stellt Cloud Build buildType-Details in der Build-Herkunft bereit. Sie können das buildType-Schema verwenden, um die parametrisierte Vorlage zu verstehen, die für den Build-Prozess verwendet wird, einschließlich der Werte, die von Cloud Build aufgezeichnet werden, und der Quelle dieser Werte. Weitere Informationen finden Sie unter Cloud Build buildType v1.

Beschränkungen

Cloud Build generiert nur Build-Herkunft für Artefakte, die in Artifact Registry gespeichert sind.
Repository-Anhänge, einschließlich der Build-Herkunft, unterliegen nicht den Bereinigungsrichtlinien. Stattdessen werden Anhänge gelöscht, wenn das Bild, an das sie angehängt sind, gelöscht wird. Weitere Informationen finden Sie unter Anhänge mit Bereinigungsrichtlinien verwalten.

Hinweis

Aktivieren Sie die Cloud Build API, die Container Analysis API und die Artifact Registry API, falls sie noch nicht aktiviert sind.
Rollen, die zum Aktivieren von APIs erforderlich sind
Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen
APIs aktivieren
Wenn Sie die Befehlszeilenbeispiele in dieser Anleitung verwenden möchten, installieren und konfigurieren Sie das Google Cloud SDK.

Hinweis: Wenn Sie das Google Cloud SDK bereits installiert haben, prüfen Sie, ob Sie die neueste verfügbare Version haben. Führen Sie dazu den Befehl gcloud components update aus.
Halten Sie Ihren Quellcode bereit.
Sie benötigen ein Repository in Artifact Registry.

Build-Herkunft generieren

In der folgenden Anleitung wird beschrieben, wie Sie die Build-Herkunft für Container-Images generieren, die Sie in Artifact Registry speichern:

Fügen Sie in Ihrer Build-Konfigurationsdatei das Feld images hinzu, um Cloud Build so zu konfigurieren, dass die erstellten Images nach Abschluss des Builds in Artifact Registry gespeichert werden.

Cloud Build kann keine Herkunftsinformationen generieren, wenn Sie Ihr Image mit einem expliziten docker push-Schritt in Artifact Registry hochladen.

Das folgende Snippet zeigt eine Build-Konfiguration, um ein Container-Image zu erstellen und das Image in einem Docker-Repository in Artifact Registry zu speichern:
YAML
steps: - name: 'gcr.io/cloud-builders/docker' args: [ 'build', '-t', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE', '.' ] images: ['LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE']
Wobei:
- LOCATION: der regionale oder multiregionale Standort Ihres Repositorys.
- PROJECT_ID: Projekt-ID in Google Cloud .
- REPOSITORY: der Name Ihres Artifact Registry-Repositorys
- IMAGE: Der Name Ihres Container-Images.
JSON
{ "steps": [ { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE", "." ] } ], "images": [ "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE" ] }
Wobei:
- LOCATION: der regionale oder multiregionale Standort Ihres Repositorys.
- PROJECT_ID: Projekt-ID in Google Cloud .
- REPOSITORY: der Name Ihres Artifact Registry-Repositorys
- IMAGE: Der Name Ihres Container-Images.
Fügen Sie im Abschnitt options Ihrer Build-Konfiguration die Option requestedVerifyOption hinzu und legen Sie den Wert VERIFIED fest.

Mit dieser Einstellung wird die Herkunftserstellung aktiviert und Cloud Build so konfiguriert, dass geprüft wird, ob Herkunftsmetadaten vorhanden sind. Builds werden nur als erfolgreich gekennzeichnet, wenn die Herkunft generiert wird.
YAML
options: requestedVerifyOption: VERIFIED
JSON
{ "options": { "requestedVerifyOption": "VERIFIED" } }
Beginnen Sie mit dem Bau.

Build-Herkunft ansehen

In diesem Abschnitt wird erläutert, wie Sie die von Cloud Build erstellten Metadaten zur Build-Herkunft aufrufen. Sie können diese Informationen zu Prüfzwecken abrufen.

Sie können auf Metadaten zur Build-Herkunft für Container über die Seitenleiste Sicherheitsstatistiken in der Google Cloud -Konsole oder über die gcloud CLI zugreifen.

Console

Die Seitenleiste Sicherheitsinformationen bietet einen allgemeinen Überblick über Sicherheitsinformationen für Artefakte, die in Artifact Registry gespeichert sind.

So rufen Sie das Feld Sicherheitserkenntnisse auf:

Öffnen Sie in der Google Cloud Console die Seite Build-Verlauf:

Zur Seite "Build-Verlauf"
Suchen Sie in der Tabelle mit den Builds die Zeile mit dem Build, für den Sie Sicherheitsinformationen aufrufen möchten.
Klicken Sie in der Spalte Sicherheitsstatistiken auf Anzeigen.

Dadurch wird der Bereich Sicherheitsinformationen für das ausgewählte Artefakt angezeigt.

Auf der Karte Build werden Herkunftsdetails und ein Link angezeigt. Sie können den Herkunftsausschnitt aufrufen, indem Sie auf das Linksymbol klicken.

Weitere Informationen zur Seitenleiste und dazu, wie Sie Cloud Build verwenden können, um Ihre Softwarelieferkette zu schützen, finden Sie unter Sicherheitserkenntnisse für Builds ansehen.

gcloud-CLI

Führen Sie den folgenden Befehl aus, um die Herkunftsmetadaten für Container-Images aufzurufen:

  gcloud artifacts docker images describe \
  LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH \
  --show-provenance --format=FORMAT

Ersetzen Sie Folgendes:

LOCATION: der regionale oder multiregionale Speicherort für Ihr Repository.
PROJECT_ID: Projekt-ID in Google Cloud .
REPOSITORY: der Name Ihres Artifact Registry-Repositorys.
IMAGE: Der Name Ihres Container-Images.
HASH: Der sha256-Hashwert des Bildes. Sie finden ihn in der Ausgabe Ihres Builds.
FORMAT: Eine optionale Einstellung, mit der Sie ein Ausgabeformat angeben können.

Beispielausgabe

Die Build-Herkunft sieht etwa so aus:

      image_summary:
      digest: sha256:7e9b6e7ba2842c91cf49f3e214d04a7a496f8214356f41d81a6e6dcad11f11e3
      fully_qualified_digest: us-central1-docker.pkg.dev/my-project/my-repo/my-image@sha256:7e9b6e7ba2842c91cf49f3e214d04a7a496f8214356f41d81a6e6dcad11f11e3
      registry: us-central1-docker.pkg.dev
      repository: my-repo
      slsa_build_level: 0
    provenance_summary:
      provenance:
      - build:
          inTotoSlsaProvenanceV1:
            _type: https://in-toto.io/Statement/v1
            predicate:
              buildDefinition:
                buildType: https://cloud.google.com/build/gcb-buildtypes/google-worker/v1
                externalParameters:
                  buildConfigSource:
                    path: cloudbuild.yaml
                    ref: refs/heads/main
                    repository: git+https://github.com/my-username/my-git-repo
                  substitutions: {}
                internalParameters:
                  systemSubstitutions:
                    BRANCH_NAME: main
                    BUILD_ID: e73ca1d4-ec4a-4ea6-acdd-ac8bb16dcc79
                    COMMIT_SHA: 525c52c501739e6df0609ed1f944c1bfd83224e7
                    LOCATION: us-west1
                    PROJECT_NUMBER: '265426041527'
                    REF_NAME: main
                    REPO_FULL_NAME: my-username/my-git-repo
                    REPO_NAME: my-git-repo
                    REVISION_ID: 525c52c501739e6df0609ed1f944c1bfd83224e7
                    SHORT_SHA: 525c52c
                    TRIGGER_BUILD_CONFIG_PATH: cloudbuild.yaml
                    TRIGGER_NAME: github-trigger-staging
                  triggerUri: projects/265426041527/locations/us-west1/triggers/a0d239a4-635e-4bd3-982b-d8b72d0b4bab
                resolvedDependencies:
                - digest:
                    gitCommit: 525c52c501739e6df0609ed1f944c1bfd83224e7
                  uri: git+https://github.com/my-username/my-git-repo@refs/heads/main
                - digest:
                    sha256: 154fcd4d2d65c6a35b06b98053a0829c581e223d530be5719326f5d85d680e8d
                  uri: gcr.io/cloud-builders/docker@sha256:154fcd4d2d65c6a35b06b98053a0829c581e223d530be5719326f5d85d680e8d
              runDetails:
                builder:
                  id: https://cloudbuild.googleapis.com/GoogleHostedWorker
                byproducts:
                - {}
                metadata:
                  finishedOn: '2023-08-01T19:57:10.734471Z'
                  invocationId: https://cloudbuild.googleapis.com/v1/projects/my-project/locations/us-west1/builds/e73ca1d4-ec4a-4ea6-acdd-ac8bb16dcc79
                  startedOn: '2023-08-01T19:56:57.451553160Z'
            predicateType: https://slsa.dev/provenance/v1
            subject:
            - digest:
                sha256: 7e9b6e7ba2842c91cf49f3e214d04a7a496f8214356f41d81a6e6dcad11f11e3
              name: https://us-central1-docker.pkg.dev/my-project/my-repo/my-image
            - digest:
                sha256: 7e9b6e7ba2842c91cf49f3e214d04a7a496f8214356f41d81a6e6dcad11f11e3
              name: https://us-central1-docker.pkg.dev/my-project/my-repo/my-image:latest
        createTime: '2023-08-01T19:57:14.810489Z'
        envelope:
          payload:
          eyJfdHlwZSI6Imh0dHBzOi8vaW4tdG90by5pby9TdGF0ZW1lbnQvdMWQ0LWVjNGEtNGVhNi1hY2RkLWFjOGJiMTZkY2M3OSIsICJzdGFydGVkT24iOiIyMDIzLTA4LTAxVDE5OjU2OjU3LjQ1MTU1MzE2MFoiLCAiZmluaXNoZWRPbiI6IjIwMjMtMDgtMDFUMTk6NTc6MTAuNzM0NDcxWiJ9LCAiYnlwcm9kdWN0cyI6W3t9XX19fQ==...
          payloadType: application/vnd.in-toto+json
          signatures:
          - keyid: projects/verified-builder/locations/global/keyRings/attestor/cryptoKeys/google-hosted-worker/cryptoKeyVersions/1
            sig: MEUCIQCss8UlQL2feFePRJuKTE8VA73f85iqj4OJ9SvVPqTNwAIgYyuyuIrl1PxQC5B109thO24Y6NA4bTa0PJY34EHRSVE=
        kind: BUILD
        name: projects/my-project/occurrences/71787589-c6a6-4d6a-a030-9fd041e40468
        noteName: projects/argo-qa/notes/intoto_slsa_v1_e73ca1d4-ec4a-4ea6-acdd-ac8bb16dcc79
        resourceUri: https://us-central1-docker.pkg.dev/my-project/my-repo/my-image@sha256:7e9b6e7ba2842c91cf49f3e214d04a7a496f8214356f41d81a6e6dcad11f11e3
        updateTime: '2023-08-01T19:57:14.810489Z'

Bei diesem Beispiel sind einige Dinge zu beachten:

Quelle: Der Build wurde über ein GitHub-Repository ausgelöst.
Objektreferenz: Die Felder mit den Namen digest und fileHash verweisen auf dasselbe Objekt. Das Feld digest in der Beispielausgabe ist in Base 16 (hexadezimal) codiert. Wenn Sie die Herkunftsinformationen von SLSA 0.1 verwenden, wird in der Ausgabe das Feld fileHash verwendet, das in Base64 codiert ist.
Signaturen: Wenn Sie die Herkunftsinformationen von SLSA Version 0.1 verwenden, enthält Ihre Ausgabe zwei Signaturen im Feld envelope. Die erste Signatur mit dem Schlüsselnamen provenanceSigner verwendet eine DSSE-konforme Signatur, die mit Pre-Authentication Encoding (PAE) formatiert ist und in Binärautorisierung-Richtlinien überprüft werden kann. Wir empfehlen, diese Signatur für neue Verwendungen dieser Herkunft zu verwenden. Die zweite Signatur mit dem Schlüsselnamen builtByGCB wird für die Legacy-Nutzung bereitgestellt.
Dienstkonten: Die Signaturen, die automatisch in die Cloud Build-Herkunft aufgenommen werden, helfen Ihnen, den Build-Dienst zu überprüfen, der einen Build ausgeführt hat. Sie können Cloud Build auch so konfigurieren, dass überprüfbare Metadaten zum Dienstkonto aufgezeichnet werden, mit dem ein Build initiiert wurde. Weitere Informationen finden Sie unter Container-Images mit Cosign signieren.
Nutzlast: Das auf dieser Seite angezeigte Beispiel für die Herkunft ist zur besseren Lesbarkeit gekürzt. Die tatsächliche Ausgabe ist länger, da die Nutzlast eine base64-codierte Version aller Herkunftsmetadaten ist.
Abhängigkeiten: Abhängigkeiten, die Sie in Ihrer Build-Datei angeben, sind in der Herkunft im Feld resolvedDependencies enthalten.

Herkunft für Artefakte ohne Container ansehen

Cloud Build generiert SLSA-Herkunftsmetadaten für eigenständige Go-, Java- (Maven), Python- und Node.js- (npm) Anwendungen, wenn Sie Ihre Build-Artefakte in Artifact Registry hochladen.

Führen Sie einen Build mit Cloud Build aus, um die Herkunftsmetadaten für Ihre Artefakte zu generieren. Verwenden Sie eine der folgenden Anleitungen:
Notieren Sie sich nach Abschluss des Builds die BuildID.

Sie können die Herkunftsmetadaten abrufen, indem Sie einen direkten API-Aufruf ausführen oder das gcloud-CLI verwenden. Wenn Sie die Herkunft für einen bestimmten Build ermitteln möchten, sollten Sie die Ergebnisse nach der Build-ID filtern.

gcloud

gcloud container analysis occurrences list \
  --project="PROJECT_ID" \
  --filter='kind="BUILD" AND build.inTotoSlsaProvenanceV1.predicate.runDetails.metadata.invocationId="https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/builds/BUILD_ID"' \
  --format=json

curl

alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
BUILD_ID="BUILD_ID"

FILTER="kind%3D%22BUILD%22%20AND%20build.inTotoSlsaProvenanceV1.predicate.runDetails.metadata.invocationId%3D%22https%3A%2F%2Fcloudbuild.googleapis.com%2Fv1%2Fprojects%2F${PROJECT_ID}%2Flocations%2F${LOCATION}%2Fbuilds%2F${BUILD_ID}%22"

gcurl "https://containeranalysis.googleapis.com/v1/projects/${PROJECT_ID}/occurrences?filter=${FILTER}"

Ersetzen Sie die Platzhalter in den vorherigen Beispielen:

PROJECT_ID: Ihre Google Cloud Projekt-ID
LOCATION: Die Region, in der der Build ausgeführt wurde, z. B. us-central1.
BUILD_ID: Die ID des Builds, der Sie interessiert.

Dadurch werden die spezifischen Vorkommen des Typs BUILD zurückgegeben, die mit der angegebenen Build-ID übereinstimmen.

Hinweis:Das Filtern nach verschachtelten JSON-Feldern wie invocationId kann langsamer sein als das Filtern nach indexierten Feldern der obersten Ebene, insbesondere in Projekten mit einer sehr großen Anzahl von Vorkommen.

Herkunft validieren

In diesem Abschnitt wird erläutert, wie Sie die Build-Herkunft für Container-Images validieren.

Durch die Validierung der Build-Herkunft können Sie:

Bestätigen, dass Build-Artefakte aus vertrauenswürdigen Quellen und Build-Prozessen generiert werden
Sorgen Sie dafür, dass die Herkunftsmetadaten, die Ihren Build-Prozess beschreiben, vollständig und authentisch sind.

Weitere Informationen finden Sie unter Builds schützen.

Herkunft mit dem SLSA-Prüftool validieren

Das SLSA-Prüftool ist ein Open-Source-Befehlszeilentool zum Prüfen der Build-Integrität auf der Grundlage der SLSA-Spezifikationen.

Wenn der Prüfer Probleme findet, werden detaillierte Fehlermeldungen zurückgegeben, die Ihnen helfen, Ihren Build-Prozess zu aktualisieren und Risiken zu minimieren.

So verwenden Sie den SLSA-Prüfer:

Installieren Sie Version 2.1 oder höher aus dem slsa-verifier-Repository.

go install github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier@VERSION

Legen Sie in der Befehlszeile eine Variable für die Bild-ID fest:
```
export IMAGE=LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH
```
Wobei:
- LOCATION: Regionaler oder multiregionaler Speicherort.
- PROJECT_ID: Google Cloud Projekt-ID.
- REPOSITORY: Name des Repositorys.
- IMAGE: Name des Bildes.
- HASH: Der sha256-Hashwert des Bildes. Sie finden sie in der Ausgabe Ihres Builds.
Autorisieren Sie die gcloud CLI, damit der SLSA-Prüfer auf Ihre Herkunftsdaten zugreifen kann:
```
gcloud auth configure-docker LOCATION-docker.pkg.dev
```

Rufen Sie die Herkunftsinformationen für Ihr Bild ab und speichern Sie sie als JSON:

gcloud artifacts docker images describe $IMAGE --format json --show-provenance > provenance.json

Herkunft prüfen:
```
slsa-verifier verify-image "$IMAGE" \
--provenance-path provenance.json \
--source-uri SOURCE \
--builder-id=BUILDER_ID
```
Wobei:
- SOURCE ist der Quell-Repository-URI für Ihr Image, z. B. github.com/my-repo/my-application.
- BUILDER_ID die eindeutige ID für den Builder, z. B. https://cloudbuild.googleapis.com/GoogleHostedWorker
Wenn Sie die validierte Herkunft zur Verwendung in einer Richtlinien-Engine ausgeben möchten, verwenden Sie den vorherigen Befehl mit dem Flag --print-provenance.

Die Ausgabe sieht etwa so aus: PASSED: Verified SLSA provenance oder FAILED: SLSA verification failed: <error details>.

Weitere Informationen zu optionalen Flags finden Sie unter Optionen.

Herkunftsmetadaten mit der gcloud CLI validieren

Wenn Sie prüfen möchten, ob die Metadaten zur Build-Herkunft manipuliert wurden, können Sie die Herkunft mithilfe der folgenden Schritte validieren:

Erstellen Sie ein neues Verzeichnis und wechseln Sie in dieses Verzeichnis.
```
mkdir provenance && cd provenance
```

Rufen Sie mithilfe der Informationen aus dem Feld keyid den öffentlichen Schlüssel ab.

gcloud kms keys versions get-public-key 1 --location global --keyring attestor \
  --key builtByGCB --project verified-builder --output-file my-key.pub

Die payload enthält die in base64url codierte JSON-Darstellung der Herkunft. Decodieren Sie die Daten und speichern Sie sie in einer Datei.

gcloud artifacts docker images describe \
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH --show-provenance \
  --format=json | jq -r '.provenance_summary.provenance[] | select(.build.intotoStatement.predicateType == "https://slsa.dev/provenance/v0.1") | .envelope.payload' | tr '\-_' '+/' | base64 -d > provenance.json

Sowohl SLSA-Version 0.1 als auch 1.0-Herkunftstypen werden gespeichert, sofern verfügbar. Wenn Sie nach Version 1.0 filtern möchten, ändern Sie predicateType in https://slsa.dev/provenance/v1. Beispiel:

gcloud artifacts docker images describe \
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH --show-provenance \
  --format=json | jq -r '.provenance_summary.provenance[] | select(.build.intotoStatement.predicateType == "https://slsa.dev/provenance/v1") | .envelope.payload' | tr '\-_' '+/' | base64 -d > provenance.json

Der Envelope enthält auch die Signatur über die Herkunft. Decodieren Sie die Daten und speichern Sie sie in einer Datei.

  gcloud artifacts docker images describe LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH --show-provenance \
  --format=json | jq -r '.provenance_summary.provenance[] | select(.build.intotoStatement.predicateType == "https://slsa.dev/provenance/v0.1") | .envelope.signatures[0].sig' | tr '\-_' '+/' | base64 -d > signature.bin

Wenn Sie nach Version 1.0 filtern möchten, ändern Sie predicateType in https://slsa.dev/provenance/v1. Beispiel:

gcloud artifacts docker images describe LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH --show-provenance \
--format=json | jq -r '.provenance_summary.provenance[] | select(.build.intotoStatement.predicateType == "https://slsa.dev/provenance/v1") | .envelope.signatures[0].sig' | tr '\-_' '+/' | base64 -d > signature.bin

Der obige Befehl verweist auf die erste Provenienzsignatur (.provenance_summary.provenance[0].envelope.signatures[0]), die mit dem Schlüssel provenanceSigner signiert ist. Die Nutzlast wird über den PAE-formatierten Envelope signiert. Führen Sie zur Überprüfung den folgenden Befehl aus, um die Herkunft in das erwartete PAE-Format "DSSEv1" + SP + LEN(type) + SP + type + SP + LEN(body) + SP + body zu transformieren.

Hinweis :Wenn Sie die zweite Signatur (.provenance_summary.provenance[0].envelope.signatures[1].sig mit dem Schlüsselnamen builtByGCB) bestätigen, überspringen Sie diesen Schritt und bestätigen Sie die provenance.json-Datei, die Sie bereits gespeichert haben.
```
echo -n "DSSEv1 28 application/vnd.in-toto+json $(cat provenance.json | wc -c) $(cat provenance.json)" > provenance.json
```
Überprüfen Sie die Signatur.
```
openssl dgst -sha256 -verify my-key.pub -signature signature.bin provenance.json
```
Nach einer erfolgreichen Validierung ist die Ausgabe Verified OK.