Diese Seite wurde von der Cloud Translation API übersetzt.

Build-Herkunft generieren und validieren

Auf dieser Seite wird beschrieben, wie Sie die Build-Herkunft generieren, die Ausgabe ansehen und validieren.

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. Mit diesen Informationen können Sie dafür sorgen, dass die erstellten Artefakte, die Sie verwenden, genau und zuverlässig sind und von vertrauenswürdigen Quellen und Buildern erstellt wurden.

Cloud Build unterstützt die Generation der Build-Herkunft, die der Prüfung der SLSA-Stufe 3 (Supply Chain Levels for Software Artifacts) basierend auf den Spezifikationen für SLSA-Version 0.1 und 1.0 entspricht.

Im Rahmen der Unterstützung der SLSA-Spezifikation Version 1.0 bietet Cloud Build buildType-Details zur Build-Herkunft. Sie können das Schema buildType verwenden, um die für den Build-Prozess verwendete parametrisierte Vorlage zu verstehen, einschließlich der von Cloud Build aufgezeichneten Werte und der Quelle dieser Werte. Weitere Informationen finden Sie unter BuildType v1 in Cloud Build.

Beschränkungen

Cloud Build generiert die Build-Herkunft nur für Artefakte, die in Artifact Registry gespeichert sind.
Wenn Sie sowohl die SLSA-Herkunft 1.0 als auch die v0.1-Herkunft abrufen möchten, müssen Sie Trigger verwenden. Wenn Sie einen Build manuell über die gcloud CLI starten, bietet Cloud Build nur die SLSA-Version 0.1-Herkunft.

Hinweise

Cloud Build, Container Analysis, and Artifact Registry APIs aktivieren.
Aktivieren Sie die APIs
Installieren und konfigurieren Sie das Google Cloud SDK, um die Befehlszeilenbeispiele in dieser Anleitung zu verwenden.

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 gcloud components update aus.
Halten Sie Ihren Quellcode bereit.
Sie müssen ein Repository in Artifact Registry haben.

Build-Herkunft generieren

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

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

Cloud Build kann keine Herkunft generieren, wenn Sie Ihr Image mit einem expliziten docker push-Schritt per Push an Artifact Registry übertragen.

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 für Ihr Repository.
- PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
- REPOSITORY: der Name Ihres Artifact Registry-Repositorys
- IMAGE ist 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 für Ihr Repository.
- PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
- REPOSITORY: der Name Ihres Artifact Registry-Repositorys
- IMAGE ist der Name Ihres Container-Images.
Fügen Sie im Abschnitt options der Build-Konfiguration die Option requestedVerifyOption hinzu und legen Sie den Wert VERIFIED fest.

Diese Einstellung ermöglicht das Generieren der Herkunft und konfiguriert Cloud Build so, dass geprüft wird, ob Herkunftsmetadaten vorhanden sind. Builds werden nur dann als erfolgreich markiert, wenn Herkunft generiert wurde.
YAML
```
options:
  requestedVerifyOption: VERIFIED
```
JSON
```
{
    "options": {
        "requestedVerifyOption": "VERIFIED"
    }
}
```
Starten Sie Ihren Build.

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 Build-Herkunftsmetadaten für Container zugreifen, indem Sie die Seitenleiste Sicherheitsinformationen in der Google Cloud Console verwenden oder die gcloud CLI verwenden.

Console

Die Seitenleiste Sicherheitsinformationen bietet einen allgemeinen Überblick über Sicherheitsinformationen zu Artefakten, die in Artifact Registry gespeichert sind.

So rufen Sie den Bereich Sicherheitsinformationen auf:

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

Zur Seite "Build-Verlauf"
Wählen Sie Ihr Projekt aus und klicken Sie auf Öffnen.
Wählen Sie im Drop-down-Menü Region die Region aus, in der Sie den Build ausgeführt haben.
Suchen Sie in der Tabelle mit den Builds die Zeile mit dem Build, für den Sie Sicherheitsinformationen ansehen möchten.
Klicken Sie in der Spalte Sicherheitsinformationen auf Ansehen.

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

Die Karte Build enthält Details zur Herkunft und einen Link. Sie können das Herkunfts-Snippet aufrufen, indem Sie auf das Linksymbol klicken.

Weitere Informationen zur Seitenleiste und zur Verwendung von Cloud Build zum Schutz Ihrer Softwarelieferkette finden Sie unter Build-Sicherheitsinformationen ansehen.

gcloud-CLI

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

  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 Standort für Ihr Repository.
PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
REPOSITORY: der Name Ihres Artifact Registry-Repositorys.
IMAGE ist der Name Ihres Container-Images.
HASH: Der sha256-Hash-Wert des Images. Sie finden dies 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'

In diesem Beispiel sind einige wichtige Punkte zu beachten:

Quelle: Der Build wurde von einem 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 Basis 16 codiert (hexadezimal codiert). Wenn Sie die SLSA-Herkunft 0.1 verwenden, verwendet die Ausgabe das mit Base64 codierte Feld fileHash.
Signaturen: Wenn Sie die SLSA-Herkunft 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 im Format Pre-Authentication Encoding (PAE), die in Richtlinien für die Binärautorisierung überprüft werden kann. Wir empfehlen, diese Signatur für neue Anwendungsfälle dieser Herkunft zu verwenden. Die zweite Signatur mit dem Schlüsselnamen builtByGCB wird für die Legacy-Nutzung bereitgestellt.
Dienstkonten: Mit den Signaturen, die automatisch in die Cloud Build-Herkunft aufgenommen werden, können Sie den Build-Dienst prüfen, mit dem ein Build ausgeführt wurde. Sie können Cloud Build auch so konfigurieren, dass überprüfbare Metadaten über das Dienstkonto aufgezeichnet werden, das zum Initiieren eines Builds verwendet wurde. Weitere Informationen finden Sie unter Container-Images mit Cosignatur signieren.
Nutzlast: Die auf dieser Seite angezeigte Beispielherkunft wurde zur besseren Lesbarkeit gekürzt. Die tatsächliche Ausgabe ist länger, da die Nutzlast eine base-64-codierte Version aller Herkunftsmetadaten ist.

Herkunft von Artefakten ohne Container ansehen

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

Führen Sie einen Build mit Cloud Build aus, um die Herkunftsmetadaten für Ihre Artefakte zu generieren. Verwenden Sie eine der folgenden Leitfäden:
Notieren Sie sich nach Abschluss des Builds das BuildID.
Führen Sie den folgenden API-Aufruf in Ihrem Terminal aus, wobei PROJECT_ID die ID ist, die Ihrem Google Cloud-Projekt zugeordnet ist:
```
alias gcurl='curl -H"Authorization: Bearer $(gcloud auth print-access-token)"'
    gcurl 'https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences'
```
Suchen Sie in den Vorkommen Ihres Projekts nach BuildID, um die Herkunftsinformationen zu jedem Build-Artefakt zu finden.

Herkunft validieren

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

Die Validierung der Build-Herkunft hilft Ihnen bei Folgendem:

Bestätigen, dass Build-Artefakte aus vertrauenswürdigen Quellen und Buildern generiert werden
stellen Sie sicher, dass die Herkunftsmetadaten, die Ihren Build-Prozess beschreiben, vollständig und authentisch sind.

Weitere Informationen finden Sie unter Safeguard-Builds.

Herkunft mit dem SLSA-Verifizierer validieren

Die SLSA-Prüfung ist ein Open-Source-CLI-Tool zum Validieren der Build-Integrität basierend auf den SLSA-Spezifikationen.

Wenn die Prüfung Probleme findet, gibt sie detaillierte Fehlermeldungen zurück, damit Sie den Build-Prozess aktualisieren und Risiken minimieren können.

So verwenden Sie den SLSA-Verifizierer:

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 Image-ID fest:
```
export IMAGE=LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH
```
Ersetzen Sie die Platzhalterwerte im Befehl durch Folgendes:
- LOCATION: Regionaler oder multiregionaler Speicherort.
- PROJECT_ID: Google Cloud-Projekt-ID.
- REPOSITORY: Name des Repositorys.
- IMAGE: Image-Name.
- HASH: Der sha256-Hash-Wert des Images. Sie finden dies in der Ausgabe Ihres Builds.
Autorisieren Sie die gcloud CLI, damit die SLSA-Prüfung auf Ihre Herkunftsdaten zugreifen kann:
```
gcloud auth configure-docker LOCATION-docker.pkg.dev
```

Rufen Sie die Herkunft für Ihr Image ab und speichern Sie es 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 URI des Quell-Repositorys für Ihr Image, z. B. github.com/my-repo/my-application.
- BUILDER_ID ist 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 in 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 Build-Herkunftsmetadaten manipuliert wurden, können Sie die Herkunft mit den folgenden Schritten 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 die SLSA-Herkunftstypen 0.1 als auch die 1.0-Herkunft werden gespeichert, sofern verfügbar. Wenn Sie nach Version 1.0 filtern möchten, ändern Sie predicateType zu 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 | '.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 zu 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 Herkunftssignatur (.provenance_summary.provenance[0].envelope.signatures[0]), die mit dem Schlüssel provenanceSigner signiert ist. Die Nutzlast ist mit einem Umschlag im PE-Format signiert. Führen Sie zur Prüfung den folgenden Befehl aus, um die Herkunft in das erwartete PAE-Format "DSSEv1" + SP + LEN(type) + SP + type + SP + LEN(body) + SP + body umzuwandeln.

Hinweis: Wenn Sie die zweite Signatur (.provenance_summary.provenance[0].envelope.signatures[1].sig mit Schlüsselname builtByGCB) verifizieren, überspringen Sie diesen Schritt und prüfen Sie die Datei provenance.json, 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.