Basic scanning - Amazon ECR
Using basic scanningManually scanning an imageRetrieving image scan findings
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Basic scanning

The improved basic scanning feature is in preview release for Amazon ECR and is subject to change. During this public preview, you can only use the Amazon Web Services Management Console to opt-in for the Improved basic scanning version.

Amazon ECR provides two versions of basic scanning which use the Common Vulnerabilities and Exposures (CVEs) database; the current GA version that uses the open-source Clair project and a newly improved version of basic scanning (in preview) that uses our Amazon native technology. With either version of Amazon ECR basic scanning enabled on your private registry, you can configure repository filters to specify which repositories are set to scan on push or you can perform manual scans. Amazon ECR provides a list of scan findings. Each container image may be scanned once per 24 hours. You can review the scan findings for information about the security of the container images that are being deployed by using the DescribeImageScanFindings API or within the console. For more information about Clair, see Clair on GitHub.

Amazon ECR uses the severity for a CVE from the upstream distribution source if available, otherwise we use the Common Vulnerability Scoring System (CVSS) score. The CVSS score can be used to obtain the NVD vulnerability severity rating. For more information, see NVD Vulnerability Severity Ratings.

Any repositories not matching a scan on push filter will be set to the manual scan frequency which means to perform a scan, you must manually trigger the scan. The last completed image scan findings can be retrieved for each image. Amazon ECR sends an event to Amazon EventBridge (formerly called CloudWatch Events) when an image scan is completed. For more information, see Amazon ECR events and EventBridge.

Important

The new version of basic scanning is supported in the following regions:

  • Asia Pacific (Hong Kong) (ap-east-1)

  • Europe (Stockholm) (eu-north-1)

  • Middle East (Bahrain) (me-south-1)

  • Asia Pacific (Mumbai) (ap-south-1)

  • Europe (Paris) (eu-west-3)

  • Amazon GovCloud (US-East) (us-gov-east-1)

  • Africa (Cape Town) (af-south-1)

  • Asia Pacific (Jakarta) (ap-southeast-3)

  • Europe (Frankfurt) (eu-central-1)

  • Europe (Ireland) (eu-west-1)

  • South America (São Paulo) (sa-east-1)

  • US East (Ohio) (us-east-2)

  • Amazon GovCloud (US-West) (us-gov-west-1)

  • Asia Pacific (Tokyo) (ap-northeast-1)

  • Asia Pacific (Seoul) (ap-northeast-2)

  • Asia Pacific (Osaka) (ap-northeast-3)

  • Europe (Milan) (eu-south-1)

  • Europe (London) (eu-west-2)

  • US East (N. Virginia) (us-east-1)

  • Asia Pacific (Singapore) (ap-southeast-1)

  • Asia Pacific (Sydney) (ap-southeast-2)

  • Canada (Central) (ca-central-1)

  • US West (N. California) (us-west-1)

  • US West (Oregon) (us-west-2)

  • Europe (Zurich) (eu-central-2)

For troubleshooting details for some common issues when scanning images, see Troubleshooting image scanning issues.

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. Once 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. Listed below are the current supported operating systems and versions.

Operating System Version
Alpine Linux (Alpine) 3.19
Alpine Linux (Alpine) 3.18
Alpine Linux (Alpine) 3.17
Alpine Linux (Alpine) 3.16
Amazon Linux 2 (AL2) AL2
Amazon Linux 2023(AL2023) AL2023
CentOS Linux (CentOS) 7
Debian Server (Bookworm) 12
Debian Server (Bullseye) 11
Debian Server (Buster) 10
Oracle Linux (Oracle) 9
Oracle Linux (Oracle) 8
Oracle Linux (Oracle) 7
Ubuntu (Lunar) 23.04
Ubuntu (Jammy) 22.04 (LTS)
Ubuntu (Focal) 20.024 (LTS)
Ubuntu (Bionic) 18.04 (ESM)
Ubuntu (Xenial) 16.04 (ESM)
Ubuntu (Trusty) 14.04 (ESM)
Red Hat Enterprise Linux (RHEL) 7
Red Hat Enterprise Linux (RHEL) 8
Red Hat Enterprise Linux (RHEL) 9

Using basic scanning

Basic scanning with Clair

By default, Amazon ECR enables basic scanning on all private registries. As a result, unless you've changed the scanning settings on your private registry there should be no need to enable basic scanning. You may use the following steps to verify that basic scanning is enabled and define one or more scan on push filters.

To turn on basic scanning for your private registry (Amazon Web Services Management Console)

The scanning configuration is defined at the private registry level on a per-Region basis.

  1. Open the Amazon ECR console at https://console.amazonaws.cn/ecr/repositories.

  2. From the navigation bar, choose the Region to set the scanning configuration for.

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

  4. On the Scanning configuration page, For Scan type choose Basic scanning.

  5. 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 Using filters.

Improved basic scanning with Amazon native technology (In preview)

A new version of Amazon ECR basic scanning is now available in preview.

To turn on the improved basic scanning for your private registry (Amazon Web Services Management Console)

The scanning configuration is defined at the private registry level on a per-Region basis.

  1. Open the Amazon ECR console at https://console.amazonaws.cn/ecr/repositories.

  2. From the navigation bar, choose the Region to set the scanning configuration for.

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

  4. On the Scanning configuration page, For Scan type choose Improved basic scanning (In preview) - new.

  5. 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 Using filters.

Manually scanning an image

You can start image scans manually when you want to scan images in repositories that aren't configured to scan on push. An image can only be scanned once each day. This limit 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 issues.

Amazon Web Services Management Console

Use the following steps to start a manual image scan using the Amazon Web Services Management Console.

  1. Open the Amazon ECR console at https://console.amazonaws.cn/ecr/repositories.

  2. From the navigation bar, choose the Region to create your repository in.

  3. In the navigation pane, choose Repositories.

  4. On the Repositories page, choose the repository that contains the image to scan.

  5. On the Images page, select the image to scan and then choose Scan.

Amazon CLI

  • start-image-scan (Amazon 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
Amazon Tools for Windows PowerShell

  • Get-ECRImageScanFinding (Amazon 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 image scan findings

You can retrieve the scan findings for the last completed image scan. The findings list by severity the software vulnerabilities that were discovered, based on the Common Vulnerabilities and Exposures (CVEs) database.

For troubleshooting details for some common issues when scanning images, see Troubleshooting image scanning issues.

Amazon Web Services Management Console

  1. Open the Amazon ECR console at https://console.amazonaws.cn/ecr/repositories.

  2. From the navigation bar, choose the Region to create your repository in.

  3. In the navigation pane, choose Repositories.

  4. On the Repositories page, choose the repository that contains the image to retrieve the scan findings for.

  5. On the Images page, under the Vulnerabilities column, select Details for the image to retrieve the scan findings for.

Amazon CLI

Use the following Amazon CLI command to retrieve image scan findings using the Amazon CLI. You can specify an image using the imageTag or imageDigest, both of which can be obtained using the list-images CLI command.

  • describe-image-scan-findings (Amazon 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
Amazon Tools for Windows PowerShell

  • Get-ECRImageScanFinding (Amazon 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