The On-Demand Scanning API lets you scan images stored locally on your computer,or remotely in Artifact Registry. You can use On-Demand Scanning toscan images in your CI/CD pipeline, for system vulnerabilities andJava (Maven) package vulnerabilities before decidingwhether to store them in a registry. See thePricing page for pricing information.

This page describes how to manually scan container images for systemvulnerabilities and Maven packages vulnerabilities.

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.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the On-Demand Scanning API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the API

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.

Toinitialize the gcloud CLI, run the following command:

gcloudinit

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.create permission.Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the On-Demand Scanning API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

Enable the API

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.

Toinitialize the gcloud CLI, run the following command:

gcloudinit

1. Add thelocal-extract component to your Google Cloud CLIinstallation

   Using the Google Cloud CLI Component Manager

   The component manager will prompt you to install the required components the first time yourun the scanning command.

   Using your system package manager

   • For Debian/Ubuntu:

     sudoaptinstallgoogle-cloud-sdk-local-extract

   • For Red Hat/Fedora/CentOS:

     sudodnfinstallgoogle-cloud-sdk-local-extract

     Alternatively, you can replacednf withyum in the previous command.

2. Grant the IAM roleOn-Demand Scanning Admin to the user or service account that you aregoing to use with On-Demand Scanning. If you are using the owner account of the projectto run the scans, you can skip this step.

Scanning a container image

• Local scan:

  gcloudartifactsdockerimagesscanIMAGE_URI\[--location=(us,europe,asia)][--async]

  For a local image, use one of the following formats for theIMAGE_URI:

  • REPOSITORY:TAG
  • REPOSITORY

• Remote scan:

  gcloudartifactsdockerimagesscanIMAGE_URI\--remote[--location=(us,europe,asia)][--async]

  For a remote image, use one of the following formats for theIMAGE_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 theIMAGE_URI must include theREPOSITORY_ID.

For both local and remote scans, you can use the following optional flags:

• --location is an optional flag to manually select the multi-region wherethe scanning takes place. Choosing a multi-region closer to your physical locationminimizes latency. The available locations are:us,europe andasia. Thedefault location isus.

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

Synchronous scanning

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

$ gcloud artifacts docker images scan jenkins:2.60.3-alpine✓ 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: truemetadata:  '@type': type.googleapis.com/google.cloud.ondemandscanning.v1.AnalyzePackagesMetadata  createTime: '2021-01-05T23:03:04.185261Z'  resourceUri: jenkins:2.60.3-alpinename: projects/my-project/locations/us/operations/87d2e137-1d1c-4790-8e5e-daf6c96ae7d7response:  '@type': type.googleapis.com/google.cloud.ondemandscanning.v1.AnalyzePackagesResponsescan: projects/my-project/locations/us/scans/2fe2bfb8-f0c5-4dd6-a8c8-38961869767a

Use the scan name toretrieve the vulnerability results. In theexample, the scan name is the value ofscanin the last line of the outputmessage.

Asynchronous scanning

The following example shows the output of performing an asynchronous scan:

$ gcloud artifacts docker images scan jenkins:2.60.3-alpine --async✓ Scanning container image  ✓ Locally extracting packages and versions from local container image  ✓ Remotely initiating analysis of packages and versionsDone.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: jenkins:2.60.3-alpinename: projects/my-project/locations/us/operations/2e1a6b1f-16e5-4427-ac86-72c998a3dd16

This launches a long-running operation and returns its ID without blocking yourterminal. Use the operation ID, the value ofname in the last line of theoutput message, topoll the operation.

Polling the long-running operation

Use the operation ID from the output of they asynchronous scanning command tocheck the operation status:

gcloudartifactsdockerimagesget-operationLRO_ID

WhereLRO_ID is the long-running operation ID.

Continuing with the example of theasynchronous 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-72c998a3dd16done: truemetadata:  '@type': type.googleapis.com/google.cloud.ondemandscanning.v1.AnalyzePackagesMetadata  createTime: '2021-01-05T23:04:54.393510Z'  resourceUri: jenkins:2.60.3-alpinename: projects/my-project/locations/us/operations/2e1a6b1f-16e5-4427-ac86-72c998a3dd16response:  '@type': type.googleapis.com/google.cloud.ondemandscanning.v1.AnalyzePackagesResponsescan: projects/my-project/locations/us/scans/2fe2bfb8-f0c5-4dd6-a8c8-38961869767a

If the output includes the linedone: true, the scanning operation iscompleted. Use the scan name to retrieve the vulnerability results.The scan name is the value ofscan in the last line of the output message.

Retrieve the scan results

To retrieve the scanning results after the scanning operation is completed, usethe following command:

gcloudartifactsdockerimageslist-vulnerabilitiesSCAN_NAME[--limit=X]

Where:

• SCAN_NAME is the scan name. You can find it in the last line ofthe output when you eitherrun a synchronous scan orpoll thelong-running operation, after the scanning is finished.

• --limit=X is an optional flag that limits the number of occurrences shownin the output.X is a numeric value.

For example:

createTime: '2021-06-29T17:01:18.819477Z'kind: VULNERABILITYname: projects/my-project/locations/us/occurrences/06305977-f557-4772-8586-4260684291d3noteName: projects/my-project/notes/CVE-2014-0114resourceUri: jenkins:2.60.3-alpineupdateTime: '2021-06-29T17:01:18.819477Z'vulnerability:  cvssScore: 4.3  effectiveSeverity: MEDIUM  longDescription: http/conn/ssl/SSLConnectionSocketFactory.java in ...  packageIssue:  - affectedCpeUri: cpe:/o:alpine:alpine_linux:3.13    affectedPackage: org.apache.httpcomponents:httpclient    affectedVersion:      fullName: 4.0.2      kind: NORMAL      name: 4.0.2    effectiveSeverity: MEDIUM    fixedCpeUri: cpe:/o:alpine:alpine_linux:3.13    fixedPackage: org.apache.httpcomponents:httpclient    fixedVersion:      fullName: 4.3.6      kind: NORMAL      name: 4.3.6packageType: MAVEN  relatedUrls:  - label: More Info    url: https://security-tracker.debian.org/tracker/CVE-2015-5262  severity: MEDIUM  shortDescription: CVE-2015-5262

The output of this command is alist of occurrences in the Grafeas format. In thiscase, it shows one medium-level severity vulnerability found in the image. Mavenpackage vulnerabilities contain the fieldpackageType:MAVEN.

The scanning results are available for 48 hours after the scanning operation iscompleted.

What's next

• Use the On-Demand Scanning API in your Cloud Build pipeline.
• Use Artifact Analysis to scanand continuously update vulnerability information for your images stored inArtifact Registry.