AWS IAM Policies skill for Codex

Done well means: every Allow names specific actions on specific ARNs, wildcards survive only where the service does not support resource-level permissions, trust policies say exactly who may assume a role, and the policy has been validated by Access Analyzer and tested against the real calls the workload makes.

Evaluation model you must reason with

A request is allowed only if nothing denies it and something allows it, across every policy type that applies:

1. An explicit Deny anywhere wins.
2. Organization SCPs and RCPs must allow it (they never grant, only limit).
3. A permissions boundary on the principal must allow it.
4. A session policy (passed on AssumeRole) must allow it.
5. The identity policy or the resource policy allows it. Within one account either is enough; across accounts both sides must allow it.
6. KMS keys are special: the key policy must allow access (directly or by delegating to IAM with the account root principal).

When debugging AccessDenied, the error message usually names the policy type that denied (with an explicit deny in a service control policy, because no identity-based policy allows). Read it before editing anything.

Workflow

• Read AGENTS.md; find where IAM is defined (CDK, Terraform, CloudFormation, SAM)
• List the exact API calls the workload makes (code, SDK calls, CloudTrail)
• Map each call to its action, resource ARN format and condition keys in the Service Authorization Reference
• Write the policy with one statement per resource type and a Sid each
• Run the offline lint script, then Access Analyzer validation
• Simulate or exercise the real calls; confirm denied calls stay denied
• Show the user any change that widens access before applying it

Writing the policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadOrderExports",
      "Effect": "Allow",
      "Action": ["s3:GetObject"],
      "Resource": "arn:aws:s3:::acme-exports-prod/orders/*"
    },
    {
      "Sid": "ListOrderPrefixOnly",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::acme-exports-prod",
      "Condition": { "StringLike": { "s3:prefix": ["orders/*"] } }
    },
    {
      "Sid": "DecryptWithExportKey",
      "Effect": "Allow",
      "Action": "kms:Decrypt",
      "Resource": "arn:aws:kms:eu-west-1:111111111111:key/1234abcd-12ab-34cd-56ef-1234567890ab",
      "Condition": { "StringEquals": { "kms:ViaService": "s3.eu-west-1.amazonaws.com" } }
    }
  ]
}

Rules:

• Bucket-level actions (s3:ListBucket) take the bucket ARN; object actions take bucket/*. Mixing them up is the most common S3 AccessDenied.
• Resource: "*" is correct only for actions without resource-level support (ec2:Describe*, s3:ListAllMyBuckets, cloudwatch:PutMetricData). Put those in their own statement so the wildcard is obviously deliberate.
• Prefer Action lists over service:*. Wildcard verbs like dynamodb:Get* are tolerable for reads; never for writes.
• Never use Allow with NotAction or NotResource; they grant everything else, including actions AWS adds later.
• Always "Version": "2012-10-17"; the old version does not resolve policy variables such as ${aws:PrincipalTag/team}.

iam:PassRole

Any principal that can create Lambdas, ECS tasks, EC2 instances or Glue jobs with iam:PassRole on * can run code as any role in the account. Scope it:

{
  "Sid": "PassOnlyTaskRole",
  "Effect": "Allow",
  "Action": "iam:PassRole",
  "Resource": "arn:aws:iam::111111111111:role/orders-task-role",
  "Condition": { "StringEquals": { "iam:PassedToService": "ecs-tasks.amazonaws.com" } }
}

Trust policies

GitHub Actions OIDC, pinned to one repo and one environment:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Federated": "arn:aws:iam::111111111111: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-service:environment:production"
      }
    }
  }]
}

Without a sub condition any repository on GitHub can assume the role. Use StringEquals on an exact sub where possible; StringLike with repo:acme/* only when the user accepts every repo in the org.

Service trust (Lambda, ECS tasks) should add confused-deputy protection where the service supports it: aws:SourceAccount and aws:SourceArn conditions.

Cross-account trust: name the role ARN in Principal.AWS rather than the whole account root, and require sts:ExternalId when a third party assumes the role.

Resource policies

For bucket, queue, topic and key policies that must allow a service or an organization:

Goal	Condition
Any principal in our AWS Organization	aws:PrincipalOrgID = o-xxxxxxxxxx
A service acting for one specific resource	aws:SourceArn (and aws:SourceAccount)
Only via our VPC endpoint	aws:SourceVpce
Only over TLS	Deny when aws:SecureTransport is false

Decision table

Situation	Do
Existing role is over-broad and has run in production for weeks	Generate a policy from CloudTrail with Access Analyzer policy generation, then review
Many teams create roles	Permissions boundary required on every role they create
Guardrail for every account (“no one disables CloudTrail”)	SCP, not per-role policies
Human access	IAM Identity Center permission sets, not IAM users with keys
Workload outside AWS (CI, on-prem)	OIDC federation or IAM Roles Anywhere, never long-lived access keys
AWS managed policy is “close enough”	Use it only for read-only or job-function policies; write your own for apps

Offline lint

scripts/iam_policy_lint.py flags the high-risk patterns above (wildcard actions, write actions on * without conditions, NotAction, unscoped iam:PassRole, escalation actions, OIDC trust without sub, Principal: "*" without an org or source condition). It runs offline with the standard library and exits 1 on any HIGH finding:

python3 scripts/iam_policy_lint.py policy.json trust.json

It accepts a bare policy document or one wrapped in PolicyDocument / AssumeRolePolicyDocument. For CDK, run cdk synth and extract the policy from cdk.out; for Terraform, use terraform show -json on a plan.

Validate with AWS (needs network and credentials)

aws accessanalyzer validate-policy --policy-type IDENTITY_POLICY \
  --policy-document file://policy.json \
  --query 'findings[].[findingType,issueCode,findingDetails]' --output table

# Prove a new version grants nothing beyond the old one (useful in CI)
aws accessanalyzer check-no-new-access --policy-type IDENTITY_POLICY \
  --existing-policy-document file://old.json --new-policy-document file://policy.json

aws iam simulate-principal-policy \
  --policy-source-arn arn:aws:iam::111111111111:role/orders-task-role \
  --action-names s3:GetObject s3:PutObject \
  --resource-arns arn:aws:s3:::acme-exports-prod/orders/2026.csv \
  --query 'EvaluationResults[].[EvalActionName,EvalDecision]' --output table

Use --policy-type RESOURCE_POLICY with --validate-policy-resource-type AWS::S3::Bucket for bucket policies. The simulator does not evaluate SCPs from other accounts or every condition key; a real call with the role’s credentials is the final test.

Gotchas

• Policy size limits: managed policies 6,144 characters, inline role policies 10,240 total. Hitting them is a sign of copy-paste rather than structure.
• Tag-based (ABAC) conditions only work for services that support aws:ResourceTag on that action; check the Service Authorization Reference first.
• IAM is eventually consistent; a just-created role can fail AssumeRole for a few seconds. Retry rather than widening the policy.
• Explicit deny statements in a boundary or SCP are invisible from the role itself. When the role’s own policy looks right, check the boundary and the org.
• Deleting roles, detaching policies in production, or applying an SCP needs explicit user confirmation; an SCP mistake can lock out a whole account.

Output

## IAM change: <role or policy>
**Calls required:** s3:GetObject on acme-exports-prod/orders/*, kms:Decrypt on key/...
**Access removed:** <actions/resources no longer granted>
**Access added:** <with justification>
**Checks:** lint OK | Access Analyzer: 0 errors, 0 security warnings | simulation results
**Risks / follow-ups:** <wildcards kept and why, boundary or SCP interactions>