Upload SBOMs

This page describes how to upload a software bill of materials (SBOM) file to Cloud Storage to help track and attest to the components of container images you store in Artifact Registry.

For information on Cloud Storage pricing, see Pricing.

Before you begin

1. Sign in to your Google Account.

   If you don't already have one, sign up for a new account.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Artifact Registry, Container Analysis APIs.

   Enable the APIs

5. Install the Google Cloud CLI.

6. To initialize the gcloud CLI, run the following command:

   gcloud init

   Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

8. Make sure that billing is enabled for your Google Cloud project.

9. Enable the Artifact Registry, Container Analysis APIs.

   Enable the APIs

10. Install the Google Cloud CLI.

11. To initialize the gcloud CLI, run the following command:

    gcloud init

    Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
12. Have a Docker repository in Artifact Registry with the container image that your SBOM describes. If you are not familiar with Artifact Registry, see the Docker quickstart.
13. Have an SBOM file ready to upload in one of the supported formats.

Required roles

To get the permissions that you need to to create and manage Cloud Storage buckets and SBOM files , ask your administrator to grant you the following IAM roles on the project:

• If you are using the default Cloud Storage bucket, to manage storage buckets: Storage Admin(roles/storage.admin)
• If you are specifying a Cloud Storage bucket, to manage storage buckets: Storage Object Admin(roles/storage.objectAdmin)
• If a note for the SBOM reference already exists: Container Analysis Notes Attacher (roles/containeranalysis.notes.attacher)
• To create a new note for SBOM reference occurrences in the current project: Container Analysis Notes Editor((roles/containeranalysis.notes.editor)
• To create an SBOM reference occurrence: Container Analysis Occurrences Editor(roles/containeranalysis.occurrences.editor)

For more information about granting roles, see Manage access.

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

Supported formats

Your SBOM file must be a JSON file in one of the following formats:

• Software Package Data Exchange (SPDX) version 2.2 or 2.3
• CycloneDX version 1.4 or 1.5

Upload your SBOM

Use the following command to upload your SBOM:

gcloud artifacts sbom load /
    --source SOURCE /
    --uri URI

Where:

• SOURCE: the path to the SBOM file to upload.
• URI: the URI for the Docker image that the SBOM file describes. Images can be in either tag format, or digest format. Images provided in tag format will be resolved into digest format.

Optional flags

• --destination: specifies a Cloud Storage bucket to use instead of the default one.
• --kms-key-version: provides a key version to sign the SBOM reference occurrence payload. You can use this key to verify the origin of the SBOM.

For example, the following command uploads a JSON file my-sbom.bom.json that was generated from the tagged image us-east1-docker.pkg.dev/my-image-repo/my-image, and signs the SBOM reference occurrence with the KMS key version ending in my-key/cryptoKeyVersions/1.

gcloud artifacts sbom load /
--source=my-sbom.bom.json
--uri=us-east1-docker.pkg.dev/my-image-repo/my-image
--kms-key-version=projects/my-project/locations/us/keyRings/my-key-ring/cryptoKeys/my-key/cryptoKeyVersions/1

The following command uploads a JSON file my-sbom.spdx.json that is associated with the image digest my-local-image@sha256:abcxyz, and stores the file in the Cloud Storage bucket gs://my-sbom-bucket.

gcloud artifacts sbom load /
    --source=my-sbom.spdx.json /
    --uri=my-local-image@sha256:abcxyz /
    --destination=gs://my-sbom-bucket

Artifact Analysis uploads your SBOM to Cloud Storage and creates an SBOM reference occurrence.

You can view SBOMs by using the Google Cloud console or the gcloud CLI. If you want to locate the Cloud Storage bucket that contains your SBOMs, you must search for SBOMs using the gcloud CLI.

What's next

• View SBOMs and dependencies.