AWS AWSEC2 high security documentation change
Summary
Added documentation about account-level IMDSv2 enforcement, clarified monitoring metrics behavior, and expanded guidance for enforcing IMDSv2 via IAM/SCP policies and account properties.
Security assessment
The changes explicitly document how to enforce IMDSv2 at the account/organization level, which mitigates security risks associated with IMDSv1 (e.g., SSRF vulnerabilities). The addition of account-level enforcement controls and warnings about failed launches when IMDSv1 is used demonstrates concrete security improvements. IMDSv2 is a security feature designed to prevent instance metadata service exploitation.
Diff
diff --git a/AWSEC2/latest/UserGuide/instance-metadata-transition-to-version-2.md b/AWSEC2/latest/UserGuide/instance-metadata-transition-to-version-2.md index 456487b01..aff0d509f 100644 --- a//AWSEC2/latest/UserGuide/instance-metadata-transition-to-version-2.md +++ b//AWSEC2/latest/UserGuide/instance-metadata-transition-to-version-2.md @@ -44,0 +45,2 @@ CloudWatch provides the following two metrics for monitoring your instances: +For each EC2 instance, these metrics are mutually exclusive. When IMDSv1 is enabled (`httpTokens = optional`), only `MetadataNoToken` emits. When IMDSv1 is disabled (`httpTokens = required`), only `MetadataNoTokenRejected` emits. For when to use these metrics, see Recommended path to requiring IMDSv2. + @@ -50 +52 @@ For more information, see [Instance metrics](./viewing_metrics_with_cloudwatch.h -New instances: Use the [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) API to launch new instances that require the use of IMDSv2. For more information, see [Configure instance metadata options for new instances](./configuring-IMDS-new-instances.html). +**New instances:** Use the [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) API to launch new instances that require the use of IMDSv2. For more information, see [Configure instance metadata options for new instances](./configuring-IMDS-new-instances.html). @@ -52 +54 @@ New instances: Use the [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/ -Existing instances: Use the [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) API to require the use of IMDSv2 on existing instances. For more information, see [Modify instance metadata options for existing instances](./configuring-IMDS-existing-instances.html). +**Existing instances:** Use the [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) API to require the use of IMDSv2 on existing instances. For more information, see [Modify instance metadata options for existing instances](./configuring-IMDS-existing-instances.html). @@ -54 +56 @@ Existing instances: Use the [ModifyInstanceMetadataOptions](https://docs.aws.ama -New instances launched by Auto Scaling groups: To require the use of IMDSv2 on all new instances launched by Auto Scaling groups, your Auto Scaling groups can use either a launch template or a launch configuration. When you [create a launch template](https://docs.aws.amazon.com/cli/latest/reference/ec2/create-launch-template.html) or [create a launch configuration](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/create-launch-configuration.html), you must configure the `MetadataOptions` parameters to require the use of IMDSv2. The Auto Scaling group launches new instances using the new launch template or launch configuration, but existing instances are not affected. +**New instances launched by Auto Scaling groups:** To require the use of IMDSv2 on all new instances launched by Auto Scaling groups, your Auto Scaling groups can use either a launch template or a launch configuration. When you [create a launch template](https://docs.aws.amazon.com/cli/latest/reference/ec2/create-launch-template.html) or [create a launch configuration](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/create-launch-configuration.html), you must configure the `MetadataOptions` parameters to require the use of IMDSv2. The Auto Scaling group launches new instances using the new launch template or launch configuration, but existing instances are not affected. @@ -56 +58 @@ New instances launched by Auto Scaling groups: To require the use of IMDSv2 on a -Existing instances in an Auto Scaling group: Use the [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) API to require the use of IMDSv2 on existing instances, or terminate the instances and the Auto Scaling group will launch new replacement instances with the instance metadata options settings that are defined in the new launch template or launch configuration. +**Existing instances in an Auto Scaling group:** Use the [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) API to require the use of IMDSv2 on existing instances, or terminate the instances and the Auto Scaling group will launch new replacement instances with the instance metadata options settings that are defined in the new launch template or launch configuration. @@ -63 +65 @@ AMIs configured with the `ImdsSupport` parameter set to `v2.0` will launch insta -New AMIs: Use the [register-image](https://docs.aws.amazon.com/cli/latest/reference/ec2/register-image.html) CLI command to set the `ImdsSupport` parameter to `v2.0` when creating a new AMI. +**New AMIs:** Use the [register-image](https://docs.aws.amazon.com/cli/latest/reference/ec2/register-image.html) CLI command to set the `ImdsSupport` parameter to `v2.0` when creating a new AMI. @@ -65 +67 @@ New AMIs: Use the [register-image](https://docs.aws.amazon.com/cli/latest/refere -Existing AMIs: Use the [modify-image-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-image-attribute.html) CLI command to set the `ImdsSupport` parameter to `v2.0` when modifying an existing AMI. +**Existing AMIs:** Use the [modify-image-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-image-attribute.html) CLI command to set the `ImdsSupport` parameter to `v2.0` when modifying an existing AMI. @@ -68,0 +71,18 @@ For more information, see [Configure the AMI](./configuring-IMDS-new-instances.h +**Account-level controls** + + +You can configure default values for all the instance metadata options at the account level. The default values are automatically applied when you launch an instance. For more information. see [Set IMDSv2 as the default for the account](./configuring-IMDS-new-instances.html#set-imdsv2-account-defaults). + +You can also enforce the requirement to use IMDSv2 at the account level. When IMDSv2 enforcement is enabled: + + * **New instances:** Instances configured to launch with IMDSv1 enabled will fail to launch + + * **Existing instances with IMDSv1 disabled:** Attempts to enable IMDSv1 on existing instances will be prevented. + + * **Existing instances with IMDSv1 enabled:** Existing instances with IMDSv1 already enabled will not be affected. + + + + +For more information, see [Enforce IMDSv2 at the account level](./configuring-IMDS-new-instances.html#enforce-imdsv2-at-the-account-level). + @@ -76 +96 @@ You can use an IAM policy or AWS Organizations service control policy (SCP) to c - * Can't modify a running instance using the [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) API to re-enable IMDSv1. + * Can't modify an existing instance using the [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) API to re-enable IMDSv1. @@ -101 +121 @@ For example IAM policies, see [Work with instance metadata](./ExamplePolicies_EC -Use Declarative Policies (a feature of AWS Organizations) to centrally set and enforce IMDSv2 as the default IMDS version across your organization. For an example policy, see the **Instance Metadata Defaults** tab in the [Supported declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative_syntax.html#declarative-policy-examples) section in the _AWS Organizations User Guide_. +Use Declarative Policies (a feature of AWS Organizations) to centrally set IMDS account defaults, including IMDSv2 enforcement, across your organization. For an example policy, see the **Instance Metadata Defaults** tab in the [Supported declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative_syntax.html#declarative-policy-examples) section in the _AWS Organizations User Guide_. @@ -257 +277,19 @@ Use a Declarative Policy to set the organization default for IMDSv2 to required. -Use the following IAM or SCP condition keys to enforce IMDSv2 usage: +Once you’ve confirmed that there is no dependency on IMDSv1 on any of your instances, we recommend that you enforce IMDSv2 on all new instances. + +Use one of the following options to enforce IMDSv2: + + 1. **Enforce IMDSv2 with an account property** + +You can enforce the use of IMDSv2 at the account level for each AWS Region. When enforced, instances can only launch if they're configured to require IMDSv2. This enforcement applies regardless of how the instance or AMI is configured. For more information, see [Enforce IMDSv2 at the account level](./configuring-IMDS-new-instances.html#enforce-imdsv2-at-the-account-level). To apply this setting at an organization level, set a Declarative Policy. For an example policy, see the **Instance Metadata Defaults** tab in the [Supported declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative_syntax.html#declarative-policy-examples) section in the _AWS Organizations User Guide_. + +To prevent a reversal of enforcement, you should use an IAM policy to prevent access to the [ModifyInstanceMetadataDefaults](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataDefaults.html) API. For more information, see [Use an IAM policy](./configuring-IMDS-new-instances.html#configure-IMDS-new-instances-iam-policy). + +###### Note + +This setting does not change the IMDS version of existing instances, but blocks enabling IMDSv1 on existing instances that currently have IMDSv1 disabled. + +###### Warning + +If IMDSv2 enforcement is enabled and `httpTokens` is not set to `required` in either the instance configuration at launch, the account settings, or the AMI configuration, the instance launch will fail. For troubleshooting information, see [Launching an IMDSv1-enabled instance fails](./troubleshooting-launch.html#launching-an-imdsv1-enabled-instance-fails). + + 2. **Alternatively, enforce IMDSv2 by using the following IAM or SCP condition keys:** @@ -264,0 +303 @@ Use the following IAM or SCP condition keys to enforce IMDSv2 usage: +These condition keys control the use of the [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) and the [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) APIs and corresponding CLIs. If a policy is created, and a parameter in the API call does not match the state specified in the policy using the condition key, the API or CLI call fails with an `UnauthorizedOperation` response. @@ -265,0 +305 @@ Use the following IAM or SCP condition keys to enforce IMDSv2 usage: +For example IAM policies, see [Work with instance metadata](./ExamplePolicies_EC2.html#iam-example-instance-metadata). @@ -268 +307,0 @@ Use the following IAM or SCP condition keys to enforce IMDSv2 usage: -These condition keys control the use of the [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) and the [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) APIs and corresponding CLIs. If a policy is created, and a parameter in the API call does not match the state specified in the policy using the condition key, the API or CLI call fails with an `UnauthorizedOperation` response. @@ -270 +308,0 @@ These condition keys control the use of the [RunInstances](https://docs.aws.amaz -For example IAM policies, see [Work with instance metadata](./ExamplePolicies_EC2.html#iam-example-instance-metadata).