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.
To use the command-line examples in this guide, install and configure the Google Cloud SDK.
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 adocker push
build step. Cloud Build only generates attestations for images pushed via theimages
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
andfileHash
fields refer to the same object. Thedigest
field is encoded in base 16 (hex-encoded) and thefileHash
field in base 64.There are two signatures on the
envelope
field. The first signature with the key nameprovenanceSigner
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 namebuiltByGCB
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 examplegithub.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 likegs://myrepo/source/1665165300.279777-955d1904741e4bbeb3461080299e929a.tgz#1665165361152799
.BUILDER_ID
the unique ID for the builder, for examplehttps://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
orFAILED: 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 usehttps://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 usehttps://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 theprovenanceSigner
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
.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.
What's next
- Configure Cloud Build to track who initiates a build
- Use vulnerability scanning in your Cloud Build pipeline
- Learn about Software Delivery Shield