Genera e convalida la provenienza della build

Questa pagina fornisce istruzioni su come generare l'origine della compilazione, visualizzare l'output e convalidarlo.

La provenienza della build è una raccolta di dati verificabili su una build. I metadati della provenienza includono dettagli come i digest delle immagini create, le posizioni delle origini di input, gli argomenti di compilazione e la durata della compilazione. Puoi utilizzare queste informazioni per assicurarti che gli elementi di cui fai uso siano accurati e affidabili, creati da autori e origini 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 delle specifiche SLSA 1.0, Cloud Build fornisce dettagli su buildType nell'origine 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 v1 di Cloud Build.

Limitazioni

• Cloud Build genera l'origine della build solo per gli artefatti archiviati in Artifact Registry.
• Per ottenere la provenienza sia della versione 1.0 che della versione 0.1 di SLSA, devi eseguire la compilazione utilizzando trigger. Se avvii una build manualmente utilizzando gcloud CLI, Cloud Build fornisce solo l'origine 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, assicurati di avere la versione più recente disponibile eseguendo gcloud components update.

3. Tieni a portata di mano il codice sorgente.

4. Avere un repository in Artifact Registry.

Genera 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 per configurare Cloud Build in modo da 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 build per creare un'immagine container e archiviarla 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: il tuo ID 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 posizione regionale o multiregionale per il tuo repository.
   • PROJECT_ID: il tuo ID progetto Google Cloud.
   • REPOSITORY: il nome del repository Artifact Registry.
   • IMAGE: il nome dell'immagine del contenitore.

2. Nella sezione options della configurazione di compilazione, aggiungi l'opzione requestedVerifyOption e imposta il 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. Avvia la compilazione.

Visualizza la provenienza della build

Questa sezione spiega come visualizzare i metadati dell'origine della compilazione creati da Cloud Build. Puoi recuperare queste informazioni a fini 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 alla gcloud CLI.

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'elemento 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 sull'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 dell'hash sha256 dell'immagine. Puoi trovarlo nell'output della build.
• FORMAT: un'impostazione facoltativa in cui puoi specificare un formato di output.

Output di esempio

L'origine della compilazione è 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'
    

Ecco 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 l'origine SLSA versione 0.1, l'output contiene due firme nel campo envelope. La prima firma, che ha il nome della chiave provenanceSigner, utilizza una firma conforme a DSSE (formattata con Pre-Authentication Encoding (PAE)), che può essere verificata nei criteri di Autorizzazione binaria. Ti consigliamo di utilizzare questa firma nei nuovi utilizzi di questa provenienza. La seconda firma, che ha il nome della chiave builtByGCB, è fornita per l'utilizzo precedente.

• Account di servizio: le firme incluse automaticamente nell'origine di Cloud Build ti aiutano a verificare il servizio di compilazione che ha eseguito una compilazione. Puoi anche configurare Cloud Build in modo da registrare metadati verificabili sull'account di servizio utilizzato per avviare una compilazione. Per ulteriori informazioni, vedi Firmare le immagini container con cosign.

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

Visualizzare la provenienza per gli artefatti non containerizzati

Cloud Build genera metadati di provenienza SLSA per le applicazioni Java (Maven), Python e Node.js (npm) autonome quando carichi gli elementi di build in Artifact Registry. Puoi recuperare i metadati di provenienza effettuando una chiamata diretta all'API.

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
   • Creare applicazioni Node.js autonome

   Al termine della compilazione, prendi nota del BuildID.

2. Recupera i metadati dell'origine eseguendo la seguente chiamata API nel terminale, dove PROJECT_ID è l'ID associato al 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 di elemento. I metadati della provenienza per gli elementi non contenitore non vengono visualizzati nella console Google Cloud o non sono accessibili tramite gcloud CLI.

3. Nelle occorrenze del progetto, cerca per BuildID per trovare le informazioni sull'origine associate a un elemento dell'assembly.

Convalida la provenienza

Questa sezione spiega come convalidare l'origine della compilazione per le immagini dei contenitori.

La convalida dell'origine della compilazione ti consente di:

• 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

Il verificatore SLSA è uno strumento CLI open source per la convalida dell'integrità della build in base alle specifiche SLSA.

Se il verificatore rileva problemi, restituisce messaggi di errore dettagliati per aiutarti a aggiornare la processo 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 quanto segue:

   • LOCATION: posizione regionale o multiregionale.
   • PROJECT_ID: l'ID progetto Google Cloud.
   • REPOSITORY: il nome del repository.
   • IMAGE: nome dell'immagine.
   • HASH: il valore dell'hash sha256 dell'immagine. Puoi trovarlo nell'output della build.

3. Autorizza l'interfaccia alla gcloud CLI in modo che il verificatore SLSA possa accedere ai dati sull'origine:

   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 compilatore, ad esempio https://cloudbuild.googleapis.com/GoogleHostedWorker

   Se vuoi stampare l'origine convalidata per utilizzarla in un motore di criteri, utilizza 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, consulta options.

Convalidare i metadati di provenienza con la gcloud CLI

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. Utilizza le informazioni del campo keyid per ottenere la chiave pubblica.

   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 dell'origine, 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
   

   Se disponibili, vengono archiviati entrambi i tipi di provenienza SLSA 0.1 e 1.0. Se vuoi filtrare in base alla 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 sopra la 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 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.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 nell'involucro in formato PAE. Per verificarlo, esegui questo comando per trasformare l'origine 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 analisi delle vulnerabilità nella pipeline Cloud Build
• Scopri di più sulla sicurezza della catena di fornitura del software