Scan Images with ECR on Push

You just pushed a container image to Amazon ECR, high-fived your teammate, and moved on. A week later, that image is running in production, and someone discovers it contains a known critical vulnerability with a public exploit. Now your incident response team is scrambling to patch and redeploy. The pain is real: vulnerabilities in container images are one of the most common paths to a breach, and manually scanning images after they are deployed is a race you will lose. That is why scan images with ECR on push — Amazon's built-in vulnerability scanning that runs automatically the moment an image is pushed — is not a nice-to-have feature, it's a security control your container supply chain needs from day one.

The problem this lesson solves

Container images are like icebergs — what you see in the Dockerfile is only a fraction of what actually ships. Base OS packages, application dependencies, and even the tools you removed in a later layer can hide known vulnerabilities. Scanning an image after it is running in production is like checking your parachute after you've jumped: technically possible, but the consequences of finding a problem are catastrophic.

Manual scanning workflows fail in practice because they rely on humans to remember to run a scanner, wait for results, and act on them — all while new pushes happen continuously. You need a mechanism that automatically triggers a scan for every image pushed to your registry, without adding a single manual step to your CI/CD pipeline. That's exactly what ECR's built-in scanning provides.

The challenge this lesson tackles is threefold: understanding what "scan on push" means, configuring it correctly, and interpreting the results so you can act before vulnerabilities reach production.

Core concept / mental model

Think of Amazon ECR's image scanning as a security checkpoint at the border of your registry. When a container image is pushed, it's like a traveler crossing the border — ECR inspects the image's layers for known vulnerabilities (CVEs) using a continuously updated database of security advisories.

The scanning engine works in two phases:

1. Image extraction: ECR downloads the image layers and constructs a software bill of materials (SBOM) — a list of packages, versions, and operating system components.
2. Vulnerability matching: That SBOM is compared against the Common Vulnerabilities and Exposures (CVE) database. Matches are reported with severity levels (Critical, High, Medium, Low), affected packages, and remediation guidance.

A key mental model to internalize: scanning is not detection — it's detection — it tells you if there's a problem, but it's still up to you to decide how to respond. The scan results are only as good as your follow-up actions, so the goal is to build a workflow where scan results trigger notifications and automated remediation steps.

Pro tip: ECR scanning is not a replacement for runtime security tools like AWS GuardDuty or third-party agents. It's your first line of defense in the build stage, not a comprehensive security posture.

How it works step by step

When you enable scanning on a repository, every new push automatically triggers a scan. But how does that happen under the hood? Let's walk through the lifecycle:

1. You push an image using docker push or via your CI system (e.g., GitHub Actions, Jenkins).
2. ECR receives the push and stores the image manifest and layers.
3. If scanning is enabled (either basic or enhanced scanning), ECR queues the image for scanning.
4. The scan engine extracts package metadata from the image layers.
5. The engine compares against vulnerability databases (CVE feeds from various sources) and produces findings.
6. Results are stored and retrievable via the AWS Console, CLI, or API. You can also route findings to Amazon EventBridge to trigger downstream actions like sending a Slack alert or blocking a deployment.
7. Findings are refreshed periodically when new CVEs are published, so an image pushed months ago might get new findings later.

This process is fully managed by AWS — you don't provision any infrastructure. The key steps are enabling the feature and deciding whether you want basic scanning (free, but only scans on push and limited to OS packages) or enhanced scanning (powered by Amazon Inspector, scans continuously, supports language-specific packages, and has a cost).

But wait — there's an important nuance. By default, basic scanning only scans new pushes, not images that were pushed before you enabled the feature. To scan pre-existing images, you need to trigger a manual rescan. Enhanced scanning, on the other hand, continuously scans all images and re-scans when new CVEs are released.

Hands-on walkthrough

Let's make this concrete. In this hands-on exercise, you'll create an ECR repository with scan-on-push enabled, push a real image, and view the scan results.

Prerequisites

• AWS CLI installed and configured with appropriate credentials
• Docker installed (for pushing the image)
• An AWS region where ECR and (optionally) Amazon Inspector are available

Step 1: Create a repository with scan-on-push enabled

Use the AWS CLI to create a repository with the --image-scanning-configuration parameter set to scanOnPush=true:

aws ecr create-repository \
    --repository-name demo-app \
    --image-scanning-configuration scanOnPush=true \
    --region us-east-1

You should see output similar to:

{
    "repository": {
        "repositoryName": "demo-app",
        "repositoryArn": "arn:aws:ecr:us-east-1:123456789012:repository/demo-app",
        "imageScanningConfiguration": {
            "scanOnPush": true
        },
        ...
    }
}

Step 2: Build a simple image and push it

Create a minimal Dockerfile to simulate a real scenario:

FROM ubuntu:20.04
RUN apt-get update && apt-get install -y curl
CMD ["echo", "Hello"]

Build, tag, and push:

# Authenticate your Docker client
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

# Build the image
docker build -t 123456789012.dkr.ecr.us-east-1.amazonaws.com/demo-app:latest .

# Push
docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/demo-app:latest

Step 3: Check scan status and results

After the push, the scan starts automatically. Use describe-images to see the scan status:

aws ecr describe-images --repository-name demo-app --image-ids imageTag=latest --region us-east-1

Look for "imageScanStatus": {"status": "COMPLETE"}. To see the findings:

aws ecr describe-image-scan-findings \
    --repository-name demo-app \
    --image-id imageTag=latest \
    --region us-east-1

This returns a JSON object with findingSeverityCounts and a list of findings with severity, package name, and CVE ID.

Step 4: Using the AWS Console (alternative)

If you prefer a GUI, navigate to the ECR console → your repository → select the image tag → click on the Scan findings tab. You'll see a visual summary of severities and each finding with remediation advice.

Pro tip: Do not ignore "negligible" findings. While they might not be exploitable today, they can become critical later as new attack techniques emerge. Set up a regular review cadence.

Compare options / when to choose what

When to choose basic scanning:

• You're building a small side project or a prototype where budget is a primary concern.
• You have a mature CI/CD that pushes frequently, and you scan at the build stage as part of your pipeline.
• You're just getting started with container security and want a zero-config initial layer.

When to choose enhanced scanning:

• You have production workloads that handle sensitive data.
• You need to catch vulnerabilities in application dependencies (e.g., pip packages) that basic scanning misses entirely.
• You want automatic re-scanning when a new CVE is published — after a critical vulnerability is announced, you don't want to wait for a new push to discover you're affected.

Troubleshooting & edge cases

Common issues and fixes

1. "Scan status: IN_PROGRESS" forever over a long period

The scan might time out due to a large image or unsupported architecture. ECR scanning works with Linux images (x86 and ARM) but may not support Windows containers. Check the image size — very large images can take longer, but if it's stuck for hours, inspect the image layers for unusual package managers that might not be parsed correctly.

2. Scan reports no findings, but you know there's a vulnerability

Basic scanning only looks at OS packages. If your vulnerability is in a Python or Node.js dependency, basic scanning will not see it. Also, if you're using a minimal base image like alpine, it uses a different package manager (apk) that may have limited CVE coverage compared to Debian/Ubuntu. Verify the vulnerability is part of the OS layer, not an application layer.

3. No scan triggered on push

Double-check that the repository's scanOnPush configuration is true. If you created the repository before enabling scanning, changes to repository settings might not take effect for existing images — you'll have to manually trigger a scan via the console or CLI using start-image-scan.

4. Findings disappear after a while

This is expected when the upstream CVE database removes an entry (e.g., it was disputed). Image scans are point-in-time snapshots; for continuous compliance, set up a scheduled rescan or use enhanced scanning.

5. IAM permission errors when using the CLI

Your IAM user/role needs permissions like ecr:StartImageScan, ecr:DescribeImages, and ecr:DescribeImageScanFindings. The managed policy AmazonEC2ContainerRegistryFullAccess includes these, but it's always better to scopes down using a custom policy.

6. EventBridge events not firing

By default, ECR sends events to EventBridge with a source of aws.ecr and detail type ECR Scan Finding. Make sure your EventBridge rule pattern matches the exact detail type — it's ECR Scan Finding with a space, not ECR ScanFinding. Also verify that you've created the rule in the same region as your repository.

What you learned & what's next

Now you know how to scan images with ECR on push — a critical control that helps you catch vulnerabilities before they reach production. Let's recap what we covered:

• The problem of manual scanning and why automated scan-on-push is a game-changer.
• The mental model of ECR as a security checkpoint, and the difference between basic and enhanced scanning.
• The step-by-step process from enabling the feature to retrieving findings via CLI or console.
• How to compare basic and enhanced scanning to choose the right fit.
• Real-world troubleshooting to handle common pitfalls.

This is a huge step forward in securing your container supply chain. But scanning images is only half the battle — you need to enforce a policy that prevents vulnerable images from being deployed. The next lesson in this track will show you how to integrate ECR scan findings into your CI/CD pipeline to block vulnerable images automatically. You'll learn how to use EventBridge to trigger a Lambda function that pulls the scan results and fails a deployment if a critical vulnerability exists. That's the final piece that turns a good security practice into a strong, automated shield.

You're building a solid, layered security mindset. Keep going!