Test Resource-Level Permissions Using the IAM Policy Simulator

To make it easier for you to test, verify, and understand resource-level permissions in your account, the AWS Identity and Access Management (IAM) policy simulator will now automatically provide a list of resources and parameters required for each AWS action. These enhancements provide you with more accurate simulation results and help ensure that your policies work as expected. Note that this information is currently only available for Amazon EC2, IAM, and AWS CloudFormation. We will add support over time for resource-level simulations of other AWS services.

The following screenshot shows the two new enhancements to the policy simulator user interface. First, Simulation Settings is now called Global Settings. The Global Settings section is where you can input information that applies to all actions in your simulation, such as the aws:SourceIP policy variable. Second, the Results table is now the Action Settings and Results table. In this table, you now must enter all the required resources and condition values specific to each action. This enables you to simulate the same conditions when making an AWS API call.

One common use case I am asked about regularly is simulating EC2. I will use this blog post to show you how the enhanced policy simulator works with the EC2 RunInstances action. This action requires access to six resources in order for the request to be granted access. Now, when you use the policy simulator console, you are prompted to enter values for these six mandatory fields. The simulation results now show allowed only if your policy grants access to all the required resources.

For this walkthrough, imagine you are an IAM administrator writing permissions for an engineer, Sam, who needs the ability to launch, stop, and terminate EC2 instances, but only within specified parameters. To set these permissions, I have created and attached a policy named EC2_Launch_ManageInstances to Sam. This policy grants permission to launch instances with a tag named Status and value Approved. It also grants start, stop, and terminate instances that have a tag named Stage that’s set to Development. However, Sam gets an error when trying to launch an instance using an image that has a tag named Status with value Approved (be sure to replace the placeholder ACCOUNTID in the policy with your own account ID).

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ConsoleAccess",
            "Effect": "Allow",
            "Action": "ec2:Describe*",
            "Resource": "*"
        },
        {
            "Sid": "RunInstances",
            "Effect": "Allow",
            "Action": "ec2:RunInstances",
            "Resource": [
                "arn:aws:ec2:us-west-2:ACCOUNTID:instance/*",
                "arn:aws:ec2:us-west-2:ACCOUNTID:security-group/*",
                "arn:aws:ec2:us-west-2:ACCOUNTID:volume/*"
            ]
        },
        {
            "Sid": "ImageTag",
            "Effect": "Allow",
            "Action": "ec2:RunInstances",
            "Resource": "arn:aws:ec2:us-west-2::image/ami-*",
            "Condition": {
                "StringEquals": {
                    "ec2:ResourceTag/Status": "Approved"
                }
            }
        },
        {
            "Sid": "StartStopTerminate",
            "Effect": "Allow",
            "Action": [
                "ec2:TerminateInstances",
                "ec2:StopInstances",
                "ec2:StartInstances"
            ],
            "Resource": "arn:aws:ec2:us-west-2:ACCOUNTID:instance/*",
            "Condition": {
                "StringEquals": {
                    "ec2:ResourceTag/Stage": "Development"
                }
            }
        }
    ]
}

Let’s troubleshoot this issue using the policy simulator. In order to simulate Sam’s access policies, you need to sign in to the IAM console, and then navigate to the policy simulator, which is shown in the following image.

Next, select Users from the drop-down list in the left pane, as shown in the following image.

From the list of users, select Sam.

Select the actions you are interested in simulating. For this example, let’s simulate access to EC2. Follow these steps to select the actions you want to simulate:

1. Click Amazon EC2 in the Select service drop-down list.
2. Select RunInstances, StartInstances, StopInstances, and TerminateInstances.

3. Because no global context keys exist in Sam’s policies, we can jump straight to specifying the resources and parameters required for each action. Expand the row on the Action Settings and Results table for Amazon EC2 RunInstances. Fill in the following required fields to simulate the resources with which Sam will launch an instance (be sure to replace the placeholder ACCOUNTID with your own account ID):

• instance: arn:aws:ec2:us-west-2:ACCOUNTID:instance/*
• image: arn:aws:ec2:us-west-2::image/ami-*
  • For condition key ec2:resourcetag/status, type the value Approved
  • For condition key ec2:resourcetag/stage, type the value Development
• security-group: arn:aws:ec2:us-west-2:ACCOUNTID:security-group/*
• network-interface: arn:aws:ec2:us-west-2:ACCOUNTID:network-interface/*
• volume: arn:aws:ec2:us-west-2:ACCOUNTID:volume/*
• subnet: arn:aws:ec2:us-west-2:ACCOUNTID:subnet/*

4. The simulator automatically populates the settings for StartInstances, StopInstances, and TerminateInstances with the values we entered for RunInstances. At this point, we have supplied all the information required for our simulation. Click Run Simulation to see the results.

In the Action Settings and Results table, you will see that RunInstances were denied access and StartInstances, StopInstances, and TerminateInstances were allowed access. We want Sam to be able to launch instances, so let’s look deeper at RunInstances.

When we filled out the action settings for RunInstances for the EC2-VPC-EBS-Subnet scenario, we saw that this action requires access to an instance, image, security group, network interface, volume, and subnet. However, if you look at the policy, we have only granted access to the instance, image, security group, and volume, which are four out of the six required resources. The policy must also include access to a network interface and subnet. And the following policy includes these two added resources.

To test this updated policy, click the EC2_Launch_ManageInstances policy in the left panel of the policy simulator and replace the existing policy with the following policy (be sure to replace the placeholder ACCOUNTID with your own account ID). Click Apply.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ConsoleAccess",
            "Effect": "Allow",
            "Action": "ec2:Describe*",
            "Resource": "*"
        },
        {
            "Sid": "RunInstances",
            "Effect": "Allow",
            "Action": "ec2:RunInstances",
            "Resource": [
                "arn:aws:ec2:us-west-2:ACCOUNTID:instance/*",
                "arn:aws:ec2:us-west-2:ACCOUNTID:security-group/*",
                "arn:aws:ec2:us-west-2:ACCOUNTID:volume/*",
                "arn:aws:ec2:us-west-2:ACCOUNTID:subnet/*",
                "arn:aws:ec2:us-west-2:ACCOUNTID:network-interface/*"
            ]
        },
        {
            "Sid": "ImageTag",
            "Effect": "Allow",
            "Action": "ec2:RunInstances",
            "Resource": "arn:aws:ec2:us-west-2::image/ami-*",
            "Condition": {
                "StringEquals": {
                    "ec2:ResourceTag/Status": "Approved"
                }
            }
        },
        {
            "Sid": "StartStopTerminate",
            "Effect": "Allow",
            "Action": [
                "ec2:TerminateInstances",
                "ec2:StopInstances",
                "ec2:StartInstances"
            ],
            "Resource": "arn:aws:ec2:us-west-2:ACCOUNTID:instance/*",
            "Condition": {
                "StringEquals": {
                    "ec2:ResourceTag/Stage": "Development"
                }
            }
        }
    ]
}

Now, to see if the updated policy grants the required permissions, click Run Simulation again. From the updated Action Settings and Results table, we can now see that Sam is allowed to call RunInstances. In addition, Sam can start, stop, and terminate instances. This policy now achieves the expected outcome, and we can now update the policy attached to Sam by using the IAM console.

In addition to using the policy simulator console, you can take advantage of these enhancements using the policy simulator APIs. Now, when you call either the SimulatePrincipalPolicy or SimulateCustomPolicy API when the request is missing the required resources, an error message will identify the missing resources. After you pass in the all the required resources to the simulation APIs, your simulation will run successfully and you can validate the results.

To get started, sign in to the IAM console and click Policy Simulator in the right pane, or go directly to the IAM policy simulator. You can learn more about the IAM policy simulator by visiting Testing IAM Policies with the IAM Policy Simulator. If you have any questions or suggestions, you can submit them below or on the IAM forum.

–Brigid