Scan OS packages manually

The On-Demand Scanning API allows you to scan images stored locally on your computer, or remotely in Artifact Registry or Container 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.

Note: Container Registry is deprecated and scheduled for shutdown. Organizations that haven't used Container Registry prior to January 8, 2024 have new gcr.io repositories hosted on Artifact Registry by default. After May 15, 2024, Google Cloud projects without previous usage of Container Registry will only support hosting and managing images for the gcr.io domain in Artifact Registry.

Container Registry is scheduled for shutdown on March 18, 2025. For details on the deprecation, see Container Registry deprecation.

This page describes how to manually scan container images with On-Demand Scanning.

Note: On-Demand Scanning runs in a Linux environment and in macOS. On-Demand Scanning is not supported on Windows.

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.

   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

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the On-Demand Scanning API.

   Enable the API

5. Install the Google Cloud CLI.

6. To initialize the gcloud CLI, run the following command:

   gcloud init

7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   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

8. Make sure that billing is enabled for your Google Cloud project.

9. Enable the On-Demand Scanning API.

   Enable the API

10. Install the Google Cloud CLI.

11. To initialize the gcloud CLI, run the following command:

    gcloud init

12. Add the local-extract component to your Google Cloud CLI installation

    Using the Google Cloud CLI 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.

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

• Local scan:

  gcloud artifacts docker images scan IMAGE_URI \
      [--location=(us,europe,asia)] [--async]
  

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

  • REPOSITORY:TAG
  • REPOSITORY

• Remote scan:

  gcloud artifacts docker images scan IMAGE_URI \
      --remote [--location=(us,europe,asia)] [--async]
  

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

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

• --location is a 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 a 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 scan name is the value of scan in 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. X is a numeric value.

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
  cvssv3:
    attackComplexity: ATTACK_COMPLEXITY_LOW
    attackVector: ATTACK_VECTOR_NETWORK
    availabilityImpact: IMPACT_HIGH
    baseScore: 7.2
    confidentialityImpact: IMPACT_HIGH
    exploitabilityScore: 1.2
    impactScore: 5.9
    integrityImpact: IMPACT_HIGH
    privilegesRequired: PRIVILEGES_REQUIRED_HIGH
    scope: SCOPE_UNCHANGED
    userInteraction: USER_INTERACTION_NONE
  effectiveSeverity: MEDIUM

The output of this command is a list of occurrences in the Grafeas format. In this case, it shows a medium-severity vulnerability found in the image.

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

What's next

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