Herkunft des Builds generieren und validieren

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

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. Anhand dieser Informationen können Sie prüfen, ob die von Ihnen verwendeten erstellten Artefakte korrekt und zuverlässig sind und von vertrauenswürdigen Quellen und Entwicklern erstellt wurden.

Cloud Build unterstützt die Erstellung einer Build-Herkunft, die die Anforderungen der Lieferkettenebenen für Software-Artefakte (SLSA) der Stufe 3 erfüllt. Dabei werden die Spezifikationen für die SLSA-Versionen 0.1 und 1.0 zugrunde gelegt.

Im Rahmen der Unterstützung der SLSA v1.0-Spezifikation enthält Cloud Build buildType-Details in der Build-Herkunft. Anhand des buildType-Schemas können Sie die für den Build-Prozess verwendete parametrisierte Vorlage nachvollziehen, einschließlich der von Cloud Build aufgezeichneten Werte und der Quelle dieser Werte. Weitere Informationen finden Sie unter Cloud Build-buildType v1.

Beschränkungen

  • Cloud Build generiert nur Build-Herkunftsinformationen für Artefakte, die in der Artifact Registry gespeichert sind.
  • Wenn Sie sowohl die Herkunft von SLSA v1.0 als auch von v0.1 erhalten möchten, müssen Sie mit Triggern erstellen. Wenn Sie einen Build manuell mit der gcloud CLI starten, stellt Cloud Build nur die Herkunftsinformationen von SLSA v0.1 bereit.

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, müssen Sie das Google Cloud SDK installieren und konfigurieren.

  3. Halten Sie Ihren Quellcode bereit.

  4. Sie haben 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 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 Provenienz generieren, wenn Sie Ihr Image mit einem expliziten docker push-Schritt in die Artifact Registry übertragen.

    Das folgende Snippet zeigt eine Build-Konfiguration, um ein Container-Image zu erstellen und 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 Speicherort für Ihr Repository.
    • PROJECT_ID: die Projekt-ID Ihres Google Cloud -Projekts.
    • 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: die Projekt-ID Ihres Google Cloud -Projekts.
    • REPOSITORY: der Name Ihres Artifact Registry-Repositorys
    • IMAGE ist der Name Ihres Container-Images.

  2. Fügen Sie in der Build-Konfiguration im Abschnitt options die Option requestedVerifyOption hinzu und setzen Sie den Wert auf VERIFIED.

    Mit dieser Einstellung wird die Herkunftsgenerierung aktiviert und Cloud Build so konfiguriert, dass geprüft wird, ob Herkunftsmetadaten vorhanden sind. Builds werden nur dann als erfolgreich gekennzeichnet, wenn eine Provenienz 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 über die Seitenleiste Sicherheitsinformationen in der Google Cloud -Konsole oder über die gcloud CLI auf Metadaten zur Buildherkunft für Container zugreifen.

Console

Im Seitenbereich Sicherheitsinformationen finden Sie einen allgemeinen Überblick über die Sicherheitsinformationen für in Artifact Registry gespeicherte Artefakte.

So rufen Sie den Bereich Sicherheitsinformationen auf:

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

    Zur Seite "Build-Verlauf"

  2. Wählen Sie Ihr Projekt aus und klicken Sie auf Öffnen.

  3. Wählen Sie im Drop-down-Menü Region die Region aus, in der Sie Ihren Build ausgeführt haben.

  4. Suchen Sie in der Tabelle mit den Builds die Zeile mit dem Build, für den Sie Sicherheitsinformationen aufrufen möchten.

  5. Klicken Sie in der Spalte Sicherheitsstatistiken auf Anzeigen.

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

    Auf der Karte Build werden Herkunftsdetails und ein Link angezeigt. Sie können sich das Herkunfts-Snippet ansehen, indem Sie auf das Linksymbol klicken.

Weitere Informationen zum Seitenbereich und dazu, wie Sie Cloud Build zum Schutz Ihrer Softwarelieferkette verwenden können, finden Sie unter Sicherheitserkenntnisse zu Builds ansehen.

gcloud-CLI

Führen Sie den folgenden Befehl aus, um 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: die Projekt-ID Ihres Google Cloud -Projekts.
  • 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: Optionale Einstellung, mit der Sie ein Ausgabeformat angeben können.

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 gibt es 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 Basis 16 (Hexadezimal) codiert. Wenn Sie die SLSA-Version 0.1 für die Provenienz verwenden, wird in der Ausgabe das Base64-codierte Feld fileHash verwendet.

  • Signaturen: Wenn Sie die Herkunftsnachweise der 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 Richtlinien für die Binäre Autorisierung überprüft werden kann. Wir empfehlen, diese Signatur bei neuen Verwendungen dieser Herkunft zu verwenden. Die zweite Signatur mit dem Schlüsselnamen builtByGCB ist für die bisherige Verwendung vorgesehen.

  • Dienstkonten: Die Signaturen, die automatisch in der Cloud Build-Herkunft enthalten sind, 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 erfasst werden, mit dem ein Build initiiert wurde. Weitere Informationen finden Sie unter Container-Images mit Cosign signieren.

  • Nutzlast: Die Beispielherkunft auf dieser Seite wurde zur besseren Lesbarkeit gekürzt. Die tatsächliche Ausgabe ist länger, da die Nutzlast eine base64-codierte Version aller Provenienzmetadaten ist.

Herkunft für Artefakte ohne Container ansehen

Cloud Build generiert SLSA-Herkunftsmetadaten für eigenständige Java- (Maven), Python- und Node.js-Anwendungen (npm), wenn Sie Ihre Build-Artefakte in die Artifact Registry hochladen. Sie können die Provenienzmetadaten über einen direkten API-Aufruf abrufen.

  1. Führen Sie einen Build mit Cloud Build aus, um die Herkunftsmetadaten für Ihre Artefakte zu generieren. Verwenden Sie einen der folgenden Leitfäden:

    Notieren Sie sich die BuildID, sobald der Build abgeschlossen ist.

  2. Rufe die Provenienzmetadaten ab, indem du den folgenden API-Aufruf in deinem Terminal ausführst. Dabei ist PROJECT_ID die ID, die mit deinem Google Cloud -Projekt verknüpft 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 Provenienzmetadaten für diesen Artifakttyp zuzugreifen. Provenienzmetadaten für nicht-containerbasierte Artefakte werden in der Google Cloud -Konsole nicht angezeigt und sind nicht über die gcloud CLI zugänglich.

  3. Suchen Sie in den Vorkommen Ihres Projekts nach BuildID, um die Herkunftsinformationen zu einem Build-Artefakt zu finden.

Herkunft prüfen

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

Wenn Sie die Herkunft von Builds prüfen, haben Sie folgende Vorteile:

  • Prüfen, ob Build-Artefakte aus vertrauenswürdigen Quellen und Build-Tools generiert werden
  • Sorgen Sie dafür, dass die Herkunftsmetadaten, die Ihren Buildprozess beschreiben, vollständig und authentisch sind.

Weitere Informationen finden Sie unter Builds schützen.

Provenienz mit dem SLSA-Validator prüfen

Der SLSA Verifier ist ein Open-Source-Befehlszeilentool zum Validieren der Buildintegrität gemäß den SLSA-Spezifikationen.

Wenn der Verifier Probleme findet, werden detaillierte Fehlermeldungen zurückgegeben, anhand derer Sie Ihren Buildprozess aktualisieren und Risiken minimieren können.

So verwenden Sie den SLSA-Prüfer:

  1. Installieren Sie Version 2.1 oder höher aus dem Repository für den SLSA-Verifier:

    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

    Ersetzen Sie die Platzhalterwerte im Befehl durch Folgendes:

    • LOCATION: Regionaler oder multiregionaler Speicherort.
    • PROJECT_ID: Google Cloud Projekt-ID.
    • REPOSITORY: Name des Repositorys.
    • IMAGE: Name des Bilds.
    • HASH: Der sha256-Hash-Wert des Images. Sie finden dies in der Ausgabe Ihres Builds.

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

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

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

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

  5. Prüfen Sie die Herkunft:

    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 die eindeutige ID für den Builder, z. B. https://cloudbuild.googleapis.com/GoogleHostedWorker

    Wenn Sie die bestätigte Provenienz zur Verwendung in einer Richtlinien-Engine ausdrucken 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 Herkunftsmetadaten des Builds 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 die Provenienztypen von SLSA-Version 0.1 als auch von Version 1.0 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 | '.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 obige Befehl verweist auf die erste Provenienzabzeichnung (.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 diesen Befehl aus, um die Provenienz in das erwartete PAE-Format von "DSSEv1" + SP + LEN(type) + SP + type + SP + LEN(body) + SP + body umzuwandeln.

    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