Herkunft des Builds generieren und validieren

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

Die Build-Herkunft ist eine Sammlung überprüfbarer Daten zu einem Build. Herkunftsmetadaten enthalten Details wie die Digests der erstellten Images, die Quell-Speicherorte, die Build-Argumente und die Build-Dauer. Mithilfe 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 der SLSA-Sicherheitsstufe 3 (Supply-chain Levels for Software Artifacts) entspricht, basierend auf den Spezifikationen für SLSA-Version 0.1 und 1.0.

Im Rahmen der Unterstützung für die 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-Provenienz für Artefakte, die in Artifact Registry gespeichert sind.
• Wenn Sie sowohl SLSA v1.0- als auch v0.1-Herkunft erhalten möchten, müssen Sie mit Triggern erstellen. Wenn Sie einen Build manuell mit der gcloud CLI starten, stellt Cloud Build nur SLSA v0.1-Herkunft bereit.
• Anhänge für Docker-Repositories, einschließlich der Build-Herkunft, unterliegen nicht den Bereinigungsrichtlinien. Stattdessen werden Anhänge gelöscht, wenn das Bild gelöscht wird, an das sie angehängt sind. Weitere Informationen finden Sie unter Anhänge mit Bereinigungsrichtlinien verwalten.

Hinweise

1. Enable the Cloud Build, Container Analysis, and Artifact Registry APIs.

   Enable the APIs

2. Wenn Sie die Befehlszeilenbeispiele in dieser Anleitung verwenden möchten, installieren und konfigurieren Sie das Google Cloud SDK.

3. Halten Sie Ihren Quellcode bereit.

4. 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:

1. 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 übertragen.

   Das folgende Snippet zeigt eine Build-Konfiguration zum Erstellen eines Container-Images und zum Speichern des Images in einem Docker-Repository in Artifact Registry:

   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 Speicherort für Ihr Repository.
   • PROJECT_ID: 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 Speicherort für Ihr Repository.
   • PROJECT_ID: Ihre Google Cloud -Projekt-ID.
   • REPOSITORY: der Name Ihres Artifact Registry-Repositorys
   • IMAGE ist der Name Ihres Container-Images.

2. 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 Generierung der Herkunft aktiviert und Cloud Build so konfiguriert, dass überprüft wird, ob Herkunftsmetadaten vorhanden sind. Builds werden nur dann als erfolgreich markiert, wenn die Herkunft generiert wird.

   YAML

   options:
     requestedVerifyOption: VERIFIED
   

   JSON

   {
       "options": {
           "requestedVerifyOption": "VERIFIED"
       }
   }
   

3. Starten Sie den 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üfungszwecken 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.

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

Beispielausgabe

Die Build-Herkunft sieht in 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 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) codiert. Wenn Sie die Herkunftsinformationen von SLSA Version 0.1 verwenden, wird für Ihre 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 (formatiert mit Pre-Authentication Encoding (PAE)), die in Binary Authorization-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 alte Verwendung 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: Von Ihnen in der Build-Datei angegebene Abhängigkeiten sind in der Herkunft im Feld resolvedDependencies enthalten.

Herkunft von Artefakten 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. Sie können die Herkunftsmetadaten durch einen direkten API-Aufruf abrufen.

1. Wenn Sie die Herkunftsmetadaten für Ihre Artefakte generieren möchten, führen Sie einen Build mit Cloud Build aus. Verwenden Sie einen der folgenden Leitfäden:

   • Eigenständige Go-Anwendungen erstellen
   • Eigenständige Java-Anwendungen erstellen
   • Eigenständige Python-Anwendungen erstellen
   • Eigenständige Node.js-Anwendungen erstellen

   Notieren Sie sich nach Abschluss des Builds die BuildID.

2. Rufen Sie die Herkunftsmetadaten ab, indem Sie den folgenden API-Aufruf in Ihrem Terminal ausführen. Dabei ist PROJECT_ID die ID, 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'
   

   Sie müssen einen API-Aufruf verwenden, um auf die Herkunftsmetadaten für diesen Artefakttyp zuzugreifen. Herkunftsmetadaten für Nicht-Container-Artefakte werden nicht in der Google Cloud -Konsole angezeigt und sind nicht über die gcloud CLI zugänglich.

3. Suchen Sie in den Vorkommen für Ihr Projekt nach BuildID, um die Herkunftsinformationen zu einem Build-Artefakt zu finden.

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 Buildern 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 Validieren der Build-Integrität basierend auf den SLSA-Spezifikationen.

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

So verwenden Sie das SLSA-Prüftool:

1. 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
   

2. 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-Hash-Wert des Images. Sie finden dies in der Ausgabe Ihres Builds.

3. Autorisieren Sie die gcloud CLI, damit der SLSA-Prüfer auf Ihre Herkunftsdaten zugreifen kann:

   gcloud auth configure-docker LOCATION-docker.pkg.dev
   

4. Rufen Sie die Herkunft für Ihr Bild ab und speichern Sie sie als JSON:

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

5. 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:

1. Erstellen Sie ein neues Verzeichnis und wechseln Sie in dieses Verzeichnis.

   mkdir provenance && cd provenance
   

2. 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
   

3. 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
   

4. 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
   

5. Der Befehl oben verweist auf die erste Herkunftssignatur (.provenance_summary.provenance[0].envelope.signatures[0]), die mit dem provenanceSigner-Schlüssel signiert ist. Die Nutzlast wird über den im PAE-Format formatierten Envelope signiert. Um dies zu überprüfen, führen Sie 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.

   echo -n "DSSEv1 28 application/vnd.in-toto+json $(cat provenance.json | wc -c) $(cat provenance.json)" > provenance.json
   

6. Ü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.

Nächste Schritte

• Cloud Build so konfigurieren, dass nachverfolgt wird, wer einen Build initiiert
• Scannen auf Sicherheitslücken in Ihrer Cloud Build-Pipeline verwenden
• Weitere Informationen zur Sicherheit der Softwarelieferkette