Scanning Amazon ECR container images with Amazon Inspector - Amazon Inspector

Scanning Amazon ECR container images with Amazon Inspector

Amazon Inspector scans container images stored in Amazon ECR for software vulnerabilities to generate package vulnerability findings.

When you activate Amazon Inspector scans for Amazon ECR, you set Amazon Inspector as the preferred scanning service for your private registry. This also means you change the scanning configuration setting for your private registry from basic scanning to enhanced scanning. For more information, see Amazon Inspector FAQs.

Note

Basic scanning is provided and billed through Amazon ECR. For more information, see Amazon Elastic Container Registry pricing. Enhanced scanning is provided and billed through Amazon Inspector. For more information, see Amazon Inspector pricing.

With enhanced scanning, you get the benefit of vulnerability scanning for operating system and programming language packages at the registry level. You can view scan-discovered findings from the Amazon Inspector console. For more information, see Managing findings in Amazon Inspector.

You can also view scan-discovered findings at the image level from the Amazon ECR console. For more information, see Image scanning in the Amazon Elastic Container Registry User Guide. Additionally, you can review and work with findings in other services not available for basic scanning, including AWS Security Hub and Amazon EventBridge.

For instructions on activating Amazon ECR scans, see Activating a scan type.

Scan behaviors for Amazon ECR scanning

When you first activate ECR scanning, and your repository is configured for continuous scanning, Amazon Inspector detects all eligible images that you have pushed within 30 days, or pulled within the last 90 days. Then Amazon Inspector scans the detected images and sets their scan status to active. Amazon Inspector continues to monitor images as long as they were pushed or pulled within the last 90 days (by default), or within the ECR rescan duration you configure. For more information, see Configuring the ECR re-scan duration.

For continuous scanning, Amazon Inspector initiates new vulnerability scans of container images in the following situations:

  • Whenever a new container image is pushed.

  • Whenever Amazon Inspector adds a new common vulnerabilities and exposures (CVE) item to its database, and that CVE is relevant to that container image (continuous scanning only).

If you configure your repository for on push scanning, images are only scanned when you push them.

You can check when a container image was last checked for vulnerabilities from the Container images tab on the Account management page, or by using the ListCoverage API. Amazon Inspector updates the Last scanned at field of an Amazon ECR image in response to the following events:

  • When Amazon Inspector completes an initial scan of a container image.

  • When Amazon Inspector re-scans a container image because a new common vulnerabilities and exposures (CVE) item that impacts that container image was added to the Amazon Inspector database.

Supported operating systems and media types

For information about supported operating systems, see Supported operating systems for Amazon ECR scanning.

Amazon Inspector scans of Amazon ECR repositories cover the following supported media types:

  • "application/vnd.docker.distribution.manifest.v1+json"

  • "application/vnd.docker.distribution.manifest.v1+prettyjws"

  • "application/vnd.oci.image.manifest.v1+json"

  • "application/vnd.docker.distribution.manifest.v2+json"

    Note

    Scratch images and DockerV2ListMediaType images aren't supported.

Configuring enhanced scanning for Amazon ECR repositories

When you activate Amazon Inspector scans for Amazon ECR container images, you change the scanning configuration setting for your private registry from basic scanning to enhanced scanning. Basic scanning uses the Common Vulnerabilities and Exposures database from the open-source Clair project. Enhanced scanning integrates with Amazon Inspector and provides automated and continuous scanning of your repositories.

With basic scanning, you configure your repositories to scan on push, or you perform manual scans. With enhanced scanning, Amazon Inspector scans your container images for operating system and programming language package vulnerabilities. For more information, see Amazon Inspector FAQs, which displays a side-by-side comparison of the differences between basic and enhanced scanning.

You can manage the settings for enhanced scanning at the repository level in ECR. You can choose on push or continuous scanning. On push scanning only scans when you push an image. Continuous scanning includes on push scans and automated rescans. You can refine the scope for both options with inclusion filters.

Note

When you activate Amazon Inspector scans for Amazon ECR container images, continuous scanning is enabled. However, you can deselect this option to apply scanning filters in the console.

To configure your enhanced scanning settings
  1. Open the Amazon ECR console at https://console.aws.amazon.com/ecr/.

  2. From the AWS Region selector dropdown menu, select the AWS Region with the repositories that you're scanning.

  3. From the navigation pane, choose Private registry, and then choose Settings.

  4. Under Scanning, choose Edit, and then Enhanced scanning.

  5. (Optional) Deselect Continuously scan all repositories to configure continuous scanning and on push scanning filters.

  6. Confirm your choices, and then choose Save.

Configuring the ECR re-scan duration

The ECR re-scan duration setting determines how long Amazon Inspector continuously monitors container images in repositories. You can configure the re-scan duration for the image push date and image pull date. The default scan duration for new accounts, including new accounts added to an organization, is 90 days.

Image push date duration

The image push date duration determines how long Amazon Inspector continuously monitors images after they were pushed to repositories following the latest pull date. The following options are available as re-scan durations:

  • 14 days

  • 30 days

  • 60 days

  • 90 days (default)

  • 180 days

  • Lifetime

Image pull date duration

The image pull date duration determines how long Amazon Inspector continuously monitors images after the latest pull date. The following options are available as re-scan durations:

  • 14 days

  • 30 days

  • 60 days

  • 90 days (default)

  • 180 days

Amazon Inspector will continue to monitor and rescan an image as long as it's been pushed or pulled within the configured push and pull dates. If the image hasn’t been pushed or pulled within the configured push and pull dates, Amazon Inspector stops monitoring it.

Note

When Amazon Inspector stops monitoring an image, it sets the image scan status code to inactive and reason code to expired. It then schedules all associated image findings to be closed.

Set the re-scan duration to best suit your environment. For example, if you build images often, choose shorter scan duration. Similarly, if you use images for long periods of time, choose a longer scan duration.

When you configure the re-scan duration from a delegated administrator account, Amazon Inspector applies the setting to all member accounts in the organization.

To configure the ECR re-scan duration
  1. Open the Amazon Inspector console at https://console.aws.amazon.com/inspector/v2/home.

  2. From the navigation pane, choose General settings, and then choose ECR scanning settings.

  3. On ECR scanning settings, under ECR re-scan duration, choose the image push date duration and image pull date duration that you want to set.

  4. Choose Save. Your new settings are applied immediately.

Note

If you increase the push date duration, Amazon Inspector applies the change to all actively scanned images in repositories configured for continual scanning. However, inactive images remain inactive, even if you pushed them within the new duration.