Basic scanning

Amazon ECR provides basic scanning type which uses the Common Vulnerabilities and Exposures (CVEs) database from the open-source Clair project. With 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. Amazon ECR uses the Common Vulnerabilities and Exposures (CVEs) database from the open-source Clair project and provides a list of scan findings. You can review the scan findings for information about the security of the container images that are being deployed. 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.

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 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.

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

Using basic scanning

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 (AWS 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.aws.amazon.com/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.

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.

To start a manual scan of an image (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/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.

To start a manual scan of an image (AWS CLI)

Use the following AWS CLI command to start a manual scan of an image. You can specify an image using the imageTag or imageDigest, both of which can be obtained using the list-images CLI command.

• start-image-scan (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

To start a manual scan of an image (AWS Tools for Windows PowerShell)

Use the following AWS Tools for Windows PowerShell command to start a manual scan of an image. You can specify an image using the ImageId_ImageTag or ImageId_ImageDigest, both of which can be obtained using the Get-ECRImage CLI command.

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

To retrieve image scan findings (console)

Use the following steps to retrieve image scan findings using the AWS Management Console.

1. Open the Amazon ECR console at https://console.aws.amazon.com/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.

To retrieve image 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 CLI command.

• describe-image-scan-findings (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

To retrieve image scan findings (AWS Tools for Windows PowerShell)

Use the following AWS Tools for Windows PowerShell command to retrieve image scan findings. You can specify an image using the ImageId_ImageTag or ImageId_ImageDigest, both of which can be obtained using the Get-ECRImage CLI command.

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