Setup guide

Baseline read of roles, users, policies, versions and account authorization details for every audit and diagnosis path.

↳ Replace with a customer-managed policy limited to iam:GetRole, iam:ListRoles, iam:ListAttachedRolePolicies, iam:ListRolePolicies, iam:GetRolePolicy, iam:GetPolicy and iam:GetPolicyVersion if full IAM read is too broad.

Predicts the authorization decision for a real principal without making the live call - the core diagnostic step.

↳ Scope Resource to the specific principal ARNs under audit rather than "*".

Tests a draft identity or resource policy document before it is attached to anything.

↳ Operates on supplied documents only and touches no account state; safe to grant on "*".

Lists the condition keys a principal's policies reference so the simulation can be run with complete context.

↳ Scope Resource to the principal ARNs under audit.

Bulk-exports every identity and policy in one call for whole-account privilege audits and 'who can do X' questions.

↳ Highly sensitive - it returns the full authorization surface of the account. Grant only for scheduled audits, not day-to-day debugging.

Starts the job that produces evidence of which services and actions a principal actually used, driving least-privilege trimming.

↳ Pair with iam:GetServiceLastAccessedDetails; scope to audited principal ARNs.

Retrieves the completed last-accessed report used to identify unused permissions safely.

↳ Job ids are caller-scoped, so "*" is acceptable here.

Produces the account-wide credential report for hygiene audits: stale keys, missing MFA, unused users.

↳ Account-level operation that cannot be resource-scoped; pair with iam:GetCredentialReport and never print key material from the result.

Lints every policy document for errors and security warnings before attachment - the mandatory dry-run for IAM.

↳ Stateless check on a supplied document; safe on "*".

Proves a policy edit does not widen access relative to the previous version, gating every change.

↳ Stateless comparison of two supplied documents; safe on "*".

Asserts a policy cannot grant named high-risk actions such as iam:PassRole or iam:CreateAccessKey.

↳ Stateless check on a supplied document; safe on "*".

Retrieves the actual denial events, including errorCode and the full errorMessage that names the responsible policy type.

↳ Cannot be resource-scoped. Restrict by attaching it only to the audit role, and prefer a read-only CloudTrail Lake query role for long-range history.

Walks the OU hierarchy to enumerate the SCPs and RCPs that apply to the account, since no effective-SCP API exists.

↳ Only works from the management or delegated administrator account. Pair with organizations:ListParents and organizations:DescribePolicy; all three are read-only.

Applies a permission boundary to cap a role's maximum privilege after the boundary has been simulated.

↳ Write action - grant only for an approved change window, scoped to the specific role ARNs, and condition on iam:PermissionsBoundary to prevent boundary removal.

Creates new service, cross-account or workload-identity roles once the trust policy has been reviewed.

↳ Write action - scope Resource to a naming prefix such as arn:aws:iam::<account>:role/app-* and require a permissions boundary via the iam:PermissionsBoundary condition key.

Cause: Implicit deny - no attached or inline policy on the principal grants the action. Nothing is explicitly blocking it; nothing is permitting it either.

Fix: Confirm with 'aws iam simulate-principal-policy' returning implicitDeny, then add a scoped Allow statement naming the exact action and resource ARN. Do not reach for Action "*".

Cause: An Organizations SCP attached to the account or a parent OU explicitly denies the action. Identity policies cannot override it.

Fix: Walk the OU tree with 'aws organizations list-parents' and 'aws organizations list-policies-for-target --filter SERVICE_CONTROL_POLICY', read each with describe-policy, and request an SCP exception from the Organizations administrator. Never try to out-grant an SCP.

Cause: Either the target role's trust policy does not name the caller, or - when the trust policy names the account root - the caller's own identity policy lacks sts:AssumeRole.

Fix: Read the trust policy with 'aws iam get-role --role-name target-role --query Role.AssumeRolePolicyDocument'. If Principal is the account root ARN, also add sts:AssumeRole to the caller's identity policy scoped to the target role ARN.

Cause: A Principal element was included in an identity-based policy. Principal is valid only in resource-based policies such as trust policies, bucket policies and KMS key policies.

Fix: Remove the Principal block from the identity policy. If the intent was a trust policy, use 'aws iam update-assume-role-policy' instead of put-role-policy.

Cause: The role still has managed policies attached, inline policies, or an instance profile association.

Fix: Detach each managed policy with 'aws iam detach-role-policy', delete inline policies with 'aws iam delete-role-policy', and remove the role from its instance profile with 'aws iam remove-role-from-instance-profile'. Confirm the deletion with the user before proceeding - it is irreversible.

Cause: The customer-managed policy already holds the maximum of five versions.

Fix: List versions with 'aws iam list-policy-versions --policy-arn <arn>' and delete a non-default one with 'aws iam delete-policy-version --version-id v2'. Prune proactively so rollback is never blocked during an incident.

Cause: Wrong account, a typo in the role name, or the caller passed a full ARN where --role-name expects a bare name.

Fix: Verify the account with 'aws sts get-caller-identity', then pass only the name segment: --role-name app-role, not the arn:aws:iam::...:role/app-role form.

Cause: Temporary credentials from AssumeRole or IAM Identity Center have passed their expiry, typically one hour by default.

Fix: Re-authenticate with 'aws sso login --profile <name>' or re-run 'aws sts assume-role'. This is an authentication failure, not an authorization problem - do not start editing policies.

Cause: The access key was deleted or deactivated, AWS_SESSION_TOKEN is missing for an ASIA... temporary key, or key and secret belong to different credentials.

Fix: Run 'aws configure list' to see which source supplies each value. For ASIA keys, export AWS_SESSION_TOKEN as well. Environment variables silently override the profile - unset stale ones.

Cause: EC2's authorization failure code. Returned in place of AccessDenied, and also emitted for a --dry-run call the principal is not permitted to make.

Fix: Decode the encoded message with 'aws sts decode-authorization-message --encoded-message <blob>' to reveal the matched statements, then simulate the action. A successful dry-run instead returns DryRunOperation.

Cause: The credentials are not in the Organizations management account or a delegated administrator account.

Fix: Switch to management-account credentials for SCP work, or report explicitly that SCPs could not be inspected. Do not conclude that no SCP is involved.

Cause: A permissions boundary attached to the principal caps its maximum privilege and omits this action, so the identity policy Allow has no effect.

Fix: Read the boundary with 'aws iam get-role --role-name <role> --query Role.PermissionsBoundary', simulate with --permissions-boundary-policy-input-list, and amend the boundary rather than the identity policy.