Skip to content

Commit 36700d3

Browse files
arnewoutersarnewouters
authored
feat: add iam-common-pitfalls skill (#28)
1 parent d128de9 commit 36700d3

2 files changed

Lines changed: 198 additions & 0 deletions

File tree

  • plugins/aws-core/skills/iam-common-pitfalls
  • skills/services-and-workloads/iam-common-pitfalls

‎plugins/aws-core/skills/iam-common-pitfalls/SKILL.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
name: iam-common-pitfalls
3+
description: "Verified corrections for IAM behaviors that AI agents frequently get\
4+
\ wrong \u2014 policy evaluation edge cases, trust policy gotchas, STS session limits,\
5+
\ Organizations quirks, and SAML/MFA specifics. Use alongside documentation when\
6+
\ working with IAM roles, policies, STS, or Organizations. Do NOT use for non-IAM\
7+
\ authorization like Cognito user-pool policies or app-level RBAC."
8+
version: 1
9+
metadata:
10+
service: [iam, sts, organizations]
11+
task: [configure, secure, audit, debug]
12+
persona: [developer, security-engineer, devops]
13+
workload: [security]
14+
---
15+
16+
# AWS IAM — Common Pitfalls
17+
18+
## About This Skill
19+
20+
This skill contains verified corrections for things that AI agents frequently get wrong about IAM. It is not a comprehensive IAM guide — for full IAM guidance, search AWS documentation.
21+
22+
When answering IAM questions, verify specific claims (limits, quotas, exact API names, edge-case behaviors) against official AWS documentation rather than relying on pre-training. Prefer fetching known documentation URLs over broad searches. Trust official documentation over memory when they conflict.
23+
24+
## Verified Edge Cases
25+
26+
**CloudTrail:**
27+
28+
- AcceptHandshake/DeclineHandshake logged in ACTING account ONLY, not management account. Organization trail required for centralization.
29+
- ConsoleLogin region varies by endpoint/cookies, NOT always us-east-1. `?region=` forces specific region.
30+
31+
**STS:**
32+
33+
- GetSessionToken restrictions: (1) No IAM APIs unless MFA included (2) No STS except AssumeRole and GetCallerIdentity.
34+
- Cross-account AssumeRole to opt-in region: TARGET account must enable region, not calling account.
35+
- Role chaining: max 1-hour session.
36+
37+
**Organizations:**
38+
39+
- Suspended/closed accounts CANNOT be removed until permanently closed (~90 days). Remove FIRST, then close.
40+
- Policy management delegation: use PutResourcePolicy, NOT register-delegated-administrator.
41+
- AI opt-out policies: management account required by default.
42+
- Organizations policy types for ListPolicies filter: SERVICE_CONTROL_POLICY, TAG_POLICY, BACKUP_POLICY, AISERVICES_OPT_OUT_POLICY, CHATBOT_POLICY, DECLARATIVE_POLICY_EC2, RESOURCE_CONTROL_POLICY.
43+
44+
**SDK Specifics:**
45+
46+
- Organizations: `DuplicatePolicyAttachmentException` (not PolicyAlreadyAttachedException).
47+
- Boto3 IAM AccessKey: methods are `activate()`, `deactivate()`, `delete()` — NO `update()`.
48+
- Instance profiles: waiter + `time.sleep(10)` pattern.
49+
- Managed policy max versions: 5.
50+
51+
**SAML:**
52+
53+
- Encrypted assertions URL: `https://region-code.signin.aws.amazon.com/saml/acs/IdP-ID`.
54+
- Private key from IdP uploaded to IAM in .pem format.
55+
56+
**Policy Evaluation:**
57+
58+
- ForAllValues with empty/missing key: evaluates to true (vacuous truth). To avoid that, use a `Null` condition in addition to the `ForAllValues` on **the same context key** to require that key to be present and non-null. For example, when evaluating the `aws:TagKeys` context key:
59+
60+
```
61+
{
62+
"Version": "2012-10-17",
63+
"Statement": {
64+
"Effect": "Allow",
65+
"Action": "ec2:RunInstances",
66+
"Resource": "*",
67+
"Condition": {
68+
"ForAllValues:StringEquals": {
69+
"aws:TagKeys": ["Alpha", "Beta"]
70+
},
71+
"Null": {
72+
"aws:TagKeys": "false"
73+
}
74+
}
75+
}
76+
}
77+
```
78+
79+
- Resource-based policies granting to IAM user ARN bypass permissions boundaries in same account.
80+
- 8 privilege escalation actions via direct IAM policy manipulation: PutGroupPolicy, PutRolePolicy, PutUserPolicy, CreatePolicy, CreatePolicyVersion, AttachGroupPolicy, AttachRolePolicy, AttachUserPolicy.
81+
- `iam:PassRole` with `Resource: "*"` + create/update on a compute service (EC2 `RunInstances`, Lambda `CreateFunction`/`UpdateFunctionConfiguration`, ECS `RegisterTaskDefinition`, Glue, SageMaker, CloudFormation, etc.) = privilege escalation to any passable role in the account, including Administrator. Scope `Resource` to specific role ARNs or an IAM path; optionally constrain with `iam:PassedToService` / `iam:AssociatedResourceArn`. See [IAM User Guide — Grant a user permissions to pass a role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html).
82+
83+
**MFA:**
84+
85+
- Unassigned virtual MFA devices auto-deleted when adding new ones.
86+
- MFA resync-only policy NotAction needs exactly: iam:ListMFADevices, iam:ListVirtualMFADevices, iam:ResyncMFADevice.
87+
88+
**SigV4:**
89+
90+
- IncompleteSignatureException includes SHA-256 hash of Authorization header for transit modification diagnosis.
91+
92+
**Service-Specific Roles:**
93+
94+
- Redshift Serverless trust policy: include BOTH `redshift-serverless.amazonaws.com` AND `redshift.amazonaws.com` as service principals (per AWS docs; omitting serverless causes `Not authorized to get credentials of role` on COPY).
95+
- IAM OIDC providers: thumbprints no longer required for most providers (AWS verifies via trusted CAs since 2022).
96+
97+
**Policy Summary Display:**
98+
99+
- Single statement with multi-service wildcard actions (e.g. `codebuild:*`, `codecommit:*`) + service-specific resource ARNs: each resource appears ONLY under its matching service's summary (CodeBuild ARN under CodeBuild, etc.). A resource whose service prefix matches NO action in the statement is the only case where it appears in all action summaries ("mismatched resource").

‎skills/services-and-workloads/iam-common-pitfalls/SKILL.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
name: iam-common-pitfalls
3+
description: "Verified corrections for IAM behaviors that AI agents frequently get\
4+
\ wrong \u2014 policy evaluation edge cases, trust policy gotchas, STS session limits,\
5+
\ Organizations quirks, and SAML/MFA specifics. Use alongside documentation when\
6+
\ working with IAM roles, policies, STS, or Organizations. Do NOT use for non-IAM\
7+
\ authorization like Cognito user-pool policies or app-level RBAC."
8+
version: 1
9+
metadata:
10+
service: [iam, sts, organizations]
11+
task: [configure, secure, audit, debug]
12+
persona: [developer, security-engineer, devops]
13+
workload: [security]
14+
---
15+
16+
# AWS IAM — Common Pitfalls
17+
18+
## About This Skill
19+
20+
This skill contains verified corrections for things that AI agents frequently get wrong about IAM. It is not a comprehensive IAM guide — for full IAM guidance, search AWS documentation.
21+
22+
When answering IAM questions, verify specific claims (limits, quotas, exact API names, edge-case behaviors) against official AWS documentation rather than relying on pre-training. Prefer fetching known documentation URLs over broad searches. Trust official documentation over memory when they conflict.
23+
24+
## Verified Edge Cases
25+
26+
**CloudTrail:**
27+
28+
- AcceptHandshake/DeclineHandshake logged in ACTING account ONLY, not management account. Organization trail required for centralization.
29+
- ConsoleLogin region varies by endpoint/cookies, NOT always us-east-1. `?region=` forces specific region.
30+
31+
**STS:**
32+
33+
- GetSessionToken restrictions: (1) No IAM APIs unless MFA included (2) No STS except AssumeRole and GetCallerIdentity.
34+
- Cross-account AssumeRole to opt-in region: TARGET account must enable region, not calling account.
35+
- Role chaining: max 1-hour session.
36+
37+
**Organizations:**
38+
39+
- Suspended/closed accounts CANNOT be removed until permanently closed (~90 days). Remove FIRST, then close.
40+
- Policy management delegation: use PutResourcePolicy, NOT register-delegated-administrator.
41+
- AI opt-out policies: management account required by default.
42+
- Organizations policy types for ListPolicies filter: SERVICE_CONTROL_POLICY, TAG_POLICY, BACKUP_POLICY, AISERVICES_OPT_OUT_POLICY, CHATBOT_POLICY, DECLARATIVE_POLICY_EC2, RESOURCE_CONTROL_POLICY.
43+
44+
**SDK Specifics:**
45+
46+
- Organizations: `DuplicatePolicyAttachmentException` (not PolicyAlreadyAttachedException).
47+
- Boto3 IAM AccessKey: methods are `activate()`, `deactivate()`, `delete()` — NO `update()`.
48+
- Instance profiles: waiter + `time.sleep(10)` pattern.
49+
- Managed policy max versions: 5.
50+
51+
**SAML:**
52+
53+
- Encrypted assertions URL: `https://region-code.signin.aws.amazon.com/saml/acs/IdP-ID`.
54+
- Private key from IdP uploaded to IAM in .pem format.
55+
56+
**Policy Evaluation:**
57+
58+
- ForAllValues with empty/missing key: evaluates to true (vacuous truth). To avoid that, use a `Null` condition in addition to the `ForAllValues` on **the same context key** to require that key to be present and non-null. For example, when evaluating the `aws:TagKeys` context key:
59+
60+
```
61+
{
62+
"Version": "2012-10-17",
63+
"Statement": {
64+
"Effect": "Allow",
65+
"Action": "ec2:RunInstances",
66+
"Resource": "*",
67+
"Condition": {
68+
"ForAllValues:StringEquals": {
69+
"aws:TagKeys": ["Alpha", "Beta"]
70+
},
71+
"Null": {
72+
"aws:TagKeys": "false"
73+
}
74+
}
75+
}
76+
}
77+
```
78+
79+
- Resource-based policies granting to IAM user ARN bypass permissions boundaries in same account.
80+
- 8 privilege escalation actions via direct IAM policy manipulation: PutGroupPolicy, PutRolePolicy, PutUserPolicy, CreatePolicy, CreatePolicyVersion, AttachGroupPolicy, AttachRolePolicy, AttachUserPolicy.
81+
- `iam:PassRole` with `Resource: "*"` + create/update on a compute service (EC2 `RunInstances`, Lambda `CreateFunction`/`UpdateFunctionConfiguration`, ECS `RegisterTaskDefinition`, Glue, SageMaker, CloudFormation, etc.) = privilege escalation to any passable role in the account, including Administrator. Scope `Resource` to specific role ARNs or an IAM path; optionally constrain with `iam:PassedToService` / `iam:AssociatedResourceArn`. See [IAM User Guide — Grant a user permissions to pass a role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html).
82+
83+
**MFA:**
84+
85+
- Unassigned virtual MFA devices auto-deleted when adding new ones.
86+
- MFA resync-only policy NotAction needs exactly: iam:ListMFADevices, iam:ListVirtualMFADevices, iam:ResyncMFADevice.
87+
88+
**SigV4:**
89+
90+
- IncompleteSignatureException includes SHA-256 hash of Authorization header for transit modification diagnosis.
91+
92+
**Service-Specific Roles:**
93+
94+
- Redshift Serverless trust policy: include BOTH `redshift-serverless.amazonaws.com` AND `redshift.amazonaws.com` as service principals (per AWS docs; omitting serverless causes `Not authorized to get credentials of role` on COPY).
95+
- IAM OIDC providers: thumbprints no longer required for most providers (AWS verifies via trusted CAs since 2022).
96+
97+
**Policy Summary Display:**
98+
99+
- Single statement with multi-service wildcard actions (e.g. `codebuild:*`, `codecommit:*`) + service-specific resource ARNs: each resource appears ONLY under its matching service's summary (CodeBuild ARN under CodeBuild, etc.). A resource whose service prefix matches NO action in the statement is the only case where it appears in all action summaries ("mismatched resource").

0 commit comments

Comments
 (0)