DEV Community

Understanding AWS Instance Metadata Service: A Closer Look

In the realm of cloud computing, particularly within the Amazon Web Services (AWS) ecosystem, there exists a service that, while invisible to many, plays a crucial role in the efficient management of virtual machines. This is the AWS Instance Metadata Service (IMDS). Below, we unravel what IMDS is, its significance in AWS, where you can find it within the AWS Management Console, and why it needs to be secured.

What is the AWS Instance Metadata Service?

AWS Instance Metadata Service is a specialized service that allows AWS Elastic Compute Cloud (EC2) instances to access instance-specific data, which is pivotal for the configuration or management of the running instance. The service is reachable at a special URL that is only accessible from the EC2 instance itself:

This metadata includes details such as the instance's IP address, the IAM role it is using, information about the AMI (Amazon Machine Image) used to launch the instance, and much more.

Why Does AWS Use IMDS?

IMDS serves as a bridge between the EC2 instance and the AWS environment. It allows instances to bootstrap themselves with the necessary configuration without the need to hard-code sensitive data into the instance or AMI. This can include dynamically setting environment variables, configuring services at runtime, or even obtaining temporary credentials to access other AWS services securely.

Security Implications of IMDS

While IMDS is undeniably useful, it can also pose a security risk if not properly secured. Here are the few potential threats to highlight

  • If an attacker gains access to your EC2 instance, they could potentially retrieve IAM credentials and other sensitive data from the IMDS.
  • AWS introduced IMDSv2, which requires session-oriented requests, to mitigate the risk of unauthorized retrieval of metadata. IMDSv1, on the other hand, allows any process that can access to retrieve instance metadata.

What is IMDSv1 and How it is different from IMDSv2

IMDSv1 stands for "Instance Metadata Service version 1" in AWS (Amazon Web Services). It's a service provided by Amazon EC2 (Elastic Compute Cloud) to allow EC2 instances to retrieve instance-specific data, such as the instance ID, public IP, and user data, among other metadata.
The Instance Metadata Service (IMDS) allows EC2 instances to access metadata about themselves. This metadata includes information like the instance type, security groups, and more. Applications or scripts running on the EC2 instance can use this data to make decisions or to configure themselves accordingly.

  • Endpoint: IMDS is available at a specific IP address ( that can be accessed from within the instance. This is a link-local address, which means it's only accessible from the instance itself and not from outside.

  • IMDSv1 vs IMDSv2: AWS introduced IMDSv2 as an enhanced version of IMDSv1. The primary difference is in the security model:

IMDSv1: Allows direct retrieval of metadata with a simple HTTP GET request to the aforementioned IP.

IMDSv2: Introduces session-based requests. Before fetching metadata, you need to create a session by making a PUT request. This session returns a token, which must be provided in subsequent GET requests for metadata.

  • Security Considerations: IMDSv1 can be vulnerable to certain types of attacks, especially if applications on the instance do not properly validate external input. For example, a server-side request forgery (SSRF) attack could trick the server into retrieving instance metadata. IMDSv2 was introduced to help mitigate this type of risk by requiring session tokens.

  • Usage: To use IMDSv1, one would typically use a tool like curl to fetch data from the endpoint. For example:


AWS recommendation and more details about IMDS

AWS recommends using IMDSv2 due to its enhanced security features. If you're using EC2 instances and rely on instance metadata, it's a good idea to evaluate and potentially migrate to IMDSv2.
In summary, IMDSv1 is the original version of the Instance Metadata Service provided by AWS EC2, allowing instances to access metadata about themselves. However, due to security improvements, AWS introduced IMDSv2, which is now the recommended version for accessing instance metadata.

Both IMDSv1 and IMDSv2 are enabled by default on all EC2 instances. This means that you can make requests using either version without any additional configuration.
Although both versions are available, AWS recommends using IMDSv2 due to its enhanced security features. IMDSv2 uses session-oriented requests, which can help protect against certain vulnerabilities, such as server-side request forgery (SSRF) attacks.
You can modify the IMDS settings for an EC2 instance. For example, if you want to enforce the use of IMDSv2 for security reasons, you can configure the instance to disable IMDSv1. This is done through EC2 instance metadata options when launching a new instance or modifying an existing one.
While new instances have both versions enabled, it's worth noting that very old EC2 instances that have been running since before the introduction of IMDSv2 might only have IMDSv1 available. However, this would be rare, as IMDSv2 has been available for several years.
In summary, by default, both IMDSv1 and IMDSv2 are enabled on all EC2 instances. AWS recommends using IMDSv2 for its security benefits, and you have the option to configure which versions are enabled on your instances.

If you're trying to determine which versions of IMDS are enabled on a running EC2 instance, you'd typically check the instance's metadata options or use AWS Management Console, AWS CLI, or SDKs. AWS provide multiple ways to determine the version of IMDS, details are as given below:

  • AWS Management Console: Checking for IMDSv1-Enabled Instances: In the AWS Management Console, it's possible to determine which instances have IMDSv1 enabled by using the IMDSv2 attribute column on the Amazon EC2 page. To view the IMDSv2 attribute column, follow these steps:
  1. Navigate to the Amazon EC2 console and select 'Instances'.
  2. Click on the settings gear icon located in the upper-right corner.
  3. Find 'IMDSv2' in the list and activate it by moving the slider to the on position.
  4. Click 'Confirm' to apply this setting.

This action will display the IMDS status for your instances. If the status is marked as 'optional', it indicates that IMDSv1 is enabled for that instance. Conversely, a status of 'required' suggests that IMDSv1 is disabled.

  • Identifying IMDSv1-Enabled Instances via AWS CLI
    To ascertain if your instances have IMDSv1 enabled, utilize the AWS Command Line Interface (AWS CLI). This is achievable by executing the aws ec2 describe-instances command and examining the HttpTokens value. This particular value is pivotal in determining the enabled version of IMDS. A setting of optional signifies that both IMDSv1 and IMDSv2 are enabled, whereas required implies that only IMDSv2 is in use. In essence, when the status is optional, it indicates the activation of IMDSv1 on the instance, and required denotes that IMDSv1 is deactivated.

  • Identifying IMDSv1-Enabled Instances Using Security Hub
    Within Security Hub, there's a specific control for Amazon EC2 that leverages the AWS Config rule, named ec2-imdsv2-check, to verify whether the instance metadata version is set to IMDSv2. Should the HttpTokens setting be configured as optional, the rule will flag as NON_COMPLIANT, indicating that the EC2 instance is operating with IMDSv1 enabled.

Below is a Python code snippet using Boto3, the AWS SDK for Python, that will list all EC2 instances (both running and stopped) in an AWS account and determine which versions of IMDS are enabled on each:

import boto3

# Initialize the EC2 client
ec2_client = boto3.client('ec2')

def check_imds_versions():
    # Paginate through all EC2 instances
    paginator = ec2_client.get_paginator('describe_instances')
    for page in paginator.paginate():
        for reservation in page['Reservations']:
            for instance in reservation['Instances']:
                instance_id = instance['InstanceId']
                state = instance['State']['Name']

                # Get IMDS version
                imds_version = "Unknown"
                if 'MetadataOptions' in instance:
                    if instance['MetadataOptions']['HttpTokens'] == 'required':
                        imds_version = "IMDSv2"
                        imds_version = "IMDSv1 & IMDSv2"

                print(f"Instance ID: {instance_id}, State: {state}, IMDS Version: {imds_version}")

if __name__ == "__main__":
Enter fullscreen mode Exit fullscreen mode

The AWS IMDSv1 service uses a request/response access method and the AWS IMDSv2 service uses a session-oriented method. Both services are fully secure, but v2 provides additional layers of protection for four types of vulnerabilities that could be used to try to access IMDS.

Implementing IMDSv2 on EC2 Instances

Upon identifying instances operating with the default IMDSv1, we can proceed to adopt recommended practices provided by AWS to transition these instances from IMDSv1 to the more secure IMDSv2 protocol.
For Launching New Instances:
To ensure new instances utilize IMDSv2, disable IMDSv1 and enable IMDSv2 through the metadata-options parameter in the run-instances CLI command:

aws ec2 run-instances \
    --image-id <ami-xxxxxxxxxxx> \
    --instance-type m4.large \
    --metadata-options "HttpEndpoint=enabled,HttpTokens=required"
Enter fullscreen mode Exit fullscreen mode

To Update Running Instances:
Modify the metadata options of an already running instance to enforce the use of IMDSv2:

aws ec2 modify-instance-metadata-options \
    --instance-id <instance-xxxxxxx> \
    --http-tokens required \
    --http-endpoint enabled
Enter fullscreen mode Exit fullscreen mode

For Configuring New AMIs:
When registering a new Amazon Machine Image (AMI), set it to support IMDSv2 by default:

aws ec2 register-image \
    --name <private-image> \
    --root-device-name /dev/xdga \
    --block-device-mappings DeviceName=/dev/xvda,Ebs={SnapshotId=<snap-xxxxxxx>} \
    --imds-support v2.0
Enter fullscreen mode Exit fullscreen mode

Launching Instances via the AWS Console with IMDSv2:
When initiating the launch of instances through the AWS Console, proceed by selecting 'Launch Instance'. After reaching the instance configuration stages, navigate to the 'Advanced details' tab. Scroll to the 'Metadata version' section and ensure to select 'V2 only (token required)' from the available options. This setting ensures that the instance will exclusively utilize IMDSv2.

Implementing IMDSv2 with EC2 Launch Templates:
EC2 launch templates serve as configurable blueprints that Amazon Auto Scaling groups leverage for the deployment of EC2 instances. When crafting these launch templates through the AWS Console, it's possible to designate the Metadata version. To enhance security, select 'V2 only (token required)' in the Metadata version settings. This choice ensures that any EC2 instances launched using this template will automatically use the more secure IMDSv2.

Configuring IMDSv2 in EC2 Launch Templates via AWS CloudFormation:
When utilizing AWS CloudFormation to create an EC2 launch template, it's crucial to set up the MetadataOptions property to enforce the use of IMDSv2. This is achieved by specifying HttpTokens as required. With this configuration, the process of fetching AWS Identity and Access Management (IAM) role credentials will only yield IMDSv2 credentials, effectively making IMDSv1 credentials inaccessible.
To implement this, include the following properties within your CloudFormation template:

  "HttpEndpoint": "<String>",
  "HttpProtocolIpv6": "<String>",
  "HttpPutResponseHopLimit": <Integer>,
  "HttpTokens": "required",
  "InstanceMetadataTags": "<String>"
Enter fullscreen mode Exit fullscreen mode

This setup ensures that any EC2 instances launched using the CloudFormation template are configured with the enhanced security standards of IMDSv2.

Leveraging IMDSv2 in EC2 Instances with AWS Cloud Development Kit (CDK):
For those employing the AWS Cloud Development Kit (AWS CDK) to orchestrate and deploy EC2 instances, the requireImdsv2 property presents a streamlined way to enhance instance security. By setting requireImdsv2 to true, you effectively disable IMDSv1 and enable IMDSv2, ensuring a higher level of security compliance.In your AWS CDK script, configure the EC2 instance as follows:

new ec2.Instance(this, 'Instance', {
    // ...include other necessary parameters
    requireImdsv2: true,
Enter fullscreen mode Exit fullscreen mode

AWS IMDSv2 provides additional protection against the following types of vulnerabilities compared to IMDSv1:

  • Server-Side Request Forgery (SSRF): SSRF vulnerabilities occur when a malicious actor can cause a server to make a request to an unintended location, such as the instance metadata service. IMDSv2 mitigates this risk by requiring a session token that is obtained via a PUT request. This token must be included in subsequent requests to access the metadata, which is something an SSRF vulnerability typically cannot perform since it can often only induce the server to make simple GET requests.
  • Open Firewalls: In some configurations, the firewall might be set to allow all traffic to reach the instance metadata service. This can be risky, especially if the services running on the instance have vulnerabilities or are misconfigured. IMDSv2 requires the use of a secret token, which is only known to the instance and AWS, thus reducing the risk from an open firewall.
  • Insecure Instance Roles: Instance roles are used to grant permissions to EC2 instances to access other AWS services. If these roles are overly permissive, they can be exploited. IMDSv2 reduces the risk by making it more difficult for a potential attacker to retrieve the credentials associated with the role since they would need to obtain a valid session token first.
  • Misconfigured HTTP Proxies: HTTP proxies within an EC2 instance can inadvertently allow access to the IMDS if not properly secured. Since IMDSv1 only requires a simple HTTP GET request, any process that can send such requests through the proxy can potentially access the metadata service. IMDSv2's use of a session-oriented approach requires a PUT request to get a token, which is typically not allowed through an HTTP proxy by default, thus mitigating this risk.

While IMDSv1 is considered secure under many circumstances, IMDSv2 adds these layers of security to protect against specific attack vectors that have been identified as potential risks. AWS recommends using IMDSv2 whenever possible to leverage these additional security benefits.

Top comments (0)