Verificare la provenienza dell'immagine

Puoi verificare le attestazioni di provenienza della build SLSA (Supply-chain Levels for Software Artifacts) per le tue immagini OS personalizzate per garantire l'integrità della catena di fornitura del software.

Quando configuri la pipeline Image Builder per l'output in Artifact Registry e attivi le opzioni di verifica, Cloud Build genera automaticamente un'attestazione crittografica che descrive il codice sorgente, le configurazioni, i parametri di esecuzione e l'immagine di base esatti della pipeline utilizzati durante la compilazione. La verifica dell'origine di questa build conferma che le pipeline attendibili hanno creato le immagini in modo sicuro senza manomissioni non autorizzate.

Prima di iniziare

  • Completa i passaggi di configurazione dell'ambiente in Prepara l'ambiente.
  • Se non l'hai ancora fatto, configura l'autenticazione. L'autenticazione verifica la tua identità per l'accesso ad API e servizi Cloud de Confiance by S3NS . Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi autenticarti su Compute Engine selezionando una delle seguenti opzioni:

    Seleziona la scheda relativa a come prevedi di utilizzare gli esempi in questa pagina:

    Console

    Quando utilizzi la console Cloud de Confiance per accedere ai servizi Cloud de Confiance by S3NS e alle API, non devi configurare l'autenticazione.

    gcloud

    1. Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata. Dopo aver eseguito l'accesso, inizializza Google Cloud CLI eseguendo il comando seguente: 

      gcloud init
  • Imposta una regione e una zona predefinite.

    • REST

    Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a gcloud CLI.

      Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata.

    Per saperne di più, consulta Autenticati per usare REST nella documentazione sull'autenticazione di Cloud de Confiance .

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per visualizzare e verificare le attestazioni di provenienza della build, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Configura la generazione della provenienza

Per generare la provenienza della build, assicurati di configurare i blocchi substitutions, options, results e artifacts nel file cloudbuild.yaml come mostrato nel seguente snippet:

substitutions:
  # 1. Specify your output path and target Artifact Registry resource URI
  _IMAGE_OUTPUT_PATH: 'image-builder/binaryOut'
  _ARTIFACT_REGISTRY_RESOURCE_URI: 'projects/PROJECT_ID/locations/REGION/repositories/REPOSITORY_NAME/packages/PACKAGE_NAME/versions/v${BUILD_ID}'

steps:
  # 2. Configure step results and base image attestations
  - name: 'REGION-docker.pkg.dev/image-builder-official/release/builder:stable'
    script: |
      #!/usr/bin/env bash
      /build
    id: 'imagebuilder-customize'
    results:
      - name: image_builder_telemetry_metrics
      - name: base_image
        attestationType: "https://cloudbuild.googleapis.com/attestations/build_content_restrictions"
        attestationContent: base_image

options:
  # 3. Enable Cloud Logging and cryptographic provenance generation
  logging: CLOUD_LOGGING_ONLY
  requestedVerifyOption: VERIFIED

artifacts:
  # 4. Upload generic image artifacts and provenance to Artifact Registry
  generic_artifacts:
    - folder: '${_IMAGE_OUTPUT_PATH}'
      registry_path: '${_ARTIFACT_REGISTRY_RESOURCE_URI}'

Verificare i dati di provenienza

Puoi visualizzare e verificare i dati di provenienza della build e gli artefatti di esecuzione utilizzando la console Cloud de Confiance o Google Cloud CLI:

Console (Cloud Build)

Per visualizzare la provenienza della build e gli artefatti di output tramite la cronologia delle build di Cloud Build:

  1. Nella Cloud de Confiance console, vai alla pagina Cloud Build.

    Vai a Cloud Build

  2. Fai clic su Cronologia e seleziona l'ID build per l'esecuzione della pipeline di immagini. La pagina dei dettagli della build mostra i log dei tre passaggi della procedura (imagebuilder-customize, imagebuilder-validate e imagebuilder-publish).

  3. Fai clic sulla scheda Artefatti build per visualizzare l'immagine sistema operativo esatta creata durante l'esecuzione.

  4. Fai clic sulla scheda Allegati per visualizzare i file di attestazione e i file dei risultati della provenienza SLSA firmata. Il file dei risultati registra l'immagine di base di origine utilizzata durante l'esecuzione.

Console (Artifact Registry)

Per visualizzare la provenienza della build direttamente in Artifact Registry:

  1. Nella console Cloud de Confiance , vai alla pagina Artifact Registry.

    Vai ad Artifact Registry

  2. Nell'elenco dei repository, fai clic sul nome del repository generico.

  3. Nell'elenco dei pacchetti, fai clic sul nome del pacchetto dell'immagine del sistema operativo.

  4. Nell'elenco della cronologia delle versioni, fai clic sull'ID versione (v${BUILD_ID}) dell'esecuzione della pipeline.

  5. Fai clic sulla scheda Allegati per visualizzare i file di attestazione della provenienza SLSA firmati e i file dei risultati per quella versione dell'immagine. Il file dei risultati registra l'immagine di origine di base utilizzata durante l'esecuzione.

gcloud

Artifact Registry archivia i record di provenienza come file allegati insieme ai tarball generici delle immagini.

Poiché l'attestazione è formattata come una busta di firma Dead Simple Signing Envelope (DSSE), il payload dell'istruzione di provenienza effettiva all'interno del JSON è codificato in base64. Per leggere i dettagli, esegui i seguenti passaggi utilizzando gcloud CLI e l'utilità jq:

  1. Elenca le versioni del pacchetto per individuare la versione specifica dell'ID build che vuoi verificare eseguendo il comando gcloud artifacts versions list:

    gcloud artifacts versions list \
    --package=PACKAGE_NAME \
    --repository=REPOSITORY_NAME \
    --location=REPOSITORY_LOCATION \
    --project=PROJECT_ID

    Sostituisci quanto segue:

    • PACKAGE_NAME: il nome del pacchetto nel repository Artifact Registry, ad esempio my-custom-image.
    • REPOSITORY_NAME: il nome del repository Artifact Registry generico, ad esempio custom-os-images.
    • REPOSITORY_LOCATION: la regione del tuo repository, ad esempio us-central1.
    • PROJECT_ID: il tuo ID progetto.

  2. Esegui una query sui metadati degli allegati corrispondenti alla versione del pacchetto di destinazione eseguendo il comando gcloud artifacts attachments list:

    gcloud artifacts attachments list \
    --target=projects/PROJECT_ID/locations/REPOSITORY_LOCATION/repositories/REPOSITORY_NAME/packages/PACKAGE_NAME/versions/vBUILD_ID \
    --repository=REPOSITORY_NAME \
    --location=REPOSITORY_LOCATION \
    --project=PROJECT_ID

    Sostituisci BUILD_ID con l'identificatore della versione restituito nel passaggio 1, ad esempio 12345.

    Nell'output comando, individua la voce dell'allegato il cui campo name contiene build-result (con type: application/vnd.in-toto+json) e copia il percorso elencato in files:, ad esempio:

    projects/PROJECT_ID/locations/REPOSITORY_LOCATION/repositories/REPOSITORY_NAME/files/sha256:SHA256_HASH

  3. Scarica il payload dell'allegato dei metadati JSON dal repository eseguendo il comando gcloud artifacts files download:

    gcloud artifacts files download ATTACHMENT_FILE_ID \
    --repository=REPOSITORY_NAME \
    --location=REPOSITORY_LOCATION \
    --project=PROJECT_ID \
    --destination=./provenance.json

    Sostituisci ATTACHMENT_FILE_ID con il percorso dell'allegato files: recuperato nel passaggio precedente.

  4. Esegui il comando seguente per isolare, decodificare in base64 e formattare i contenuti del payload JSON:

    cat ./provenance.json | jq -r '.payload' | base64 --decode | jq

    L'output contiene parametri di formato SLSA standard che evidenziano il trigger di build, i dettagli del repository delle ricette, le immagini container utilizzate, gli hash di build e gli attributi dell'immagine di base.