Applying managed instance policy best practices

Since AWS Systems Manager was launched, the service has continued to add new features for customers to use. Many features are enabled by granting your Amazon EC2 instances and on-premises servers access to Systems Manager using an AWS Identity and Access Management (IAM) role with the necessary permissions. To provide customers more flexible, fine-grained permission control, AWS introduced the Managed Policy AmazonSSMManagedInstanceCore. This policy grants instances the permissions needed for core Systems Manager functionality.

Overview

In order to take advantage of the new granular permissions model, the AmazonEC2RoleforSSM policy should be replaced with AmazonSSMManagedInstanceCore. To ensure we’re following best practices, the AmazonEC2RoleforSSM policy will no longer be available for new resources. We’ll cover the specifics on this policy deprecation later on.

In this blog post:

• I review each of the IAM Managed Policies available for you to use with Systems Manager managed instances.
• Next, I show you which managed policies enable specific Systems Manager features, so you can allow the features you’re using while following a least privilege security best practice.
• Finally, I demonstrate how to plan for the deprecation of the AmazonEC2RoleforSSM policy and how you can automatically remediate your existing IAM roles in AWS Config by replacing the policy.

AWS IAM managed policies for AWS Systems Manager

Systems Manager provides the following managed policies in IAM to use with Amazon EC2 Instances and on-premises servers. These policies grant permission to the required API actions to be registered as managed instances within the service, and to use additional service features:

To view the full details of each managed policy, navigate to the IAM Console, choose Policies in the navigation pane, and search for the policy name.

For a list of all AWS-provided managed policies for Systems Manager, refer to AWS Managed Policies for AWS Systems Manager.

Managed policy support for Systems Manager features

The following table details the managed policies required for core agent functionality (including registration to Systems Manager as a managed instance) and other common features.

¹ A custom IAM policy is required when using your own Amazon S3 bucket with Systems Manager. For example, Run Command can save command output to an Amazon S3 bucket. For more information, refer to Create a Custom Policy for Amazon S3 Bucket Access.

² In order to take VSS-enabled EBS snapshots, a custom policy is required to grant access to the needed Amazon EC2 service API calls.

Plan for replacing the AmazonEC2RoleforSSM policy

To help you through the transition of your existing environments, the AmazonEC2RoleforSSM policy remains in place after the introduction of the new AmazonSSMManagedInstanceCore policy.

In the near future, the AmazonEC2RoleforSSM policy will be deprecated. The policy will continue to provide the included permissions to any currently attached users, groups, and roles. However, it will not be available for attachment to new resources and cannot be re-attached once detached from a resource. For more details, see Deprecated AWS Managed Policies.

To prepare for the deprecation of the AmazonEC2RoleforSSM policy, we recommend the following transition plan:

• Phase 1: Define required policies
• Phase 2: Update policy references
• Phase 3: Update existing IAM entities

Phase 1: Define required policies

Confirm the managed policy or policies required for the Systems Manager features used in your environment, and create custom policies as required.

For example, to enable core agent functionality (such as Run Command and Session Manager), the AmazonSSMManagedInstanceCore policy is sufficient. To enable CloudWatch Agent, you need to include the policy CloudWatchAgentServerPolicy.

If you plan to use your own Amazon S3 bucket in your System Manager operations—for example, to store Run Command output—a custom IAM policy is required to provide access. For steps to create a custom policy, refer to Create a Custom Policy for Amazon S3 Bucket Access.

For other agent features, refer to the Systems Manager user guide for any IAM permissions which may be required.

Phase 2: Update policy references

Update any references to the AmazonEC2RoleforSSM policy used within your environment to refer to your new set of policies, for example:

• Amazon EC2 launch templates
• AWS CloudFormation templates or other automation code

It is important to update these references to prevent failed requests to attach the AmazonEC2RoleforSSM policy or failed requests to launch resources with this policy attached.

Phase 3: Update existing IAM entities

Update any IAM entities (users, groups, and roles) which have the AmazonEC2RoleforSSM policy attached by attaching your replacement policy or policies, and detaching AmazonEC2RoleforSSM. Most commonly, this policy is attached to an IAM role associated with an instance profile.

One way you can update your IAM entities is using AWS Config, which allows you to audit your existing roles by checking if the AmazonEC2RoleforSSM policy is attached. The managed rule IAM-policy-blacklisted-check allows you to mark any entities with this policy attached as noncompliant. Using the remediation feature with a custom Systems Manager automation document, you can automatically replace the AmazonEC2RoleforSSM policy with a set of new policies.

In the next steps, I use an example AWS CloudFormation template to demonstrate how to deploy AWS Config and a custom remediation document.

For details on AWS Config pricing, refer to the AWS Config pricing page.

Auditing and remediating roles with AWS Config

You need the following prerequisites for auditing and remediating roles:

• Custom instance policies defined
• IAM permissions to launch a CloudFormation stack and create associated resources
• Example CloudFormation template

Step 1: Enable AWS Config

To get started, navigate to the AWS Config console and enable the service if needed.

To collect IAM entities, verify that Include global resources is enabled. If you are recording only specific resource types, ensure IAM:Role, IAM:User, and IAM:Group are being recorded.  For more details about enabling AWS Config, refer to Setting Up AWS Config.

Step 2: Launch CloudFormation stack

Next, launch an AWS CloudFormation stack template to create the following resources:

• AWS Config rule to scan/remediate IAM roles for the AmazonEC2RoleforSSM policy
• AWS Config rule to scan IAM users and groups for the AmazonEC2RoleforSSM policy
• Systems Manager automation remediation document
• IAM automation service role used for remediation
• AWS Config remediation configuration

To launch the stack, take the following steps:

1. Download the example CloudFormation template SSMManagedPolicyBestPractice.yaml located in GitHub.
2. In the AWS CloudFormation console, select Stacks and choose Create Stack.
3. In the Template source section, choose Upload a template file and specify the downloaded example template.
4. Choose Next and enter a Stack Name.
5. Specify your replacement IAM policies in the policiesToAdd parameter, using Amazon Resource Names (ARNs) in comma-separated format. Specified policies are attached to the noncompliant IAM role, replacing the policy specified in policyToRemove. The default limit is 10 managed policies attached to a role. For more details, see IAM Object Limits. The following AWS Managed Policies are specified by default:

   arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore
   arn:aws:iam::aws:policy/AmazonSSMDirectoryServiceAccess
   arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy

6. Leaving other parameters as default, choose Next and continue to the Review
7. On the Review page, scroll to the end to acknowledge that IAM resources will be created, then choose Create stack.
8. Review the stack details and verify the status changes to CREATE_COMPLETE. For more details, refer to Creating a Stack on the AWS CloudFormation Console.

Step 3: Run AWS Config remediation

Now that the AWS Config rule and remediation document are created, you can remediate any noncompliant IAM roles.

Navigate back to the AWS Config console and choose Rules, as shown in the following screenshot. Note that it can take some time for your resources to be recorded by AWS Config.

Choose the rule Iam-Roles-Deprecated-AmazonEC2RoleforSSM to review any IAM roles marked Noncompliant, as shown in the following screenshot.

In the example shown in the screenshot, I have one IAM role with the AmazonEC2RoleforSSM policy attached marked Noncompliant, which can be manually remediated by selecting the role and choosing Remediate.

Note that the resource must be re-scanned by the AWS Config rule to be updated as Compliant, as shown in the following screenshot.

You can review details about the remediation actions performed in the Systems Manager automations console.

You should also review any resources marked Noncompliant in the separate Iam-UsersGroups-Deprecated-AmazonEC2RoleforSSM AWS Config rule. Since the AmazonEC2RoleforSSM policy is intended for use in instance profile roles, any IAM users or groups with this policy attached should be carefully reviewed to assign the intended permissions.

Conclusion

In this blog post, I covered the AWS IAM managed policies recommended for use with managed instances and how they enable features in Systems Manager. I also provided recommended steps you can take to transition from the AmazonEC2RoleforSSM policy, along with an example solution using AWS Config to remediate your current IAM roles.

To expand on the example solution, you can also consider enabling AWS Config to automatically remediate any detected noncompliant roles, or deploying this solution across multiple AWS accounts using AWS CloudFormation StackSets. For more information, see Setting Up Auto Remediation and Working with AWS CloudFormation StackSets.

About the authors

Adam Creech is a Cloud Support Engineer in AWS Premium Support. He specializes in AWS Systems Manager and Amazon EC2 Windows. In his personal time, he enjoys reading and playing the piano.

Vladimir Drozdenko is a Senior Software Engineer with AWS Systems Manager. He is passionate about building secure and effective solutions for AWS customers. Outside of work, he is a martial art enthusiast and a coffee junky.