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/
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
-
Open the Amazon ECR console at https://console.aws.amazon.com/ecr/
. -
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.
-
In the navigation pane, choose Private registry, then choose Scanning.
-
In the Scanning configuration section, choose Edit.
-
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.
-
(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.
-
-
Choose Save.
-
(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
-
Open the Amazon Inspector console at https://console.aws.amazon.com/inspector/v2/home
. -
In the navigation pane, under Settings, choose General.
-
Under ECR automated re-scan duration, choose the duration that you want.
-
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.
-
Open the Amazon Inspector console at https://console.aws.amazon.com/inspector/v2/home
. -
By using the AWS Region selector in the upper-right corner of the page, select the Region where you want to deactivate scans.
-
In the navigation pane, choose Settings, and then choose Account management.
-
Choose the Accounts tab to show the scanning status of an account.
-
Select the check box for each account that you want to deactivate scans for.
-
On the Actions menu, choose the scan type to deactivate.