AWS IAM Policy Minimizer

What this skill does

Reads an existing IAM role's attached policies, queries CloudTrail (via Access Analyzer's policy-generation API) for actions that role actually used over a window, and proposes a minimized replacement policy.

Inputs

• role_arn: target IAM role ARN.
• window_days: how many days of history to consider (max 90).
• AWS credentials (env or ~/.aws/credentials) with iam:GetRolePolicy, iam:ListAttachedRolePolicies, accessanalyzer:StartPolicyGeneration, accessanalyzer:GetGeneratedPolicy.
• Optional output_path: defaults to iam-min-<role>.json.

Steps

1. List the role's attached policies: aws iam list-attached-role-policies --role-name $(basename <role_arn>).
2. Fetch each policy's current document: aws iam get-policy-version.
3. Trigger an Access Analyzer policy generation job: aws accessanalyzer start-policy-generation --policy-generation-details principalArn=<role_arn>. Poll get-generated-policy until status is SUCCEEDED.
4. Diff the union of currently-allowed actions vs. actions present in the generated policy. The difference is the over-grant.
5. For each action in the over-grant, label it unused (no calls in window) or risky (e.g., iam:*, s3:DeleteBucket).
6. Build a new policy document combining the generated policy with any actions Access Analyzer missed but that the role's known runtime requires (driven by an optional must-keep allowlist).
7. Run aws accessanalyzer validate-policy --policy-document file://new.json --policy-type IDENTITY_POLICY and ensure zero ERROR findings.
8. Compute "actions removed" count and emit a markdown report alongside the JSON policy.
9. Write both files.

Output

Two artifacts: iam-min-<role>.json (the minimized policy) and iam-min-<role>.md (the rationale: actions removed by service, sample CloudTrail events that justified what stayed). Exit 0 if at least one action was removed.

Verification

Apply the new policy to a non-production role first: clone the role, attach the new policy, and run the workload's known operations against it. Watch CloudTrail for AccessDenied events for 24h. Iterate by adding any denied action back. Run aws accessanalyzer get-finding for any open findings on the role; the count must not increase post-rollout.

Edge cases

• Window shorter than the workload's longest cycle (e.g., monthly batch jobs): extend the window or note "may be undercounting".
• Roles assumed by humans for ad-hoc work: policy minimization is risky; keep a "human-ops" appendix of broad permissions and require manual override.
• Cross-account assume-role usage: Access Analyzer covers it but the report should note the trust boundary explicitly.
• Roles attached to AWS-managed policies: cannot edit; suggest creating a customer-managed copy minus unused actions.