Signierte Herkunft und Binärautorisierung verwenden

Auf dieser Seite finden Sie eine Anleitung zum Aufrufen von Build-Herkunftsmetadaten und zum Steuern von Bereitstellungen mit Cloud Build.

Die Build-Herkunft ist eine Sammlung überprüfbarer Daten zu einem Build, der von Cloud Build ausgeführt wird. Herkunftsmetadaten enthalten Details wie die Digests der erstellten Images, die Quell-Speicherorte, die Build-Argumente und die Build-Dauer.

Zum Schutz Ihrer Softwarelieferkette erfasst Cloud Build Herkunftsmetadaten und erstellt während der Build-Erstellung Attestierungen für Container-Images. Sie können die Herkunftsmetadaten für Prüfungszwecke und die Attestierungen verwenden, um Bereitstellungen mit Binärautorisierung zu steuern.

Beschränkungen

Cloud Build generiert alle Ressourcen für die Binärautorisierung und Container Analysis im selben Projekt. Wenn Sie Ihre Bereitstellungsplattform in einem anderen Projekt ausführen, müssen Sie beim Konfigurieren der Binärautorisierung auf das Cloud Build-Projekt verweisen, wenn Sie den Attestierer built-by-cloud-build hinzufügen.

Hinweis

  • So rufen Sie die generierten Metadaten zur Build-Herkunft auf:

    Cloud Build, Container Analysis, and Artifact Registry APIs aktivieren.

    Aktivieren Sie die APIs

  • So steuern Sie Bereitstellungen mit Binärautorisierung und rufen die Attestierermetadaten auf:

    1. Cloud Build, Binary Authorization, and Artifact Registry APIs aktivieren.

      Aktivieren Sie die APIs

    2. Binärautorisierung für die Plattform einrichten.

Build-Herkunft ansehen

In diesem Abschnitt wird erläutert, wie Sie die von Cloud Build erstellten Metadaten zur Build-Herkunft aufrufen.

Wenn Sie ein Image mit Cloud Build erstellen, wird die Build-Herkunft des Images automatisch aufgezeichnet. Sie können diese Informationen später zu Prüfungszwecken abrufen. Erstellen Sie mit Cloud Build einen Build, um die Herkunftsmetadaten zu generieren.

Führen Sie den folgenden Befehl aus, um die Herkunftsmetadaten aufzurufen:

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

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 Images.
  • HASH: Der sha256-Hash-Wert des Images. Sie finden dies in der Ausgabe Ihres Builds.

Die Ausgabe ist die Containerherkunft, wie in der SLSA-Herkunftsspezifikation beschrieben. Beispiel:

image_summary:
  digest: sha256:991ff3a4548c72e671070be2e86ff684fd0924f6b75ee60d25d85c8cdfde1293
  fully_qualified_digest: us-east1-docker.pkg.dev/PROJECT_ID/my-repo/my-image@sha256:991ff3a4548c72e671070be2e86ff684fd0924f6b75ee60d25d85c8cdfde1293
  registry: us-east1-docker.pkg.dev
  repository: my-repo
provenance_summary:
  provenance:
  - createTime: '2021-09-24T16:20:36.854156Z'
    dsseAttestation:
      envelope:
        payload: eyJfdHlwZS...
        payloadType: application/vnd.in-toto+json
        signatures:
        - keyid: projects/verified-builder/locations/global/keyRings/attestor/cryptoKeys/builtByGCB/cryptoKeyVersions/1
          sig: MEQCIHusA75t6LoyCngZ1_ACc-wWOlTThW6VKCyz75bnmSU0AiBYV50eFWQlDlp2cF-OV1u6j1_CtmrFdCNJCdyB6pYFsw==
      statement:
        predicateType: https://slsa.dev/provenance/v0.1
        provenance:
          builderConfig:
            id: https://cloudbuild.googleapis.com/Worker@v336731714
          metadata:
            buildFinishedOn: '2021-09-24T16:20:35.828284Z'
            buildInvocationId: c2f645df-f705-4aab-8d8f-ba2b1260f8ab
            buildStartedOn: '2021-09-24T16:20:23.224165401Z'
          recipe:
            arguments:
            - '@type': type.googleapis.com/google.devtools.cloudbuild.v1.BuildStep
              args:
              - build
              - --network
              - cloudbuild
              - --no-cache
              - -t
              - us-east1-docker.pkg.dev/PROJECT_ID/my-repo/my-image:tag1
              ....

Wenn Sie prüfen möchten, ob die Metadaten 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[0].dsseAttestation.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[0].dsseAttestation.envelope.signatures[0].sig' | tr '\-_' '+/' | base64 -d > signature.bin
    
  5. Ü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.

Ihren Bildern müssen Herkunftsmetadaten zugeordnet sein

Wenn Cloud Build keine Herkunftsmetadaten generiert, ist der Build dennoch erfolgreich abgeschlossen. Wenn Sie das Standardverhalten überschreiben und Builds fehlschlagen, wenn Cloud Build keine Herkunftsmetadaten für Ihr Image generiert, fügen Sie der Datei cloudbild.yaml die Option requestedVerifyOption: VERIFIED hinzu:

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: [ 'build', '-t', 'us-central1-docker.pkg.dev/$PROJECT_ID/quickstart-docker-repo/quickstart-image:tag1', '.' ]
images:
- 'us-central1-docker.pkg.dev/$PROJECT_ID/quickstart-docker-repo/quickstart-image:tag1'
options:
  requestedVerifyOption: VERIFIED

Nach dem Hinzufügen von requestedVerifyOption markiert Cloud Build den Build nur dann als erfolgreich, wenn die entsprechenden Herkunftsmetadaten generiert werden können. Dies betrifft auch Images, die in einem privaten Pool erstellt wurden und das Erstellen von Provenance-Metadaten und Attestierungen für diese Images ermöglicht.

Bereitstellungen mit Binärautorisierung steuern

Eine Richtlinie im Rahmen der Binärautorisierung ist eine Reihe von Regeln für das Deployment von Images. Sie können eine Regel so konfigurieren, dass digital signierte Attestierungen erforderlich sind.

Cloud Build generiert und signiert die Attestierungen zur Build-Zeit. Mit der Binärautorisierung können Sie den Attestierer built-by-cloud-build verwenden, um die Attestierungen zu prüfen und nur Images bereitzustellen, die von Cloud Build erstellt wurden. Der Attestierer built-by-cloud-build wird erstellt, wenn Sie zum ersten Mal einen Build in einem Projekt ausführen.

Führen Sie die folgenden Schritte aus, um die Bereitstellung von Images zu erlauben, die von Cloud Build erstellt wurden:

Console

  1. Rufen Sie in der Google Cloud Console die Seite Binärautorisierung auf.

    Zur Binärautorisierung

  2. Im Tab Richtlinie klicken Sie auf Richtlinie bearbeiten.

  3. Wählen Sie im Dialogfeld Richtlinie bearbeiten die Option Nur Images zulassen, die von allen folgenden Attestierern genehmigt wurden aus.

  4. Klicken Sie auf Attestierer hinzufügen.

  5. Führen Sie im Dialogfeld Attestierer hinzufügen die folgenden Schritte aus:

    1. Wählen Sie Nach Projekt und Attestierername hinzufügen aus und führen Sie die folgenden Schritte aus:
      1. Geben Sie im Feld Projektname das Projekt ein, in dem Sie Cloud Build ausführen.
      2. Klicken Sie auf das Feld Name des Attestierers und prüfen Sie, ob der Attestierer built-by-cloud-build verfügbar ist.
      3. Klicken Sie auf built-by-cloud-build.
    2. Alternativ können Sie Nach Attestierer-Ressourcen-ID hinzufügen auswählen. Geben Sie unter Attestierer-Ressourcen-ID projects/PROJECT_ID/attestors/built-by-cloud-build ein und ersetzen Sie PROJECT_ID durch das Projekt, in dem Sie Cloud Build ausführen.
  6. Klicken Sie auf 1 Attestierer hinzufügen.

  7. Klicken Sie auf Save Policy (Richtlinie speichern).

gcloud

  1. Exportieren Sie Ihre vorhandene Richtlinie mit dem folgenden Befehl in eine Datei:

    gcloud container binauthz policy export > /tmp/policy.yaml
    
  2. Bearbeiten Sie die Richtliniendatei.

  3. Bearbeiten Sie eine der folgenden Regeln:

    • defaultAdmissionRule
    • clusterAdmissionRules
    • istioServiceIdentityAdmissionRules
    • kubernetesServiceAccountAdmissionRules
  4. Fügen Sie der Regel einen requireAttestationsBy-Block hinzu, sofern noch keiner vorhanden ist.

  5. Fügen Sie im requireAttestationsBy-Block projects/<var>PROJECT_ID</var>/attestors/built-by-cloud-build hinzu und ersetzen Sie PROJECT_ID durch das Projekt, in dem Sie Cloud Build ausführen.

  6. Speichern Sie die Richtliniendatei.

  7. Importieren Sie die Richtliniendatei.

    gcloud container binauthz policy import /tmp/policy.yaml
    

    Das folgende Beispiel zeigt eine Richtliniendatei, die den Verweis auf built-by-cloud-build-attestor enthält:

    defaultAdmissionRule:
      evaluationMode: REQUIRE_ATTESTATION
      enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
      requireAttestationsBy:
        - projects/PROJECT_ID/attestors/built-by-cloud-build
    name: projects/PROJECT_ID/policy
    

    Ersetzen Sie PROJECT_ID durch die Projekt-ID, in der Sie Cloud Build ausführen.

Sie können Richtlinienfehler in den Nachrichten der Binärautorisierung für GKE oder Cloud Run aufrufen.

Probelaufmodus verwenden

Im Probelaufmodus prüft die Binärautorisierung die Richtliniencompliance, ohne die Bereitstellung tatsächlich zu blockieren. Stattdessen werden Statusmeldungen zur Einhaltung von Richtlinien in Cloud Logging protokolliert. Anhand dieser Logs können Sie feststellen, ob Ihre Blockierrichtlinie korrekt funktioniert, und falsch positive Ergebnisse identifizieren.

So aktivieren Sie den Probelauf:

Console

  1. Rufen Sie in der Google Cloud Console die Seite "Binärautorisierung" auf.

    Zur Binärautorisierung

  2. Klicken Sie auf Richtlinie bearbeiten.

  3. Wählen Sie in der Standardregel oder eine bestimmte Regel den Probelaufmodus aus.

  4. Klicken Sie auf Save Policy (Richtlinie speichern).

gcloud

  1. Exportieren Sie die Richtlinie für die Binärautorisierung in eine YAML-Datei:

    gcloud container binauthz policy export  > /tmp/policy.yaml
    
  2. Legen Sie in einem Texteditor enforcementMode auf DRYRUN_AUDIT_LOG_ONLY fest und speichern Sie die Datei.

  3. Importieren Sie zum Aktualisieren der Richtlinie die Datei mit dem folgenden Befehl:

    gcloud container binauthz policy import /tmp/policy.yaml
    

Sie können Richtlinienfehler in den Nachrichten der Binärautorisierung für GKE oder Cloud Run aufrufen.

Attestierermetadaten ansehen

Ein Attestierer wird erstellt, wenn Sie zum ersten Mal einen Build in einem Projekt ausführen. Die Attestierer-ID ist projects/PROJECT_ID/attestors/built-by-cloud-build. Sie können die Metadaten des Build-Attestierers mit dem folgenden Befehl prüfen:

curl -X GET -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://binaryauthorization.googleapis.com/v1beta1/projects/PROJECT_ID/attestors/built-by-cloud-build

Ersetzen Sie PROJECT_ID durch das Projekt, in der Sie Cloud Build ausführen.

Die Ausgabe enthält Informationen zum Attestierer und zu den entsprechenden öffentlichen Schlüsseln. Beispiel:

name": "projects/PROJECT_ID/attestors/built-by-cloud-build",
  "userOwnedDrydockNote": {
    "noteReference": "projects/PROJECT_ID/notes/built-by-cloud-build",
    "publicKeys": [
      {
        "id": "//cloudkms.googleapis.com/v1/projects/verified-builder/locations/asia/keyRings/attestor/cryptoKeys/builtByGCB/cryptoKeyVersions/1",
        "pkixPublicKey": {
          "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEMMvFxZLgIiWOLIXsaTkjTmOKcaK7\neIZrgpWHpHziTFGg8qyEI4S8O2/2wh1Eru7+sj0Sh1QxytN/KE5j3mTvYA==\n-----END PUBLIC KEY-----\n",
          "signatureAlgorithm": "ECDSA_P256_SHA256"
        }
      },
...
      }
    ],
    "delegationServiceAccountEmail": "service-942118413832@gcp-binaryauthorization.iam.gserviceaccount.com"
  },
  "updateTime": "2021-09-24T15:26:44.808914Z",
  "description": "Attestor autogenerated by build ID fab07092-30f4-4f70-caf7-4545cbc404d6"

Nächste Schritte