# Security Risks of iam:PassRole and How to Properly Restrict It in IAM Policies

> Secure your AWS environment by understanding iam:PassRole risks and learn how to properly restrict it in IAM policies to prevent privilege escalation.

- Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws)
- Tags: best-practices
- Published: 2026-06-29

---

**Granting `iam:PassRole` with `Resource: "*"` creates a privilege escalation vector that allows principals to assume any attachable IAM role through AWS compute services.**

The `iam:PassRole` permission lets principals hand off IAM roles to AWS services like EC2, Lambda, and Step Functions, but when overly broad, it enables attackers to inherit administrative privileges. According to the **aws/agent-toolkit-for-aws** repository, properly restricting this permission requires scoping resources to specific ARNs and leveraging condition keys to bind roles to intended services. This guide covers the security risks and implementation patterns found in the repository's IAM skill documentation.

## Why iam:PassRole Creates Privilege Escalation Risks

When a principal possesses `iam:PassRole` permissions, they can cause AWS services to assume IAM roles on their behalf. This creates several critical attack vectors documented in [`skills/core-skills/aws-iam/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/core-skills/aws-iam/SKILL.md) and [`plugins/aws-core/skills/aws-iam/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-core/skills/aws-iam/SKILL.md).

### The Wildcard Resource Problem

Using `"Resource": "*"` with `iam:PassRole` allows a principal to pass any role in the account, including highly privileged administrator roles. When combined with permissions to launch EC2 instances or create Lambda functions, this effectively grants the principal the ability to assume any role that can be attached to those services.

### Cross-Account Abuse Potential

If a role ARN from another AWS account is passable, an attacker can gain access to resources in external accounts. The repository notes that cross-account `PassRole` permissions without account-based conditions (`aws:PrincipalAccount`) create lateral movement opportunities across organizational boundaries.

## How to Restrict iam:PassRole Using Least-Privilege Patterns

The repository's IAM skill files provide specific patterns for implementing least-privilege `PassRole` permissions across multiple AWS services.

### Scope Resources to Specific Role ARNs

Never use wildcard resources. Instead, enumerate exact role ARNs that the principal needs to pass:

```json
{
  "Effect": "Allow",
  "Action": "iam:PassRole",
  "Resource": [
    "arn:aws:iam::123456789012:role/ecsTaskExecutionRole",
    "arn:aws:iam::123456789012:role/lambdaExecutionRole"
  ]
}

```

### Leverage Condition Keys for Service Restrictions

Use the `iam:PassedToService` condition key to limit which service can receive the passed role. This prevents role misuse across unintended services:

```json
{
  "Effect": "Allow",
  "Action": "iam:PassRole",
  "Resource": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole",
  "Condition": {
    "StringEquals": {
      "iam:PassedToService": "ecs.amazonaws.com"
    }
  }
}

```

Additional condition keys include `iam:AssociatedResourceArn` for tying roles to specific resources and `aws:PrincipalAccount` for cross-account restrictions.

### Combine with Service-Specific API Permissions

Only grant `PassRole` when the principal also needs to invoke the service API that consumes the role. This reduces blast radius if the principal's credentials are compromised:

```json
{
  "Effect": "Allow",
  "Action": [
    "ecs:RegisterTaskDefinition",
    "iam:PassRole"
  ],
  "Resource": [
    "arn:aws:ecs:us-east-1:123456789012:task-definition/my-app:*",
    "arn:aws:iam::123456789012:role/ecsTaskExecutionRole"
  ],
  "Condition": {
    "StringEquals": {
      "iam:PassedToService": "ecs.amazonaws.com"
    }
  }
}

```

## Practical IAM Policy Examples

The repository provides concrete implementations in [`skills/specialized-skills/serverless-skills/processing-s3-uploads-with-step-functions/references/iam-roles.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/specialized-skills/serverless-skills/processing-s3-uploads-with-step-functions/references/iam-roles.md) and [`plugins/aws-core/skills/aws-containers/references/task-definition-authoring.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-core/skills/aws-containers/references/task-definition-authoring.md).

### Restricting PassRole for Lambda Functions

Limit `PassRole` to specific Lambda execution roles and bind them to the Lambda service:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowLambdaToPassExecutionRole",
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::123456789012:role/MyLambdaExecRole",
      "Condition": {
        "StringEquals": {
          "iam:PassedToService": "lambda.amazonaws.com"
        }
      }
    },
    {
      "Sid": "AllowCreateLambda",
      "Effect": "Allow",
      "Action": [
        "lambda:CreateFunction",
        "lambda:UpdateFunctionConfiguration"
      ],
      "Resource": "*"
    }
  ]
}

```

### Step Functions and ECS Task Roles

When Step Functions launches ECS tasks, both the Step Functions role and the ECS task role require `iam:PassRole`. Restrict the ECS task role as follows:

```json
{
  "Effect": "Allow",
  "Action": "iam:PassRole",
  "Resource": "arn:aws:iam::123456789012:role/EcsTaskRole",
  "Condition": {
    "StringEquals": {
      "iam:PassedToService": "ecs-tasks.amazonaws.com"
    }
  }
}

```

### Cross-Account Role Restrictions

For scenarios requiring cross-account role passing, restrict by principal account:

```json
{
  "Effect": "Allow",
  "Action": "iam:PassRole",
  "Resource": "arn:aws:iam::111122223333:role/SharedReadOnlyRole",
  "Condition": {
    "StringEquals": {
      "aws:PrincipalAccount": "123456789012"
    }
  }
}

```

## Key Repository References

The **aws/agent-toolkit-for-aws** repository contains authoritative guidance in these locations:

- **[`skills/core-skills/aws-iam/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/core-skills/aws-iam/SKILL.md)**: Core guidance on `iam:PassRole` risks, least-privilege patterns, and condition key usage.
- **[`plugins/aws-core/skills/aws-iam/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-core/skills/aws-iam/SKILL.md)**: Plugin-layer duplicate of the core IAM security guidance.
- **[`skills/specialized-skills/serverless-skills/processing-s3-uploads-with-step-functions/references/iam-roles.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/specialized-skills/serverless-skills/processing-s3-uploads-with-step-functions/references/iam-roles.md)**: Concrete IAM role definitions for Step Functions workflows, including required `PassRole` actions.
- **[`plugins/aws-core/skills/aws-containers/references/task-definition-authoring.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-core/skills/aws-containers/references/task-definition-authoring.md)**: ECS-specific `PassRole` requirements for task definitions.

## Summary

- **Never grant `iam:PassRole` on `*`**; always enumerate specific role ARNs that principals need to pass.
- **Leverage condition keys** (`iam:PassedToService`, `iam:AssociatedResourceArn`, `aws:PrincipalAccount`) to bind permissions to specific services or accounts.
- **Pair `PassRole` with service actions** that actually require the role, such as `ecs:RegisterTaskDefinition` or `lambda:CreateFunction`.
- **Restrict role trust policies** independently so that even if a role is passed, only intended principals can assume it.
- Consult the repository's **IAM skill documentation** when drafting new policies to ensure alignment with AWS security best practices.

## Frequently Asked Questions

### What makes iam:PassRole a security risk?

`iam:PassRole` becomes dangerous when granted with wildcard resources (`"*"`), allowing principals to pass any IAM role—including administrator roles—to AWS services they can invoke. This creates a privilege escalation path where a user with limited permissions can effectively assume highly privileged roles by launching compute resources like EC2 instances or Lambda functions.

### How do I restrict iam:PassRole to specific services?

Use the `StringEquals` condition with the `iam:PassedToService` key to specify the exact service endpoint that can receive the role. For example, `"iam:PassedToService": "ecs.amazonaws.com"` ensures the role can only be passed to ECS, preventing misuse by Lambda, Step Functions, or other services even if the principal has broader permissions.

### Can I use wildcards in iam:PassRole resource ARNs?

While technically possible, the repository explicitly warns against using wildcards in `iam:PassRole` resource fields. Instead, list explicit role ARNs or use path-based ARN patterns with appropriate naming conventions. Never use `"Resource": "*"` with `iam:PassRole` in production environments, as this violates the principle of least privilege and creates audit findings.

### How does iam:PassRole relate to role trust policies?

`iam:PassRole` controls which principals can hand a role to a service, while the role's **trust policy** (assume role policy) controls which entities can actually assume the role. Both must be restricted: even if you properly limit `PassRole` permissions, a permissive trust policy (`"Principal": "*"`) on the target role still allows unauthorized assumption. Secure implementations require tightening both the `PassRole` IAM policy and the target role's trust relationships.