Genera e convalida la provenienza della build

Questa pagina fornisce istruzioni su come generare la provenienza della build, visualizzare l'output e convalidarlo.

La provenienza della build è una raccolta di dati verificabili su una build. I metadati di provenienza includono dettagli come le sintesi delle immagini create, le località dell'origine di input, gli argomenti di build e la durata della build. Puoi utilizza queste informazioni per garantire che gli artefatti creati che stai utilizzando siano accurati e affidabili, creati da fonti e generatori attendibili.

Cloud Build supporta la generazione della provenienza della build che soddisfa la garanzia di livello 3 di Supply-chain Levels for Software Artifacts (SLSA) in base alle specifiche per le versioni 0.1 e 1.0 di SLSA.

Nell'ambito del supporto della specifica SLSA v1.0, Cloud Build fornisce Dettagli di buildType nella provenienza della build. Puoi utilizzare lo schema buildType per comprendere il modello parametrizzato utilizzato per il processo di compilazione, inclusi i valori registrati da Cloud Build e la relativa origine. Per ulteriori informazioni, consulta BuildType Cloud Build v1.

Limitazioni

• Cloud Build genera l'origine della build solo per gli artefatti archiviati in Artifact Registry.
• Per ottenere la provenienza di SLSA v1.0 e v0.1, devi creare utilizzando trigger. Se avvii una build manualmente, utilizzando gcloud CLI, Cloud Build fornisce solo Provenienza SLSA v0.1.

Prima di iniziare

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

   Enable the APIs

2. Per utilizzare gli esempi a riga di comando in questa guida, installa e configura il Google Cloud SDK.

   Nota: se hai già installato Google Cloud SDK in precedenza, assicurati di avere ultima versione disponibile eseguendo gcloud components update.

3. Tieni a portata di mano il codice sorgente.

4. Avere un repository in Artifact Registry.

Generare la provenienza della build

Le seguenti istruzioni spiegano come generare l'origine della compilazione per le immagini container archiviate in Artifact Registry:

1. Nel file di configurazione della build, aggiungi il campo images da configurare Cloud Build per archiviare le immagini create in Artifact Registry al termine della build.

   Cloud Build non può generare la provenienza se esegui il push dell'immagine su Artifact Registry utilizzando un passaggio docker push esplicito.

   Lo snippet seguente mostra una configurazione di compilazione per creare un'immagine container archiviare l'immagine in un repository Docker 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']
   

   Dove:

   • LOCATION: la posizione regionale o multiregionale per il tuo repository.
   • PROJECT_ID: l'ID del tuo progetto Google Cloud.
   • REPOSITORY: il nome del repository Artifact Registry.
   • IMAGE: il nome dell'immagine del contenitore.

   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"
     ]
     }
   

   Dove:

   • LOCATION: la località a livello di una o più regioni per il tuo repository.
   • PROJECT_ID: il tuo ID progetto Google Cloud.
   • REPOSITORY: il nome del repository Artifact Registry.
   • IMAGE: il nome dell'immagine container.

2. Nella sezione options della configurazione della build, aggiungi requestedVerifyOption e impostata sul valore VERIFIED.

   Questa impostazione attiva la generazione della provenienza e configura Cloud Build per verificare la presenza dei metadati della provenienza. Le compilazioni verranno contrassegnate come riuscite solo se viene generata la provenienza.

   YAML

   options:
     requestedVerifyOption: VERIFIED
   

   JSON

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

3. Inizia la build.

Visualizza la provenienza della build

Questa sezione spiega come visualizzare i metadati di provenienza della build creati in Cloud Build. Puoi recuperare queste informazioni per motivi di controllo.

Puoi accedere ai metadati dell'origine della compilazione per i container utilizzando il riquadro laterale Approfondimenti sulla sicurezza nella console Google Cloud o l'interfaccia a riga di comando gcloud.

console

Il riquadro laterale Approfondimenti sulla sicurezza fornisce una panoramica generale delle informazioni sulla sicurezza per gli elementi archiviati in Artifact Registry.

Per visualizzare il riquadro Approfondimenti sulla sicurezza:

1. Apri la pagina Cronologia di Build nella console Google Cloud:

   Apri la pagina Cronologia build

2. Seleziona il progetto e fai clic su Apri.

3. Nel menu a discesa Regione, seleziona la regione in cui hai eseguito la compilazione.

4. Nella tabella con le build, individua la riga con la build per la quale vuoi visualizzare gli approfondimenti sulla sicurezza.

5. Nella colonna Approfondimenti sulla sicurezza, fai clic su Visualizza.

   Viene visualizzato il riquadro Approfondimenti sulla sicurezza per l'artefatto selezionato.

   La scheda Build mostra i dettagli della provenienza e un link. Puoi visualizzare lo snippet di provenienza facendo clic sull'icona del link.

Per scoprire di più sul riquadro laterale e su come utilizzare Cloud Build per contribuire a proteggere la tua catena di fornitura del software, consulta Visualizzare gli insight sulla sicurezza della build.

Interfaccia a riga di comando gcloud

Per visualizzare i metadati dell'origine per le immagini container, esegui il seguente comando:

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

Sostituisci quanto segue:

• LOCATION: la posizione regionale o multiregionale del tuo repository.
• PROJECT_ID: il tuo ID progetto Google Cloud.
• REPOSITORY: il nome del repository di Artifact Registry.
• IMAGE: il nome dell'immagine del contenitore.
• HASH: il valore hash sha256 dell'immagine. Puoi visualizzare nell'output della build.
• FORMAT: un'impostazione facoltativa in cui puoi specificare un formato di output.

Output di esempio

La provenienza della build è simile alla seguente:

      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'
    

Alcuni aspetti importanti da notare in questo esempio:

• Origine: la build è stata attivata da un repository GitHub.

• Riferimento a un oggetto: i campi denominati digest e fileHash fanno riferimento allo stesso oggetto. Il campo digest incluso nell'output di esempio è codificato in base 16 (codifica esadecimale). Se utilizzi l'origine SLSA versione 0.1, il risultato utilizza il campo fileHash codificato in base 64.

• Firme: se utilizzi la provenienza di SLSA versione 0.1, i valori di output contiene due firme nel campo envelope. Il primo con nome della chiave provenanceSigner, utilizza una Firma conforme a DSSE (formattato con Pre-Authentication Encoding (PAE), che può essere verificata in Autorizzazione binaria criteri. Ti consigliamo di usare questa firma nei nuovi utilizzi di questo provenienza. La seconda firma, con il nome della chiave builtByGCB, è fornite per l'utilizzo precedente.

• Account di servizio: le firme che vengono incluse automaticamente in La provenienza di Cloud Build ti aiuta a verificare il servizio di build ha eseguito una build. Puoi anche configurare Cloud Build in modo che metadati verificabili sull'account di servizio utilizzato per avviare una build. Per ulteriori informazioni, vedi Firmare le immagini container con cosign.

• Payload: l'origine di esempio visualizzata in questa pagina è abbreviata per una migliore leggibilità. L'output effettivo sarà più lungo, poiché il payload è un formato base-64 una versione codificata di tutti i metadati di provenienza.

Visualizza la provenienza per gli artefatti non containerizzati

Cloud Build genera la provenienza SLSA metadati per applicazioni autonome Java (Maven), Python e Node.js (npm) quando carichi gli artefatti della build in Artifact Registry. Puoi recuperare il di provenienza dei dati effettuando una chiamata API diretta.

1. Per generare i metadati dell'origine per gli elementi, esegui una build con Cloud Build. Utilizza una delle seguenti guide:

   • Creare applicazioni Java autonome
   • Creare applicazioni Python autonome
   • Crea applicazioni Node.js autonome

   Quando la build è completata, prendi nota del BuildID.

2. Recupera i metadati di provenienza eseguendo la seguente chiamata API nel tuo terminale, dove PROJECT_ID è l'ID associato a per il tuo progetto Google Cloud:

   alias gcurl='curl -H"Authorization: Bearer $(gcloud auth print-access-token)"'
       gcurl 'https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences'
   

   Devi utilizzare una chiamata API per accedere ai metadati di provenienza per questo tipo dell'artefatto. I metadati di provenienza per gli artefatti non containerizzati non vengono visualizzati nella console Google Cloud o accessibili tramite gcloud CLI.

3. Nelle occorrenze del tuo progetto, cerca per BuildID per trovare le informazioni sulla provenienza associate a un artefatto della build.

Convalida la provenienza

Questa sezione spiega come convalidare la provenienza della build per le immagini container.

La convalida della provenienza della build ti aiuta a:

• verifica che gli elementi di compilazione vengano generati da compilatori e fonti attendibili
• assicurati che i metadati di provenienza che descrivono il processo di compilazione siano completi e autentici

Per ulteriori informazioni, vedi Eseguire build protette.

Convalida la provenienza utilizzando lo strumento di verifica SLSA

Lo strumento di verifica SLSA è uno strumento di interfaccia a riga di comando open source per e convalidare l'integrità della build in base alle specifiche SLSA.

Se il verificatore rileva problemi, restituisce messaggi di errore dettagliati per aiutarti a aggiornare la procedura di compilazione e a mitigare i rischi.

Per utilizzare lo strumento di verifica SLSA:

1. Installa la versione 2.1 o successive dal repository slsa-verifier:

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

2. Nella CLI, imposta una variabile per l'identificatore immagine:

   export IMAGE=LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH
   

   Sostituisci i valori segnaposto nel comando con i seguenti:

   • LOCATION: località a livello di una o più regioni.
   • PROJECT_ID: ID progetto Google Cloud.
   • REPOSITORY: il nome del repository.
   • IMAGE: nome dell'immagine.
   • HASH: il valore hash sha256 dell'immagine. Puoi lo trovi nell'output della build.

3. Autorizza gcloud CLI in modo che lo strumento di verifica SLSA possa accedere ai dati di provenienza:

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

4. Recupera la provenienza dell'immagine e memorizzala come JSON:

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

5. Verifica la provenienza:

   slsa-verifier verify-image "$IMAGE" \
   --provenance-path provenance.json \
   --source-uri SOURCE \
   --builder-id=BUILDER_ID
   

   Dove:

   • SOURCE è l'URI del repository di origine dell'immagine, ad esempio github.com/my-repo/my-application.
   • BUILDER_ID l'ID univoco del costruttore, ad esempio https://cloudbuild.googleapis.com/GoogleHostedWorker

   Se vuoi stampare la provenienza convalidata per l'utilizzo in un motore dei criteri, usa il comando precedente con il flag --print-provenance.

   L'output è simile al seguente: PASSED: Verified SLSA provenance o FAILED: SLSA verification failed: <error details>.

Per ulteriori informazioni sui flag facoltativi, vedi le opzioni.

Convalidare i metadati di provenienza con la CLI gcloud

Se vuoi verificare che i metadati dell'origine della compilazione non siano stati manomessi, puoi convalidare l'origine seguendo questi passaggi:

1. Crea una nuova directory e vai a quella directory.

   mkdir provenance && cd provenance
   

2. Recupera la chiave pubblica utilizzando le informazioni contenute nel campo keyid.

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

3. payload contiene la rappresentazione JSON della provenienza, codificata in base64url. Decodifica i dati e archiviali in un file.

   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
   

   Entrambi i tipi di provenienza SLSA versione 0.1 e 1.0 sono memorizzati quando disponibili. Se vuoi filtrare per la versione 1.0, cambia predicateType in modo da utilizzare https://slsa.dev/provenance/v1. Ad esempio:

   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. La busta contiene anche la firma sulla provenienza. Decodificare i dati e archiviarli in un file.

     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
   

   Se vuoi filtrare in base alla versione 1.0, modifica predicateType in modo da utilizzare https://slsa.dev/provenance/v1. Ad esempio:

   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. Il comando riportato sopra fa riferimento alla prima firma di provenienza (.provenance_summary.provenance[0].envelope.signatures[0]) firmata dalla chiave provenanceSigner. Il payload viene firmato sopra l'involucro in formato PAE. Per verificarlo, esegui questo comando per trasformare la provenienza nel formato PAE previsto di "DSSEv1" + SP + LEN(type) + SP + type + SP + LEN(body) + SP + body.

   Nota: se stai verificando la seconda firma (.provenance_summary.provenance[0].envelope.signatures[1].sig con nome chiave builtByGCB), salta questo passaggio e verifica il file provenance.json che hai già archiviato.

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

6. Convalida la firma.

   openssl dgst -sha256 -verify my-key.pub -signature signature.bin provenance.json
   

   Dopo una convalida riuscita, l'output è Verified OK.

Passaggi successivi

• Configurare Cloud Build per monitorare chi avvia una build
• Utilizzare l'analisi delle vulnerabilità nella pipeline di Cloud Build
• Scopri di più su Software Delivery Shield