Container Analysis provides vulnerability information for the container images in Container Registry and Artifact Registry. The metadata is stored as notes. An occurrence is created for each instance of a note associated with an image. See the overview and pricing documents for more information.
In this document you will learn how to enable the Container Analysis scanning API, push an image on Artifact Registry, and see the list of vulnerabilities found in the image.
Before you begin
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
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. Learn how to check if billing is enabled on a project.
-
Enable the Container Scanning API.
- 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. Learn how to check if billing is enabled on a project.
-
Enable the Container Scanning API.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
Create a repository and push a container image
Create a Docker repository in Artifact Registry and push a container image to the repository. If you are not familiar with Artifact Registry, see the Docker quickstart.
View the image vulnerabilities
Container Analysis scans new images when they're uploaded to Artifact Registry. This scan extracts information about the system packages in the container.
You can view vulnerability occurrences for your images in Container Registry or Artifact Registry using Google Cloud console, Google Cloud CLI, or the Container Analysis API. If an image has vulnerabilities, you can then obtain the details.
Container Analysis only updates the vulnerability metadata for images that were pushed or pulled in the last 30 days. Container Analysis archives vulnerability metadata that is older than 30 days. To re-scan an image with archived vulnerability metadata, push or pull that image.
Viewing occurrences in Google Cloud console
To see the vulnerabilities in an image:
Get the list of repositories.
In the repositories list, click a repository.
Click an image name.
Vulnerability totals for each image digest are displayed in the Vulnerabilities column.
To view the list of vulnerabilities for an image, click the link in the Vulnerabilities column.
The vulnerability list shows the severity, availability of a fix, and the name of the package that contains the vulnerability.
Google Cloud console displays up to 1200 vulnerabilities. If your image has more than 1200 vulnerabilities, use gcloud or the API to view the full list.
To learn more about a specific vulnerability from the vulnerability source, click the link in the Documentation column.
Viewing occurrences using gcloud
To view occurrences for an image:
Artifact Registry
gcloud artifacts docker images list --show-occurrences \
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID
Where:
- LOCATION is the regional or multi-regional location of the repository.
- PROJECT_ID is your Google Cloud project ID.
- REPOSITORY is the name of the repository where the image is stored.
- IMAGE_ID is the name of the image in the repository. You cannot specify an image tag with this command.
By default, the command returns the 10 most recent images. To show a
different number of images, use the --show-occurrences-from
flag.
For example, this command returns the 25 most recent images.
gcloud artifacts docker images list --show-occurrences-from=25 \
us-central1-docker.pkg.dev/my-project/my-repo/my-image
Container Registry
gcloud beta container images list-tags \
HOSTNAME/PROJECT_ID/IMAGE_ID
Where:
- HOSTNAME is the multi-regional hostname:
gcr.io
asia.gcr.io
eu.gcr.io
us.gcr.io
- PROJECT_ID is the ID of the project containing the images.
- IMAGE_ID is the ID of the image for which you want to view vulnerabilities. You cannot specify an image tag with this command.
By default, the command returns the 10 most recent images. To show a
different number of images, use the --show-occurrences-from
flag.
For example, this command returns the 25 most recent images.
gcloud beta container images list-tags --show-occurrences-from=25 \
gcr.io/my-project/my-image
To view vulnerabilities for an image tag or a layer:
Artifact Registry
gcloud artifacts docker images describe \
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID:TAG \
--show-package-vulnerability
or
gcloud artifacts docker images describe \
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID@sha256:HASH \
--show-package-vulnerability
Where:
- LOCATION is the regional or multi-regional location of the repository.
- PROJECT_ID is your Google Cloud project ID.
- REPOSITORY is the name of the repository where the image is stored.
- IMAGE_ID is the name of the image in the repository.
- TAG is the image tag about which you want to get information.
- HASH is the image digest.
Container Registry
gcloud beta container images describe HOSTNAME/PROJECT_ID/IMAGE_ID@sha256:HASH \
--show-package-vulnerability
Where:
- HOSTNAME is the multi-regional hostname:
gcr.io
asia.gcr.io
eu.gcr.io
us.gcr.io
- PROJECT_ID is the ID of the project containing the images.
- IMAGE_ID is the ID of the image for which you want to view vulnerabilities.
- HASH is the image digest.
To filter the vulnerability occurrences:
Artifact Registry
gcloud artifacts docker images list --show-occurrences \
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID --occurrence-filter=FILTER_EXPRESSION
Where:
- LOCATION is the regional or multi-regional location of the repository.
- PROJECT_ID is your Google Cloud project ID.
- REPOSITORY is the name of the repository where the image is stored.
- IMAGE_ID is the name of the image in the repository.
- FILTER_EXPRESSION is a sample filter expression in the format explained in Filtering vulnerability occurrences.
Container Registry
gcloud beta container images list-tags \
HOSTNAME/PROJECT_ID/IMAGE_ID --occurrence-filter=FILTER_EXPRESSION
Where:
- HOSTNAME is the multi-regional hostname:
gcr.io
asia.gcr.io
eu.gcr.io
us.gcr.io
- PROJECT_ID is the ID of the project containing the images.
- IMAGE_ID is the ID of the image for which you want to view vulnerability occurrences.
- FILTER_EXPRESSION is a sample filter expression in the format explained in Filtering vulnerability occurrences.
Viewing occurrences using the API or code
To view occurrences for an image, use the appropriate snippet. The code snippets specify URLs for images in Container Registry. If you are using Artifact Registry, specify images with a URL in the format:
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID
API
Using cURL
To get a list of occurrences in your project:
curl -X GET -H "Content-Type: application/json" -H \
"Authorization: Bearer $(gcloud auth print-access-token)" \
https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences
To get a summary of vulnerabilities in your project:
curl -X GET -H "Content-Type: application/json" -H \
"Authorization: Bearer $(gcloud auth print-access-token)" \
https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences:vulnerabilitySummary
To get an occurrence:
curl -X GET -H "Content-Type: application/json" -H \
"Authorization: Bearer $(gcloud auth print-access-token)" \
https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences/OCCURRENCE_ID
Java
To learn how to install and use the client library for Container Analysis, see Container Analysis client libraries. For more information, see the Container Analysis Java API reference documentation.
To authenticate to Container Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Container Analysis, see Container Analysis client libraries. For more information, see the Container Analysis Go API reference documentation.
To authenticate to Container Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Container Analysis, see Container Analysis client libraries. For more information, see the Container Analysis Node.js API reference documentation.
To authenticate to Container Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Container Analysis, see Container Analysis client libraries. For more information, see the Container Analysis Ruby API reference documentation.
To authenticate to Container Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Container Analysis, see Container Analysis client libraries. For more information, see the Container Analysis Python API reference documentation.
To authenticate to Container Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Viewing occurrences in Cloud Build
If you're using Cloud Build, you can also view image vulnerabilities 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.
Filtering occurrences
You can use filter strings in the gcloud
commands and the
Container Analysis API to filter occurrences before viewing them. The
following sections describe the supported search filters.
Viewing discovery occurrences
When an image is initially pushed to the Container Registry, it creates a discovery occurrence, which contains information about the initial scan of the container image.
To retrieve the discovery occurrence for an image, use the following filter expression:
kind="DISCOVERY" AND resourceUrl="RESOURCE_URL"
The following snippet shows how to use the above filter expression to view discovery occurrences for an image. The code snippets specify URLs for images in Container Registry. If you are using Artifact Registry, specify images with a URL in the format:
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID
gcloud
To view discovery occurrences for an image:
In this case the expression is not used directly in the command, but the same information is passed as arguments:
Artifact Registry:
gcloud artifacts docker images list --show-occurrences \
--occurrence-filter='kind="DISCOVERY"' --format=json \
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID
Container Registry:
gcloud beta container images list-tags \
--occurrence-filter='kind="DISCOVERY"' --format=json HOSTNAME/PROJECT_ID/IMAGE_ID
API
To retrieve the discovery occurrence, the above filter expression should be URL
encoded and embedded in a GET
request as follows:
GET https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences?filter=kind%3D%22DISCOVERY%22%20AND%20resourceUrl%3D%22ENCODED_RESOURCE_URL%22
See
projects.occurrences.get
API endpoint for more details.
Java
To learn how to install and use the client library for Container Analysis, see Container Analysis client libraries. For more information, see the Container Analysis Java API reference documentation.
To authenticate to Container Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Container Analysis, see Container Analysis client libraries. For more information, see the Container Analysis Go API reference documentation.
To authenticate to Container Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Container Analysis, see Container Analysis client libraries. For more information, see the Container Analysis Node.js API reference documentation.
To authenticate to Container Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Container Analysis, see Container Analysis client libraries. For more information, see the Container Analysis Ruby API reference documentation.
To authenticate to Container Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Container Analysis, see Container Analysis client libraries. For more information, see the Container Analysis Python API reference documentation.
To authenticate to Container Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Viewing vulnerability occurrences
To view vulnerability occurrences for a specific image, create a query with a filter expression:
kind="VULNERABILITY" AND resourceUrl="RESOURCE_URL"
The following snippet shows how to retrieve a list of vulnerability occurrences for an image. The code snippets specify URLs for images in Container Registry. If you are using Artifact Registry, specify images with a URL in the format:
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID
gcloud
To view vulnerability occurrences for an image:
In this case the expression is not used directly in the command, but the same information is passed as arguments:
Artifact Registry
gcloud artifacts docker images list --show-occurrences \
--occurrence-filter='kind="VULNERABILITY"' --format=json \
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_ID
Container Registry
gcloud beta container images list-tags \
--occurrence-filter='kind="VULNERABILITY"' --format=json HOSTNAME/PROJECT_ID/IMAGE_ID
API
The desired resource URL should be URL encoded, and embedded in a GET request as follows:
GET https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences?filter=kind%3D%22VULNERABILITY%22%20AND%20resourceUrl%3D%22ENCODED_RESOURCE_URL%22
See
projects.occurrences.get
API endpoint for more details.
Java
To learn how to install and use the client library for Container Analysis, see Container Analysis client libraries. For more information, see the Container Analysis Java API reference documentation.
To authenticate to Container Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Container Analysis, see Container Analysis client libraries. For more information, see the Container Analysis Go API reference documentation.
To authenticate to Container Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Container Analysis, see Container Analysis client libraries. For more information, see the Container Analysis Node.js API reference documentation.
To authenticate to Container Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Container Analysis, see Container Analysis client libraries. For more information, see the Container Analysis Ruby API reference documentation.
To authenticate to Container Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Container Analysis, see Container Analysis client libraries. For more information, see the Container Analysis Python API reference documentation.
To authenticate to Container Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Viewing occurrences of a specific type
In the two previous examples the only difference between the filter expressions
is the value of kind
, which identifies the type of occurrence. Use
this field to limit the list of occurrences to a particular type, such as a
vulnerability or deployment.
To retrieve occurrences for a specific image, use this filter expression:
kind="NOTE_KIND" AND resourceUrl="RESOURCE_URL"
Where:
- NOTE_KIND is the
kind of note.
- For example, use the kind
DISCOVERY
to list discovery occurrences. These are created for images when they are initially pushed to the Container Registry. - To list vulnerability occurrences, use the kind
VULNERABILITY
.
- For example, use the kind
-
RESOURCE_URL is the complete URL of the image
https://HOSTNAME/PROJECT_ID/IMAGE_ID@sha256:HASH
The filter expression to retrieve occurrences of a specific kind across many images is:
kind="NOTE_KIND" AND has_prefix(resourceUrl, "RESOURCE_URL_PREFIX")
Where:
- RESOURCE_URL_PREFIX is the URL prefix for some images
- To list for all version of an image:
https://HOSTNAME/PROJECT_ID/IMAGE_ID@
- To list for all images in a project:
https://HOSTNAME/PROJECT_ID/
- To list for all version of an image:
Viewing images associated with a specific note
You can retrieve a list of resources that are associated with a specific note ID. For example, you can list images with a specific CVE vulnerability.
To list all images within a project that are associated with a particular note, use the following filter expression:
noteProjectId="PROVIDER_PROJECT_ID" AND noteId="NOTE_ID"
To check a specific image for a specific note, use the following filter expression:
resourceUrl="RESOURCE_URL" AND noteProjectId="PROVIDER_PROJECT_ID" \ AND noteId="NOTE_ID"
Where:
- PROVIDER_PROJECT_ID is the ID of the provider project. For
example,
goog-vulnz
provides the default vulnerability analysis. - NOTE_ID is the ID of the note. Security related notes are often
formatted as
CVE-2019-12345
. -
RESOURCE_URL is the complete URL of the image
https://HOSTNAME/PROJECT_ID/IMAGE_ID@sha256:HASH
For example, to check for all images that have an occurrence of CVE-2017-16231 as analyzed by Google, use the following filter expression:
noteProjectId="goog-vulnz" AND noteId="CVE-2017-16231"
What's next
Use Pub/Sub notifications to get notifications about vulnerabilities and other metadata.
Kritis Signer and Voucher allow you create Binary Authorization attestations as part of your build pipeline. These tools can create Binary Authorization attestations based on vulnerability scanning results. For more information, see Creating attestations with Kritis Signer or Creating attestations with Voucher.