# IAM Policy and Trust Boundary Guide

Use this reference for AWS IAM identity policies, trust policies, resource policies, permission boundaries, SCPs, session policies, PassRole, federation, OIDC, Access Analyzer findings, and least-privilege remediation.

## What people get wrong

The lazy story is:

> Remove wildcards and the policy becomes least privilege.

Wrong. Least privilege is about actions, resources, conditions, trust, session context, permission boundaries, and how the role is reached. A narrow action on a dangerous resource can still be privilege escalation.

Common bad assumptions:

- Managed policies are safer than inline policies.
- Trust policy principal is enough without conditions.
- `iam:PassRole` is harmless if deployment needs it.
- SCP denies prove workload least privilege.
- Access Analyzer generated policy is complete authorization design.
- OIDC federation is safe if the provider is official.

## IAM failure modes

- Broad trust allows external accounts, services, or web identities without audience, subject, source, or external ID constraints.
- `iam:PassRole`, `sts:AssumeRole`, `iam:CreatePolicyVersion`, or permissions-boundary edits enable escalation.
- Resource policies grant cross-account/public access bypassing identity-only review.
- Conditions use wrong operator, key, or case; deny/allow precedence is misunderstood.
- Session policies, permission boundaries, and SCPs interact differently than expected.
- Break-glass or CI/CD roles accumulate production admin over time.

## Minimum safe workflow

1. Identify principal, resource, action path, caller context, account/Org boundary, and business need.
2. Review effective access path: identity policy, trust policy, resource policy, boundary, SCP, session policy, and service control conditions.
3. Classify escalation risk: PassRole, policy administration, KMS decrypt, network/security group, data exfiltration, secrets, and logging disablement.
4. Reduce access by action, resource ARN, condition, tag, principal, source account/ARN, VPC endpoint, and time/session constraints where supported.
5. Use IAM Access Analyzer, policy validation, and simulation as evidence inputs, not proof of production safety.
6. Provide a minimal diff and explain what it grants, denies, and cannot prove.
7. Require approval before live IAM changes, especially denies, trust changes, and production deploy roles.

## Verification targets

- identity policies, trust policies, resource policies, permission boundaries, SCPs, session policies, and permission sets
- Access Analyzer external access and unused access findings, policy validation, generated policies, and simulate-principal-policy output
- condition keys: ExternalId, SourceArn, SourceAccount, PrincipalOrgID, VPC endpoint, MFA, tags, audience/subject for OIDC
- `iam:PassRole`, `sts:AssumeRole`, policy version/admin actions, KMS decrypt, S3/object access, Secrets Manager, and logging controls
- CloudTrail evidence of actual usage, last accessed data, and role chaining/session name patterns
- rollback path for policy denies, boundary changes, SCPs, and trust policy edits

## When to push back

Push back if the user asks to:

- grant wildcard admin to unblock delivery
- trust an external/OIDC principal without tight conditions
- approve PassRole without target role and service constraints
- rely on SCPs as least-privilege proof
- remove denies or boundaries without blast-radius analysis
- apply IAM changes live without simulation and rollback plan

# Official sources

Use this reference only when you need source grounding for AWS service behavior or the detailed source list.

## AWS documentation

Use these as starting points, not as proof of the user's live AWS state:
- https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html
- https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html
- https://docs.aws.amazon.com/IAM/latest/UserGuide/access-analyzer-custom-policy-checks.html
- https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started-reduce-permissions.html

## Grounding rule

Official documentation explains AWS service behavior. It does not prove the user's current account, Region, quota, resource configuration, IAM boundary, pricing, entitlement, or operational state. Prefer read-only AWS MCP or CLI evidence, repository evidence, or sanitized user-provided evidence for current-state claims.

## Current MCP/documentation refresh (2026-06-02)

Service facts from official docs:
- IAM best practices call for least-privilege permissions, federation and temporary credentials, MFA, Access Analyzer policy generation/validation, removal of unused permissions, policy conditions, and cross-account/public-access analysis.
- IAM policy documents grant permissions through identity-based, resource-based, and other policy types; least privilege requires narrowing actions, resources, conditions, and principals.

Sampled live evidence:
- Read-only regional availability sampling reported IAM as `isAvailableIn` in `us-east-1`, `us-west-2`, `eu-west-1`, and `ap-southeast-1`.
- Sampled API `AccessAnalyzer+ValidatePolicy` was reported `isAvailableIn` in those regions; `IAM+GetPolicy` was `isAvailableIn` in `us-east-1` and `us-west-2`, and `Not Found` in `eu-west-1` and `ap-southeast-1`, so treat IAM as global/service-specific availability evidence rather than regional resource proof.

Review implications:
- Do not approve broad IAM from intent alone. Require action/resource/condition scope, Access Analyzer findings, last-accessed or CloudTrail evidence, boundary/SCP context, and break-glass exception handling.
- Documentation cannot prove the user's actual principals, policies, or account guardrails.

# Safety checklist

Use this reference before privileged, destructive, traffic-changing, cost-changing, compliance-impacting, or production-impacting recommendations.

## Non-negotiables

- Never ask users to paste secrets, access keys, session tokens, private keys, customer identifiers, or sensitive account data into chat.
- Use read-only AWS MCP or read-only AWS CLI evidence for live state when available; otherwise use repository evidence, sanitized user evidence, or official documentation and label the evidence level.
- Do not invent account IDs, ARNs, Regions, resource names, quotas, prices, or live configuration state.
- Require explicit user approval before privileged, destructive, traffic-changing, cost-changing, or production-impacting actions.
- Use current official AWS documentation for service behavior when the answer depends on AWS service details.
- Keep remediation least-privilege, reversible, and scoped to the requested workload or account boundary.

## Stress checks

- What can expose data?
- What can escalate privilege?
- What can break production or block rollback?
- What can create unbounded cost?
- What compliance or audit evidence is missing?
- What rollback or validation path is unproven?

## Evidence labels

Use `live evidence`, `repo evidence`, `user-provided evidence`, `documentation-based`, or `inference`. Documentation alone never proves the user's live AWS state.

# Workflow and output contract

Use this reference only when performing the full review, implementation guidance, incident triage, or production-readiness pass.

## Review domains

Check these areas before giving a verdict:
- Policy type, principal, resource, action, condition, account boundary, and intended operations
- Wildcard actions/resources, privilege escalation, confused deputy, pass-role, iam/sts/kms/secrets risks
- Resource-level support, condition keys, trust constraints, service-linked roles, and data/control-plane split
- Access Analyzer validation, simulation where useful, rollback, and explicit residual risk

## Safe workflow

1. **Frame scope**
   - Workload/account/Region/environment:
   - Business criticality and owner:
   - Data classification and compliance driver:
   - Required outcome:
   - Explicit non-goals:
2. **Collect evidence**
   - Prefer read-only AWS MCP or read-only AWS CLI evidence for current-state claims when available.
   - Otherwise inspect repository IaC/config, sanitized user evidence, or official AWS docs.
   - Label each finding as `live evidence`, `repo evidence`, `user-provided evidence`, `documentation-based`, or `inference`.
3. **Stress-test risk**
   - What can expose data?
   - What can escalate privilege?
   - What can break production or block rollback?
   - What can create unbounded cost?
   - What evidence is missing?
4. **Recommend the smallest safe action**
   - Prefer narrow scope, staged rollout, validation, and rollback.
   - If the safest action is to stop and gather evidence, say that plainly.

## Output contract

Return this structure:
```markdown
# AWS IAM Least Privilege Review: <scope>
## Executive verdict
- Status: READY / READY WITH RISKS / NOT READY / NEEDS EVIDENCE
- Biggest risk:
- Evidence level:
## Scope and assumptions
- Confirmed:
- Unknown:
- Out of scope:
## Findings
| Severity | Finding | Evidence | Why it matters | Minimum safe action |
|---|---|---|---|---|
## Recommended actions
1. <action> — owner: <owner>, validation: <check>, rollback: <rollback>
## Validation
- Commands or checks:
- Expected result:
## Residual risk
- <risk or explicit none>
```