# Scan images for software vulnerabilities in Amazon ECR Scan images for vulnerabilities Amazon ECR image scanning helps to identify software vulnerabilities in your container images. The following scanning types are offered. **Important** Switching between **Enhanced scanning** and **Basic scanning** will cause previously established scans to no longer be available. You will have to set up your scans again. However, if you switch back to your previous scanning type the established scans will be available. **Note** Archived images cannot be scanned. Archived images must be restored before they can be scanned. For more information about archiving and restoring images, see [Archiving an image in Amazon ECR](archive_restore_image.md). + **Enhanced scanning** – Amazon ECR integrates with Amazon Inspector to provide automated, continuous scanning of your repositories. Your container images are scanned for both operating systems and programming language package vulnerabilities. As new vulnerabilities appear, the scan results are updated and Amazon Inspector emits an event to EventBridge to notify you. Enhanced scanning provides the following: + OS and programming languages package vulnerabilities + Two scanning frequencies: Scan on push and continuous scan + **Basic scanning** – Amazon ECR uses AWS native technology with the Common Vulnerabilities and Exposures (CVEs) database to scan for operating system vulnerabilities. With basic scanning, you configure your repositories to scan on push or you can perform manual scans and Amazon ECR provides a list of scan findings. Basic scanning provides the following: + OS scans + Two scanning frequencies: Manual and scan on push **Important** The new version of Amazon ECR Basic Scanning doesn't use the ` imageScanFindingsSummary` and `imageScanStatus` attributes from the `DescribeImages` API response to return scan results. Use the ` DescribeImageScanFindings` API instead. For more information, see [https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_DescribeImageScanFindings.html](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_DescribeImageScanFindings.html). # Filters to choose which repositories are scanned in Amazon ECR Filters for repositories When you configure image scanning for your private registry, you can use filters to choose which repositories are scanned. When **basic** scanning is used, you may specify scan on push filters to specify which repositories are set to do an image scan when new images are pushed. Any repositories not matching a basic scanning scan on push filter will be set to the ** manual** scan frequency which means to perform a scan, you must manually trigger the scan. When **enhanced** scanning is used, you may specify separate filters for scan on push and continuous scanning. Any repositories not matching an enhanced scanning filter will have scanning disabled. If you are using enhanced scanning and specify separate filters for scan on push and continuous scanning where multiple filters match the same repository, then Amazon ECR enforces the continuous scanning filter over the scan on push filter for that repository. ## Filter wildcards When a filter is specified, a filter with no wildcard will match all repository names that contain the filter. A filter with a wildcard (`*`) matches on any repository name where the wildcard replaces zero or more characters in the repository name. The following table provides examples where repository names are expressed on the horizontal axis and example filters are specified on the vertical axis. | | prod | repo-prod | prod-repo | repo-prod-repo | prodrepo | | --- | --- | --- | --- | --- | --- | | prod | Yes | Yes | Yes | Yes | Yes | | \$1prod | Yes | Yes | No | No | No | | prod\$1 | Yes | No | Yes | No | Yes | | \$1prod\$1 | Yes | Yes | Yes | Yes | Yes | | prod\$1repo | No | No | Yes | No | Yes | # Scan images for OS and programming language package vulnerabilities in Amazon ECR Enhanced scanning Amazon ECR enhanced scanning is an integration with Amazon Inspector which provides vulnerability scanning for your container images. Your container images are scanned for both operating systems and programming language package vulnerabilities. You can view the scan findings with both Amazon ECR and with Amazon Inspector directly. For more information about Amazon Inspector, see [Scanning container images with Amazon Inspector](https://docs.aws.amazon.com/inspector/latest/user/enable-disable-scanning-ecr.html) in the *Amazon Inspector User Guide*. With enhanced scanning, you can choose which repositories are configured for automatic, continuous scanning and which are configured for scan on push. This is done by setting scan filters. ## Considerations for enhanced scanning Consider the following before enabling Amazon ECR enhanced scanning. + There is no additional cost from Amazon ECR to use this feature, however there is a cost from Amazon Inspector to scan your images. This feature is available in Regions where Amazon Inspector is supported. For more information, see: + Amazon Inspector pricing – [Amazon Inspector pricing](https://aws.amazon.com/inspector/pricing/). + Amazon Inspector supported Regions – [Regions and endpoints](https://docs.aws.amazon.com//inspector/latest/user/inspector_regions.html). + Amazon ECR enhanced scanning shows how images are used on Amazon EKS and Amazon ECS. You can see when images were last used and identify how many clusters use each image. This information helps you prioritize vulnerability remediation for actively used images. You can quickly determine which clusters might be affected by newly discovered vulnerabilities. For more information about how to request these information and view the response, see [https://docs.aws.amazon.com//AmazonECR/latest/APIReference/API_DescribeImageScanFindings.html](https://docs.aws.amazon.com//AmazonECR/latest/APIReference/API_DescribeImageScanFindings.html). + Amazon Inspector supports scanning for specific operating systems. For a full list, see [Supported operating systems - Amazon ECR scanning](https://docs.aws.amazon.com/inspector/latest/user/supported.html#supported-os) in the *Amazon Inspector User Guide*. + Amazon Inspector uses a service-linked IAM role, which provides the permissions needed to provide enhanced scanning for your repositories. The service-linked IAM role is created automatically by Amazon Inspector when enhanced scanning is turned on for your private registry. For more information, see [Using service-linked roles for Amazon Inspector](https://docs.aws.amazon.com/inspector/latest/user/using-service-linked-roles.html) in the *Amazon Inspector User Guide*. + When you initially turn on enhanced scanning for your private registry, Amazon Inspector only recognizes images pushed to Amazon ECR in the last 14 days, based on the image push timestamp. Older images will have the ` SCAN_ELIGIBILITY_EXPIRED` scan status. If you'd like these images to be scanned by Amazon Inspector you should push them again to your repository. + When enhanced scanning is turned on for your Amazon ECR private registry, repositories matching the scan filters are scanned using enhanced scanning only. Any repositories that don't match a filter will have an `Off` scan frequency and won't be scanned. Manual scans using enhanced scanning aren't supported. For more information, see [Filters to choose which repositories are scanned in Amazon ECR](image-scanning-filters.md). + If you specify separate filters for scan on push and continuous scanning where multiple filters match the same repository, then Amazon ECR enforces the continuous scanning filter over the scan on push filter for that repository. + When enhanced scanning is turned on, Amazon ECR sends an event to EventBridge when the scan frequency for a repository is changed. Amazon Inspector emits events to EventBridge when an initial scan is completed and when an image scan finding is created, updated, or closed. ## Changing the enhanced scanning duration for images in Amazon Inspector Changing the enhanced scanning duration After enabling enhanced scanning, Amazon ECR continually scans newly pushed images for the configured duration. By default, Amazon Inspector monitors your repositories until images are deleted or enhanced scanning is disabled. You can configure both push date duration (up to Lifetime) and re-scan duration in the Amazon Inspector console to suit your environment's needs. When the scan duration for a repository elapses, the scan status shows as `SCAN_ELIGIBILITY_EXPIRED`. For more information about configuring re-scan duration settings for Amazon ECR in Amazon Inspector, see [Configuring the Amazon ECR re-scan duration](https://docs.aws.amazon.com/inspector/latest/user/enable-disable-scanning-ecr.html#scan-duration-setting) in the *Amazon Inspector User Guide*. # IAM permissions required for enhanced scanning in Amazon ECR Required IAM permissions Amazon ECR enhanced scanning requires an Amazon Inspector service-linked IAM role and that the IAM principal enabling and using enhanced scanning has permissions to call the Amazon Inspector APIs needed for scanning. The Amazon Inspector service-linked IAM role is created automatically by Amazon Inspector when enhanced scanning is turned on for your private registry. For more information, see [Using service-linked roles for Amazon Inspector](https://docs.aws.amazon.com/inspector/latest/user/using-service-linked-roles.html) in the *Amazon Inspector User Guide*. The following IAM policy grants the required permissions for enabling and using enhanced scanning. It includes the permission needed for Amazon Inspector to create the service-linked IAM role as well as the Amazon Inspector API permissions needed to turned on and off enhanced scanning and retrieve the scan findings. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "inspector2:Enable", "inspector2:Disable", "inspector2:ListFindings", "inspector2:ListAccountPermissions", "inspector2:ListCoverage" ], "Resource": "*" }, { "Effect": "Allow", "Action": "iam:CreateServiceLinkedRole", "Resource": "*", "Condition": { "StringEquals": { "iam:AWSServiceName": [ "inspector2.amazonaws.com" ] } } } ] } ``` ------ # Configuring enhanced scanning for images in Amazon ECR Configuring enhanced scanning Configure enhanced scanning per Region for your private registry. Verify that you have the proper IAM permissions to configure enhanced scanning. For information, see [IAM permissions required for enhanced scanning in Amazon ECR](image-scanning-enhanced-iam.md). ------ #### [ AWS Management Console ] **To turn on enhanced scanning for your private registry** 1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/repositories](https://console.aws.amazon.com/ecr/repositories). 1. From the navigation bar, choose the Region to set the scanning configuration for. 1. In the navigation pane, choose **Private registry**, and then choose **Settings** . 1. On the **Scanning configuration** page, for **Scan type** choose **Enhanced scanning**. By default, when **Enhanced scanning** is selected, all of your repositories are continuously scanned. 1. To choose specific repositories to continuously scan, clear the **Continuously scan all repositories** box, and then define your filters: **Important** Filters with no wildcard will match all repository names that contain the filter. Filters with wildcards (`*`) match on a repository name where the wildcard replaces zero or more characters in the repository name. To see examples of how filters behave, see [Filter wildcards](image-scanning-filters.md#image-scanning-filters-wildcards). 1. Enter a filter based on repository names, and then choose **Add filter**. 1. Decide which repositories to scan when an image is pushed: + To scan all repositories on push, select **Scan on push all repositories**. + To choose specific repositories to scan on push, enter a filter based on repository names, and then choose **Add filter**. 1. Choose **Save**. 1. Repeat these steps in each Region in which you want to turn on enhanced scanning. ------ #### [ AWS CLI ] Use the following AWS CLI command to turn on enhanced scanning for your private registry using the AWS CLI. You can specify scan filters using the ` rules` object. + [ put-registry-scanning-configuration](https://docs.aws.amazon.com/cli/latest/reference/ecr/put-registry-scanning-configuration.html) (AWS CLI) The following example turns on enhanced scanning for your private registry. By default, when no `rules` are specified, Amazon ECR sets the scanning configuration to continuous scanning for all repositories. ``` aws ecr put-registry-scanning-configuration \ --scan-type ENHANCED \ --region us-east-2 ``` The following example turns on enhanced scanning for your private registry and specifies a scan filter. The scan filter in the example turns on continuous scanning for all repositories with `prod` in its name. ``` aws ecr put-registry-scanning-configuration \ --scan-type ENHANCED \ --rules '[{"repositoryFilters" : [{"filter":"prod","filterType" : "WILDCARD"}],"scanFrequency" : "CONTINUOUS_SCAN"}]' \ --region us-east-2 ``` The following example turns on enhanced scanning for your private registry and specifies multiple scan filters. The scan filters in the example turns on continuous scanning for all repositories with `prod` in its name and turns on scan on push only for all other repositories. ``` aws ecr put-registry-scanning-configuration \ --scan-type ENHANCED \ --rules '[{"repositoryFilters" : [{"filter":"prod","filterType" : "WILDCARD"}],"scanFrequency" : "CONTINUOUS_SCAN"},{"repositoryFilters" : [{"filter":"*","filterType" : "WILDCARD"}],"scanFrequency" : "SCAN_ON_PUSH"}]' \ --region us-west-2 ``` ------ # EventBridge events sent for enhanced scanning in Amazon ECR EventBridge events When enhanced scanning is turned on, Amazon ECR sends an event to EventBridge when the scan frequency for a repository is changed. Amazon Inspector sends events to EventBridge when an initial scan is completed and when an image scan finding is created, updated, or closed. **Event for a repository scan frequency change** When enhanced scanning is turned on for your registry, the following event is sent by Amazon ECR when there is a change with a resource that has enhanced scanning turned on. This includes new repositories being created, the scan frequency for a repository being changed, or when images are created or deleted in repositories with enhanced scanning turned on. For more information, see [Scan images for software vulnerabilities in Amazon ECR](image-scanning.md). ``` { "version": "0", "id": "0c18352a-a4d4-6853-ef53-0abEXAMPLE", "detail-type": "ECR Scan Resource Change", "source": "aws.ecr", "account": "123456789012", "time": "2021-10-14T20:53:46Z", "region": "us-east-1", "resources": [], "detail": { "action-type": "SCAN_FREQUENCY_CHANGE", "repositories": [{ "repository-name": "repository-1", "repository-arn": "arn:aws:ecr:us-east-1:123456789012:repository/repository-1", "scan-frequency": "SCAN_ON_PUSH", "previous-scan-frequency": "MANUAL" }, { "repository-name": "repository-2", "repository-arn": "arn:aws:ecr:us-east-1:123456789012:repository/repository-2", "scan-frequency": "CONTINUOUS_SCAN", "previous-scan-frequency": "SCAN_ON_PUSH" }, { "repository-name": "repository-3", "repository-arn": "arn:aws:ecr:us-east-1:123456789012:repository/repository-3", "scan-frequency": "CONTINUOUS_SCAN", "previous-scan-frequency": "SCAN_ON_PUSH" } ], "resource-type": "REPOSITORY", "scan-type": "ENHANCED" } } ``` **Event for an initial image scan (enhanced scanning)** When enhanced scanning is turned on for your registry, the following event is sent by Amazon Inspector when the initial image scan is completed. The `finding-severity-counts` parameter will only return a value for a severity level if one exists. For example, if the image contains no findings at `CRITICAL` level, then no critical count is returned. For more information, see [Scan images for OS and programming language package vulnerabilities in Amazon ECR](image-scanning-enhanced.md). Event pattern: ``` { "source": ["aws.inspector2"], "detail-type": ["Inspector2 Scan"] } ``` Example output: ``` { "version": "0", "id": "739c0d3c-4f02-85c7-5a88-94a9EXAMPLE", "detail-type": "Inspector2 Scan", "source": "aws.inspector2", "account": "123456789012", "time": "2021-12-03T18:03:16Z", "region": "us-east-2", "resources": [ "arn:aws:ecr:us-east-2:123456789012:repository/amazon/amazon-ecs-sample" ], "detail": { "scan-status": "INITIAL_SCAN_COMPLETE", "repository-name": "arn:aws:ecr:us-east-2:123456789012:repository/amazon/amazon-ecs-sample", "finding-severity-counts": { "CRITICAL": 7, "HIGH": 61, "MEDIUM": 62, "TOTAL": 158 }, "image-digest": "sha256:36c7b282abd0186e01419f2e58743e1bf635808231049bbc9d77e5EXAMPLE", "image-tags": [ "latest" ] } } ``` **Event for an image scan finding update (enhanced scanning)** When enhanced scanning is turned on for your registry, the following event is sent by Amazon Inspector when the image scan finding is created, updated, or closed. For more information, see [Scan images for OS and programming language package vulnerabilities in Amazon ECR](image-scanning-enhanced.md). Event pattern: ``` { "source": ["aws.inspector2"], "detail-type": ["Inspector2 Finding"] } ``` Example output: ``` { "version": "0", "id": "42dbea55-45ad-b2b4-87a8-afaEXAMPLE", "detail-type": "Inspector2 Finding", "source": "aws.inspector2", "account": "123456789012", "time": "2021-12-03T18:02:30Z", "region": "us-east-2", "resources": [ "arn:aws:ecr:us-east-2:123456789012:repository/amazon/amazon-ecs-sample/sha256:36c7b282abd0186e01419f2e58743e1bf635808231049bbc9d77eEXAMPLE" ], "detail": { "awsAccountId": "123456789012", "description": "In libssh2 v1.9.0 and earlier versions, the SSH_MSG_DISCONNECT logic in packet.c has an integer overflow in a bounds check, enabling an attacker to specify an arbitrary (out-of-bounds) offset for a subsequent memory read. A crafted SSH server may be able to disclose sensitive information or cause a denial of service condition on the client system when a user connects to the server.", "findingArn": "arn:aws:inspector2:us-east-2:123456789012:finding/be674aaddd0f75ac632055EXAMPLE", "firstObservedAt": "Dec 3, 2021, 6:02:30 PM", "inspectorScore": 6.5, "inspectorScoreDetails": { "adjustedCvss": { "adjustments": [], "cvssSource": "REDHAT_CVE", "score": 6.5, "scoreSource": "REDHAT_CVE", "scoringVector": "CVSS:3.0/AV:N/AC:L/PR:N/UI:R/S:U/C:H/I:N/A:N", "version": "3.0" } }, "lastObservedAt": "Dec 3, 2021, 6:02:30 PM", "packageVulnerabilityDetails": { "cvss": [ { "baseScore": 6.5, "scoringVector": "CVSS:3.0/AV:N/AC:L/PR:N/UI:R/S:U/C:H/I:N/A:N", "source": "REDHAT_CVE", "version": "3.0" }, { "baseScore": 5.8, "scoringVector": "AV:N/AC:M/Au:N/C:P/I:N/A:P", "source": "NVD", "version": "2.0" }, { "baseScore": 8.1, "scoringVector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:U/C:H/I:N/A:H", "source": "NVD", "version": "3.1" } ], "referenceUrls": [ "https://access.redhat.com/errata/RHSA-2020:3915" ], "source": "REDHAT_CVE", "sourceUrl": "https://access.redhat.com/security/cve/CVE-2019-17498", "vendorCreatedAt": "Oct 16, 2019, 12:00:00 AM", "vendorSeverity": "Moderate", "vulnerabilityId": "CVE-2019-17498", "vulnerablePackages": [ { "arch": "X86_64", "epoch": 0, "name": "libssh2", "packageManager": "OS", "release": "12.amzn2.2", "sourceLayerHash": "sha256:72d97abdfae3b3c933ff41e39779cc72853d7bd9dc1e4800c5294dEXAMPLE", "version": "1.4.3" } ] }, "remediation": { "recommendation": { "text": "Update all packages in the vulnerable packages section to their latest versions." } }, "resources": [ { "details": { "awsEcrContainerImage": { "architecture": "amd64", "imageHash": "sha256:36c7b282abd0186e01419f2e58743e1bf635808231049bbc9d77e5EXAMPLE", "imageTags": [ "latest" ], "platform": "AMAZON_LINUX_2", "pushedAt": "Dec 3, 2021, 6:02:13 PM", "lastInUseAt": "Dec 3, 2021, 6:02:13 PM", "inUseCount": 1, "registry": "123456789012", "repositoryName": "amazon/amazon-ecs-sample" } }, "id": "arn:aws:ecr:us-east-2:123456789012:repository/amazon/amazon-ecs-sample/sha256:36c7b282abd0186e01419f2e58743e1bf635808231049bbc9d77EXAMPLE", "partition": "N/A", "region": "N/A", "type": "AWS_ECR_CONTAINER_IMAGE" } ], "severity": "MEDIUM", "status": "ACTIVE", "title": "CVE-2019-17498 - libssh2", "type": "PACKAGE_VULNERABILITY", "updatedAt": "Dec 3, 2021, 6:02:30 PM" } } ``` # Retrieving the findings for enhanced scans in Amazon ECR Retrieving findings You can retrieve the scan findings for the last completed enhanced image scan, and then open the findings in Amazon Inspector to see more detail. The software vulnerabilities that were discovered are listed by severity based on the Common Vulnerabilities and Exposures (CVEs) database. For troubleshooting details for some common issues when scanning images, see [Troubleshooting image scanning in Amazon ECR](image-scanning-troubleshooting.md). ------ #### [ AWS Management Console ] Use the following steps to retrieve image scan findings using the AWS Management Console. **To retrieve image scan findings** 1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/). 1. From the navigation bar, choose the Region where your repository exists. 1. In the navigation pane, choose **Repositories** . 1. On the **Repositories** page, choose the repository that contains the image to retrieve the scan findings for. 1. On the **Images** page, under the **Image tag** column, select the image tag to retrieve the scan findings. 1. To view more details in the Amazon Inspector console, choose the vulnerability name in the **Name** column. ------ #### [ AWS CLI ] Use the following AWS CLI command to retrieve image scan findings using the AWS CLI. You can specify an image using the `imageTag` or ` imageDigest`, both of which can be obtained using the [list-images](https://docs.aws.amazon.com/cli/latest/reference/ecr/list-images.html) CLI command. + [ describe-image-scan-findings](https://docs.aws.amazon.com/cli/latest/reference/ecr/describe-image-scan-findings.html) (AWS CLI) The following example uses an image tag. ``` aws ecr describe-image-scan-findings \ --repository-name name \ --image-id imageTag=tag_name \ --region us-east-2 ``` The following example uses an image digest. ``` aws ecr describe-image-scan-findings \ --repository-name name \ --image-id imageDigest=sha256_hash \ --region us-east-2 ``` ------ # Scan images for OS vulnerabilities in Amazon ECR Basic scanning Amazon ECR basic scanning uses AWS native technology to scan your container images for software vulnerabilities. Basic scanning provides vulnerability detection across a broad set of popular operating systems, sourcing more than 50 data feeds to generate findings for common vulnerabilities and exposures (CVEs). These sources include vendor security advisories, data feeds, threat intelligence feeds, as well as the National Vulnerability Database (NVD) and MITRE. Amazon ECR basic scanning is supported in all regions listed in [AWS Services by Region](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/). Amazon ECR uses the severity for a CVE from the upstream distribution source if available. Otherwise, the Common Vulnerability Scoring System (CVSS) score is used. The CVSS score can be used to obtain the NVD vulnerability severity rating. For more information, see [NVD Vulnerability Severity Ratings](https://nvd.nist.gov/vuln-metrics/cvss). Amazon ECR basic scanning supports filters to specify which repositories to scan on push. Any repositories that don't match a scan on push filter are set to the ** manual** scan frequency which means you must manually start the scan. An image can be scanned once per 24 hours. The 24 hours includes the initial scan on push, if configured, and any manual scans. With basic scanning, you can scan up to 100,000 images per 24 hours in a given registry. The last completed image scan findings can be retrieved for each image. When an image scan is completed, Amazon ECR sends an event to Amazon EventBridge. For more information, see [Amazon ECR events and EventBridge](ecr-eventbridge.md). ## Operating system support for basic scanning As a security best practice and for continued coverage, we recommend that you continue to use supported versions of an operating system. In accordance with vendor policy, discontinued operating systems are no longer updated with patches and, in many cases, new security advisories are no longer released for them. In addition, some vendors remove existing security advisories and detections from their feeds when an affected operating system reaches the end of standard support. After a distribution loses support from its vendor, Amazon ECR may no longer support scanning it for vulnerabilities. Any findings that Amazon ECR does generate for a discontinued operating system should be used for informational purposes only. For a full list of supported operating systems and versions, see [Supported operating systems - Amazon Inspector scan](https://docs.aws.amazon.com/inspector/latest/user/supported.html#supported-os-scan-inspector-scan) in the *Amazon Inspector User Guide*. # Configuring basic scanning for images in Amazon ECR Configuring basic scanning By default, Amazon ECR turns on basic scanning for all private registries. As a result, unless you've changed the scanning settings on your private registry there is no need to turn on basic scanning. You can use the following steps to define one or more scan on push filters. **To turn on basic scanning for your private registry** 1. Open the Amazon ECR console at [ https://console.aws.amazon.com/ecr/private-registry/repositories](https://console.aws.amazon.com/ecr/private-registry/repositories) 1. From the navigation bar, choose the Region to set the scanning configuration for. 1. In the navigation pane, choose **Private registry**, ** Scanning**. 1. On the **Scanning configuration** page, For **Scan type** choose **Basic scanning**. 1. By default all of your repositories are set for **Manual** scanning. You can optionally configure scan on push by specifying **Scan on push filters**. You can set scan on push for all repositories or individual repositories. For more information, see [Filters to choose which repositories are scanned in Amazon ECR](image-scanning-filters.md). **Note** If scan on push is enabled for a repository, scans are also done on images that are restored after being archived. No old scans will be available from the restored image. # Manually scanning an image for OS vulnerabilities in Amazon ECR Manually scanning an image If your repositories aren't configured to **scan on push**, you can manually start image scans. An image can be scanned once per 24 hours. The 24 hours includes the initial scan on push, if configured, and any manual scans. For troubleshooting details for some common issues when scanning images, see [Troubleshooting image scanning in Amazon ECR](image-scanning-troubleshooting.md). ------ #### [ AWS Management Console ] Use the following steps to start a manual image scan using the AWS Management Console. 1. Open the Amazon ECR console at [ https://console.aws.amazon.com/ecr/private-registry/repositories](https://console.aws.amazon.com/ecr/private-registry/repositories) 1. From the navigation bar, choose the Region to create your repository in. 1. In the navigation pane, choose **Repositories** . 1. On the **Repositories** page, choose the repository that contains the image to scan. 1. On the **Images** page, select the image to scan and then choose **Scan**. ------ #### [ AWS CLI ] + [ start-image-scan](https://docs.aws.amazon.com/cli/latest/reference/ecr/start-image-scan.html) (AWS CLI) The following example uses an image tag. ``` aws ecr start-image-scan --repository-name name --image-id imageTag=tag_name --region us-east-2 ``` The following example uses an image digest. ``` aws ecr start-image-scan --repository-name name --image-id imageDigest=sha256_hash --region us-east-2 ``` ------ #### [ AWS Tools for Windows PowerShell ] + [ Get-ECRImageScanFinding](https://docs.aws.amazon.com/powershell/latest/reference/items/Start-ECRImageScan.html) (AWS Tools for Windows PowerShell) The following example uses an image tag. ``` Start-ECRImageScan -RepositoryName name -ImageId_ImageTag tag_name -Region us-east-2 -Force ``` The following example uses an image digest. ``` Start-ECRImageScan -RepositoryName name -ImageId_ImageDigest sha256_hash -Region us-east-2 -Force ``` ------ # Retrieving the findings for basic scans in Amazon ECR Retrieving findings You can retrieve the scan findings for the last completed basic image scan. The software vulnerabilities that were discovered are listed by severity based on the Common Vulnerabilities and Exposures (CVEs) database. For troubleshooting details for some common issues when scanning images, see [Troubleshooting image scanning in Amazon ECR](image-scanning-troubleshooting.md). ------ #### [ AWS Management Console ] Use the following steps to retrieve image scan findings using the AWS Management Console. **To retrieve image scan findings** 1. Open the Amazon ECR console at [ https://console.aws.amazon.com/ecr/private-registry/repositories](https://console.aws.amazon.com/ecr/private-registry/repositories) 1. From the navigation bar, choose the Region to create your repository in. 1. In the navigation pane, choose **Repositories** . 1. On the **Repositories** page, choose the repository that contains the image to retrieve the scan findings for. 1. On the **Images** page, under the **Image tag** column, select the image tag to retrieve the scan findings. ------ #### [ AWS CLI ] Use the following AWS CLI command to retrieve image scan findings using the AWS CLI. You can specify an image using the `imageTag` or ` imageDigest`, both of which can be obtained using the [list-images](https://docs.aws.amazon.com/cli/latest/reference/ecr/list-images.html) CLI command. + [ describe-image-scan-findings](https://docs.aws.amazon.com/cli/latest/reference/ecr/describe-image-scan-findings.html) (AWS CLI) The following example uses an image tag. ``` aws ecr describe-image-scan-findings --repository-name name --image-id imageTag=tag_name --region us-east-2 ``` The following example uses an image digest. ``` aws ecr describe-image-scan-findings --repository-name name --image-id imageDigest=sha256_hash --region us-east-2 ``` ------ #### [ AWS Tools for Windows PowerShell ] + [ Get-ECRImageScanFinding](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-ECRImageScanFinding.html) (AWS Tools for Windows PowerShell) The following example uses an image tag. ``` Get-ECRImageScanFinding -RepositoryName name -ImageId_ImageTag tag_name -Region us-east-2 ``` The following example uses an image digest. ``` Get-ECRImageScanFinding -RepositoryName name -ImageId_ImageDigest sha256_hash -Region us-east-2 ``` ------ # Troubleshooting image scanning in Amazon ECR Troubleshooting image scanning The following are common image scan failures. You can view errors like this in the Amazon ECR console by displaying the image details or through the API or AWS CLI by using the ` DescribeImageScanFindings` API. UnsupportedImageError You may get an `UnsupportedImageError` error when attempting to perform a basic scan on an image that was built using an operating system that Amazon ECR doesn't support basic image scanning for. Amazon ECR supports package vulnerability scanning for major versions of Amazon Linux, Amazon Linux 2, Debian, Ubuntu, CentOS, Oracle Linux, Alpine, and RHEL Linux distributions. Once a distribution loses support from its vendor, Amazon ECR may no longer support scanning it for vulnerabilities. Amazon ECR does not support scanning images built from the [Docker scratch](https://hub.docker.com/_/scratch) image. When using enhanced scanning, Amazon Inspector supports scanning for specific operating systems and media types. For a full list, see [Supported operating systems and media types](https://docs.aws.amazon.com/inspector/latest/user/enable-disable-scanning-ecr.html#ecr-supported-media) in the *Amazon Inspector User Guide*. An `UNDEFINED` severity level is returned You may receive a scan finding that has a severity level of ` UNDEFINED`. The following are the common causes for this: + The vulnerability was not assigned a priority by the CVE source. + The vulnerability was assigned a priority that Amazon ECR did not recognize. To determine the severity and description of a vulnerability, you can view the CVE directly from the source. ## Understanding scan status `SCAN_ELIGIBILITY_EXPIRED` When enhanced scanning using Amazon Inspector is enabled for your private registry and you are viewing your scan vulnerabilities, you may see a scan status of ` SCAN_ELIGIBILITY_EXPIRED`. The following are the most common causes of this. + When you initially turn on enhanced scanning for your private registry, Amazon Inspector only recognizes images pushed to Amazon ECR in the last 30 days, based on the image push timestamp. Older images will have the ` SCAN_ELIGIBILITY_EXPIRED` scan status. If you'd like these images to be scanned by Amazon Inspector you should push them again to your repository. + If the **ECR re-scan duration** is changed in the Amazon Inspector console and that time elapses, the scan status of the image is changed to ` inactive` with a reason code of `expired`, and all associated findings for the image are scheduled to be closed. This results in the Amazon ECR console listing the scan status as ` SCAN_ELIGIBILITY_EXPIRED`.