AWS IAM Least Privilege skill for Claude Code

A good IAM change grants only the actions a workload actually calls, on the specific resource ARNs it touches, under conditions that pin who and from where; uses roles with temporary credentials instead of access keys; and is validated by Access Analyzer before it ships. An AccessDenied is diagnosed by evidence (which policy type denied), not by widening permissions until it works.

Workflow: writing a policy

- [ ] 1. List the exact API calls the workload makes (code, SDK calls, CloudTrail history)
- [ ] 2. Map each call to IAM actions, resource ARNs and supported condition keys
- [ ] 3. Choose where permissions live: identity policy, resource policy, or both
- [ ] 4. Write the policy with specific ARNs and conditions; add explicit denies for guardrails
- [ ] 5. Validate: Access Analyzer validate-policy + scripts/policy_lint.py
- [ ] 6. Test with the simulator or a real call in a non-prod account
- [ ] 7. Review unused access later and trim

1-2. From calls to actions

• The Service Authorization Reference lists, per service, every action, its resource types, and supported condition keys. Some actions do not support resource-level permissions and require "Resource": "*"; that is fine for those actions only (e.g. ec2:DescribeInstances, s3:ListAllMyBuckets).
• Some calls need several actions (e.g. S3 multipart uploads, KMS-encrypted objects need kms:GenerateDataKey/kms:Decrypt on the key, CloudWatch Logs needs logs:CreateLogStream and logs:PutLogEvents).
• For existing workloads, generate a starting policy from CloudTrail with Access Analyzer policy generation (console: role > “Generate policy”), then tighten it.

3. Where permissions live

Situation	Use
A workload (Lambda, ECS task, EC2) calls AWS	Role with identity policy; service trust policy
CI/CD deploys to AWS	OIDC federation role (GitHub Actions, GitLab), no access keys
Humans	IAM Identity Center permission sets, not IAM users
Cross-account access	Role in the target account trusted by the source account principal, or resource policy (S3, KMS, SQS, SNS)
Guardrails for a whole org or OU	SCPs (cap principals) and RCPs (cap resources)
Delegating role creation to developers safely	Permission boundaries

4. Policy patterns

Scoped identity policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadWriteUploadsPrefix",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject"],
      "Resource": "arn:aws:s3:::acme-prod-uploads/tenants/*"
    },
    {
      "Sid": "ListOnlyThatPrefix",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::acme-prod-uploads",
      "Condition": { "StringLike": { "s3:prefix": ["tenants/*"] } }
    },
    {
      "Sid": "PassOnlyTheWorkerRoleToEcs",
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::123456789012:role/orders-worker-task",
      "Condition": { "StringEquals": { "iam:PassedToService": "ecs-tasks.amazonaws.com" } }
    }
  ]
}

GitHub Actions OIDC trust policy:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com" },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": {
        "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
        "token.actions.githubusercontent.com:sub": "repo:acme/orders:environment:production"
      }
    }
  }]
}

Without the sub condition any GitHub repository can assume the role. Prefer environment:<name> or ref:refs/heads/main over repo:acme/*.

Condition keys worth knowing:

Key	Use
aws:PrincipalOrgID	Resource policies: allow only principals in your AWS Organization
aws:ResourceOrgID	Identity policies/SCPs: only touch resources in your org (data perimeter)
aws:SourceArn, aws:SourceAccount	Service-to-service calls (S3 to SNS, EventBridge to Lambda): prevent confused deputy
aws:SecureTransport	Deny non-TLS access in bucket/queue policies
aws:RequestedRegion	Restrict regions in SCPs
aws:PrincipalTag/..., aws:ResourceTag/...	ABAC: match principal and resource tags
aws:SourceVpce, aws:SourceVpc	Only via a VPC endpoint
sts:ExternalId	Third-party cross-account roles (confused deputy)
aws:MultiFactorAuthPresent	Require MFA for sensitive actions (human sessions)

Condition operators: StringEquals/StringLike, ArnLike, Bool, IpAddress, ForAnyValue:/ForAllValues: for multivalued keys (ForAllValues is true when the key is absent; pair with a Null check). Use ...IfExists deliberately.

Evaluation order (for diagnosis)

1. Explicit Deny in any applicable policy wins.
2. Organizations SCPs (principal side) and RCPs (resource side) must allow.
3. Resource-based policy can grant access (within the same account, it can allow even without an identity policy for most services; KMS key policies and IAM role trust policies must explicitly allow).
4. Permission boundary on the principal must allow.
5. Session policy (assumed-role session policies) must allow.
6. Identity-based policy must allow.

Cross-account: both the identity policy in the caller’s account and the resource policy (or role trust) in the target account must allow.

Workflow: debugging AccessDenied

- [ ] 1. Read the full error: action, resource ARN, principal, and "because no ... policy allows"/"with an explicit deny in a ... policy"
- [ ] 2. Confirm who is calling: aws sts get-caller-identity (in the same environment)
- [ ] 3. Decode encoded messages (EC2 and some others)
- [ ] 4. Find the CloudTrail event for the failed call
- [ ] 5. Check each policy type in evaluation order; simulate
- [ ] 6. Fix the narrowest policy; re-test the same call

aws sts get-caller-identity
aws sts decode-authorization-message --encoded-message "$MSG" --query DecodedMessage --output text | jq .
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventName,AttributeValue=PutObject \
  --max-results 20 --query 'Events[].CloudTrailEvent' --output text | jq -c 'select(.errorCode != null) | {eventTime, errorCode, errorMessage, userIdentity: .userIdentity.arn}'
aws iam simulate-principal-policy \
  --policy-source-arn arn:aws:iam::123456789012:role/orders-api \
  --action-names s3:PutObject --resource-arns arn:aws:s3:::acme-prod-uploads/tenants/t1/a.png \
  --query 'EvaluationResults[].{action:EvalActionName,decision:EvalDecision}'

Common causes, in order of frequency:

• Wrong principal: the code runs with a different role than expected (local profile, missing task role, Lambda execution role vs deploy role).
• Missing companion permission: KMS key policy/grant, s3:ListBucket on the bucket ARN (needed to get 404 instead of 403 for missing objects), iam:PassRole.
• Resource ARN mismatch: bucket ARN vs object ARN (bucket vs bucket/*), wrong region or account, a path in the role ARN.
• Explicit deny from an SCP, permission boundary, bucket policy (aws:SecureTransport, VPC endpoint conditions), or VPC endpoint policy. The error message names the policy type.
• Condition not met: missing tag, wrong s3:prefix, request without encryption header.
• Propagation: new IAM changes are eventually consistent; retry after a few seconds before concluding.

Validate

aws accessanalyzer validate-policy --policy-type IDENTITY_POLICY \
  --policy-document file://policy.json --query 'findings[].[findingType,issueCode,findingDetails]' --output table
python3 scripts/policy_lint.py policy.json trust.json      # wildcards, PassRole, OIDC sub, public principals

validate-policy catches invalid actions, ARN formats, and security warnings; scripts/policy_lint.py (stdlib) flags least-privilege smells and exits 1 on high findings, so it fits in CI next to Terraform/CDK synth output. Access Analyzer custom policy checks (check-no-new-access, check-access-not-granted) can gate PRs against a reference policy or forbidden actions.

Hard rules

• No "Action": "*" or service:* for workloads. No NotAction with Allow.
• No long-lived access keys for workloads or CI; use roles and OIDC. Rotate or remove any that exist (aws iam list-access-keys, check LastUsedDate).
• iam:PassRole always scoped to specific role ARNs and iam:PassedToService.
• Never grant iam:*Policy*, iam:CreateAccessKey, iam:UpdateAssumeRolePolicy to workloads: each is a privilege-escalation path.
• One role per workload; do not share roles across services.
• Changes to production trust policies, SCPs or admin roles require explicit user confirmation.

Verification

1. Access Analyzer validate-policy returns no errors or security warnings.
2. scripts/policy_lint.py exits 0 at the agreed fail level.
3. The original failing call succeeds; a call outside the intended scope (another bucket prefix, another table) still fails with AccessDenied.
4. After 30-90 days, Access Analyzer unused-access findings or last-accessed data (aws iam generate-service-last-accessed-details) confirm nothing granted is unused.