View build provenance

This page provides instructions on how you can view and audit build provenance metadata generated by Cloud Build.

Build provenance is a collection of verifiable data about a build run by Cloud Build. Provenance metadata includes details such as the digests of the built images, the input source locations, the build arguments, and the build duration.

Cloud Build supports the generation of build provenance that meets Supply-chain Levels for Software Artifacts (SLSA) level 3 assurance based on the SLSA version 0.1 specifications, and support for SLSA version 1.0 is now in Preview.

As part of support for the SLSA v1.0 spec, Cloud Build provides buildType details. You can use the buildType schema to understand the parameterized template used for the build process. For more information, see Cloud Build buildType v1.

Before you begin

Enable the Cloud Build, Artifact Analysis, and Artifact Registry APIs.
Enable the APIs
To use the command-line examples in this guide, install and configure the Google Cloud SDK.

Note: If you've installed Google Cloud SDK previously, make sure you have the latest available version by running gcloud components update.

This feature only works with container images stored in Artifact Registry.

View build provenance

This section explains how to view the build provenance metadata created by Cloud Build.

When you build an image with Cloud Build, the image's build provenance is automatically recorded. You can later fetch this information for auditing purposes.

View provenance in the Google Cloud console

You can view build provenance in the Security insights side panel within the Google Cloud console.

The Security insights side panel provides a high-level overview of security information for artifacts stored in Artifact Registry. To learn more about the side panel and how you can use Cloud Build to help protect your software supply chain, see View build security insights.

View provenance using the Google Cloud CLI

To generate the provenance metadata, run a build with Cloud Build.

Push the built image using the images field instead of a docker push build step. Cloud Build only generates attestations for images pushed via the images field.

To view the generated provenance metadata, run the following command:

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

Replace the placeholder values in the command with the following:

LOCATION: Regional or multi-regional location.
PROJECT_ID: Google Cloud project ID.
REPOSITORY: Name of the repository.
IMAGE: Image's name.
HASH: The sha256 hash value of the image. You can find this in the output of your build.

The output is the container provenance, as described in the SLSA provenance spec. For example:

  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: eyJfdHlwZSI6Imh0dHBzOi8vaW4tdG90by5pby9TdGF0ZW1lbnQvdjEiLCAic3ViamVjdCI6W3sibmFtZSI6Imh0dHBzOi8vdXMtY2VudHJhbDEtZG9ja2VyLnBrZy5kZXYvYXJnby1sb2NhbC1raGFsay9raGFsay1kb2NrZXItYXIvdGFnZ2VkLXdvcmxkLWdlbi10d28iLCAiZGlnZXN0Ijp7InNoYTI1NiI6IjdlOWI2ZTdiYTI4NDJjOTFjZjQ5ZjNlMjE0ZDA0YTdhNDk2ZjgyMTQzNTZmNDFkODFhNmU2ZGNhZDExZjExZTMifX0sIHsibmFtZSI6Imh0dHBzOi8vdXMtY2VudHJhbDEtZG9ja2VyLnBrZy5kZXYvYXJnby1sb2NhbC1raGFsay9raGFsay1kb2NrZXItYXIvdGFnZ2VkLXdvcmxkLWdlbi10d286bGF0ZXN0IiwgImRpZ2VzdCI6eyJzaGEyNTYiOiI3ZTliNmU3YmEyODQyYzkxY2Y0OWYzZTIxNGQwNGE3YTQ5NmY4MjE0MzU2ZjQxZDgxYTZlNmRjYWQxMWYxMWUzIn19XSwgInByZWRpY2F0ZVR5cGUiOiJodHRwczovL3Nsc2EuZGV2L3Byb3ZlbmFuY2UvdjEiLCAicHJlZGljYXRlIjp7ImJ1aWxkRGVmaW5pdGlvbiI6eyJidWlsZFR5cGUiOiJodHRwczovL2Nsb3VkLmdvb2dsZS5jb20vYnVpbGQvZ2NiLWJ1aWxkdHlwZXMvZ29vZ2xlLXdvcmtlci92MSIsICJleHRlcm5hbFBhcmFtZXRlcnMiOnsiYnVpbGRDb25maWdTb3VyY2UiOnsicGF0aCI6ImNsb3VkYnVpbGQueWFtbCIsICJyZWYiOiJyZWZzL2hlYWRzL21haW4iLCAicmVwb3NpdG9yeSI6ImdpdCtodHRwczovL2dpdGh1Yi5jb20va2hhbGtpZS9nY2ItcmVwby1zdGFnaW5nIn0sICJzdWJzdGl0dXRpb25zIjp7fX0sICJpbnRlcm5hbFBhcmFtZXRlcnMiOnsic3lzdGVtU3Vic3RpdHV0aW9ucyI6eyJCUkFOQ0hfTkFNRSI6Im1haW4iLCAiQlVJTERfSUQiOiJlNzNjYTFkNC1lYzRhLTRlYTYtYWNkZC1hYzhiYjE2ZGNjNzkiLCAiQ09NTUlUX1NIQSI6IjUyNWM1MmM1MDE3MzllNmRmMDYwOWVkMWY5NDRjMWJmZDgzMjI0ZTciLCAiTE9DQVRJT04iOiJ1cy13ZXN0MSIsICJQUk9KRUNUX05VTUJFUiI6IjI2NTQyNjA0MTUyNyIsICJSRUZfTkFNRSI6Im1haW4iLCAiUkVQT19GVUxMX05BTUUiOiJraGFsa2llL2djYi1yZXBvLXN0YWdpbmciLCAiUkVQT19OQU1FIjoiZ2NiLXJlcG8tc3RhZ2luZyIsICJSRVZJU0lPTl9JRCI6IjUyNWM1MmM1MDE3MzllNmRmMDYwOWVkMWY5NDRjMWJmZDgzMjI0ZTciLCAiU0hPUlRfU0hBIjoiNTI1YzUyYyIsICJUUklHR0VSX0JVSUxEX0NPTkZJR19QQVRIIjoiY2xvdWRidWlsZC55YW1sIiwgIlRSSUdHRVJfTkFNRSI6ImdpdGh1Yi10cmlnZ2VyLXN0YWdpbmcifSwgInRyaWdnZXJVcmkiOiJwcm9qZWN0cy8yNjU0MjYwNDE1MjcvbG9jYXRpb25zL3VzLXdlc3QxL3RyaWdnZXJzL2EwZDIzOWE0LTYzNWUtNGJkMy05ODJiLWQ4YjcyZDBiNGJhYiJ9LCAicmVzb2x2ZWREZXBlbmRlbmNpZXMiOlt7InVyaSI6ImdpdCtodHRwczovL2dpdGh1Yi5jb20va2hhbGtpZS9nY2ItcmVwby1zdGFnaW5nQHJlZnMvaGVhZHMvbWFpbiIsICJkaWdlc3QiOnsiZ2l0Q29tbWl0IjoiNTI1YzUyYzUwMTczOWU2ZGYwNjA5ZWQxZjk0NGMxYmZkODMyMjRlNyJ9fSwgeyJ1cmkiOiJnY3IuaW8vY2xvdWQtYnVpbGRlcnMvZG9ja2VyQHNoYTI1NjoxNTRmY2Q0ZDJkNjVjNmEzNWIwNmI5ODA1M2EwODI5YzU4MWUyMjNkNTMwYmU1NzE5MzI2ZjVkODVkNjgwZThkIiwgImRpZ2VzdCI6eyJzaGEyNTYiOiIxNTRmY2Q0ZDJkNjVjNmEzNWIwNmI5ODA1M2EwODI5YzU4MWUyMjNkNTMwYmU1NzE5MzI2ZjVkODVkNjgwZThkIn19XX0sICJydW5EZXRhaWxzIjp7ImJ1aWxkZXIiOnsiaWQiOiJodHRwczovL2Nsb3VkYnVpbGQuZ29vZ2xlYXBpcy5jb20vR29vZ2xlSG9zdGVkV29ya2VyIn0sICJtZXRhZGF0YSI6eyJpbnZvY2F0aW9uSWQiOiJodHRwczovL2Nsb3VkYnVpbGQuZ29vZ2xlYXBpcy5jb20vdjEvcHJvamVjdHMvYXJnby1sb2NhbC1raGFsay9sb2NhdGlvbnMvdXMtd2VzdDEvYnVpbGRzL2U3M2NhMWQ0LWVjNGEtNGVhNi1hY2RkLWFjOGJiMTZkY2M3OSIsICJzdGFydGVkT24iOiIyMDIzLTA4LTAxVDE5OjU2OjU3LjQ1MTU1MzE2MFoiLCAiZmluaXNoZWRPbiI6IjIwMjMtMDgtMDFUMTk6NTc6MTAuNzM0NDcxWiJ9LCAiYnlwcm9kdWN0cyI6W3t9XX19fQ==
      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'
  - build:
      intotoStatement:
        _type: https://in-toto.io/Statement/v0.1
        predicateType: https://slsa.dev/provenance/v0.1
        slsaProvenance:
          builder:
            id: https://cloudbuild.googleapis.com/GoogleHostedWorker@v0.3
          materials:
          - digest:
              sha1: 525c52c501739e6df0609ed1f944c1bfd83224e7
            uri: git+https://github.com/my-username/my-git-repo
          metadata:
            buildFinishedOn: '2023-08-01T19:57:10.734471Z'
            buildInvocationId: e73ca1d4-ec4a-4ea6-acdd-ac8bb16dcc79
            buildStartedOn: '2023-08-01T19:56:57.451553160Z'
          recipe:
            arguments:
              '@type': type.googleapis.com/google.devtools.cloudbuild.v1.Build
              id: e73ca1d4-ec4a-4ea6-acdd-ac8bb16dcc79
              name: projects/265426041527/locations/us-west1/builds/e73ca1d4-ec4a-4ea6-acdd-ac8bb16dcc79
              options:
                dynamicSubstitutions: true
                logging: LEGACY
                pool: {}
                requestedVerifyOption: VERIFIED
                substitutionOption: ALLOW_LOOSE
              sourceProvenance: {}
              steps:
              - args:
                - tag
                - hello-world
                - us-central1-docker.pkg.dev/my-project/my-repo/my-image
                name: gcr.io/cloud-builders/docker
                pullTiming:
                  endTime: '2023-08-01T19:57:07.231646287Z'
                  startTime: '2023-08-01T19:57:07.225609188Z'
                status: SUCCESS
                timing:
                  endTime: '2023-08-01T19:57:08.343864907Z'
                  startTime: '2023-08-01T19:57:07.225609188Z'
              substitutions:
                BRANCH_NAME: main
                COMMIT_SHA: 525c52c501739e6df0609ed1f944c1bfd83224e7
                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
            entryPoint: cloudbuild.yaml
            type: https://cloudbuild.googleapis.com/CloudBuildYaml@v0.1
        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:13.168653Z'
    envelope:
      payload: eyJfdHlwZSI6Imh0dHBzOi8vaW4tdG90by5pby9TdGF0ZW1lbnQvdjAuMSIsInByZWRpY2F0ZSI6eyJidWlsZGVyIjp7ImlkIjoiaHR0cHM6Ly9jbG91ZGJ1aWxkLmdvb2dsZWFwaXMuY29tL0dvb2dsZUhvc3RlZFdvcmtlckB2MC4zIn0sIm1hdGVyaWFscyI6W3siZGlnZXN0Ijp7InNoYTEiOiI1MjVjNTJjNTAxNzM5ZTZkZjA2MDllZDFmOTQ0YzFiZmQ4MzIyNGU3In0sInVyaSI6ImdpdCtodHRwczovL2dpdGh1Yi5jb20va2hhbGtpZS9nY2ItcmVwby1zdGFnaW5nIn1dLCJtZXRhZGF0YSI6eyJidWlsZEZpbmlzaGVkT24iOiIyMDIzLTA4LTAxVDE5OjU3OjEwLjczNDQ3MVoiLCJidWlsZEludm9jYXRpb25JZCI6ImU3M2NhMWQ0LWVjNGEtNGVhNi1hY2RkLWFjOGJiMTZkY2M3OSIsImJ1aWxkU3RhcnRlZE9uIjoiMjAyMy0wOC0wMVQxOTo1Njo1Ny40NTE1NTMxNjBaIn0sInJlY2lwZSI6eyJhcmd1bWVudHMiOnsiQHR5cGUiOiJ0eXBlLmdvb2dsZWFwaXMuY29tL2dvb2dsZS5kZXZ0b29scy5jbG91ZGJ1aWxkLnYxLkJ1aWxkIiwiaWQiOiJlNzNjYTFkNC1lYzRhLTRlYTYtYWNkZC1hYzhiYjE2ZGNjNzkiLCJuYW1lIjoicHJvamVjdHMvMjY1NDI2MDQxNTI3L2xvY2F0aW9ucy91cy13ZXN0MS9idWlsZHMvZTczY2ExZDQtZWM0YS00ZWE2LWFjZGQtYWM4YmIxNmRjYzc5Iiwib3B0aW9ucyI6eyJkeW5hbWljU3Vic3RpdHV0aW9ucyI6dHJ1ZSwibG9nZ2luZyI6IkxFR0FDWSIsInBvb2wiOnt9LCJyZXF1ZXN0ZWRWZXJpZnlPcHRpb24iOiJWRVJJRklFRCIsInN1YnN0aXR1dGlvbk9wdGlvbiI6IkFMTE9XX0xPT1NFIn0sInNvdXJjZVByb3ZlbmFuY2UiOnt9LCJzdGVwcyI6W3siYXJncyI6WyJ0YWciLCJoZWxsby13b3JsZCIsInVzLWNlbnRyYWwxLWRvY2tlci5wa2cuZGV2L2FyZ28tbG9jYWwta2hhbGsva2hhbGstZG9ja2VyLWFyL3RhZ2dlZC13b3JsZC1nZW4tdHdvIl0sIm5hbWUiOiJnY3IuaW8vY2xvdWQtYnVpbGRlcnMvZG9ja2VyIiwicHVsbFRpbWluZyI6eyJlbmRUaW1lIjoiMjAyMy0wOC0wMVQxOTo1NzowNy4yMzE2NDYyODdaIiwic3RhcnRUaW1lIjoiMjAyMy0wOC0wMVQxOTo1NzowNy4yMjU2MDkxODhaIn0sInN0YXR1cyI6IlNVQ0NFU1MiLCJ0aW1pbmciOnsiZW5kVGltZSI6IjIwMjMtMDgtMDFUMTk6NTc6MDguMzQzODY0OTA3WiIsInN0YXJ0VGltZSI6IjIwMjMtMDgtMDFUMTk6NTc6MDcuMjI1NjA5MTg4WiJ9fV0sInN1YnN0aXR1dGlvbnMiOnsiQlJBTkNIX05BTUUiOiJtYWluIiwiQ09NTUlUX1NIQSI6IjUyNWM1MmM1MDE3MzllNmRmMDYwOWVkMWY5NDRjMWJmZDgzMjI0ZTciLCJSRUZfTkFNRSI6Im1haW4iLCJSRVBPX0ZVTExfTkFNRSI6ImtoYWxraWUvZ2NiLXJlcG8tc3RhZ2luZyIsIlJFUE9fTkFNRSI6ImdjYi1yZXBvLXN0YWdpbmciLCJSRVZJU0lPTl9JRCI6IjUyNWM1MmM1MDE3MzllNmRmMDYwOWVkMWY5NDRjMWJmZDgzMjI0ZTciLCJTSE9SVF9TSEEiOiI1MjVjNTJjIiwiVFJJR0dFUl9CVUlMRF9DT05GSUdfUEFUSCI6ImNsb3VkYnVpbGQueWFtbCIsIlRSSUdHRVJfTkFNRSI6ImdpdGh1Yi10cmlnZ2VyLXN0YWdpbmcifX0sImVudHJ5UG9pbnQiOiJjbG91ZGJ1aWxkLnlhbWwiLCJ0eXBlIjoiaHR0cHM6Ly9jbG91ZGJ1aWxkLmdvb2dsZWFwaXMuY29tL0Nsb3VkQnVpbGRZYW1sQHYwLjEifX0sInByZWRpY2F0ZVR5cGUiOiJodHRwczovL3Nsc2EuZGV2L3Byb3ZlbmFuY2UvdjAuMSIsInNsc2FQcm92ZW5hbmNlIjp7ImJ1aWxkZXIiOnsiaWQiOiJodHRwczovL2Nsb3VkYnVpbGQuZ29vZ2xlYXBpcy5jb20vR29vZ2xlSG9zdGVkV29ya2VyQHYwLjMifSwibWF0ZXJpYWxzIjpbeyJkaWdlc3QiOnsic2hhMSI6IjUyNWM1MmM1MDE3MzllNmRmMDYwOWVkMWY5NDRjMWJmZDgzMjI0ZTcifSwidXJpIjoiZ2l0K2h0dHBzOi8vZ2l0aHViLmNvbS9raGFsa2llL2djYi1yZXBvLXN0YWdpbmcifV0sIm1ldGFkYXRhIjp7ImJ1aWxkRmluaXNoZWRPbiI6IjIwMjMtMDgtMDFUMTk6NTc6MTAuNzM0NDcxWiIsImJ1aWxkSW52b2NhdGlvbklkIjoiZTczY2ExZDQtZWM0YS00ZWE2LWFjZGQtYWM4YmIxNmRjYzc5IiwiYnVpbGRTdGFydGVkT24iOiIyMDIzLTA4LTAxVDE5OjU2OjU3LjQ1MTU1MzE2MFoifSwicmVjaXBlIjp7ImFyZ3VtZW50cyI6eyJAdHlwZSI6InR5cGUuZ29vZ2xlYXBpcy5jb20vZ29vZ2xlLmRldnRvb2xzLmNsb3VkYnVpbGQudjEuQnVpbGQiLCJpZCI6ImU3M2NhMWQ0LWVjNGEtNGVhNi1hY2RkLWFjOGJiMTZkY2M3OSIsIm5hbWUiOiJwcm9qZWN0cy8yNjU0MjYwNDE1MjcvbG9jYXRpb25zL3VzLXdlc3QxL2J1aWxkcy9lNzNjYTFkNC1lYzRhLTRlYTYtYWNkZC1hYzhiYjE2ZGNjNzkiLCJvcHRpb25zIjp7ImR5bmFtaWNTdWJzdGl0dXRpb25zIjp0cnVlLCJsb2dnaW5nIjoiTEVHQUNZIiwicG9vbCI6e30sInJlcXVlc3RlZFZlcmlmeU9wdGlvbiI6IlZFUklGSUVEIiwic3Vic3RpdHV0aW9uT3B0aW9uIjoiQUxMT1dfTE9PU0UifSwic291cmNlUHJvdmVuYW5jZSI6e30sInN0ZXBzIjpbeyJhcmdzIjpbInRhZyIsImhlbGxvLXdvcmxkIiwidXMtY2VudHJhbDEtZG9ja2VyLnBrZy5kZXYvYXJnby1sb2NhbC1raGFsay9raGFsay1kb2NrZXItYXIvdGFnZ2VkLXdvcmxkLWdlbi10d28iXSwibmFtZSI6Imdjci5pby9jbG91ZC1idWlsZGVycy9kb2NrZXIiLCJwdWxsVGltaW5nIjp7ImVuZFRpbWUiOiIyMDIzLTA4LTAxVDE5OjU3OjA3LjIzMTY0NjI4N1oiLCJzdGFydFRpbWUiOiIyMDIzLTA4LTAxVDE5OjU3OjA3LjIyNTYwOTE4OFoifSwic3RhdHVzIjoiU1VDQ0VTUyIsInRpbWluZyI6eyJlbmRUaW1lIjoiMjAyMy0wOC0wMVQxOTo1NzowOC4zNDM4NjQ5MDdaIiwic3RhcnRUaW1lIjoiMjAyMy0wOC0wMVQxOTo1NzowNy4yMjU2MDkxODhaIn19XSwic3Vic3RpdHV0aW9ucyI6eyJCUkFOQ0hfTkFNRSI6Im1haW4iLCJDT01NSVRfU0hBIjoiNTI1YzUyYzUwMTczOWU2ZGYwNjA5ZWQxZjk0NGMxYmZkODMyMjRlNyIsIlJFRl9OQU1FIjoibWFpbiIsIlJFUE9fRlVMTF9OQU1FIjoia2hhbGtpZS9nY2ItcmVwby1zdGFnaW5nIiwiUkVQT19OQU1FIjoiZ2NiLXJlcG8tc3RhZ2luZyIsIlJFVklTSU9OX0lEIjoiNTI1YzUyYzUwMTczOWU2ZGYwNjA5ZWQxZjk0NGMxYmZkODMyMjRlNyIsIlNIT1JUX1NIQSI6IjUyNWM1MmMiLCJUUklHR0VSX0JVSUxEX0NPTkZJR19QQVRIIjoiY2xvdWRidWlsZC55YW1sIiwiVFJJR0dFUl9OQU1FIjoiZ2l0aHViLXRyaWdnZXItc3RhZ2luZyJ9fSwiZW50cnlQb2ludCI6ImNsb3VkYnVpbGQueWFtbCIsInR5cGUiOiJodHRwczovL2Nsb3VkYnVpbGQuZ29vZ2xlYXBpcy5jb20vQ2xvdWRCdWlsZFlhbWxAdjAuMSJ9fSwic3ViamVjdCI6W3siZGlnZXN0Ijp7InNoYTI1NiI6IjdlOWI2ZTdiYTI4NDJjOTFjZjQ5ZjNlMjE0ZDA0YTdhNDk2ZjgyMTQzNTZmNDFkODFhNmU2ZGNhZDExZjExZTMifSwibmFtZSI6Imh0dHBzOi8vdXMtY2VudHJhbDEtZG9ja2VyLnBrZy5kZXYvYXJnby1sb2NhbC1raGFsay9raGFsay1kb2NrZXItYXIvdGFnZ2VkLXdvcmxkLWdlbi10d28ifSx7ImRpZ2VzdCI6eyJzaGEyNTYiOiI3ZTliNmU3YmEyODQyYzkxY2Y0OWYzZTIxNGQwNGE3YTQ5NmY4MjE0MzU2ZjQxZDgxYTZlNmRjYWQxMWYxMWUzIn0sIm5hbWUiOiJodHRwczovL3VzLWNlbnRyYWwxLWRvY2tlci5wa2cuZGV2L2FyZ28tbG9jYWwta2hhbGsva2hhbGstZG9ja2VyLWFyL3RhZ2dlZC13b3JsZC1nZW4tdHdvOmxhdGVzdCJ9XX0=
      payloadType: application/vnd.in-toto+json
      signatures:
      - keyid: projects/verified-builder/locations/global/keyRings/attestor/cryptoKeys/provenanceSigner/cryptoKeyVersions/1
        sig: MEUCIQDsD7nX7YgnKrhgiNZXWuvSf_1AG8DgGDUAlZnjT_SB1AIgTBHZPCjTTPk3lQPAccL6WNg457QHufk9T9YB1FW5xbQ=
      - keyid: projects/argo-qa/locations/us-west1/keyRings/attestor/cryptoKeys/builtByGCB/cryptoKeyVersions/1
        sig: MEUCIQDnQmgbIcCkbDZy91HicY-IkcuV5bV_Zo0D1Y_rmsAMyQIga17tv0c_KAW3Uhv8mM2SZwY8D3YuP6TUy7QXDs2cmpA=
    kind: BUILD
    name: projects/my-project/occurrences/8b5dcf9d-4076-4b85-a934-adfb91042088
    noteName: projects/argo-qa/notes/intoto_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:13.168653Z'

A few important things to notice in this example:

The build was triggered from a GitHub repository. You can see the corresponding commit in the materials field.
The digest and fileHash fields refer to the same object. The digest field is encoded in base 16 (hex-encoded) and the fileHash field in base 64.
There are two signatures on the envelope field. The first signature with the key name provenanceSigner uses a DSSE-conformant signature (formatted with Pre-Authentication Encoding (PAE)), which can be verified in Binary Authorization policies. We recommend that you use this signature in new usages of this provenance. The second signature with the key name builtByGCB is provided for legacy usage.
The signatures that are automatically included in Cloud Build provenance help you verify the build service that executed a build. You can also configure Cloud Build to record verifiable metadata about the service account used to initiate a build. For more information, see sign container images with cosign.

View build provenance for regional pools

Cloud Build does not generate provenance metadata for builds in regional pool, whether you are using a private pool or a default pool with an assigned region. You can enable provenance metadata for regional builds by adding an option to your build file. For more information on regions, see Cloud build locations.

View provenance for non-container artifacts

Cloud Build generates Supply chain Levels for Software Artifacts (SLSA) provenance metadata for standalone Java (Maven), Python and Node.js (npm) applications when you upload your build artifacts to Artifact Registry.

To generate the provenance metadata for your artifacts, run a build with Cloud Build:
When your build completes, note the BuildID.
Run the following API call in your terminal, where PROJECT_ID is the ID associated with your Google Cloud project:
```
alias gcurl='curl -H"Authorization: Bearer $(gcloud auth print-access-token)"'
    gcurl 'https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences'
```
In the occurrences for your project, search by BuildID to find the provenance information associated with each build artifact.

Validate provenance

This section explains how to validate build provenance.

Validating build provenance helps you to:

confirm that build artifacts are being generated from trusted sources and builders
ensure that provenance metadata describing your build process is complete and authentic

For more information, see Safeguard builds.

Validate provenance using the SLSA verifier

The SLSA verifier is an open source CLI tool for validating build integrity based on the SLSA specifications.

If the verifier finds issues, it returns detailed error messages to help you update your build process and mitigate risks.

To use the SLSA verifier:

Install version 2.1 or higher from the slsa-verifier repository:

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

In your CLI, set a variable for your image identifier:
```
export IMAGE=LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH
```
Replace the placeholder values in the command with the following:
- LOCATION: Regional or multi-regional location.
- PROJECT_ID: Google Cloud project ID.
- REPOSITORY: Name of the repository.
- IMAGE: Image name.
- HASH: The sha256 hash value of the image. You can find this in the output of your build.
Authorize the gcloud CLI so that the SLSA verifier can access your provenance data:
```
gcloud auth configure-docker LOCATION-docker.pkg.dev
```

Retrieve the provenance for your image and store it as JSON:

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

Verify the provenance:
```
slsa-verifier verify-image "$IMAGE" \
--provenance-path provenance.json \
--source-uri SOURCE \
--builder-id=BUILDER_ID
```
Where:
- SOURCE is the source repository URI for your image, for example github.com/username/my-application.
  
  If you are verifying a build that wasn't produced by a Git trigger, the source looks different. For example, when you are working on source code locally, gcloud builds submit uploads your source to Cloud Storage. Then your Cloud Storage source info looks like gs://myrepo/source/1665165300.279777-955d1904741e4bbeb3461080299e929a.tgz#1665165361152799.
- BUILDER_ID the unique ID for the builder, for example https://cloudbuild.googleapis.com/GoogleHostedWorker
If you want to print the validated provenance for use in a policy engine, use the previous command with the --print-provenance flag.

The output is similar to the following: PASSED: Verified SLSA provenance or FAILED: SLSA verification failed: <error details>.

For more information on optional flags, see options.

Validate provenance metadata with the gcloud CLI

If you want to verify that the build provenance metadata has not been tampered with, you can validate the provenance by performing the following steps:

Create a new directory and go to that directory.
```
mkdir provenance && cd provenance
```

Using the information from the keyid field, get the public key.

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

The payload contains the JSON representation of the provenance, encoded in base64url. Decode the data and store it in a 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

Both SLSA version 0.1 and 1.0 provenance types are stored when available. If you want to filter for version 1.0, change the predicateType to use https://slsa.dev/provenance/v1. For example:

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

The envelope also contains the signature over the provenance. Decode the data and store it in a 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

If you want to filter for version 1.0, change the predicateType to use https://slsa.dev/provenance/v1. For example:

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

The command above references the first provenance signature (.provenance_summary.provenance[0].envelope.signatures[0]) which is signed by the provenanceSigner key. The payload is signed over the PAE-formatted envelope. In order to verify it, run this command to transform the provenance into the expected PAE format of "DSSEv1" + SP + LEN(type) + SP + type + SP + LEN(body) + SP + body.

Note: If you are verifying the second signature (.provenance_summary.provenance[0].envelope.signatures[1].sig with keyname builtByGCB), skip this step and verify the provenance.json file you have already stored.
```
echo -n "DSSEv1 28 application/vnd.in-toto+json $(cat provenance.json | wc -c) $(cat provenance.json)" > provenance.json
```

Validate the signature.

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

After a successful validation, the output is Verified OK.

Require that your images have associated provenance metadata

By default, if Cloud Build does not generate provenance metadata, the build is still completed successfully. To overwrite this behavior and fail builds if Cloud Build does not generate provenance metadata for your image, add the requestedVerifyOption: VERIFIED option to your build configuration file.

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: [ 'build', '-t', 'us-central1-docker.pkg.dev/$PROJECT_ID/quickstart-docker-repo/quickstart-image:tag1', '.' ]
images:
- 'us-central1-docker.pkg.dev/$PROJECT_ID/quickstart-docker-repo/quickstart-image:tag1'
options:
  requestedVerifyOption: VERIFIED

After adding the requestedVerifyOption, Cloud Build only marks the build as successful if it can generate the corresponding provenance metadata. This also affects images built in a regional pool, enabling provenance metadata and attestation generation for those images.

View build provenance

Before you begin

View build provenance

View provenance in the Google Cloud console

View provenance using the Google Cloud CLI

View build provenance for regional pools

View provenance for non-container artifacts

Validate provenance

Validate provenance using the SLSA verifier

To use the SLSA verifier:

Validate provenance metadata with the gcloud CLI

Require that your images have associated provenance metadata

What's next