Verify image provenance

Linux

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

For information about access to this release, see the access request page.

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 Google Cloud 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 Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:

     gcloud init

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
  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.

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  For more information, see Authenticate for using REST in the Google Cloud 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:

• Artifact Registry Reader (roles/artifactregistry.reader)
• Cloud Build Viewer (roles/cloudbuild.builds.viewer)

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 Google Cloud console or the Google Cloud CLI:

Console (Cloud Build)

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

1. In the Google Cloud 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.

   Note: The Build Artifacts tab appears only if you configure an Artifact Registry repository. Click the artifact link to open your package in the generic repository in Artifact Registry.

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 Google Cloud 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.