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. For information about the types of findings produced for these issues, see Finding types in Amazon Inspector.

When you activate Amazon Inspector scans for Amazon ECR, you set Amazon Inspector as your preferred scanning service for your private registry. This replaces the default Basic scanning, which is provided at no charge by Amazon ECR, with Enhanced scanning, which is provided and billed through Amazon Inspector.

The enhanced scanning provided by Amazon Inspector gives you the benefit of vulnerability scanning for both operating system and programming language packages at the registry level. You can review findings discovered using enhanced scanning at the image level, for each layer of the image, on the Amazon ECR console. Additionally, you can review and work with these findings in other services not available for basic scanning findings, including AWS Security Hub and Amazon EventBridge. You can view findings discovered by scans on the Amazon Inspector console at https://console.aws.amazon.com/inspector/. For information about working with findings, see Managing findings in Amazon Inspector.

Enhanced scanning gives you a choice between continuous scanning or on-push scanning at the repository level. Continuous scanning includes on-push scans and automated rescans. On-push scanning scans only when you initially push an image. For both options, you can refine the scanning scope through inclusion filters.

Scan behaviors for Amazon ECR scanning

When you first activate Amazon ECR scanning, Amazon Inspector scans eligible images that have been pushed in the last 30 days. By default, images are scanned for a Lifetime duration. However, you can configure a different duration through the console or API. For more information, see Configuring the ECR automated re-scan duration. 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).

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 a finding 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 Operating system support 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.

Activating and configuring enhanced scanning for Amazon ECR repositories

When you activate enhanced scanning for Amazon ECR, Amazon Inspector scans all images in the repositories you specify that have been pushed in the last 30 days. If you have images older than 30 days that you want Amazon Inspector to scan, you must re-push them to your repository. You can select specific repositories for scanning using the Amazon ECR console.

To activate and configure your enhanced scanning settings

1. Open the Amazon ECR console at https://console.aws.amazon.com/ecr/.

2. By using the AWS Region selector in the upper-right corner of the page, select the Region that has the repositories that you want to scan.

3. In the navigation pane, choose Private registry, then choose Scanning.

4. In the Scanning configuration section, choose Edit.

5. Under Scan type, choose Enhanced scanning.

   By default, the Continuously scan all repositories option is selected which turns on complete Amazon Inspector scan coverage for all repositories. Deselect that option and select Scan on push all repositories to run scans only on initial push of an image.

   1. (Optional) Specify which repositories to include in scans for continuous or on-push scans by entering the repository names in the input box and selecting Add filter.

      After you add inclusion filters, choose Preview repository matches to show which repositories Amazon Inspector will scan with those settings.

6. Choose Save.

7. (Recommended) Repeat these steps in each AWS Region for which you want to activate Amazon Inspector scans for Amazon ECR repositories.

Configuring the ECR automated re-scan duration

The Amazon ECR automated re-scan duration setting determines how long Amazon Inspector continuously monitors images pushed into repositories. When the number of days from when an image is first pushed exceeds the automated re-scan duration configuration, Amazon Inspector stops monitoring the image. When Amazon Inspector stops monitoring an image, it changes the scan status of the image to inactive with a reason code of expired. Then all associated findings for the image are scheduled to be closed.

You can set the Amazon ECR automated re-scan duration in Amazon Inspector to best suit your environment. For example, if you build images frequently, a shorter scan duration is sufficient. However, if you continue to use images for long periods of time you can choose a longer scan duration. The default scan duration for new accounts, including new accounts added to an organization, is Lifetime. This means Amazon Inspector scans your images until they're deleted.

The following scan duration options are available.

• 30 days

• 180 days

• Lifetime (default)

To configure the ECR automated re-scan duration

1. Open the Amazon Inspector console at https://console.aws.amazon.com/inspector/v2/home.

2. In the navigation pane, under Settings, choose General.

3. Under ECR automated re-scan duration, choose the duration that you want.

4. Choose Save. Your new setting applies immediately.

If you increase the duration, for example, from 30 days to 180 days, Amazon Inspector applies the change to all images actively being scanned in repositories configured for continual scanning. However, images with a scan status of expired remain expired.

If you decrease the duration, for example, from Lifetime to 180 days, Amazon Inspector applies the change to all active images being scanned in repositories configured for continual scanning. Images that are older than your new setting have their scan status changed to expired and are no longer monitored. For scanning to be resumed, you must push the image to the repository again.

Deactivating Amazon ECR scans

You can deactivate scanning for Amazon ECR container images or Amazon EC2 instances at any time. Deactivating all scan types for an account deactivates Amazon Inspector for that account in that AWS Region. For more information, see Deactivating Amazon Inspector.

When you deactivate Amazon ECR container image scanning for an account, the Amazon ECR scan type for that account changes from Enhanced scanning with Amazon Inspector to Basic scanning with Amazon ECR.

To deactivate scans

To complete this procedure for a multi-account environment, follow these steps while signed in as the Amazon Inspector delegated administrator. Member accounts cannot deactivate scans.

1. Open the Amazon Inspector console at https://console.aws.amazon.com/inspector/v2/home.

2. By using the AWS Region selector in the upper-right corner of the page, select the Region where you want to deactivate scans.

3. In the navigation pane, choose Settings, and then choose Account management.

4. Choose the Accounts tab to show the scanning status of an account.

5. Select the check box for each account that you want to deactivate scans for.

6. On the Actions menu, choose the scan type to deactivate.