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
-
Sign in to your Google Account.
If you don't already have one, sign up for a new account.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Artifact Registry, Container Analysis APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Artifact Registry, Container Analysis APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
- 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.
- Have an SBOM file ready to upload in one of the supported formats.
Required roles
To get the permissions that you need 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 to projects, folders, and organizations.
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.