How to enforce IMDSv2 on Amazon EC2 instances

The instance metadata service (IMDS) hands out instance details and temporary role credentials to software on the instance. IMDSv1 answers plain requests, while IMDSv2 requires a session token. Requiring IMDSv2 is the safer setting.

• Permissions to look: ec2:DescribeInstances, ec2:GetInstanceMetadataDefaults and CloudWatch read access.
• Permissions to change: ec2:ModifyInstanceMetadataOptions and ec2:ModifyInstanceMetadataDefaults. Your organisation may restrict these with an IAM or service control policy.
• Tools: the AWS CLI configured for the account, and the EC2 console.
• Know the risk: AWS warns that applications or agents that use IMDSv1 will break once IMDSv2 is required. Old SDKs, agents and scripts are the usual cause. Containers may need a metadata hop limit of 2.
• Settings are per Region, so plan for every Region you use.

Steps 1 and 2 only read information. Steps 3 to 5 change your account and are marked CHANGE.

1. Find instances that allow IMDSv1 (read-only). Repeat for each Region:

   aws ec2 describe-instances --region us-east-1 \
     --filters "Name=metadata-options.http-tokens,Values=optional" \
     --query "Reservations[].Instances[].[InstanceId,Tags[?Key=='Name']|[0].Value]" --output table

   Every instance listed accepts IMDSv1.
2. Check whether anything still calls IMDSv1 (read-only). In CloudWatch, look at the MetadataNoToken metric in the EC2 namespace for each instance. AWS says an instance whose IMDSv1 usage is zero is ready to require IMDSv2. If it is not zero, update that software to use IMDSv2 first, and re-check.
3. CHANGE: require IMDSv2 on a running instance. Start with a test instance:

   aws ec2 modify-instance-metadata-options --instance-id i-0123456789abcdef0 --http-tokens required --http-endpoint enabled

   Console: EC2 > Instances > Actions > Instance settings > Modify instance metadata options, then set IMDSv2 to Required. To go back, run the same command with --http-tokens optional. Containers that need it can also use --http-put-response-hop-limit 2.
4. CHANGE: make IMDSv2 the default for new instances. This does not alter existing instances. Run it in each Region:

   aws ec2 modify-instance-metadata-defaults --region us-east-1 --http-tokens required --http-put-response-hop-limit 2

   Also set HttpTokens=required in your launch templates, and use --imds-support v2.0 when you register images. Be careful with that last one: AWS says it cannot be undone on an AMI.
5. CHANGE (optional): enforce it. Once you are sure nothing needs IMDSv1, block launches and changes that would turn it back on:

   aws ec2 modify-instance-metadata-defaults --region us-east-1 --http-tokens required --http-tokens-enforced enabled

   With enforcement on, launching an instance with HttpTokens=optional fails. For many accounts and Regions, AWS Organizations declarative policies can apply the setting centrally. You can also limit who may call the modify APIs with an IAM or service control policy.

These commands only read.

aws ec2 describe-instances --region us-east-1 \
  --filters "Name=metadata-options.http-tokens,Values=optional" \
  --query "Reservations[].Instances[].InstanceId" --output text
aws ec2 get-instance-metadata-defaults --region us-east-1

The first command should print nothing. The second should show HttpTokens as required and, if you enforced it, HttpTokensEnforced as enabled. A ManagedBy value of declarative-policy means a central policy owns the setting. Repeat for every Region, and keep an eye on MetadataNoToken staying at zero.

• Requiring IMDSv2 without checking MetadataNoToken, which breaks software that still uses IMDSv1.
• Believing the account default fixes running instances. It only affects new launches.
• Forgetting that settings are per Region and checking only one.
• Leaving the hop limit at 1 for containerised workloads, so containers cannot reach the metadata service.
• Setting imds-support v2.0 on an AMI whose software is not ready. It cannot be reversed on that AMI.
• Turning on enforcement before launch templates and auto scaling groups are fixed, so new launches fail.

ConfigCobra is read-only: it never changes your AWS. It reads your accounts through an assume-role connection, and its AWS coverage includes CIS Amazon Web Services Foundations v7.0.0 (70 controls) and CIS AWS Compute Services v2.0.0 (82 controls), 306 controls across the four AWS benchmarks. The related checks below cover the metadata service setting.

The AWS inventory lists resources across the accounts in scope with their security properties. Remediation impact analysis shows the affected resources before you apply a fix, and scheduled scans with drift detection send an email when a control regresses.