The Truth Behind EC2 Metadata at 169.254.169.254 - Link-Local Addresses and IMDSv2 Design
Learn why the EC2 Instance Metadata Service endpoint 169.254.169.254 is a link-local address, the history of SSRF exploitation, and how IMDSv2's token-based authentication came to be.
Where Is 169.254.169.254?
When you access http://169.254.169.254/latest/meta-data/ from inside an EC2 instance, it returns metadata about the instance, including the instance ID, AMI ID, IAM role temporary credentials, and network configuration. The address 169.254.169.254 is not a server on the internet but a local service answered by the underlying infrastructure that hosts the instance. 169.254.0.0/16 is a link-local address range defined in RFC 3927 that is never forwarded beyond routers. This means requests to this address never leave the instance; the underlying infrastructure responds directly. This design makes the metadata service immune to network failures and independent of VPC routing configuration. The metadata service is accessible from the moment an instance launches, even before network configuration completes. This reliability is why cloud-init first retrieves user data and network configuration from the metadata service when performing initial instance setup.
The Capital One Incident - The Day Metadata Was Leaked via SSRF
In 2019, a breach at Capital One (a major US bank) exposed the personal information of approximately 100 million people. The attacker exploited an SSRF (Server-Side Request Forgery) vulnerability in Capital One's web application to retrieve IAM role temporary credentials from the EC2 instance metadata service. SSRF is an attack that forces a server-side application to make requests to arbitrary URLs. The attacker had the web application send a request to http://169.254.169.254/latest/meta-data/iam/security-credentials/role-name, obtaining the IAM role's access key, secret key, and session token. Using these credentials, the attacker accessed S3 buckets and downloaded massive amounts of personal data. This incident exposed a fundamental design weakness in IMDSv1 (Instance Metadata Service Version 1). IMDSv1 returns metadata in response to simple HTTP GET requests, making it easily accessible through SSRF attacks.
IMDSv2 - Defense Through Token-Based Authentication
In response to the Capital One incident, AWS released IMDSv2 (Instance Metadata Service Version 2) in November 2019. IMDSv2 is a token-based authentication mechanism that requires a session token to access metadata. To retrieve metadata with IMDSv2, you must first obtain a session token via a PUT request, then include that token in an HTTP header when sending the GET request. This two-step authentication prevents SSRF attacks because most SSRF vulnerabilities can only execute GET requests. SSRF vulnerabilities capable of executing PUT requests are rare, and the additional complexity of extracting a token from the response header and including it in the next request makes exploitation extremely difficult. Furthermore, IMDSv2 token retrieval requests require the X-aws-ec2-metadata-token-ttl-seconds header, and IP-forwarded requests (which set TTL to 1, preventing them from crossing network hops) are also blocked. The migration to IMDSv2 is progressing in stages, and AWS strongly recommends requiring IMDSv2 and disabling IMDSv1.
The Full Picture of Information Available via Metadata
The metadata service provides a wide range of information: basic instance information (instance-id, instance-type, ami-id, hostname), network information (local-ipv4, public-ipv4, mac, network/interfaces), IAM role temporary credentials (iam/security-credentials/role-name), user data (user-data), and block device mapping (block-device-mapping), among others. The most critical piece is the IAM role temporary credentials. When an IAM role is attached to an EC2 instance, temporary access keys, secret keys, and session tokens become available through the metadata service. AWS SDKs use this mechanism internally and automatically, so developers never need to hardcode access keys in their code. Temporary credentials have an expiration, and the metadata service rotates them automatically before they expire. AWS SDKs re-fetch them based on the remaining lifetime of the credentials they already hold, so applications do not have to manage the expiration themselves. The metadata service also includes instance user data. User data consists of scripts or data specified at instance launch time, used by cloud-init for initial configuration. Including passwords or secrets in user data is dangerous because anyone can read them through the metadata service.
Hardening the Metadata Service
Beyond enabling IMDSv2, there are several ways to further secure the metadata service. First, review HttpPutResponseHopLimit. Specifying 1 explicitly, instead of leaving in place whatever the AMI sets, keeps the metadata service out of reach of setups that require an extra network hop, such as an application inside a Docker container on a bridge network. Conversely, in setups that legitimately reach the metadata service through the host, lowering it stops normal processing as well. Second, disable the metadata service entirely. Setting HttpEndpoint to disabled completely blocks access to the metadata service. For instances that do not need IAM role credentials (those using fixed credentials), disabling the metadata service is the safest option. Third, minimize IAM role permissions. Even if credentials leak from the metadata service, limiting the role's permissions contains the damage. In the Capital One incident, the leaked role had broad access permissions to S3 buckets, which amplified the damage.
References (Official AWS Resources)
The primary sources for this page are the official AWS website and documentation. Check the official pages below for the latest specifications and pricing.
If this page and the official documentation disagree, treat the official documentation as authoritative.