Container Analysis

Container Analysis provides metadata for the container images in Container Registry. Additionally, third-party metadata providers can use Container Analysis to store and retrieve metadata for their customer's images.

This page describes the kinds of metadata that Container Analysis supports and some key concepts and terminologies.

Supported metadata types

The following table lists all the metadata types Container Analysis supports and provides for images in Container Registry. Third-party metadata providers can store and retrieve all of the following metadata types for their customers' images.

Metadata type Provided by Container Analysis for Container Registry images
Vulnerability, which provides vulnerability information for container images. Yes. Container Analysis obtains the vulnerability information from external sources.
Build, which provides information on build provenance. Yes. Container Analysis provides this information only if you use Cloud Build to build the image.
Deployment, which provides information on image deployment events. No
Image, which is the metadata about the container image, for example, information about the different layers of an image. No
Package, which contains information about the packages installed in your image. No
Attestation, which is the logical role that can attest to the images. No
Discovery, contains information about the initial scan of images. Yes. Container Analysis provides this information only for vulnerabilities.

Default Container Analysis service account and Cloud Pub/Sub topics

Container Analysis analyzes your container images using a service account, a special Google account that collects information about your images on your behalf. The email for the Container Analysis service account is [PROJECT_NUMBER]

You can view your project's service accounts via the IAM menu of the GCP Console.

When you enable the Container Analysis API, the service account is automatically created and granted the Container Vulnerability Scanner Service Agent Editor role for your project.

Do not edit or delete this service account. If you delete this service account accidentally, disable and then reenable the Container Analysis API.

When you enable the Container Analysis API, it automatically creates a number of subscriptions for the topic projects/[PROJECT_ID]/topics/gcr. These subscriptions are of the form projects/[PROJECT_ID]/subscriptions/gcr-analysis-[SUBSCRIPTION_ID]. The subscriptions are used by Container Analysis to scan your images in Container Registry. Do not edit or delete the topic or subscriptions. If you delete them accidentally, disable and then reenable the Container Analysis API.

Concepts and terminologies

To use Container Analysis effectively, you must understand some of the concepts on which it is built. This section provides an overview of the terminology and concepts that apply to Container Analysis.


A note describes a high-level piece of metadata. For example, you could create a note about a particular vulnerability after analyzing a Linux package. You would also use a note to store information about the builder of a build process. Notes are often owned and created by the providers performing the analysis. Notes are generally found by analyzing the container images and occur multiple times across different projects.

It is recommended to store notes and occurrences in separate projects, allowing for more fine-grained access control.

Notes must be editable only by the note owner, and read-only for customers who have access to occurrences referencing them.


An occurrence represents when a note was found on an image; it can be thought of as an instantiation of a note. For example, an occurrence of a note about a vulnerability would describe the package that the vulnerability was found in, specific remediation steps, and so on. Alternatively, an occurrence of a note about build details would describe the container images that resulted from a build.

Typically, occurrences are stored in separate projects than those where notes are created. Write access to occurrences should only be granted to users who have access to link a note to the occurrence. Any user can have read access to occurrences.

Vulnerability result

A vulnerability result is a collection of vulnerability occurrences for an image.

Vulnerability source

Container Analysis API supports package vulnerability scanning for Ubuntu, Debian, and Alpine and obtains the CVE data from the following sources:

Severity levels for vulnerabilities

Container Analysis assigns severity levels to the vulnerabilities based on CVSS scores. The following tables maps the CVSS score to the vulnerability level:

CVSS score Vulnerability level
>= 9.0 Critical
(9, 7] High
(7, 4] Medium
< 4.0 Low

Providers and customers

Providers are the companies that provide metadata for their customers' images. Providers can use Container Analysis to store and retrieve metadata for their customers' images. For example, a company that provide security management for their customers' Docker containers can use Container Analysis to store and retrieve security-related metadata for the images. For more information see Providing metadata for Projects.

Customers use the metadata provided either by Google for the images in Container Registry or by the third-party providers.

Discovery occurrences

Discovery occurrences contain information about the initial scan of container images. They are created for all existing images when the Container Analysis API is first activated, and then for the new images when they're pushed to Container Registry.

Types of vulnerability scanning

Container Analysis performs the following types of vulnerability scanning for the images in Container Registry:

  • Initial scanning: When you first activate the Container Analysis API, it performs a scan of all your existing images in Container Registry and extracts package manager, image basis, and vulnerability occurrences for the images. After initial scanning is complete, Container Analysis creates a discovery occurrence with these metadata.

  • Incremental scanning: Container Analysis scans new images as and when they're uploaded to Container Registry.

  • Continuous scanning: Container Analysis scans all the images periodically and makes sure that the vulnerability occurrences for already scanned images are up to date. It creates new occurrences for new notes, and deletes occurrences that are no longer relevant. This type of scanning only pertains to package vulnerabilities and does not look for other kinds of metadata.

Container Analysis interfaces

In the GCP Console, you can view the vulnerability information for images in the Container Registry page.

You can use the gcloud tool to view vulnerability information.

You can also use the Container Analysis REST API to perform any of these actions. As with other Cloud Platform APIs, you must authenticate access using OAuth2. After you have authenticated, you can use the API to create new notes and occurrences, view vulnerability occurrences, etc.

The Container Analysis API supports both gRPC and REST/JSON. You can make calls to the API either using the client libraries or using cURL for REST/JSON.

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Container Registry