Enforcing IMDSv2 Across Your Entire AWS Estate: The Practical Migration Guide

AWS released IMDSv2 in November 2019, the same year as the Capital One breach that exploited IMDSv1 via an SSRF vulnerability in a WAF. AWS has nudged customers toward IMDSv2 ever since but never forced the migration, because doing so would break a significant number of running applications.

The breakage risk is real. Applications that query the metadata service for credentials include: older AWS SDK versions (pre-2018), custom scripts that directly curl 169.254.169.254 for instance metadata, container workloads that use instance role credentials without the SDK abstraction layer, and tools that pull from the metadata service at startup before the application code runs.

The result is that most AWS environments have a mix of instances: new workloads that use IMDSv2, old workloads that still use v1, and nobody knows which is which. Enforcing IMDSv2 via a Service Control Policy without auditing first breaks production workloads.

AWS Config has a managed rule that checks this: ec2-imdsv2-check. Enable it across all regions and accounts in your organization via a conformance pack, or deploy it via AWS Security Hub's EC2 controls (EC2.8: EC2 instances should use IMDSv2).

For a faster point-in-time check without waiting for Config to evaluate:

aws ec2 describe-instances \
  --query 'Reservations[].Instances[?MetadataOptions.HttpTokens!=`required`].[InstanceId,Tags[?Key==`Name`].Value|[0],MetadataOptions.HttpTokens]' \
  --output table

This returns every instance where HttpTokens is not required, meaning IMDSv1 is still accessible. Run this in every region. For multi-account organizations, use AWS Organizations with the AWS CLI profile chaining, or deploy this as a Lambda that iterates over all accounts via the Organizations API.

Sort the results by instance age and tag. Older instances (launched before 2020) are more likely to run software that queries v1. Instances tagged as dev or test are safer to migrate first.

Before disabling v1 on any instance, enable IMDSv2 in optional mode, meaning v2 is available but v1 still works. Then check CloudWatch metrics to see whether v1 is being used:

AWS publishes two CloudWatch metrics per instance:

• MetadataNoToken: requests using IMDSv1 (no session token)
• MetadataWithToken: requests using IMDSv2

Enable this monitoring by setting HttpPutResponseHopLimit to 2 (or your required value) and HttpTokens to optional on each instance. After 7 to 14 days of production traffic, check MetadataNoToken. If it is zero, the instance is safe to migrate to required. If it is non-zero, something on that instance is still calling v1.

To identify exactly what is making v1 calls on a given instance:

sudo tcpdump -i lo -n 'host 169.254.169.254 and port 80' -w /tmp/imds.pcap

Capture for 60 seconds during normal operation, then read the capture to see which processes are making HTTP (not HTTPS) GET requests to 169.254.169.254 without a PUT session token request preceding them.

The most common sources of IMDSv1 calls and their fixes:

Old AWS SDK versions: boto3 before 1.9.0 and the AWS CLI before 1.16.0 do not support IMDSv2. Update the SDK. For Lambda, update the runtime. For EC2 instances, update via your package manager.

Direct curl to metadata endpoint: Any script with curl http://169.254.169.254/latest/meta-data/iam/security-credentials/ needs to be updated to use the session token flow:

TOKEN=$(curl -s -X PUT 'http://169.254.169.254/latest/api/token' \
  -H 'X-aws-ec2-metadata-token-ttl-seconds: 21600')
curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/iam/security-credentials/

Kubernetes node metadata access: Pods that use kiam, kube2iam, or the AWS VPC CNI to access instance credentials need their configurations updated. In kiam and kube2iam, update to versions that support IMDSv2 token passing. In EKS with the VPC CNI, ensure you are on CNI version 1.11 or later.

Once you have migrated all applications on an instance to use IMDSv2, flip the instance-level setting:

aws ec2 modify-instance-metadata-options \
  --instance-id i-xxxxxxxxx \
  --http-tokens required

For enforcing that all new instances launch with IMDSv2 required, use a Service Control Policy. This SCP denies launching any EC2 instance without IMDSv2 required:

{
  "Effect": "Deny",
  "Action": "ec2:RunInstances",
  "Resource": "arn:aws:ec2:*:*:instance/*",
  "Condition": {
    "StringNotEquals": {
      "ec2:MetadataHttpTokens": "required"
    }
  }
}

Apply this SCP to all OUs in your organization except a break-glass OU for legacy workloads still being migrated. Set a deadline for migrating remaining v1 workloads and remove them from the exception OU as each one is fixed.

ECS tasks on EC2 launch types inherit the instance's IMDS settings. If the underlying EC2 instance requires IMDSv2, task metadata queries use v2. Set HttpPutResponseHopLimit to 2 for ECS instances to allow containers to reach the metadata service (the default TTL of 1 is consumed by the first network hop from container to host).

Lambda does not use IMDS, Lambda functions receive credentials through the Lambda execution environment, not through 169.254.169.254. Lambda is not affected by IMDS enforcement.

EKS pods using the AWS VPC CNI and IRSA (IAM Roles for Service Accounts) do not use the instance metadata service for credentials, they use the EKS OIDC provider. These pods are unaffected by IMDSv2 enforcement. Pods that do not use IRSA and fall back to the instance role are the ones that may be making v1 calls.