View and filter SBOMs

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

  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.

    Go to project selector

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

  4. Enable the Container Analysis, Artifact Registry APIs.

    Enable the APIs

  5. Install the Google Cloud CLI.

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

    gcloud init
    7.

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

    Go to project selector

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

  9. Enable the Container Analysis, Artifact Registry APIs.

    Enable the APIs

  10. Install the Google Cloud CLI.

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

    gcloud init
    12.
  12. 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:

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:

  1. Open the Artifact Registry Repositories page.

    Open the Repositories page

    The page displays a list of your repositories.

  2. In the repositories list, click a repository name.

    The Repository details page opens and displays a list of your images.

  3. In the images list, click an image name.

    The page displays a list of your image digests.

  4. 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.

  5. 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

What's next