Stay organized with collections
Save and categorize content based on your preferences.
Assured OSS packages are built with SLSA Level 2
compliance. Build provenance is provided as part of the security metadata. This
page explains how to verify the build provenance metadata.
Build provenance is signed using an in-toto attestation which in turn uses
dsse envelope format.
This means that the generated signature contains the wrapped signature and the
raw data.
Using the aoss-verifier tool
To verify build provenance, install the
aoss-verifier tool.
Export $(go env GOPATH)/bin, and run the aoss-verifier verify-package
command with the --verify_build_provenance flag.
LANGUAGE: The package language. The value must
be in lowercase.
PACKAGE_ID: For Java, the format is
groupId:artifactId. For Python, the format is
packageName. The value must be in lowercase.
VERSION: The version of the package.
ARTIFACT_PATH: The path to the data file in your
local directory that you want to verify. Use the following filename
extensions:
jar file extension for a Java package
whl file extension for a Python package
--disable_certificate_verification is an optional flag which skips matching
leaf certificate to the root certificate through the certificate chain, if
used.
--temp_downloads_path is an optional flag to set the path where you want to
download the files. Replace TEMP_DOWNLOADS_DIR_PATH.
If this flag isn't set, the files are downloaded to the tmp_downloads folder in the
current directory.
--disable_deletes is an optional flag which keeps the downloaded files. By
default, the tool cleans all the downloaded files.
The EnvelopeSignature section in build provenance contains the reference to
the key that is used to sign the build provenance. The key is stored in one
of the following formats:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 UTC."],[[["\u003cp\u003eAssured Open Source Software (OSS) packages are built with SLSA Level 2 compliance, and build provenance is included in the security metadata for verification.\u003c/p\u003e\n"],["\u003cp\u003eYou can verify build provenance using the \u003ccode\u003eaoss-verifier\u003c/code\u003e tool, which requires specifying the package language, package ID, version, and artifact path, among other options, to verify the provenance.\u003c/p\u003e\n"],["\u003cp\u003eAlternatively, you can manually verify build provenance by retrieving the build provenance, the build provenance signature, and the public key, and then using the \u003ccode\u003ecosign\u003c/code\u003e tool to verify the signature.\u003c/p\u003e\n"],["\u003cp\u003eThe build provenance signature is stored in a file named \u003ccode\u003esignature.sig\u003c/code\u003e, and its format depends on how the metadata was downloaded.\u003c/p\u003e\n"],["\u003cp\u003eThe public key needed for manual verification is stored in a Cloud Storage bucket owned by Assured OSS, and it can be retrieved using the Google Cloud CLI, specifying the key name and optionally the key version.\u003c/p\u003e\n"]]],[],null,["# Verify the build provenance\n\nAssured OSS packages are built with [SLSA Level 2](https://slsa.dev/spec/v0.1/levels)\ncompliance. Build provenance is provided as part of the security metadata. This\npage explains how to verify the build provenance metadata.\n\nThis document applies to the free tier. For information about the build\nprovenance in the premium tier, see [Access security metadata and verify packages](/security-command-center/docs/aoss-access-security-metadata).\n\nBefore you begin\n----------------\n\n- Install [cosign](https://github.com/sigstore/cosign) to verify the signature in the build provenance.\n\nSet up authentication\n---------------------\n\nFor information about setting up authentication, see [Set up authentication](/assured-open-source-software/docs/validate-connection#set_up_authentication).\n\nVerify build provenance\n-----------------------\n\nBuild provenance is signed using an in-toto attestation which in turn uses\n[dsse envelope format](https://github.com/secure-systems-lab/dsse/blob/master/protocol.md).\nThis means that the generated signature contains the wrapped signature and the\nraw data.\n\n### Using the aoss-verifier tool\n\n1. To verify build provenance, install the\n [aoss-verifier](https://github.com/google/aoss-verifier) tool.\n\n2. Export `$(go env GOPATH)/bin`, and run the `aoss-verifier verify-package`\n command with the `--verify_build_provenance` flag.\n\n aoss-verifier verify-package \\\n --language \u003cvar translate=\"no\"\u003eLANGUAGE\u003c/var\u003e \\\n --package_id \u003cvar translate=\"no\"\u003ePACKAGE_ID\u003c/var\u003e \\\n --version \u003cvar translate=\"no\"\u003eVERSION\u003c/var\u003e \\\n --artifact_path \u003cvar translate=\"no\"\u003eARTIFACT_PATH\u003c/var\u003e \\\n --verify_build_provenance \\\n [--disable_certificate_verification] \\\n [--temp_downloads_path \u003cvar translate=\"no\"\u003eTEMP_DOWNLOADS_DIR_PATH\u003c/var\u003e] \\\n [--disable_deletes]\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eLANGUAGE\u003c/var\u003e: The package language. The value must be in lowercase.\n - \u003cvar translate=\"no\"\u003ePACKAGE_ID\u003c/var\u003e: For Java, the format is \u003cvar translate=\"no\"\u003egroupId:artifactId\u003c/var\u003e. For Python, the format is \u003cvar translate=\"no\"\u003epackageName\u003c/var\u003e. The value must be in lowercase.\n - \u003cvar translate=\"no\"\u003eVERSION\u003c/var\u003e: The version of the package.\n - \u003cvar translate=\"no\"\u003eARTIFACT_PATH\u003c/var\u003e: The path to the data file in your local directory that you want to verify. Use the following filename extensions:\n - `jar` file extension for a Java package\n - `whl` file extension for a Python package\n\n `--disable_certificate_verification` is an optional flag which skips matching\n leaf certificate to the root certificate through the certificate chain, if\n used.\n\n `--temp_downloads_path` is an optional flag to set the path where you want to\n download the files. Replace \u003cvar translate=\"no\"\u003eTEMP_DOWNLOADS_DIR_PATH\u003c/var\u003e.\n If this flag isn't set, the files are downloaded to the `tmp_downloads` folder in the\n current directory.\n\n `--disable_deletes` is an optional flag which keeps the downloaded files. By\n default, the tool cleans all the downloaded files.\n\nFor more information, see the\n[README file of the tool](https://github.com/google/aoss-verifier#readme).\n\n### Manual verification\n\nTo verify the build provenance, do the following:\n\n1. Retrieve build provenance.\n\n Depending on how you [access security metadata](/assured-open-source-software/docs/access-metadata-using-container-analysis), the build provenance is\n accessed differently.\n - If you [access security metadata using Cloud Storage](/assured-open-source-software/docs/access-metadata-using-cloud-storage), build provenance is available as part of the `Build Information` metadata under the `buildDetails` field.\n\n For more information, see the following sample metadata snippet: \n\n {\n \"creationTime\": \"2023-03-25T05:32:23Z\",\n \"buildDetails\": [\n {\n \"packageFileName\": \"jackson-databind-2.13.3.jar\",\n \"envelope\": {\n \"payload\": \"eyJfdHlwZSI6Imh0d...............\",\n \"payloadType\": \"application/vnd.in-toto+json\",\n \"signatures\": [\n \"sig\": \"eyJwYXlsb2FkVHlwZSI6Im......\",\n \"keyid\": \"gcpkms://projects/cloud-aoss/locations/global/keyRings/cloud-aoss-ring/cryptoKeys/tekton-chains\"\n }\n ]\n },\n \"buildProvenance\": \"{\\\"_type\\\":\\\"https://in-toto.io/Statement/v0.1...\"\n .....\n\n - If you [access security metadata using Artifact Analysis API](/assured-open-source-software/docs/access-metadata-using-container-analysis), build provenance is stored in the `BuildOccurrence` section of the security metadata.\n\n Sample metadata snippet: \n\n {'BuildOccurrence': name: \"projects/cloud-aoss/occurrences/06c514bb-1069-4cde-8d68-b1306f19535a\"\n resource_uri: \"jackson-databind-2.13.3.jar@sha256:4c01a14673bc1cd4a2df337a3b4e695af0a6ed8ac6be19c9e4077377fb8adf92\"\n note_name: \"projects/cloud-aoss/notes/tekton-cloudbuild-intoto\"\n kind: BUILD\n create_time {\n seconds: 1665556616\n nanos: 891004000\n }\n ......\n ......\n }\n envelope {\n payload: \"{\\\"_type\\\":\\\"https://in-toto.io/Statement/v0.1\\\", .....\"\n payload_type: \"application/vnd.in-toto+json\"\n signatures {\n sig: \"{\\\"payloadType\\\":\\\"application/vnd.in-toto+json\\\",.....\"\n keyid: \"gcpkms://projects/cloud-aoss/locations/global/keyRings/cloud-aoss-ring/cryptoKeys/tekton-chains\"\n }\n }\n ,\n ...\n\n2. Retrieve the build provenance signature.\n\n Build provenance contains a section named [Envelope](/container-analysis/docs/reference/rest/v1/projects.occurrences#envelope) which contains signatures as [EnvelopeSignature](/container-analysis/docs/reference/rest/v1/projects.occurrences#envelope). To retrieve\n the signature, follow these steps:\n 1. Store the `sig` data in a file named `signature.txt`.\n 2. Check if the metadata is downloaded using the metadata script.\n\n If the metadata is downloaded using the metadata script, modify the\n signature and store it in another file called `signature.sig`.\n\n To modify the signature, run the following command: \n\n cat signature.txt | sed -e 's/\\\\\"/\"/g' \u003e signature.sig\n\n If the metadata is **not** downloaded using the metadata script, decode\n the signature and store it in another file called `signature.sig`.\n\n To decode the signature, use the following command: \n\n cat signature.txt | tr '\\-_' '+/' | base64 -d \u003e signature.sig\n\n3. Retrieve the build provenance public key.\n\n The [EnvelopeSignature](/container-analysis/docs/reference/rest/v1/projects.occurrences#EnvelopeSignature) section in build provenance contains the reference to\n the key that is used to sign the build provenance. The key is stored in one\n of the following formats:\n 1. `gcpkms://projects/cloud-aoss/locations/global/keyRings/cloud-aoss-ring/cryptoKeys/`\u003cvar translate=\"no\"\u003eKEY_NAME\u003c/var\u003e\n 2. `gcpkms://projects/cloud-aoss/locations/global/keyRings/cloud-aoss-ring/cryptoKeys/`\u003cvar translate=\"no\"\u003eKEY_NAME\u003c/var\u003e`/cryptoKeyVersions/`\u003cvar translate=\"no\"\u003eKEY_VERSION\u003c/var\u003e\n\n Where \u003cvar translate=\"no\"\u003eKEY_NAME\u003c/var\u003e and \u003cvar translate=\"no\"\u003eKEY_VERSION\u003c/var\u003e are the\n name and version of the Cloud Key Management Service key.\n\n The public key is stored in a Cloud Storage bucket that is owned by Assured OSS.\n\n Retrieve the public key using the Google Cloud CLI. Use one of the following\n commands:\n - If only \u003cvar translate=\"no\"\u003eKEY_NAME\u003c/var\u003e is present:\n\n gcloud storage cp gs://cloud-aoss/keys/\u003cvar translate=\"no\"\u003eKEY_NAME\u003c/var\u003e-public.pem \u003cvar translate=\"no\"\u003ePATH_TO_LOCAL_STORE\u003c/var\u003e\n\n - If both \u003cvar translate=\"no\"\u003eKEY_NAME\u003c/var\u003e and \u003cvar translate=\"no\"\u003eKEY_VERSION\u003c/var\u003e are present:\n\n gcloud storage cp gs://cloud-aoss/keys/\u003cvar translate=\"no\"\u003eKEY_NAME\u003c/var\u003e-\u003cvar translate=\"no\"\u003eKEY_VERSION\u003c/var\u003e-public.pem \u003cvar translate=\"no\"\u003ePATH_TO_LOCAL_STORE\u003c/var\u003e\n\n Replace the following :\n - \u003cvar translate=\"no\"\u003eKEY_NAME\u003c/var\u003e with the name of the Cloud Key Management Service key.\n - \u003cvar translate=\"no\"\u003eKEY_VERSION\u003c/var\u003e with the version of the Cloud Key Management Service key.\n - \u003cvar translate=\"no\"\u003ePATH_TO_LOCAL_STORE\u003c/var\u003e with the name of the local path for storing the public key.\n4. Verify the provenance signature.\n\n 1. To verify the signature, run the following command:\n\n cosign verify-blob-attestation --insecure-ignore-tlog --key \u003cvar translate=\"no\"\u003eKEY_REF\u003c/var\u003e --signature \u003cvar translate=\"no\"\u003esignature.sig\u003c/var\u003e --type slsaprovenance --check-claims=false /dev/null\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eKEY_REF\u003c/var\u003e: The path to the public key you downloaded in the previous step.\n - \u003cvar translate=\"no\"\u003esignature.sig\u003c/var\u003e: The file containing the signature retrieved in the previous step.\n\n The following output is returned after the command runs successfully:\n\n `Verified OK`\n 2. To also verify the artifact hash associated with the provenance, use the\n following command:\n\n cosign verify-blob-attestation --insecure-ignore-tlog --key \u003cvar translate=\"no\"\u003eKEY_REF\u003c/var\u003e --signature \u003cvar translate=\"no\"\u003esignature.sig\u003c/var\u003e --type slsaprovenance --check-claims=true \u003cvar translate=\"no\"\u003eARTIFACT_PATH\u003c/var\u003e \n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eKEY_REF\u003c/var\u003e: The path to the public key you downloaded in the previous step.\n - \u003cvar translate=\"no\"\u003esignature.sig\u003c/var\u003e: The file containing the signature retrieved in the previous step.\n - \u003cvar translate=\"no\"\u003eARTIFACT_PATH\u003c/var\u003e: The path to the artifact.\n\n The following output is returned after the command runs successfully:\n\n `Verified OK`\n\nWhat's next\n-----------\n\n- [Subscribe to notifications](/assured-open-source-software/docs/use-notifications)"]]