Compliance

Enable ECR tag immutability

Security Hub ECR.2 — mutable tags mean a known-good ":v1.2.3" image can be silently replaced with a different one. Make tags immutable.

9 min·10 sections·AWS

Last reviewed 27 May 2026

Remediates AWS Security Hub: ECR.2

ECR tag immutability: the basics

What does "mutable" actually mean for a container tag?

An Elastic Container Registry (ECR) repository holds container image manifests, each addressed by a content-hash digest (sha256:...). Tags like :v1.2.3 or :latest are just human-readable labels that point at one of those digests. The image itself is immutable — the digest is a hash of the bytes — but in the default MUTABLE mode the tag-to-digest mapping is a writable pointer. Anyone with ecr:PutImage can push a new image, reuse the same tag, and silently re-aim the label at a different digest.

What "bad" looks like: your build pipeline pushes myapp:v1.2.3 on Monday, you audit it, and your Kubernetes deployment pulls that exact tag. On Friday a compromised CI token (or a sloppy engineer) pushes a different image under the same :v1.2.3 tag. The deployment restarts, pulls the tag, and runs new bytes. Nothing in your audit log or your manifest history changes — from the workload's perspective it's still :v1.2.3.

AWS Security Hub flags this exact pattern as control ECR.2 ("ECR private repositories should have tag immutability configured"). The control simply checks the repo's imageTagMutability setting. IMMUTABLE passes; MUTABLE fails. It's a one-flag fix — but the discipline change around how you tag images is the actual work.

In this lesson you'll learn why mutable image tags are a supply-chain vulnerability, how to identify which of your ECR repositories still allow them, and exactly which CLI calls flip the setting. You'll also see the tagging discipline that has to come with the change — because flipping the flag without retraining your pipelines is how you brick a deploy at 3am.

Fun fact

The :latest tag broke an entire airline

In 2021 a regional carrier traced an outage to a base image push: their build system kept pulling python:3.9 from a public registry under a mutable tag, the upstream maintainer rebuilt the tag against a newer Debian, and a glibc dependency drift broke a native module in production. Total downtime: 6 hours. The remediation wasn't "never use Python" — it was "never trust a tag you don't control the immutability of." Pinning to a digest or to an immutable internal mirror is the only way to know your :v1.2.3 is the :v1.2.3 you audited.

Locking down a mutable ECR repo in action

Marco is the platform lead at a fintech. A weekly Security Hub digest lands in his inbox: 14 ECR.2 findings across the production account. Severity: MEDIUM. Affected resources: every repository his team owns, plus a handful left over from a contractor project.

He doesn't flip them all at once. Some repos are pushed to by build pipelines that re-use tags like :dev or :staging deliberately — those will start failing the moment he turns immutability on. He needs to see which repos still have mutable settings, what their last-pushed-tag patterns look like, and then make the change repo by repo.

He starts by listing every repository's mutability state in one shot.

First, list every private repo with its mutability flag. The query slices to just the three fields that matter for triage.

$ aws ecr describe-repositories --query "repositories[].{Name:repositoryName,Mutability:imageTagMutability,URI:repositoryUri}" --output table

┌────────────────────┬──────────────┬───────────────────────────────┐

│ Name │ Mutability │ URI │

├────────────────────┼──────────────┼───────────────────────────────┤

│ payments-api │ MUTABLE │ 1234.dkr.ecr.../payments-api │

│ ledger-worker │ MUTABLE │ 1234.dkr.ecr.../ledger-worker │

│ risk-scoring │ IMMUTABLE │ 1234.dkr.ecr.../risk-scoring │

│ legacy-batch │ MUTABLE │ 1234.dkr.ecr.../legacy-batch │

└────────────────────┴──────────────┴───────────────────────────────┘

# Three repos still MUTABLE. risk-scoring already migrated — use it as the template.

Repo-by-repo mutability state for the production account.

Now flip payments-api to IMMUTABLE. The call is idempotent — re-running it on an already-immutable repo is a no-op.

$ aws ecr put-image-tag-mutability --repository-name payments-api --image-tag-mutability IMMUTABLE

{

"registryId": "123456789012",

"repositoryName": "payments-api",

"imageTagMutability": "IMMUTABLE"

}

# Existing tags keep their current digests. Future pushes to an existing tag will be rejected.

One flag flip. The next push that tries to re-tag an existing label returns TagAlreadyExistsException.

Tag immutability under the hooddeep dive

Every push to ECR is an ecr:PutImage API call that sends a manifest, a digest, and zero or more tags. With imageTagMutability = MUTABLE, the registry accepts the call and overwrites whatever the tag previously pointed at — the old manifest is still in the repo (referenced by its digest), but the tag now resolves to the new one. With IMMUTABLE, the same call returns TagAlreadyExistsException if any of the tags are already in use. The image bytes are accepted (the digest is still pushed), but the human-readable label refuses to move.

Flipping the flag is a metadata-only change on the repository — it does not rewrite history. Tags that were mutated yesterday stay where they last pointed; you just can't mutate them again. This is why IMMUTABLE is safe to enable on a live repo: existing deployments pulling current tags don't see anything different, but the next attempt to re-use a tag fails fast.

Security Hub's ECR.2 control runs against AWS Config's recorded state for each ECR repository and re-evaluates within minutes of a configuration change. The fix is real-time visible — by the time you finish reading the Security Hub finding, the repo you just flipped will already show as compliant.

# The exact check ECR.2 performs — any MUTABLE repo fails the control.
aws ecr describe-repositories \
  --query "repositories[?imageTagMutability=='MUTABLE'].repositoryName" \
  --output text

What is the impact of leaving tags mutable?

The primary impact is a supply-chain attack vector. An attacker with ecr:PutImage on a repo — stolen CI credentials, a compromised developer laptop, an over-permissive IAM role on a build server — can replace :v1.2.3 or :latest with a malicious image. Every workload pulling that tag on its next restart runs the attacker's bytes. Because the tag string didn't change, nothing in your deployment manifests, your audit records, or your monitoring suggests anything happened.

The second-order impact is forensic. After an incident you need to prove what code was running where, and when. With mutable tags you can't — the same label has pointed at multiple digests over time, and ECR doesn't keep an audit trail of who pushed which digest under which tag. With immutable tags every release is a permanent record: :v1.2.3 always means the digest it meant on Monday.

The regulatory impact is now explicit. The CIS Docker Benchmark, NIST SP 800-190 (Application Container Security), and the SLSA framework all call out tag immutability and digest pinning as baseline controls. SOC 2 and PCI auditors increasingly ask for evidence that container artefacts are immutable end-to-end — a MUTABLE ECR repo is the simplest way to fail that question.

The cost impact is small but real: a mutated tag leaves the old manifest in the repository (still billable by storage), and most teams never garbage-collect. Repos that have been overwritten on :latest weekly for two years routinely hold hundreds of orphan manifests. Lifecycle policies cleaning these up usually shave a small but non-zero amount off the storage line.

How do you safely enable tag immutability?

Flipping immutability is a four-step loop. The flag itself is one CLI call — the real work is making sure your build pipelines stop re-using tags before you turn it on.

1. Inventory which repos are still MUTABLE

Run aws ecr describe-repositories across every account and region and filter on imageTagMutability=='MUTABLE'. Multi-account orgs should script this via AWS Organizations and a cross-account read role — ECR is per-region, so a single account easily holds dozens of repos across us-east-1, eu-west-1, and friends.

2. Retire :latest from your build pipelines

Switch your CI to tag every image with an immutable identifier — a git commit SHA is the canonical choice (myapp:7e3f2a1), with optional semver (myapp:v1.2.3) for human-readable releases. :latest can still exist if your registry only pushes to it once and never re-tags. The discipline is: a tag is a name for one specific build, forever.

3. Flip the flag and pin downstream consumers to digests

Run aws ecr put-image-tag-mutability --image-tag-mutability IMMUTABLE on every cleared repo. For the highest-trust paths — production deploys, base images in your Dockerfiles — go one step further and pin to the digest (FROM myapp@sha256:...). Pair this with image signing (Notary v2 or Sigstore/cosign) so the digest can be cryptographically verified at pull time.

4. Prevent recurrence with AWS Config and SCPs

Enable the AWS Config managed rule ecr-private-tag-immutability-enabled to alert within minutes if any new ECR repo is created without immutability set. For prevention, attach a Service Control Policy that denies ecr:CreateRepository calls unless ecr:imageTagMutability=IMMUTABLE is specified — engineers can still create repos, but only immutable ones.

# Flip every MUTABLE repo in the current account/region to IMMUTABLE in one pass.
aws ecr describe-repositories \
  --query "repositories[?imageTagMutability=='MUTABLE'].repositoryName" \
  --output text \
  | tr '\t' '\n' \
  | while read repo; do
      echo "Flipping $repo"
      aws ecr put-image-tag-mutability \
        --repository-name "$repo" \
        --image-tag-mutability IMMUTABLE
    done

# Verify the change took effect.
aws ecr describe-repositories \
  --query "repositories[?imageTagMutability=='MUTABLE'].repositoryName"

Quick quiz

Question 1 of 5

You enable IMMUTABLE on an ECR repo whose CI still pushes :latest on every build. What happens to the next build?

Keep learning

Dig deeper into ECR hardening and container supply-chain security.

You've completed Enable ECR tag immutability. You can now inventory mutable ECR repositories across an account, retire :latest in favour of commit-SHA tags, flip immutability safely, and prevent regressions with AWS Config and SCPs. The next time Security Hub fires an ECR.2 finding, you'll have a four-step loop ready to run.

Back to the library

ECR tag immutability: what it means for cost, risk, and auditability

A near-zero-cost configuration change that closes a supply-chain gap with direct audit implications

Amazon ECR is the container image registry that stores the software your cloud workloads run. By default, the human-readable labels on those images — version tags like :v1.2.3 — can be silently overwritten. Anyone with the right access credential can push a different image under an existing tag and every service pulling that label on restart runs whatever the new bytes contain. Security Hub flags this as control ECR.2 at Medium severity.

From a finance and governance standpoint, mutable tags create two direct exposures. First, an audit gap: if a version tag can be rewritten, you cannot prove after the fact what code was running during a given period. SOC 2 and PCI auditors increasingly ask for evidence of container artefact immutability — a MUTABLE ECR repo is the quickest way to fail that question. Second, there is a small but real storage cost: when a tag is overwritten the old image stays in the repo billing you for storage, and most teams never clean them up. Repos with years of overwritten tags routinely hold hundreds of orphan manifests.

The fix — flipping a single setting per repository — has effectively zero recurring cost. This is one of the few security controls where the finance calculus is one-sided: the risk and audit exposure of leaving it MUTABLE is real; the cost of making it IMMUTABLE is negligible. The actual work is a one-time pipeline change to retire reused tags in favour of unique per-build identifiers.

This lesson is for the finance partner who needs to understand what ECR tag immutability protects, what it costs (almost nothing), and what the audit implications are of leaving it off. It covers why a MUTABLE ECR repository is an explicit gap in container provenance, how that gap surfaces in SOC 2 and PCI reviews, the small storage cost of orphaned overwritten images, and why this is one of the few security controls where the finance case is entirely one-directional. No CLI knowledge required.

Fun fact

The :latest tag broke an entire airline

How a finance partner frames the ECR.2 remediation conversation

Priya is the finance partner aligned to the platform team. The ECR.2 findings appear on the compliance dashboard — 14 repositories flagged MUTABLE in production. She doesn't need to understand the CLI to have a useful perspective. Her question is: what's the cost of fixing it, and what's the cost of leaving it?

The fix cost is nearly zero. Flipping the immutability flag takes minutes per repository and adds no recurring charge. The pipeline change — retiring :latest in favour of unique per-build tags — is a one-time engineering task, not ongoing spend. The only material cost is the engineering time to do it, measured in hours not days.

The cost of leaving it is harder to quantify but easy to articulate. At the next SOC 2 or PCI review, a MUTABLE ECR registry is an explicit gap in container provenance — the auditor's question is "can you prove what code ran during this period?" and the honest answer with mutable tags is no. There is also a small storage bill from orphaned overwritten images that compounds quietly over time. Priya's guidance to the team is straightforward: this is one of the lowest-cost security controls on the board; the ROI is obvious; prioritise it above higher-effort findings with lesser audit consequences.

The audit exposure and storage cost of mutable ECR repositories

The most direct finance impact of mutable ECR tags is audit exposure. SOC 2, PCI DSS, and supply-chain frameworks now treat container image provenance as a baseline control — the auditor's question is whether you can prove, for any given period, exactly what code was running. With MUTABLE repositories the honest answer is no: the same version label may have pointed at multiple different images over time, and there is no built-in record of which tag pointed where on which date. That is an explicit finding in a compliance review, not a theoretical risk.

The secondary finance impact is a slow-growth storage cost. Every time a mutable tag is overwritten, the old image manifest remains in the repository. The bytes are still there; ECR bills for them. A repository whose build pipeline has been pushing to :latest or :dev weekly for two years can accumulate hundreds of orphaned manifests. Individually each manifest is cheap — ECR storage runs at $0.10 per GB-month — but across dozens of repositories in multiple regions and accounts the unmanaged backlog becomes a visible line. Lifecycle policies can clean this up, but mutable repos create the problem in the first place.

The remediation cost is near-zero ongoing. Flipping a repository to IMMUTABLE is a one-time configuration change with no recurring charge. The engineering work to retire :latest in build pipelines is a bounded one-time task. This makes ECR.2 one of the highest-ROI controls on the compliance dashboard: the fix is cheap and one-directional, the audit risk of leaving it open is real and recurring, and the storage savings from enforcing immutable lifecycle practices can partially offset the engineering time.

From a governance standpoint, every MUTABLE repository that passes an audit cycle without being addressed is a liability that compounds. The right posture for finance is to track the count of MUTABLE production repositories as a risk indicator, ensure the remediation is budgeted as a near-term task rather than a backlog item, and confirm that new repository creation policy defaults to IMMUTABLE so the problem cannot silently regrow.

What finance can drive on ECR.2

Finance doesn't flip the flag, but it owns the framing that makes remediation a prioritised, budgeted task rather than a perpetual backlog item. Three levers matter here.

1. Treat MUTABLE production repos as an open audit liability

Each MUTABLE production ECR repository is an evidence gap in your container provenance story for SOC 2 and PCI. Track the count of MUTABLE production repositories as a risk indicator at the monthly security-and-cost review — not as a technical metric but as a compliance posture one. The target is zero unintentional MUTABLE production repos; any remainder should have a recorded, time-bounded justification.

2. Budget the pipeline migration as a one-time task

The engineering work to retire :latest in build pipelines is bounded and one-time. Frame it as a compliance remediation task with a concrete delivery date rather than a backlog item that slips indefinitely. The cost is engineering hours measured in days, not weeks; the audit risk of deferral compounds at every review cycle.

3. Enforce IMMUTABLE-by-default as a standing policy

Work with engineering to confirm that the Service Control Policy or AWS Config rule preventing new MUTABLE repositories is in place. That converts ECR.2 from a recurring remediation task into a standing control — once the existing repos are fixed and the prevention policy is live, the finding count stays zero without ongoing spend or attention.

Quick quiz

Question 1 of 5

Your SOC 2 auditor asks whether you can prove what container image version was running in the payments service on a specific date last quarter. The ECR repository was MUTABLE at the time. What is the honest answer?

Keep learning

Dig deeper into ECR hardening and container supply-chain security.

You've finished the finance partner's view of ECR tag immutability. You know why MUTABLE repositories create an audit evidence gap for SOC 2 and PCI, how orphaned overwritten images silently inflate ECR storage costs, why this is one of the highest-ROI controls on the compliance board (near-zero fix cost against real ongoing audit exposure), and the three levers — tracking MUTABLE production repos as a risk indicator, budgeting the pipeline migration as a bounded task, and enforcing IMMUTABLE-by-default through policy — that close the finding permanently. Next time ECR.2 appears in the review, you'll have a sharper framing than 'is this an engineering problem?'

Back to the library

ECR tag immutability: the headline

Whether the software running in production is provably the software you reviewed

Container images are the units of software that run in cloud environments. By default, the version labels on those images can be overwritten after the fact — meaning what a service runs on Tuesday under ":v1.2.3" may not be what you approved last week under the same label. Security Hub flags repositories that allow this as a Medium-severity finding.

This is a provenance and accountability question, not a cost one. The fix is a single configuration change per repository with no ongoing spend. The reason it matters at the leadership level is audit: SOC 2, PCI, and supply-chain frameworks now expect evidence that container artefacts are immutable — that what ran during a given period can be proved. A MUTABLE ECR repository is an explicit gap in that proof chain. The healthy end state is simple: every repository is IMMUTABLE by default, pipelines use unique per-build tags, and the registry is a permanent, tamper-resistant record of what was deployed when.

A short read for the executive who wants the plain-English version: what ECR tag immutability means, why it is a provenance and accountability control rather than a technical detail, and what the one-line answer to an auditor's question looks like. You'll leave knowing what the policy should be, what a clean picture looks like, and why this is a near-zero-cost control worth tracking at the governance level.

Fun fact

The :latest tag broke an entire airline

What accountability looks like when this control is in place

At one company the General Counsel asked a pointed question after a security review: "If a regulator asks us to prove what version of the payments service was running on a specific date, can we do that?" The engineering lead's honest answer was: not reliably. The container registry allowed tag overwriting, so the version label in the deployment manifest didn't uniquely identify an image.

After enabling ECR tag immutability across production repositories, the answer changed. Every version tag permanently identifies one specific build. The registry is now a tamper-resistant record: you can pull the deployment log, cross-reference the tag, and prove exactly what code was running and when. That's the kind of evidence chain that satisfies regulators, auditors, and incident investigators alike.

The lesson for leadership is that this control is a provenance policy, not a technical detail. The question it answers is not 'did we scan this image?' but 'is the registry a trustworthy record?' Making tag immutability the default by policy — so new repositories are always created IMMUTABLE — is the one-line governance decision that makes the answer yes.

Why this is on the board-level risk register

The core question this control answers is: can you prove what software was running in your environment during a specific period? That question arises in regulatory audits, post-incident investigations, and customer due-diligence reviews. With mutable ECR tags, the honest answer is no — the same version label may have referred to different code at different times, and there is no registry-level record of the substitution.

This sits at the intersection of two executive-level concerns. The first is supply-chain integrity: a mutable tag means a compromised credential can silently replace production software without triggering any deployment pipeline or change-management alert. The second is regulatory posture: SOC 2 and PCI frameworks now explicitly treat container artefact immutability as a baseline control, and a MUTABLE registry is an evidence gap that shows up in audit reports.

The fix carries no meaningful cost. The governance question is simply whether the policy is set correctly: IMMUTABLE as the default for all production repositories, with every exception a recorded, deliberate decision. That is a one-sentence policy that turns this from a recurring audit finding into a standing control.

The leadership decision on ECR.2

This control requires one policy decision and one delivery commitment — neither requires technical depth.

1. Set the policy: IMMUTABLE is the default

The governance decision is that every production ECR repository must be IMMUTABLE unless there is a documented, time-bounded exception. That policy makes tag immutability the standing baseline, not an optional hardening step. Engineering can enforce it technically; leadership just needs to name it as the expectation.

2. Get the remediation on a delivery date

Existing MUTABLE repositories need a one-time fix. The ask from leadership is a committed completion date — not an open-ended backlog item. Each month these repositories remain MUTABLE is another month of SOC 2 and PCI exposure. The fix is cheap; the delay is the only cost.

3. Close the loop at the next audit cycle

Ask at the next compliance review: are all production ECR repositories IMMUTABLE, and is the prevention policy preventing new MUTABLE repos from being created? A yes to both means this finding is closed permanently, not revisited quarterly. That is the right end state.

Quick quiz

Question 1 of 5

Engineering reports that all production ECR repositories are now IMMUTABLE and a Service Control Policy prevents creating new MUTABLE repos. A dev/test repository remains MUTABLE with a documented, reviewed exception. What is the right read on this posture?

Keep learning

Dig deeper into ECR hardening and container supply-chain security.

That's the lesson. The one policy decision: IMMUTABLE is the default for all production ECR repositories, with exceptions documented and time-bounded. The one delivery commitment: existing MUTABLE repos remediated by a named date. Once those two things are true, this control is closed permanently — not revisited each quarter. The underlying question it answers — 'can you prove what code was running and when?' — goes from 'no' to 'yes, always.'

Back to the library

Enable ECR tag immutability

ECR tag immutability: the basics

The :latest tag broke an entire airline

Locking down a mutable ECR repo in action

Tag immutability under the hooddeep dive

What is the impact of leaving tags mutable?

How do you safely enable tag immutability?

1. Inventory which repos are still MUTABLE

2. Retire :latest from your build pipelines

3. Flip the flag and pin downstream consumers to digests

4. Prevent recurrence with AWS Config and SCPs

Quick quiz

Keep learning

ECR tag immutability: what it means for cost, risk, and auditability

The :latest tag broke an entire airline

How a finance partner frames the ECR.2 remediation conversation

The audit exposure and storage cost of mutable ECR repositories

What finance can drive on ECR.2

1. Treat MUTABLE production repos as an open audit liability

2. Budget the pipeline migration as a one-time task

3. Enforce IMMUTABLE-by-default as a standing policy

Quick quiz

Keep learning

ECR tag immutability: the headline

The :latest tag broke an entire airline

What accountability looks like when this control is in place

Why this is on the board-level risk register

The leadership decision on ECR.2

1. Set the policy: IMMUTABLE is the default

2. Get the remediation on a delivery date

3. Close the loop at the next audit cycle

Quick quiz

Keep learning

Related compliance lessons