This document describes how to access your software bill of materials (SBOM) records and related dependency metadata to help you understand the components of your container images stored in Artifact Registry.
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 Container Analysis, Artifact Registry 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 Container Analysis, Artifact Registry APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
- Have SBOMs stored in Cloud Storage. See instructions on generating SBOMs.
Required roles
To get the permissions that you need to view SBOM data and filter results, ask your administrator to grant you the following IAM roles on the project:
-
Container Analysis Occurrences Viewer (
roles/containeranalysis.occurrences.viewer
) -
Service Usage Consumer (
roles/serviceusage.serviceUsageConsumer
) -
Artifact Registry Reader (
roles/artifactregistry.reader
) -
To verify SBOMS:
Storage Object Viewer (
roles/storage.objectViewer
) - a specific Cloud Storage bucket
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.
View SBOMs in the Google Cloud console
To view SBOMs and related dependency metadata for container images stored in Artifact Registry:
Open the Artifact Registry Repositories page.
The page displays a list of your repositories.
In the repositories list, click a repository name.
The Repository details page opens and displays a list of your images.
In the images list, click an image name.
The page displays a list of your image digests.
In the image digest list, click a digest name.
The page displays a row of tabs where the Overview tab is open, showing details such as format, location, repository, virtual size, and tags.
In the row of tabs, click the Dependencies tab.
The dependencies tab opens and displays the following information:
- SBOM section
- Licenses section
- A filterable list of dependencies
SBOM
The SBOM summary section displays the following information:
- File: A clickable SBOM filename, which opens the location where your SBOM is saved in Cloud Storage.
- Type: The type of SBOM standard used, such as Software Package Data Exchange (SPDX) or Cyclone.
- Version: The version of the SBOM standard used.
- Generated by: The origin of the SBOM data, whether generated by Artifact Analysis or uploaded manually.
Licenses
The Licenses summary section displays a bar graph called Most common licenses. This represents the types of licenses that appear most often in your dependency information. When you hold the pointer over a bar in the graph, the console displays the exact count for instances of that license type.
Dependencies
The list of dependencies displays the contents of your image digest including:
- Package name
- Package version
- Package type
- License type
You can filter the list of dependencies by any of these categories.
View SBOMs in Cloud Build
If you're using Cloud Build, you can view image metadata in the Security insights side panel within the Google Cloud console.
The Security insights side panel provides a high-level overview of build 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 SBOMs with the gcloud CLI
Use the
gcloud artifacts sbom list
command to search for SBOMs stored in Cloud Storage. This search
applies to all of your SBOMs in Cloud Storage, including those
generated by Artifact Analysis and any you choose to upload from another
source using a supported format.
You can use filters with the gcloud command to narrow results and focus on SBOMs most relevant to a specific security concern or compliance request.
For example, the following command demonstrates how to obtain information about
the SBOM for a Docker image my-image
stored in Artifact Registry:
gcloud artifacts sbom list \
--resource="us-east1-docker.pkg.dev/my-project/my-repo/my-image:1.0"
Where:
--resource
specifies the image resource URI to list SBOM file references for.
Output includes the following:
- The Cloud Storage location for the SBOM. Using the Cloud Storage location, you can view the SBOM in the gcloud CLI by running the gcloud storage cat command.
- Whether the SBOM is still in the Cloud Storage bucket or has been removed.
- A hash of the SBOM which you can use to verify that it wasn't modified.
Filters
You can filter for specific SBOMs by using any of the following optional flags:
Flag | Purpose | Input value |
---|---|---|
--dependency |
List all SBOM file references where a resource has the specified package installed. See supported package types. | The name of an installed package |
--resource |
List SBOM file references related to a specific image. | The resource URI |
--resource-prefix |
List SBOM file references related to the resource path prefix. | A resource path, which will be used as a prefix for the search |
Filtering examples
Filter results by resource URI:
gcloud artifacts sbom list \
--resource="us-east1-docker.pkg.dev/project/repo/my-image@sha256:88b205d7995332e10e836514fbfd59ecaf8976fc15060cd66e85cdcebe7fb356"
Filter by resource prefix:
gcloud artifacts sbom list \
--resource-prefix="us-east1-docker.pkg.dev/project/repo"
Limitations
- License information is only provided for OS packages and supported language packages.
What's next
- Generate SBOMs.
- Learn how to use VEX statements.