Amazon ECR
User Guide (API Version 2015-09-21)

Image Scanning

Amazon ECR image scanning helps in identifying software vulnerabilities in your container images. Amazon ECR uses the Common Vulnerabilities and Exposures (CVEs) database from the open source CoreOS Clair project and provides you with 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 CoreOS Clair, see CoreOS Clair.

You can manually scan container images stored in Amazon ECR, or you can configure your repositories to scan images when you push them to a repository. 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.

Configuring a Repository to Scan on Push

You can configure the image scan settings either for a new repository during creation or for an existing repository. When scan on push is enabled, images are scanned after being pushed to a repository. If scan on push is disabled on a repository then you must manually start each image scan to get the scan results.

Creating a New Repository to Scan on Push

When a new repository is configured to scan on push, all new images pushed to the repository will be scanned. Results from the last completed image scan can then be retrieved. For more information, see Retrieving Scan Findings.

For AWS Management Console steps, see Creating a Repository.

To create a repository configured for scan on push (AWS CLI)

Use the following command to create a new repository with image scan on push configured.

  • create-repository (AWS CLI)

    aws ecr create-repository --repository-name name --image-scanning-configuration scanOnPush=true --region us-east-2
To create a repository configured for scan on push (AWS Tools for Windows PowerShell)

Use the following command to create a new repository with image scan on push configured.

  • New-ECRRepository (AWS Tools for Windows PowerShell)

    New-ECRRepository -RepositoryName name -ImageScanningConfiguration_ScanOnPush true -Region us-east-2 -Force

Configure an Existing Repository to Scan on Push

Your existing repositories can be configured to scan images when you push them to a repository. This setting will apply to future image pushes. Results from the last completed image scan can then be retrieved. For more information, see Retrieving Scan Findings.

For AWS Management Console steps, see Editing a Repository.

To edit the settings of an existing repository (AWS CLI)

Use the following command to edit the image scanning settings of an existing repository.

  • put-image-scanning-configuration (AWS CLI)

    aws ecr put-image-scanning-configuration --repository-name name --image-scanning-configuration scanOnPush=true --region us-east-2

    Note

    To disable image scan on push for a repository, specify scanOnPush=false.

To edit the settings of an existing repository (AWS Tools for Windows PowerShell)

Use the following command to edit the image scanning settings of an existing repository.

  • New-ECRRepository (AWS Tools for Windows PowerShell)

    Write-ECRImageScanningConfiguration -RepositoryName name -ImageScanningConfiguration_ScanOnPush true -Region us-east-2 -Force

Manually Scanning an Image

You can start image scans manually when you want to scan images in repositories that are not configured to scan on push. An image can only be scanned once per day. This limit includes the initial scan on push, if enabled, 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 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 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.

  • 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