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](https://cloud.google.com/storage/pricing).

## Before you begin

1. 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](https://docs.cloud.google.com/artifact-registry/docs/docker/store-docker-container-images).
2. Have an SBOM file ready to upload in one of the [supported formats](https://docs.cloud.google.com/artifact-analysis/docs/upload-sbom#formats).

<br />

### 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](https://docs.cloud.google.com/iam/docs/roles-permissions/containeranalysis#containeranalysis.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](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## Supported formats

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

- [Software Package Data Exchange (SPDX)](https://spdx.dev/) version 2.2 or 2.3
- [CycloneDX](https://cyclonedx.org/) 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:

- <var translate="no">SOURCE</var>: the path to the SBOM file to upload.
- <var translate="no">URI</var>: 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](https://docs.cloud.google.com/artifact-analysis/docs/sbom-overview#sbom-ref).

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](https://docs.cloud.google.com/artifact-analysis/docs/view-sboms-dependencies#gcloud).

## What's next

- [View SBOMs and dependencies](https://docs.cloud.google.com/artifact-analysis/docs/view-sboms-dependencies).