Skip to main content

ECR Repositories Have Tag Immutability Enabled

Overview​

This check verifies that your Amazon ECR (Elastic Container Registry) repositories have tag immutability enabled. When tag immutability is turned on, image tags cannot be overwritten once they are assigned to an image.

Think of it like a permanent label: once you tag an image as v1.2.3, that tag always refers to the same image and cannot be reassigned to a different one.

Risk​

Without tag immutability, container images can be overwritten, which creates several security and operational risks:

  • Inconsistent deployments: A tag like latest or v1.0 could point to different images at different times, causing unexpected behavior
  • Supply chain attacks: Attackers with push access could replace a trusted image with a malicious one while keeping the same tag
  • Audit difficulties: You cannot reliably trace which exact image was deployed if tags can change
  • Accidental overwrites: A CI/CD pipeline mistake could replace a production image

Severity: Medium

Remediation Steps​

Prerequisites​

You need permission to modify ECR repository settings. Specifically, the ecr:PutImageTagMutability permission is required.

AWS Console Method​

  1. Open the Amazon ECR console
  2. In the left navigation, click Private registry then Repositories
  3. Select the repository you want to update
  4. Click Actions then Edit
  5. Under Image tag mutability, select Immutable
  6. Click Save

Repeat for each repository that needs this setting.

AWS CLI

Enable tag immutability for a single repository:

aws ecr put-image-tag-mutability \
    --repository-name <your-repository-name> \
    --image-tag-mutability IMMUTABLE \
    --region us-east-1

Enable tag immutability for all repositories in your account:

# List all repositories and enable immutability on each
aws ecr describe-repositories \
    --region us-east-1 \
    --query 'repositories[*].repositoryName' \
    --output text | tr '\t' '\n' | while read repo; do
    echo "Enabling tag immutability for: $repo"
    aws ecr put-image-tag-mutability \
        --repository-name "$repo" \
        --image-tag-mutability IMMUTABLE \
        --region us-east-1
done

Check current tag mutability settings:

aws ecr describe-repositories \
    --region us-east-1 \
    --query 'repositories[*].{Name:repositoryName,TagMutability:imageTagMutability}' \
    --output table
CloudFormation

Use the ImageTagMutability property when creating ECR repositories:

AWSTemplateFormatVersion: '2010-09-09'
Description: ECR repository with tag immutability enabled

Resources:
  ECRRepository:
    Type: AWS::ECR::Repository
    Properties:
      RepositoryName: my-secure-repository
      ImageTagMutability: IMMUTABLE
      ImageScanningConfiguration:
        ScanOnPush: true
      EncryptionConfiguration:
        EncryptionType: AES256

Outputs:
  RepositoryUri:
    Description: ECR repository URI
    Value: !GetAtt ECRRepository.RepositoryUri

Key property:

  • ImageTagMutability: IMMUTABLE - Prevents image tags from being overwritten
Terraform

Use the image_tag_mutability argument when creating ECR repositories:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "us-east-1"
}

resource "aws_ecr_repository" "secure_repository" {
  name                 = "my-secure-repository"
  image_tag_mutability = "IMMUTABLE"

  image_scanning_configuration {
    scan_on_push = true
  }

  encryption_configuration {
    encryption_type = "AES256"
  }

  tags = {
    Environment = "production"
    ManagedBy   = "terraform"
  }
}

output "repository_url" {
  description = "ECR repository URL"
  value       = aws_ecr_repository.secure_repository.repository_url
}

Key argument:

  • image_tag_mutability = "IMMUTABLE" - Prevents image tags from being overwritten

Verification​

After making changes, verify that tag immutability is enabled:

  1. In the ECR console, select your repository
  2. Check that Image tag mutability shows Immutable
CLI Verification
aws ecr describe-repositories \
    --repository-names <your-repository-name> \
    --region us-east-1 \
    --query 'repositories[0].imageTagMutability'

Expected output: "IMMUTABLE"

List all repositories with mutable tags (to find remaining issues):

aws ecr describe-repositories \
    --region us-east-1 \
    --query 'repositories[?imageTagMutability==`MUTABLE`].repositoryName' \
    --output table

Additional Resources​

Notes​

  • Existing images are not affected: Enabling immutability only prevents future tag overwrites; existing images and tags remain unchanged
  • Use versioned tags: Adopt a tagging strategy that uses unique versions (e.g., v1.2.3, git commit SHA) rather than mutable tags like latest
  • CI/CD adjustments may be needed: If your pipelines rely on overwriting tags (like pushing to latest repeatedly), you will need to update them to use unique tags
  • Immutable with exclusions: AWS now supports IMMUTABLE_WITH_EXCLUSION mode which allows specific tag patterns to remain mutable while protecting others - useful for development workflows