# security agent's runbook step assumed an IAM role it wasn't granted

## TL;DR

The runbook step assumed an IAM role the agent was never granted, so it failed at runtime. Check the trust policy and the agent's own permissions, grant the assumption explicitly, and pre-flight the assumption before the runbook runs. AssumeRole is a permission, not a given.

```text
security agent's runbook step assumed an IAM role it wasn't granted (AccessDenied on AssumeRole)
```

## Steps

1. Read the trust policy on the target role: which principals may assume it.
   Expected: The allowed set is known.

2. Check the agent's identity against that set.
   Expected: The gap is identified.

3. Grant the assumption: add the agent's role to the trust policy (with conditions like ExternalId where appropriate).
   Expected: The assumption is allowed.

4. Pre-flight the assumption at runbook start: fail fast with a clear message if it is denied.
   Expected: The failure moves to the start.

5. Test the full runbook with the granted role.
   Expected: The steps execute.

## When to use

- automation fails on AssumeRole
- the runbook was written for a different identity
- cross-account actions are involved

## When not to use

- the trust policy allows it (check for a condition mismatch instead)
- the failure is on the assumed role's permissions, not the assumption (different fix)
- the agent should not have that role (redesign the runbook)

## Tool compatibility

- AWS IAM
- runbook automation

## Variant phrasings

- "runbook assumed role not granted"
- "AssumeRole AccessDenied agent"
- "IAM role assumption failed runbook"

## Why it happens

AssumeRole requires the target role's trust policy to name the caller, and runbooks written against one identity break when run as another. The agent discovered the missing grant at the worst moment: mid-incident, mid-runbook. Permission pre-flights move the discovery to the start, where it is cheap.

## Edge cases

- trust policy conditions (MFA, ExternalId, IP) fail silently as denials; read them carefully
- the pre-flight should test the actual assumption, not just list permissions
- cross-account assumptions need the trust on the target side, not the source side

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_pBaDML7CNzDPNMke0C4mHQ