Container Analysis

Container Analysis is a service that provides vulnerability scanning and metadata storage for software artifacts. The service performs vulnerability scans on built software artifacts, such as the images in Container Registry, then stores the resulting metadata and makes it available for consumption through an API. The metadata may come from several sources, including vulnerability scanning, other Cloud services, and third-party providers.

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

Vulnerability scanning

Software vulnerabilities are weaknesses that can either cause an accidental system failure or be intentionally exploited.

Container Analysis performs vulnerability scans on images in Container Registry and monitors the vulnerability information to keep it up to date. This process comprises two main tasks:

  • Incremental scanning: Container Analysis scans new images when they're uploaded to Container Registry. The scan gathers metadata based on the container manifest and updates this metadata every time you re-upload (re-push) the image.

  • Continuous analysis: Container Analysis continuously monitors the metadata of scanned images in Container Registry for new vulnerabilities. As Container Analysis receives new and updated vulnerability information from vulnerability sources, it re-analyzes the containers to keep the list of vulnerability occurrences for already scanned images up-to-date. It creates new occurrences for new notes, and deletes occurrences that are no longer valid. This type of analysis pertains only to package vulnerabilities and does not include other kinds of metadata.

When the scan of an image is completed, the produced vulnerability result is the collection of vulnerability occurrences for that image.

Vulnerability source

Container Analysis API supports package vulnerability scanning for Linux distributions and obtains CVE data from the following sources:

Severity levels for vulnerabilities

Container Analysis uses the following severity levels:

  • Critical
  • High
  • Medium
  • Low
  • Minimal

The severity levels are qualitative labels that reflect factors such as exploitability, scope, impact, and maturity of the vulnerability. For example, if a vulnerability enables a remote user to easily access a system and run arbitrary code without authentication or user interaction, that vulnerability would be classified as Critical.

Two types of severity are associated with each vulnerability:

  • Effective severity - The severity level assigned by the Linux distribution. If distribution-specific severity levels are unavailable, Container Analysis uses the severity level assigned by the note provider.

  • CVSS score - The Common Vulnerability Scoring System score and associated severity level. Refer to the CVSS 3.0 specification for details on how CVSS scores are calculated.

For a given vulnerability, the severity derived from a calculated CVSS score might not match the effective severity. Linux distributions that assign severity levels use their own criteria to assess the specific impacts of a vulnerability on their distributions.

Associating metadata with images

A high-level piece of metadata, such as a vulnerability or build information, is called a note. When Container Analysis analyzes an image, each instance of a note that it finds is identified as an occurrence.


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.

Discovery occurrences include information collected from the initial scan of container images. As it scans containers, Container Analysis updates discovery occurrences to record scan status. Discovery occurrences are created for all existing images when the Container Analysis API is first activated, and then for all new images pushed to Container Registry.

Supported metadata types

The following table lists the metadata types Container Analysis supports and provides for images in Container Registry as notes. 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.

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 provides 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 third-party providers.

Default Container Analysis service account

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 service-[PROJECT_NUMBER] This account uses the Container Analysis Service Agent role.

If you enable Vulnerability Scanning, the Container Scanning API used by this feature also uses a special Google account. The email for that service account is service-[PROJECT_NUMBER] The account uses the Container Scanner Service Agent role.

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

Container Analysis interfaces

In the Cloud Console, you can view image vulnerabilities and image metadata for containers in Container Registry.

You can use the gcloud tool to view vulnerabilities and image metadata.

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.

Controlling deployment of vulnerable images

You can integrate Container Analysis with Binary Authorization to prevent images with known security issues from running in your deployment environment.

What's next