Verify image provenance

You can verify SLSA (Supply-chain Levels for Software Artifacts) build provenance attestations for your custom OS images to ensure software supply chain integrity.

When you configure your Image Builder pipeline to output to Artifact Registry and enable verification options, Cloud Build automatically generates a cryptographic attestation describing the exact pipeline source code, configurations, execution parameters, and base image used during compilation. Verifying this build provenance confirms that trusted pipelines built your images securely without unauthorized tampering.

Before you begin

  • Complete the environment setup steps in Prepare your environment.
  • If you haven't already, set up authentication. Authentication verifies your identity for access to Cloud de Confiance by S3NS services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Cloud de Confiance console to access Cloud de Confiance by S3NS services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, and then sign in to the gcloud CLI with your federated identity. After signing in, initialize the Google Cloud CLI by running the following command: 

      gcloud init
    2. Set a default region and zone.

    REST

    To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

      Install the Google Cloud CLI, and then sign in to the gcloud CLI with your federated identity.

    For more information, see Authenticate for using REST in the Cloud de Confiance authentication documentation.

Required roles

To get the permissions that you need to view and verify build provenance attestations, ask your administrator to grant you the following IAM roles on your project:

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Configure provenance generation

To generate build provenance, ensure that you configure the substitutions, options, results, and artifacts blocks in your cloudbuild.yaml file as shown in the following 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}'

Verify provenance data

You can view and verify build provenance data and execution artifacts by using either the Cloud de Confiance console or the Google Cloud CLI:

Console (Cloud Build)

To view build provenance and output artifacts through Cloud Build build history:

  1. In the Cloud de Confiance console, go to the Cloud Build page.

    Go to Cloud Build

  2. Click History and select the Build ID for your image pipeline run. The build details page displays logs for the three process steps (imagebuilder-customize, imagebuilder-validate, and imagebuilder-publish).

  3. Click the Build Artifacts tab to view the exact OS image created during execution.

  4. Click the Attachments tab to view the signed SLSA provenance attestation files and results files. The results file records the source base image used during execution.

Console (Artifact Registry)

To view build provenance directly in Artifact Registry:

  1. In the Cloud de Confiance console, go to the Artifact Registry page.

    Go to Artifact Registry

  2. In the repositories list, click the name of your generic repository.

  3. In the package list, click your OS image package name.

  4. In the version history list, click the version ID (v${BUILD_ID}) for your pipeline run.

  5. Click the Attachments tab to view the signed SLSA provenance attestation files and results files for that image version. The results file records the base source image used during execution.

gcloud

Artifact Registry stores provenance records as attachment files alongside the generic image tarballs.

Because the attestation is formatted as a Dead Simple Signing Envelope (DSSE), the actual provenance statement payload inside the JSON is base64-encoded. To read the details, perform the following steps using the gcloud CLI and jq utility:

  1. List the versions of your package to locate the specific build ID version that you want to verify by running the gcloud artifacts versions list command:

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

    Replace the following:

    • PACKAGE_NAME: the name of the package in your Artifact Registry repository, for example, my-custom-image.
    • REPOSITORY_NAME: the name of your generic Artifact Registry repository, for example, custom-os-images.
    • REPOSITORY_LOCATION: the region of your repository, for example, us-central1.
    • PROJECT_ID: your project ID.

  2. Query the attachments metadata matching the target package version by running the gcloud artifacts attachments list command:

    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

    Replace BUILD_ID with the version identifier returned in step 1, for example, 12345.

    From the command output, locate the attachment entry whose name field contains build-result (with type: application/vnd.in-toto+json), and copy the path listed under files:, for example:

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

  3. Download the JSON metadata attachment payload from your repository by running the gcloud artifacts files download command:

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

    Replace ATTACHMENT_FILE_ID with the files: attachment path retrieved in the previous step.

  4. Run the following command to isolate, base64-decode, and format the JSON payload contents:

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

    The output contains standard SLSA format parameters highlighting the build trigger, recipe repository details, container images used, build hashes, and base image attributes.