The On-Demand Scanning API allows you to scan images stored locally on your computer, in Container Registry, or in Artifact Registry. This gives you granular control over the containers you want to scan for vulnerabilities. You can use On-Demand Scanning to scan images in your CI/CD pipeline before deciding whether to store them in a registry.
See the Pricing page for pricing information.
This page describes how to manually scan container images with On-Demand Scanning.
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 Cloud project. Learn how to confirm that billing is enabled for your project.
- Enable the On-Demand Scanning API.
- Install and initialize the Cloud SDK.
Add the local-extract component to your Cloud SDK installation
Using the Cloud SDK Component Manager
The component manager will prompt you to install the required components the first time you run the scanning command.
Using your system package manager
sudo apt install google-cloud-sdk-local-extract
For Red Hat/Fedora/CentOS:
sudo dnf install google-cloud-sdk-local-extract
Alternatively, you can replace
yumin the previous command.
- For Debian/Ubuntu:
- Grant the IAM role On-Demand Scanning Admin to the user or service account that you are going to use with On-Demand Scanning. If you are using the owner account of the project to run the scans, you can skip this step.
Scanning a container image
To scan a container image use the following command:
gcloud artifacts docker images scan IMAGE_URI [--remote] [--location=(us,europe,asia)] [--async]
--remoteis an optional flag that you must use if your image is hosted remotely, on Artifact Registry or Container Registry. For a remote image, use one of the following formats for the IMAGE_URI:
For images in Artifact Registry the IMAGE_URI must include the
For a local image, omit the
--remoteflag and use one of the following formats for the IMAGE_URI:
--locationis an optional flag to manually select the multi-region where the scanning takes place. Choosing a multi-region closer to your physical location minimizes latency. The available locations are:
asia. The default location is
--asyncis an optional flag to run the scanning process asynchronously. If you omit this flag your terminal will block until the scanning process is complete.
The following example shows the output of a synchronous scan, without the
$ gcloud artifacts docker images scan ubuntu:latest ✓ Scanning container image ✓ Locally extracting packages and versions from local container image ✓ Remotely initiating analysis of packages and versions ✓ Waiting for analysis operation to complete [projects/my-project/locations/us/operations/87d2e137-1d1c-4790-8e5e-daf6c96ae7d7] Done. done: true metadata: '@type': type.googleapis.com/google.cloud.ondemandscanning.v1.AnalyzePackagesMetadata createTime: '2021-01-05T23:03:04.185261Z' resourceUri: ubuntu:latest name: projects/my-project/locations/us/operations/87d2e137-1d1c-4790-8e5e-daf6c96ae7d7 response: '@type': type.googleapis.com/google.cloud.ondemandscanning.v1.AnalyzePackagesResponse scan: projects/my-project/locations/us/scans/2fe2bfb8-f0c5-4dd6-a8c8-38961869767a
Use the scan name to retrieve the vulnerability results. The name is
the value of
scanin the last line of the output message.
The following example shows the output of performing an asynchronous scan:
$ gcloud artifacts docker images scan ubuntu:latest --async ✓ Scanning container image ✓ Locally extracting packages and versions from local container image ✓ Remotely initiating analysis of packages and versions Done. Check operation [projects/cloud-project/locations/us/operations/2e1a6b1f-16e5-4427-ac86-72c998a3dd16] for status. metadata: '@type': type.googleapis.com/google.cloud.ondemandscanning.v1.AnalyzePackagesMetadata createTime: '2021-01-05T23:04:54.393510Z' resourceUri: ubuntu:latest name: projects/my-project/locations/us/operations/2e1a6b1f-16e5-4427-ac86-72c998a3dd16
This launches a long-running operation and returns its ID without blocking your
terminal. Use the operation ID, the value of
name in the last line of the
output message, to poll the operation.
Polling the long-running operation
Use the operation ID, from the output of they asynchronous scanning command, to check the operation status.
gcloud artifacts docker images get-operation LRO_ID
Where LRO_ID is the long-running operation id.
Continuing with the example of the asynchronous scanning section, to check the status of the operation:
$ gcloud artifacts docker images get-operation \ projects/cloud-project/locations/us/operations/2e1a6b1f-16e5-4427-ac86-72c998a3dd16 done: true metadata: '@type': type.googleapis.com/google.cloud.ondemandscanning.v1.AnalyzePackagesMetadata createTime: '2021-01-05T23:04:54.393510Z' resourceUri: ubuntu:latest name: projects/my-project/locations/us/operations/2e1a6b1f-16e5-4427-ac86-72c998a3dd16 response: '@type': type.googleapis.com/google.cloud.ondemandscanning.v1.AnalyzePackagesResponse scan: projects/my-project/locations/us/scans/2fe2bfb8-f0c5-4dd6-a8c8-38961869767a
If the output includes the line
done: true, the scanning operation is
completed. Use the scan name to retrieve the vulnerability results.
The name is the value of
scan in the last line of the output message
Retrieve the scan results
To retrieve the scanning results after the scanning operation is completed, use the following command:
gcloud artifacts docker images list-vulnerabilities SCAN_NAME [--limit=X]
- SCAN_NAME is the scan name. You can find it at the bottom of the output when you poll the long-running operation, after the scanning is finished.
--limit=Xis an optional flag that limits the number of occurrences shown in the output.
gcloud artifacts docker images list-vulnerabilities \ projects/my-project/locations/us/scans/2fe2bfb8-f0c5-4dd6-a8c8-38961869767a createTime: '2021-01-05T23:05:42.956227Z' kind: VULNERABILITY name: projects/my-project/locations/us/occurrences/f82a1efd-a261-4973-acbd-f9854d8b8135 noteName: projects/goog-vulnz/notes/CVE-2018-1000654 resourceUri: ubuntu:latest updateTime: '2021-01-05T23:05:42.956227Z' vulnerability: cvssScore: 7.1 effectiveSeverity: LOW packageIssue: - affectedCpeUri: cpe:/o:canonical:ubuntu_linux:20.04 affectedPackage: libtasn1-6 affectedVersion: kind: NORMAL name: 4.16.0 revision: '2' fixedCpeUri: cpe:/o:canonical:ubuntu_linux:20.04 fixedPackage: libtasn1-6 fixedVersion: kind: MAXIMUM severity: HIGH
The output of this command is a list of occurrences in the Grafeas format. In this case, it shows a high-severity vulnerability found in the image.
The scanning results are available for 48 hours after the scanning operation is completed.
- Learn about On-Demand Scanning concepts.
- Use Container Analysis to scan and continuously update vulnerability information for your images stored in Artifact Registry and Container Registry.