Scanning images on demand

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

  1. 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.
  2. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

  4. Enable the On-Demand Scanning API.

    Enable the API

  5. Install and initialize the Cloud SDK.
  6. 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

    • For Debian/Ubuntu:
      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 dnf with yum in the previous command.

  7. 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]

Where:

  • --remote is 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:

    • HOSTNAME/PROJECT_ID/REPOSITORY_ID/IMAGE_ID@sha256:HASH
    • HOSTNAME/PROJECT_ID/REPOSITORY_ID/IMAGE_ID:HASH
    • HOSTNAME/PROJECT_ID/REPOSITORY_ID/IMAGE_ID
    • HOSTNAME/PROJECT_ID/IMAGE_ID@sha256:HASH
    • HOSTNAME/PROJECT_ID/IMAGE_ID:HASH
    • HOSTNAME/PROJECT_ID/IMAGE_ID

    For images in Artifact Registry the IMAGE_URI must include the REPOSTIORY_ID.

    For a local image, omit the --remote flag and use one of the following formats for the IMAGE_URI:

    • IMAGE_ID:TAG
    • IMAGE_ID
  • --location is 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: us, europe and asia. The default location is us.

  • --async is an optional flag to run the scanning process asynchronously. If you omit this flag your terminal will block until the scanning process is complete.

Synchronous scanning

The following example shows the output of a synchronous scan, without the --async flag:

$ 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.

Asynchronous scanning

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]

Where:

  • 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=X is an optional flag that limits the number of occurrences shown in the output.

For example:

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.

What's next