This document explains how to enable the Container Scanning API, push an image to Artifact Registry, and see the list of vulnerabilities found in the image.
Artifact Analysis stores vulnerability information 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.
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.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Artifact Registry and Container Scanning APIs.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.-
Install the Google Cloud CLI.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
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.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Artifact Registry and Container Scanning APIs.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.-
Install the Google Cloud CLI.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
To initialize the gcloud CLI, run the following command:
gcloud init - Create a Docker repository in Artifact Registry and push a container image
with your npm code to the repository. If you are not familiar with
Artifact Registry, see the
Docker quickstart.
View the image vulnerabilities
Artifact Analysis scans new images when they're uploaded to Artifact Registry. This scan extracts information about the packages in the container.
You can view vulnerability occurrences for your images in Artifact Registry using the Google Cloud console, Google Cloud CLI, or the Container Analysis API. If an image has vulnerabilities, you can then obtain the details.
Artifact Analysis continues to scan images and packages as long as they have been pulled within the last 30 days. After 30 days, metadata for scanned images and packages will no longer be updated, and the results will be stale.
Artifact Analysis archives metadata that has been stale for more than 90 days. This archived metadata can be evaluated only by using the API. You can re-scan an image with stale or archived metadata by pulling that image. Refreshing metadata can take up to 24 hours. Packages with stale or archived metadata can't be rescanned.
View occurrences in the Google Cloud console
To see the vulnerabilities in an image:
Get the list of repositories.
In the repositories list, click a repository.
In the images list, 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 Scan results section displays a summary of the package types scanned, total vulnerabilities, vulnerabilities with fixes available, vulnerabilities without fixes, and effective severity.
The table of vulnerabilities lists the Common Vulnerabilities and Exposures (CVE) name for each vulnerability found, the effective severity, Common Vulnerability Scoring System (CVSS) score, fixes (when available), the name of the package that contains the vulnerability, and the package type.
Google Cloud console displays up to 1200 vulnerabilities per page in this table. You can filter and sort these files to check a specific file, directory, layer, or type of file by file extension.
For details about a specific CVE, click the CVE name.
To view vulnerability occurrence details such as version number and affected location, in the row with the name of the vulnerability, click View or View Fixed. The link text is View for vulnerabilities without a fix, and View Fixed for vulnerabilities where a fix has been applied.
View vulnerabilities in a specific layer
Artifact Analysis provides layer-specific metadata to help you identify which package contains vulnerabilities, and which Docker build command introduced that layer.To view layer-based vulnerability metadata in the Google Cloud console:
In Artifact Registry, open your list of repositories.
In the Repositories page, click a repository.
In the Repository Details page, click an image.
In the image version list, click an image digest.
In the image digest details page, click the Vulnerabilities tab.
When layer-based metadata is available, Artifact Analysis shows a selectable list of layers in the Layer bar:
To see the list of layers, click the layer drop-down menu.
A drop-down list opens, showing a numbered list of layers. Layer 0 represents the bottom layer, with each following layer building on the previous layer. Only layers where vulnerabilities have been found are shown.
For each layer, Artifact Analysis shows the Docker command used to build the layer and the number of vulnerabilities found in that layer.
To learn more about the vulnerabilities in a specific layer, select a layer from the layer list.
The table of vulnerabilities updates to show only the vulnerabilities found in the selected layer. You can apply more filters or investigate specific vulnerabilities.
Click VIEW or VIEW FIX beside a vulnerability to see more detailed vulnerability information.
The Vulnerability details side panel shows file locations where packages have vulnerabilities.
In the File location(s) table, hover over the question mark to open additional layer metadata.
A dialog displays the layer index, layer build command, layer digest, and base image where you can remediate the vulnerability.
View occurrences using gcloud
To view occurrences for images in Artifact Registry, run the
gcloud artifacts docker images list
command:
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 console 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 results. To show a
different number of results, use the --show-occurrences-from flag.
For example, the following command returns the 25 most recent results:
gcloud artifacts docker images list --show-occurrences-from=25 \
us-central1-docker.pkg.dev/my-project/my-repo/my-image
The output looks similar to:
Sample image output
{
"name": "projects/my-project/locations/us-central1/occurrences/22d3edfb-34f2-4d3f-be08-fd90c549f010",
"resource": {
"uri": "https://us-central1-docker.pkg.dev/my-project/my-repo/golang-nginx@sha256:5b54ef20748417ccdb0b87afedf98c44e699e2f59bd6cv48cbdc1ca2e72c80e3"
},
"noteName": "projects/my-project/locations/us-central1/notes/CVE-2005-2541",
"kind": "VULNERABILITY",
"createTime": "2025-01-21T15:57:01.238832Z",
"updateTime": "2025-01-21T15:57:01.238832Z",
"vulnerability": {
"severity": "CRITICAL",
"cvssScore": 10,
"packageIssue": [
{
"affectedLocation": {
"cpeUri": "cpe:/o:debian:debian_linux:12",
"package": "tar",
"version": {
"name": "1.34+dfsg",
"revision": "1.2+deb12u1",
"kind": "NORMAL"
}
},
"fixedLocation": {
"cpeUri": "cpe:/o:debian:debian_linux:12",
"package": "tar",
"version": {
"kind": "MAXIMUM"
}
},
"packageType": "OS",
"effectiveSeverity": "LOW",
"file_location": [
{
"file_path": "/var/lib/dpkg/status",
"layerDetails": {
"index": 0,
"diffID": "sha256:123",
"buildCommand": "FROM golang:example_sha256",
"BaseImages": [
{
"name": "library/golang",
},
],
},
},
],
}
],
"shortDescription": "CVE-2005-2541",
"longDescription": "NIST vectors: AV:N/AC:L/Au:N/C:C/I:C/A:C",
"relatedUrls": [
{
"url": "https://security-tracker.debian.org/tracker/CVE-2005-2541",
"label": "More Info"
}
],
"effectiveSeverity": "LOW",
"cvssVersion": "CVSS_VERSION_2",
"cvssV2": {
"baseScore": 10,
"attackVector": "ATTACK_VECTOR_NETWORK",
"attackComplexity": "ATTACK_COMPLEXITY_LOW",
"authentication": "AUTHENTICATION_NONE",
"confidentialityImpact": "IMPACT_COMPLETE",
"integrityImpact": "IMPACT_COMPLETE",
"availabilityImpact": "IMPACT_COMPLETE"
}
}
}
Filter vulnerability occurrences
To filter vulnerability occurrences, use --occurrence-filter parameter: