Image scanning - Amazon ECR

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

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 image scan findings.

For AWS Management Console steps, see Creating a repository.

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

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 image scan findings.

For AWS Management Console steps, see Editing a repository.

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.

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.

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.

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

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.

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.

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

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