1. Overview

Prisma Cloud can scan container images in both public and private repositories on both public and private registries.

The registry is a system for storing and distributing container images. The most well-known public registry is Docker Hub, although there are also registries from Amazon, Google, and others. Organizations can also set up their own internal private registries. Prisma Cloud can scan container images on all of these types of registries.

After repository scanning is configured, Prisma Cloud automatically scans images for vulnerabilities. Periodic scans are run at an interval specified in Configure > System > Scan (by default, once every 24 hours).

2. Deployment patterns

Registry scanning is handled by Defenders. When you configure Prisma Cloud to scan a registry, you can select the scope of defenders that will be used for performing the scan job.

Any Container Defender running on a host with the Docker Engine container runtime or container runtime interface (CRI) can scan a registry, and any number of them can simultaneously operate as registry scanners. This gives you a lot of options when you’re trying to determine how to cover disparate environments.

Select a collection of defenders defined by hostnames or AWS tags, and the scan job will be distributed between them according to the "Number of scanners" setting. When selecting the "All" collection, you let Prisma Cloud automatically distribute the scan job across all available Defenders.

In general, you should configure Prisma Cloud with a large scope of defenders, because it reduces operational complexity and improves resiliency. At scan-time, Prisma Cloud enumerates the available Defenders according to your scope, manages the resource pool, and handles issues such as restarting partially completed jobs. If you explicitly select one or two defenders to handle scanning, the hosts where these Defenders run are a single point of failure. If the host fails, or gets destroyed, you have to reconfigure your scan settings with different Defenders.

Registry scanning is scoped by OS type. Windows Defenders can only scan Windows images, and Linux Defenders can only scan Linux images.

If you remove an image from the registry, or the registry becomes unavailable, Prisma Cloud maintains the scan results according to your setup under Manage > System > Scan > Registry scan results. After the specified number of days, the scan results are purged.

3. Registry scan settings

Each rule has the following parameters, although the parameters can vary according to registry type. For step-by-step instructions for a registry from a specific vendor, see the appropriate registry-specific guide.

Field Description

Version

Specify the type of registry to scan.

  • If you do not find your vendor’s registry in the drop-down list, try Docker Registry v2. Most vendors comply with the Docker Registry version 2 API.

Registry

Specify the URL for the registry.

Docker Hub: leave this field blank.

Harbor: specify the FQDN of your Harbor registry (https://).

Repository name

Specify the repository to scan. This field supports pattern matching. To scan all repositories, simply leave this field blank or enter a wildcard (*).

Docker Hub: To specify an official Docker repository, enter library/, followed by the short string used to designate the repo. For example, to scan the images in the official Alpine Linux repository, enter library/alpine.

To specify non-official repositories, enter the user name or organization name, followed by a slash, followed by the name of the repo. For example, to specify the alpine repository in onescience’s account, enter onescience/alpine.

To scan all repos from a user or organization, simply enter the user or organization name, followed by a wildcard (*). For example, to scan all repos created by onescience, enter onescience*.

Google Cloud Platform Container Registry: Enter your project ID and image name in the following format: project-id/image-name. To scan all images, follow the repository name with /*. (e.g. company-sandbox/*)

Harbor: Enter the name of the repository, followed by a wildcard (*). For example, to scan repository library, enter library*.

Any Docker Registry version 2 API compliant registry: Docker Hub, Docker Registry, and Alibaba Container Registry all support the Docker Registry version 2 API.

Tag

Specify an image tag. Leave this field blank to scan all tags (limited by the value in Cap).

Credentials

Specify the credentials required to access the registry. If the credentials have already been created in the Prisma Cloud credential store, select it. If not, click Add New.

Public repositories on public registries (such as Docker Hub): Leave this field blank. No credentials are required.

AWS EC2 Container Registry: Use the IAM access keys for authentication. For more information, see Amazon EC2 Container Registry (ECR).

Google Container Registry: Use the service account and JSON token. For more information, Google Container Registry (GCR).

Harbor Registry: Create a Basic authentication credential. Credentials for Harbor can be a Limited Guest.

Registries that support token authentication (e.g. Quary, GitLab): Create a Basic authentication credential. Username is the name of the token and the token value is entered into the password field.

OS Type

Specify whether the image is built on a Windows or Linux base OS.

Scanners scope

Select collections of Defenders to scan this registry.

Only Linux Defenders can scan Linux container images, and only Windows Defenders can scan Windows container images.

Number of scanners

Number of Defenders from scope across which the scan job can be distributed. Increase the number of Defenders to increase throughtput and reduce scan time.

Cap

Specify the maximum number of images to scan in the given repository, sorted according to last modified date. That is, the most recently modified image in each repository is scanned first, followed by the image next most recently modified, and so on.

The Docker Registry API does not support directly querying for the most recently updated images. To handle your CAP setting, Prisma Cloud first polls the registry for all tags and manifests in the given repository to discover the last updated dates. This is a low overhead operation because images do not need to be downloaded. Prisma Cloud then sorts the results by date, and then scans the most recently updated images in each repository up to the limit specified by CAP. Even when CAP is set to a low number, you might still notice the Prisma Cloud UI polling the registry for data about the images in the repository.

To scan all images in a repository, set CAP to 0.

Version matching pattern

Customize sort order by values in the image tag. Specify a pattern from which a version or date can be extracted from the image tag. There are two use cases for specifying version matching patterns:

  • You want to reduce the total time it takes to complete the scan for very large registries. Rather than fetching the metadata from the registry required to sort images, you specify how the scanner can extract the metadata directly from the image tag.

  • You want to order and cap the images to be scanned by some value other than last modified date.

Specify patterns with strings, wildcards, timedate elements, and integers.

  • %d - version number

  • %Y - 4 digit year

  • %M - 2 digit month

  • %D - 2 digit day

  • %H - 2 digit hour

  • %m - 2 digit minute

  • %s - 2 digit second

For image tags that match the pattern, the tag is split into its constituent parts. After all image tags are parsed, they’re ordered and capped according to the value set in Cap.

Ordering is best-effort. Tags that don’t conform to the pattern are ignored.

If both date and version are specified in your pattern, date takes precendence.

If the version matching pattern is left unspecified, Prisma Cloud orders images by last modified date.

4. Configure Prisma Cloud to scan a registry

To scan images in a registry, create a new registry scan rule.

  1. Open Console.

  2. Go to Defend > Vulnerabilities > Registry.

  3. Click Add registry settings.

5. Registries on a large scale

When you have very large registries, or a large amount of regitries, you must optimize your scan configuration to maximize throughput and minimize scan time. Follow the instructions below to improve your registry scanning process:

  1. For large registries or aggressive scan intervals, increase the number of scanners in the scope.

    The number of scanning defenders should increase with regard to the registry size. As the number of images in the registry increases, so does the number of defenders scanning this registry.

  2. Use the deafult cap value (Cap = 5) in your registry scan configuration.

    The scanner makes many API calls to the registry to retrieve metadata for the registry, repos, and images. All metadata must be collected, collated, and sorted before scanning can start. Consider the normal flow for collecting metadata:

    Get a list of all repos in the registry
    For each repo:
      Get a list of all image tags
      For each image tag:
        Get the image manifest (which contains the last modified date)
    
    Sort, Cap, Scan

    After fetching all metadata, the scanner sorts the images by last modified date, and caps the list if a cap value is specified in the scan configuration. The default cap value is 5. With a cap of 5, the scanner fetches the five most recently modified images from each repository in the registry for scanning.

    When setting a large number for cap, or setting cap to 0 (to scan all images in a repository), the registry scan will be longer.

  3. Use version matching pattern in your registry scan configuration.

    Optimizing registry scans with version pattern matching is only necessary for very large registries with tens of thousands of repositories and millions of images.

    Further to the previous section on cap, if you specify a version matching pattern, the scanner looks to the image tag for sort order. Without a version matching pattern, the sort order is last modified date. With a version matching pattern, you customize how the scanner interprets image tags for sorting. For example, if you utilize semantic versioning in your image names, you could specify the following version pattern:

    *-%d.%d.%d

    The scanner parses each image tag, extracts the pattern from the tag, and splits it into its constituent parts. After all tags are parsed, they are sorted, and capped according to your configuration. The optimized flow for collecting metadata eliminates the inner loop, substantially reducing the number of requests to the registry so scanning can start sooner.

    Get a list of all repos in the registry
    For each repo:
      Get a list of all images tags
    
    Sort, Cap, Scan

    If your repo had three images, and your scan configuration specified a cap of 2 and version pattern of *-%d.%d.%d, you’d get the following result:

    myimage-3.0.0 <<<--- Scan
    myimage-2.0.1 <<<--- Scan
    myimage-2.0.0 (Not scanned)
  4. Create multiple collections of Defender scanners when you have multiple registries.

    Each registry should have dedicated Defenders to perform the scanning. If a 1:1 ratio of Defender collections to registries isn’t feasible, create as many collections as possible to split the load. Don’t reuse the same Defender collection for all registries.

    This setup prevents the scenario where a single IP (a single Defender) performs too many queries to the registry provider API for repo/tag discovery, which might cause the Defender to be throttled.

  5. Follow the guidance for hardware requirements for Defenders that perform registry scanning.

  6. Colocate Defender scanners in the same region as the registry.

6. Additional scan settings

Additional scan settings can be found under Manage > System > Scan, where you can set the registry scan interval.

The Manage > System > Scan page has an option called Only scan images with running containers. This option does NOT apply to registry scanning; all images targeted by your registry scanning rule will be scanned regardless of how Only scan images with running containers is set.

7. CRI/containerd-only environments

Prisma Cloud fully supports scanning CRI/containerd-only environments.