AWS AWSEC2 high security documentation change
Summary
Updated documentation for transitioning to IMDSv2 with enhanced guidance on tools, monitoring metrics, API usage, and policy enforcement. Added details about Declarative Policies, Auto Scaling integration, and structured migration steps.
Security assessment
The changes promote mandatory use of IMDSv2 which mitigates SSRF vulnerabilities present in IMDSv1. Added CloudWatch metrics for monitoring IMDSv1 usage, IAM/SCP policy examples for enforcement, and Declarative Policy integration all directly relate to security hardening. The documentation explicitly addresses protecting against insecure metadata service usage.
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 eafdfcea7..6a80f20f3 100644 --- a//AWSEC2/latest/UserGuide/instance-metadata-transition-to-version-2.md +++ b//AWSEC2/latest/UserGuide/instance-metadata-transition-to-version-2.md @@ -5 +5 @@ -Tools for helping with the transition to IMDSv2Recommended path to requiring IMDSv2 +Tools for transitioning to IMDSv2Recommended path to requiring IMDSv2 @@ -9 +9 @@ Tools for helping with the transition to IMDSv2Recommended path to requiring IMD -If you want to migrate your instances so that local code or users must use Instance Metadata Service Version 2 (IMDSv2), we recommend that you use the following tools and transition path. +If you want to configure your instances to only accept Instance Metadata Service Version 2 (IMDSv2) calls, we recommend that you use the following tools and transition path. @@ -13 +13 @@ If you want to migrate your instances so that local code or users must use Insta - * Tools for helping with the transition to IMDSv2 + * Tools for transitioning to IMDSv2 @@ -20 +20 @@ If you want to migrate your instances so that local code or users must use Insta -## Tools for helping with the transition to IMDSv2 +## Tools for transitioning to IMDSv2 @@ -22 +22 @@ If you want to migrate your instances so that local code or users must use Insta -If your software uses IMDSv1, use the following tools to help reconfigure your software to use IMDSv2. +The following tools can help you identify, monitor, and manage the transition of your software from IMDSv1 to IMDSv2. For the instructions on how to use these tools, see Recommended path to requiring IMDSv2. @@ -27 +27 @@ If your software uses IMDSv1, use the following tools to help reconfigure your s -The latest versions of the AWS CLI and AWS SDKs support IMDSv2. To use IMDSv2, make sure that your EC2 instances have the latest versions of the CLI and SDKs. For information about updating the CLI, see [Installing or updating to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the _AWS Command Line Interface User Guide_. +The latest versions of the AWS CLI and AWS SDKs support IMDSv2. To use IMDSv2, update your EC2 instances to use the latest versions. For the minimum AWS SDK versions that support IMDSv2, see [Use a supported AWS SDK](./configuring-instance-metadata-service.html#use-a-supported-sdk-version-for-imdsv2). @@ -29,3 +29 @@ The latest versions of the AWS CLI and AWS SDKs support IMDSv2. To use IMDSv2, m -All Amazon Linux 2 and Amazon Linux 2023 software packages support IMDSv2. In Amazon Linux 2023, IMDSv1 is disabled by default. - -For the minimum AWS SDK versions that support IMDSv2, see [Use a supported AWS SDK](./configuring-instance-metadata-service.html#use-a-supported-sdk-version-for-imdsv2). +All Amazon Linux 2 and Amazon Linux 2023 software packages support IMDSv2. Amazon Linux 2023 disables IMDSv1 by default. @@ -36 +34 @@ For the minimum AWS SDK versions that support IMDSv2, see [Use a supported AWS S -The IMDS Packet Analyzer is an open-sourced tool that identifies and logs IMDSv1 calls from your instance’s boot phase. This can assist in identifying the software making IMDSv1 calls on EC2 instances, allowing you to pinpoint exactly what you need to update to get your instances ready to use IMDSv2 only. You can run IMDS Packet Analyzer from a command line or install it as a service. For more information, see [AWS ImdsPacketAnalyzer](https://github.com/aws/aws-imds-packet-analyzer) on _GitHub_. +IMDS Packet Analyzer is an open-source tool that identifies and logs IMDSv1 calls during your instance’s boot phase and runtime operations. By analyzing these logs, you can precisely identify the software making IMDSv1 calls on your instances and determine what needs to be updated to support IMDSv2 only on your instances. You can run IMDS Packet Analyzer from a command line or install it as a service. For more information, see [AWS ImdsPacketAnalyzer](https://github.com/aws/aws-imds-packet-analyzer) on _GitHub_. @@ -41 +39,3 @@ The IMDS Packet Analyzer is an open-sourced tool that identifies and logs IMDSv1 -IMDSv2 uses token-backed sessions, while IMDSv1 does not. The `MetadataNoToken` CloudWatch metric tracks the number of calls to the Instance Metadata Service (IMDS) that are using IMDSv1. By tracking this metric to zero, you can determine if and when all of your software has been upgraded to use IMDSv2. +CloudWatch provides the following two metrics for monitoring your instances: + +`MetadataNoToken` – IMDSv2 uses token-backed sessions, while IMDSv1 does not. The `MetadataNoToken` metric tracks the number of calls to the Instance Metadata Service (IMDS) that are using IMDSv1. By tracking this metric to zero, you can determine if and when all of your software has been upgraded to use IMDSv2. @@ -43 +43 @@ IMDSv2 uses token-backed sessions, while IMDSv1 does not. The `MetadataNoToken` -After you've disabled IMDSv1, you can use the `MetadataNoTokenRejected` CloudWatch metric to track the number of times an IMDSv1 call was attempted and rejected. By tracking this metric, you can ascertain whether your software needs to be updated to use IMDSv2. +`MetadataNoTokenRejected` – After you've disabled IMDSv1, you can use the `MetadataNoTokenRejected` metric to track the number of times an IMDSv1 call was attempted and rejected. By tracking this metric, you can ascertain whether your software needs to be updated to use IMDSv2. @@ -47 +47,6 @@ For more information, see [Instance metrics](./viewing_metrics_with_cloudwatch.h -**Updates to EC2 APIs and CLIs** +**Launch APIs** + + +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). + +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). @@ -48,0 +54 @@ For more information, see [Instance metrics](./viewing_metrics_with_cloudwatch.h +New instances launched by Amazon EC2 Auto Scaling groups: To require the use of IMDSv2 on all new instances launched by Amazon EC2 Auto Scaling groups, your Amazon EC2 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 Amazon EC2 Auto Scaling group launches new instances using the new launch template or launch configuration, but existing instances are not affected. @@ -50 +56 @@ For more information, see [Instance metrics](./viewing_metrics_with_cloudwatch.h -For new instances, you can 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). +Existing instances in an Amazon EC2 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 Amazon EC2 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. @@ -52 +58 @@ For new instances, you can use the [RunInstances](https://docs.aws.amazon.com/AW -For existing instances, you can use the [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) API to require the use of IMDSv2. For more information, see [Modify instance metadata options for existing instances](./configuring-IMDS-existing-instances.html). +**AMIs** @@ -54 +59,0 @@ For existing instances, you can use the [ModifyInstanceMetadataOptions](https:// -To require the use of IMDSv2 on all new instances launched by Amazon EC2 Auto Scaling groups, your Amazon EC2 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 Amazon EC2 Auto Scaling group launches new instances using the new launch template or launch configuration, but existing instances are not affected. For existing instances in an Amazon EC2 Auto Scaling group, you can use the [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) API to require the use of IMDSv2 on the existing instances, or terminate the instances and the Amazon EC2 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. @@ -56 +61 @@ To require the use of IMDSv2 on all new instances launched by Amazon EC2 Auto Sc -**Use an AMI that configures IMDSv2 by default** +AMIs configured with the `ImdsSupport` parameter set to `v2.0` will launch instances that require IMDSv2 by default. Amazon Linux 2023 is configured with `ImdsSupport = v2.0`. @@ -57,0 +63 @@ To require the use of IMDSv2 on all new instances launched by Amazon EC2 Auto Sc +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. @@ -59 +65,3 @@ To require the use of IMDSv2 on all new instances launched by Amazon EC2 Auto Sc -When you launch an instance, you can automatically configure it to use IMDSv2 by default (the `HttpTokens` parameter is set to `required`) by launching it with an AMI that is configured with the `ImdsSupport` parameter set to `v2.0`. You can set the `ImdsSupport` parameter to `v2.0` when you register the AMI using the [register-image](https://docs.aws.amazon.com/cli/latest/reference/ec2/register-image.html) CLI command, or you can modify an existing AMI by using the [modify-image-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-image-attribute.html) CLI command. For more information, see [Configure the AMI](./configuring-IMDS-new-instances.html#configure-IMDS-new-instances-ami-configuration). +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. + +For more information, see [Configure the AMI](./configuring-IMDS-new-instances.html#configure-IMDS-new-instances-ami-configuration). @@ -84 +92 @@ The IAM policy or SCP must contain the following IAM condition keys: -If a parameter in the API or CLI call does not match the state specified in the policy that contains the condition key, the API or CLI call fails with an `UnauthorizedOperation` response. +If a parameter in the API or CLI call doesn't match the state specified in the policy that contains the condition key, the API or CLI call fails with an `UnauthorizedOperation` response. @@ -86 +94 @@ If a parameter in the API or CLI call does not match the state specified in the -Furthermore, you can choose an additional layer of protection to enforce the change from IMDSv1 to IMDSv2. At the access management layer with respect to the APIs called via EC2 Role credentials, you can use a new condition key in either IAM policies or AWS Organizations service control policies (SCPs). Specifically, by using the condition key `ec2:RoleDelivery` with a value of `2.0` in your IAM policies, API calls made with EC2 Role credentials obtained from IMDSv1 will receive an `UnauthorizedOperation` response. The same thing can be achieved more broadly with that condition required by an SCP. This ensures that credentials delivered via IMDSv1 cannot actually be used to call APIs because any API calls not matching the specified condition will receive an `UnauthorizedOperation` error. +Furthermore, you can choose an additional layer of protection to enforce the change from IMDSv1 to IMDSv2. At the access management layer with respect to the APIs called via EC2 Role credentials, you can use a condition key in either IAM policies or AWS Organizations service control policies (SCPs). Specifically, by using the condition key `ec2:RoleDelivery` with a value of `2.0` in your IAM policies, API calls made with EC2 Role credentials obtained from IMDSv1 will receive an `UnauthorizedOperation` response. The same thing can be achieved more broadly with that condition required by an SCP. This ensures that credentials delivered via IMDSv1 cannot actually be used to call APIs because any API calls not matching the specified condition will receive an `UnauthorizedOperation` error. @@ -89,0 +98,5 @@ For example IAM policies, see [Work with instance metadata](./ExamplePolicies_EC +**Declarative Policies** + + +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_. + @@ -92 +105 @@ For example IAM policies, see [Work with instance metadata](./ExamplePolicies_EC -Using the above tools, we recommend that you follow this path for transitioning to IMDSv2. +###### Using the above tools, we recommend the following path for transitioning to IMDSv2: @@ -94 +107 @@ Using the above tools, we recommend that you follow this path for transitioning -### Step 1: At the start + * Step 1: Identify instances with IMDSv2=optional and audit IMDSv1 usage @@ -96 +109 @@ Using the above tools, we recommend that you follow this path for transitioning -Update the SDKs, CLIs, and your software that use Role credentials on their EC2 instances to versions compatible with IMDSv2. For more information about updating the CLI, see [Installing or updating to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the _AWS Command Line Interface User Guide_. + * Step 2: Update software to IMDSv2 @@ -98 +111 @@ Update the SDKs, CLIs, and your software that use Role credentials on their EC2 -Then, change your software that directly accesses instance metadata (in other words, that does not use an SDK) using the IMDSv2 requests. You can use the [IMDS Packet Analyzer](https://github.com/aws/aws-imds-packet-analyzer) to identify the software that you need to change to use IMDSv2 requests. + * Step 3: Require IMDSv2 on instances @@ -100 +113 @@ Then, change your software that directly accesses instance metadata (in other wo -### Step 2: Track your transition progress + * Step 4: Set IMDSv2=required as the default @@ -102 +115 @@ Then, change your software that directly accesses instance metadata (in other wo -Track your transition progress by using the CloudWatch metric `MetadataNoToken`. This metric shows the number of IMDSv1 calls to the IMDS on your instances. For more information, see [Instance metrics](./viewing_metrics_with_cloudwatch.html#ec2-cloudwatch-metrics). + * Step 5: Enforce instances to require IMDSv2 @@ -104 +116,0 @@ Track your transition progress by using the CloudWatch metric `MetadataNoToken`. -### Step 3: When there is zero IMDSv1 usage @@ -106 +117,0 @@ Track your transition progress by using the CloudWatch metric `MetadataNoToken`. -When the CloudWatch metric `MetadataNoToken` records zero IMDSv1 usage, your instances are ready to be fully transitioned to using IMDSv2. At this stage, you can do the following: @@ -108 +118,0 @@ When the CloudWatch metric `MetadataNoToken` records zero IMDSv1 usage, your ins - * **Account default** @@ -110 +120 @@ When the CloudWatch metric `MetadataNoToken` records zero IMDSv1 usage, your ins -You can set IMDSv2 to be required as an account default. When an instance is launched, the instance configuration is automatically set to the account default. +### Step 1: Identify instances with IMDSv2=optional and audit IMDSv1 usage @@ -112 +122 @@ You can set IMDSv2 to be required as an account default. When an instance is lau -To set the account default, do the following: +To assess your IMDSv2 migration scope, identify instances that are configured to allow either IMDSv1 or IMDSv2, and audit IMDSv1 calls. @@ -114 +124 @@ To set the account default, do the following: - * Amazon EC2 console: On the EC2 Dashboard, under **Account attributes** , **Data protection and security** , for **IMDS defaults** , set **Instance metadata service** to **Enabled** and **Metadata version** to **V2 only (token required)**. For more information, see [Set IMDSv2 as the default for the account](./configuring-IMDS-new-instances.html#set-imdsv2-account-defaults). + 1. **Identify instances that are configured to allow either IMDSv1 or IMDSv2:** @@ -116 +126 @@ To set the account default, do the following: - * AWS CLI: Use the [modify-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-defaults.html) CLI command and specify `--http-tokens required` and `--http-put-response-hop-limit `2``. +Amazon EC2 console @@ -118 +127,0 @@ To set the account default, do the following: - * **New instances** @@ -120 +129 @@ To set the account default, do the following: -When launching a new instance, you can do the following: + 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). @@ -122 +131 @@ When launching a new instance, you can do the following: - * Amazon EC2 console: In the launch instance wizard, set **Metadata accessible** to **Enabled** and **Metadata version** to **V2 only (token required)**. For more information, see [Configure the instance at launch](./configuring-IMDS-new-instances.html#configure-IMDS-new-instances-instance-settings). + 2. In the navigation pane, choose **Instances**. @@ -124 +133 @@ When launching a new instance, you can do the following: - * AWS CLI: Use the [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) command and specify that IMDSv2 is required. + 3. To see only the instances that are configured to allow IMDSv1 or IMDSv2, add the filter **IMDSv2 = optional**. @@ -126 +135 @@ When launching a new instance, you can do the following: - * **Existing instances** + 4. Alternatively, to see whether IMDSv2 is **optional** or **required** for all instances, open the **Preferences** window (gear icon), toggle on **IMDSv2** , and choose **Confirm**. This adds the **IMDSv2** column to the **Instances** table. @@ -128 +137 @@ When launching a new instance, you can do the following: -For existing instances, you can do the following: +AWS CLI @@ -130 +138,0 @@ For existing instances, you can do the following: - * Amazon EC2 console: On the **Instances** page, select your instance, choose **Actions** , **Instance settings** , **Modify instance metadata options** , and for **IMDSv2** , choose **Required**. For more information, see [Require the use of IMDSv2](./configuring-IMDS-existing-instances.html#modify-require-IMDSv2). @@ -132 +140 @@ For existing instances, you can do the following: - * AWS CLI: Use the [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) CLI command to specify that only IMDSv2 is to be used. +Use the [describe-instances](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/modify-instance-metadata-options.html) command and filter by `metadata-options.http-tokens = optional`, as follows: @@ -134 +142 @@ For existing instances, you can do the following: -You can modify the instance metadata options on running instances, and you don't need to restart the instances after modifying the instance metadata options. + aws ec2 describe-instances --filters "Name=metadata-options.http-tokens,Values=optional" --query "Reservations[*].Instances[*].[InstanceId]" --output text @@ -135,0 +144 @@ You can modify the instance metadata options on running instances, and you don't + 2. **Audit IMDSv1 calls on each instance:** @@ -136,0 +146 @@ You can modify the instance metadata options on running instances, and you don't +Use the CloudWatch metric `MetadataNoToken`. This metric shows the number of IMDSv1 calls to the IMDS on your instances. For more information, see [Instance metrics](https://docs.aws.amazon.com/en_us/AWSEC2/latest/UserGuide/viewing_metrics_with_cloudwatch.html#ec2-cloudwatch-metrics). @@ -137,0 +148 @@ You can modify the instance metadata options on running instances, and you don't + 3. **Identify software on your instances making IMDSv1 calls:** @@ -139 +150 @@ You can modify the instance metadata options on running instances, and you don't -### Step 4: Check if your instances are transitioned to IMDSv2 +Use the open source [IMDS Packet Analyzer](https://github.com/aws/aws-imds-packet-analyzer) to identify and log IMDSv1 calls during your instance’s boot phase and runtime operations. Use this information to identify the software to update to get your instances ready to use IMDSv2 only. You can run IMDS Packet Analyzer from a command line or install it as a service. @@ -141 +151,0 @@ You can modify the instance metadata options on running instances, and you don't -You can check if any instances are not yet configured to require the use of IMDSv2, in other words, IMDSv2 is still configured as `optional`. If any instances are still configured as `optional`, you can modify the instance metadata options to make IMDSv2 `required` by repeating the preceding Step 3. @@ -143 +152,0 @@ You can check if any instances are not yet configured to require the use of IMDS -To filter your instances: @@ -145 +153,0 @@ To filter your instances: - * Amazon EC2 console: On the **Instances** page, filter your instances by using the **IMDSv2 = optional** filter. For more information about filtering, see [Filter resources using the console](./Using_Filtering.html#console-filter). You can also view whether IMDSv2 is required or optional for each instance: In the **Preferences** window, toggle on **IMDSv2** to add the **IMDSv2** column to the **Instances** table. @@ -147 +155 @@ To filter your instances: - * AWS CLI: Use the [describe-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) command and filter by `metadata-options.http-tokens = optional`, as follows: +### Step 2: Update software to IMDSv2 @@ -149 +157,48 @@ To filter your instances: - aws ec2 describe-instances --filters "Name=metadata-options.http-tokens,Values=optional" --query "Reservations[*].Instances[*].[InstanceId]" --output text +Update all SDKs, CLIs, and software that use Role credentials on your instances to IMDSv2-compatible versions. For more information about updating the CLI, see [Installing or updating to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the _AWS Command Line Interface User Guide_. + +### Step 3: Require IMDSv2 on instances + +After confirming zero IMDSv1 calls through the `MetadataNoToken` metric, configure your existing instances to require IMDSv2. Also, configure all new instances to require IMDSv2. In other words, disable IMDSv1 on all existing and new instances. + + 1. **Configure existing instances to require IMDSv2:** + +Amazon EC2 console + + + 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). + + 2. In the navigation pane, choose **Instances**. + + 3. Select your instance. + + 4. Choose **Actions** , **Instance settings** , **Modify instance metadata options**. + + 5. For **IMDSv2** , choose **Required**. + + 6. Choose **Save**. + +AWS CLI + + +Use the [modify-instance-metadata-options](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/modify-instance-metadata-options.html) CLI command to specify that only IMDSv2 is to be used. + +###### Note + +You can modify this setting on running instances. The change takes effect immediately without needing an instance restart. + +For more information, see [Require the use of IMDSv2](./configuring-IMDS-existing-instances.html#modify-require-IMDSv2). + + 2. **Monitor for issues after disabling IMDSv1:** + + 1. Track the number of times an IMDSv1 call was attempted and rejected with the `MetadataNoTokenRejected` CloudWatch metric. + + 2. If the `MetadataNoTokenRejected` metric records IMDSv1 calls on an instance that is experiencing software issues, this indicates that the software requires updating to use IMDSv2. + + 3. **Configure new instances to require IMDSv2:**