Prisma Cloud Compute Edition Administrator’s Guide
    : Configure Registry Scans
    Focus
    Download PDF
    Focus
    1. Home
    2. Prisma
    3. Prisma Cloud
    4. Prisma Cloud Compute Edition Administrator’s Guide
    5. Vulnerability management
    6. Registry scanning
    7. Configure Registry Scans
    Download PDF

    Prisma Cloud Compute Edition Administrator’s Guide

    Configure Registry Scans

    Table of Contents

    Configure Registry Scans

    Prisma Cloud can scan container images in public and private repositories on public and private registries.
    A registry is a system that stores and distributes container images. You can use Prisma Cloud to scan registries from different public registry providers such as DockerHub, Amazon, and Google, as well as your internal private registries.
    After you configure repository scanning, Prisma Cloud automatically scans images for vulnerabilities. By default, scans occur once every 24 hours, but you can configure periodic scans at specific intervals specified in
    Manage > System > Scan
    .
    You can scan all registries or select multiple registries to scan in parallel, thus reducing the scan time. By default, the registry scan limit is set to scan one registry at a time.
    Prisma Cloud can scan upto 4 registries in parallel. The new registry scans wait in a queue, until the previous scan completes.
    Note: You can configure this default (1) registry scan limit to scan up to 4 registries by editing the REGISTRY_SCANNERS variable in the twistlock.cfg file.

    Configure Prisma Cloud to Scan a Registry

    To scan images in a registry, create a new registry scan rule.
    1. On the Prisma Cloud console, go to
      Defend > Vulnerabilities > Images > Registry settings
      .
    2. Review the available settings.
    3. If the default values don’t fit your scenario, select
      Add registry
      .
    4. Enter the registry fields, then select
      Add and scan
      .
      This triggers a registry scan and you can view the progress notification at the top right corner with a list of registries (<registry>/repository:tag) being scanned.

    Registry Scan Results

    Verify that the images in the repository are being scanned.
    You can add a maximum of 19,999 registry entries in
    Defend > Vulnerabilities > Images > Registry settings
    .
    1. Go to
      Monitor > Vulnerabilities > Images > Registries
      .
      You can choose to
      Scan all registries
       or
      Select registries
       (multiple registries) to
      Scan
      .
      As the scan of each image is completed, its findings are added to the results table.
    2. Select an image to get details about the vulnerabilities in an image.
      To force a specific repository to be scanned again, select
      Scan
       from the top right of the results table, then select a specific registry to re-scan. Alternatively, you can also scan an individual registry by selecting
      Scan
       next to the registry.
      If the registry scans are already in progress, the newly added registry is queued until the previous registry scan finishes, the available Defender is then assigned to scan the very next registry in queue.
      The
      Last scan time
       of a registry is updated under
      Registry details > General info
      .

    On-demand Registry Scanning

    You can trigger an on-demand scan for individual images with the Scan Registry API. This feature allows you to scan the images immediately and not wait for the next periodic scan. You can trigger multiple on-demand image scans without interrupting the main registry scanning process. However, every trigger is for a single image only.
    For an on-demand scan, you must pre-define the image registry scope in the registry scanning configuration.

    Deployment Patterns

    Defenders handle registry scanning. When you configure registry scanning, you can select the scope of Defenders used to perform the scans.
    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 flexibility gives you a lot of options when trying to determine how to cover disparate environments.
    You can use host names or AWS tags to select a collection of Defenders to distribute the scanning job between them, and use the
    Number of scanners
     setting to control how many defenders are included in the collection. When you select
    All
     collection, Prisma Cloud automatically distributes the scan job across all available Defenders.
    Configuring Prisma Cloud to use a large number of Defenders reduces operational complexity and improves resiliency. During a scan, Prisma Cloud lists the available Defenders based on the configured scope, manages the resource pool, and handles issues such as restarting partially completed jobs. If you explicitly select one or two Defenders to handle the registry scan, the hosts running those Defenders become a single point of failure. If that host fails or gets destroyed, you have to reconfigure your scan settings with different Defenders.
    The type of operating system (OS) scopes registry scanning. Windows Defenders only scan Windows images, and Linux Defenders only scan Linux images.
    When you remove an image from the registry or the registry becomes unavailable, Prisma Cloud maintains the scan results for a specific number of days. You can configure the number of days under
    Manage > System > Scan > Registry scan results
    . After the specified number of days, the scan results are purged.

    Registry Scan Steps

    At a high level, Defenders scan your registries following these steps.
    1. Scan multiple registries in parallel, the default value is set to scan only 1 registry at a time. Note: You can configure this default (1) registry scan limit to scan up to 4 registries by editing the REGISTRY_SCANNERS variable in the twistlock.cfg file.
    2. Discover the repositories based on your registry configuration.
    3. Discover the images using tags within each configured repository.
    4. Scan the discovered images.
    In more detail, Defenders scanning your registries follow this sequential flow to collect the metadata.
    1. Get a list of all repositories in the registry.
    2. For each repository, scanning Defenders perform the following tasks.
      • Get a list of all image tags.
      • For each image tag, they get the image manifest containing the date the image was last modified.
    3. Once the metadata of all images is discovered, scanning defenders perform the following tasks.
      • Sort the images by the last modified date.
      • Cap the list of images based on the configured value. By default, lists are capped at five.
      • Scan the images.
    The Console manages the current scan state and distributes the work to Defenders.
    • If a Defender is disconnected during the scan, the Console assigns the scan task to another Defender and continues to scan the resources.
    • When the Console is updated, the periodic scan restarts.
    • When the Console loses communication with the Defender, the Defender continues to defend the nodes and reports the results to the Console when the communication with the Console resumes.

    Registry Scan Settings

    You can set the following parameters for each rule, but the parameters can vary between registry types. If you use a specific registry provider, follow the appropriate step-by-step instructions in our guides.
    Field
    Description
    Version
    Specify the type of registry to scan.
    If you do not find your vendor’s registry in the drop-down list, use
    Docker Registry v2
    . Most vendors comply with the Docker Registry version 2 API.
    Container and registry images built on Docker Registry v1 are no longer supported, you must upgrade to Docker Registry v2.
    Registry
    Specify the URL for the registry.
    Docker Hub:
     leave this field blank.
    Harbor
    : specify the FQDN of your Harbor registry (https://).
    Nexus Registry:
    <http|https://<nexus_hostname>:<HTTP/HTTPS connector port for the specific Nexus repo>
    JFrog Artifactory:
     Enter the Artifactory registry URL for JFrog Cloud (ending in *.io) or JFrog self-hosted whichever is applicable.
    Repository name
    Specify the repository to scan. This field supports pattern matching. To scan all repositories, 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 username 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, 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 /*. (for example, company-sandbox/*).
    Harbor:
     Enter the name of the repository, followed by a wildcard (*). For example, to scan the repository library, enter library*.
    Any Docker V2 API compliant registry:
     Docker Hub, Docker Registry, and Alibaba Container Registry all support the Docker Registry version 2 API.
    Nexus Registry:
     Leave blank or include a pattern to match the Docker repositories inside the Nexus registry. For example: To scan all the images under a path, include the
    path/to
     string.
    Repositories to exclude (Optional)
    Specify repository names to exclude. Enter the repository name or pattern to exclude that repository from being scanned. Leave this field blank to scan all repositories.
    Tag (Optional)
    Specify an image tag. Leave this field blank to scan all tags (limited by the value in Cap).
    Tags to exclude (Optional)
    Specify tags to exclude. Leave blank to exclude all image tags (default).
    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 Elastic Container Registry (ECR).
    Google Container Registry:
     Use the service account and JSON token. For more information, see Google Container Registry (GCR).
    Harbor Registry:
     Create a
    Basic authentication
     credential. Credentials for Harbor can be a
    Limited Guest
    .
    Registries that support token authentication (such as, Quary, and GitLab):
     Create a
    Basic authentication
     credential. Username is the name of the token and the token value is entered into the password field.
    To scan a
    GitLab
     registry, configure the registry in Prisma Cloud as a
    GitLab Container Registry
    .
    You can use GitLab personal access token to scan a GitLab registry.
    CA certificate (Optional)
    Enter a CA certificate in PEM format to allow Prisma Cloud to validate the registry.
    Custom CA certificate validation is supported only for non-docker nodes (for example, OpenShift), and for the following Cloud providers:
    • Docker registry v2
    • JFrog Artifactory (On-prem)
    • Harbor
    • Sonatype Nexus
      Note:
       Certificate revocation checking for the registry’s certificate is your responsibility to ensure that the certificate is not revoked by the issuing authority.
      Only Defenders running with CRI runtime support custom CA certificate configuration.
      Place the CA certificate (ca.cert) file in any of the following paths. The Defender searches for the certificate files in the below directories in the following precedence:
    OS Type
    Specify whether the image is built on a Windows or Linux-based 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. App-Embedded Defenders can’t be used for registry scanning.
    Number of scanners
    Number of Defenders from the scope across which the scan job can be distributed. Increase the number of Defenders to increase throughput and reduce scan time.
    Cap (Capacity)
    Specify the maximum number of images to scan in the given repository, sorted according to the last modified date. A repository is a collection of different docker images with the same name, that have different tags. That is, the most recently modified image in each repository is scanned first, followed by the image next most recently modified, and so on.
    With a cap of five, scanning Defenders fetch the five most recently modified images from each repository in the registry. In other words, for each image in the registry, we will include the 5 latest versions.
    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 the last modified date.
    Specify patterns with strings, wildcards, time/date 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 the best-effort. Tags that don’t conform to the pattern are ignored.
    If both date and version are specified in your pattern, the date takes precedence.
    If the version matching pattern is left unspecified, Prisma Cloud orders images by the last modified date.
    To scan a small set of registries that contain a small set of images, use a VM host with a single container Defender optimized to scan the target registries.

    Registries with a Large Scale

    For larger registries, optimize your scan configuration to maximize throughput and minimize scan time. Defenders scan registries parallely following specific steps. The following best practices help you improve your registry scanning speed.
    • If you have large registries or need aggressive scan intervals, increase the number of scanners in the scope.
      The number of scanning Defenders should increase with the registry size. As the number of images in the registry increases, so does the number of Defenders scanning this registry.
    • Use the default cap value of five in your registry scan configuration.
      The cap value impacts the duration of the scan. Large-cap values lead to longer scan times since more images are scanned.
    • Use a version-matching pattern in your registry scan configuration. Only use version pattern matching for deployments with very large registries containing tens of thousands of repositories and millions of images.
      If you specify a version matching pattern, the scanner looks to the image tag for sort order. Without a version-matching pattern, images are sorted by the last modified date. With a version-matching pattern, you configure how image tags are sorted. Using semantic versioning in your image names, you can specify the following version pattern:
      *-%d.%d.%d
      This optimized flow to collect metadata eliminates the sorting loop and substantially reduces the number of requests. Then, Defenders can start scanning the registry sooner. The simplified flow is as follows.
      1. Get a list of all repos in the registry.
      2. For each repository, scanning Defenders perform the following tasks.
        • Get a list of all image tags
      3. Once the metadata of all images is discovered, scanning Defenders perform the following tasks.
        • Sort the images by last modified date.
        • Cap the list of images based on the configured value. By default, lists are capped at five.
        • Scan the images.
      A repository with three images, configured with a cap of 2, and a version pattern of *-%d.%d.%d, produces the following set of images to be scanned.
        myimage-3.0.0 <<<--- Image scanned
  myimage-2.0.1 <<<--- Image scanned
  myimage-2.0.0 (Not scanned)
    • When you have multiple registries to scan, create a dedicated collection of Defenders with the scope for each registry scan profile. Ensure that the Defenders are able to reach the defined registry. To improve throughput and reduce scan time, you can increase the number of Defenders in the collection.
      This dedicated collection of Defenders will target all the registries and scan them in parallel as per the registry scan limit configured in the twistlock.cfg file.
      This dedicated collection of Defenders will target all the registries and scan one registry at a time.
    • Properly dimension the hardware running your Defenders.
      Ensure the hardware system requirements for Defenders scanning registries are met.
    • Colocate scanning Defenders in the same region as the registry.
      This best practice minimizes network latency since the Defenders run in the same region as your registries.

    Additional Scan Settings

    You can find additional scan settings 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 included in your registry scanning rule are scanned regardless of the setting to
    Only scan images with running containers
    .

    CRI and containerd-only Environments

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

    Registry Scanning Limitations

    When scanning registries, consider the following constraints.
    • Defenders only scan the operating system images that match the OS of the system running them.
      For example, a Defender running on a Linux host can only scan Linux images and won’t scan Windows images.
    • Defenders running on Linux only scan images suited for the hardware architecture that matches the architecture of the system running them.
      For example, a Defender running on x86_64 architecture with Linux can only scan images for x86_64 systems with Linux. Similarly, a Defender running on ARM64 architecture with Linux can only scan images for ARM64 systems with Linux. You can’t mix Linux ARM64 and Linux x86_64 Defenders within the same registry scanning scope.
    • The Prisma scanner may potentially fail to retrieve image details for Docker registries and may fail with 429 connection error when you try to parallely scan more than one Docker registry at a time.
      To avoid this error, limit the registry scan to 1, by setting REGISTRY_SCANNERS = 1 in the twistlock.cfg config file.

    Recommended For You

    © 2023 Palo Alto Networks, Inc. All rights reserved.