{"id":41093940,"url":"https://github.com/boogy/iam-policy-validator","last_synced_at":"2026-02-12T20:01:43.869Z","repository":{"id":320641655,"uuid":"1082873271","full_name":"boogy/iam-policy-validator","owner":"boogy","description":"⚡ Stop IAM misconfigurations before they become breaches — Catch overprivileged permissions, dangerous wildcards, and policy errors before deployment.","archived":false,"fork":false,"pushed_at":"2026-02-04T23:11:27.000Z","size":2278,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-05T11:44:01.728Z","etag":null,"topics":["aws","iam","security"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boogy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-24T22:54:08.000Z","updated_at":"2026-02-04T23:05:50.000Z","dependencies_parsed_at":"2025-10-25T01:06:10.070Z","dependency_job_id":"2b965682-f835-4830-9ea7-f6e79fabd2ab","html_url":"https://github.com/boogy/iam-policy-validator","commit_stats":null,"previous_names":["boogy/iam-validator"],"tags_count":56,"template":false,"template_full_name":null,"purl":"pkg:github/boogy/iam-policy-validator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boogy%2Fiam-policy-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boogy%2Fiam-policy-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boogy%2Fiam-policy-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boogy%2Fiam-policy-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boogy","download_url":"https://codeload.github.com/boogy/iam-policy-validator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boogy%2Fiam-policy-validator/sbom","scorecard":{"id":1239812,"data":{"date":"2025-11-17T17:47:36Z","repo":{"name":"github.com/boogy/iam-policy-validator","commit":"bc082aabe407f331d9e91af7a667fe87b132b138"},"scorecard":{"version":"v5.3.0","commit":"c22063e786c11f9dd714d777a687ff7c4599b600"},"score":6.4,"checks":[{"name":"Dependency-Update-Tool","score":10,"reason":"update tool detected","details":["Info: detected update tool: Dependabot: .github/dependabot.yml:1"],"documentation":{"short":"Determines if the project uses a dependency update tool.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#dependency-update-tool"}},{"name":"Code-Review","score":0,"reason":"Found 0/9 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#code-review"}},{"name":"Maintained","score":0,"reason":"project was created within the last 90 days. Please review its contents carefully","details":["Warn: Repository was created within the last 90 days."],"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#maintained"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: SECURITY.md:1","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#security-policy"}},{"name":"Token-Permissions","score":10,"reason":"GitHub workflow tokens follow principle of least privilege","details":["Warn: jobLevel 'contents' permission set to 'write': .github/workflows/cleanup-prereleases.yml:27","Info: jobLevel 'actions' permission set to 'read': .github/workflows/codeql.yml:18","Info: jobLevel 'contents' permission set to 'read': .github/workflows/codeql.yml:19","Warn: jobLevel 'contents' permission set to 'write': .github/workflows/pre-release.yml:46","Warn: jobLevel 'contents' permission set to 'write': .github/workflows/release.yml:19","Info: topLevel permissions set to 'read-all': .github/workflows/ci.yml:10","Info: topLevel permissions set to 'read-all': .github/workflows/cleanup-prereleases.yml:20","Info: topLevel permissions set to 'read-all': .github/workflows/codeql.yml:11","Info: topLevel permissions set to 'read-all': .github/workflows/pre-release.yml:38","Info: topLevel permissions set to 'read-all': .github/workflows/release.yml:8","Info: topLevel permissions set to 'read-all': .github/workflows/scorecard.yml:18"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#token-permissions"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#dangerous-workflow"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#packaging"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":10,"reason":"all dependencies are pinned","details":["Info:  20 out of  20 GitHub-owned GitHubAction dependencies pinned","Info:   9 out of   9 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#pinned-dependencies"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#vulnerabilities"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#cii-best-practices"}},{"name":"SAST","score":10,"reason":"SAST tool is run on all commits","details":["Info: SAST configuration detected: CodeQL","Info: all commits (30) are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#sast"}},{"name":"Branch-Protection","score":5,"reason":"branch protection is not maximal on development and all release branches","details":["Info: 'allow deletion' disabled on branch 'main'","Info: 'force pushes' disabled on branch 'main'","Warn: 'branch protection settings apply to administrators' is disabled on branch 'main'","Info: 'stale review dismissal' is required to merge on branch 'main'","Warn: required approving review count is 1 on branch 'main'","Warn: codeowners review is not required on branch 'main'","Info: 'last push approval' is required to merge on branch 'main'","Warn: 'up-to-date branches' is disabled on branch 'main'","Info: status check found to merge onto on branch 'main'","Info: PRs are required in order to make changes on branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#branch-protection"}},{"name":"Signed-Releases","score":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact v1.10.1 not signed: https://api.github.com/repos/boogy/iam-policy-validator/releases/262807881","Warn: release artifact v1.10.0 not signed: https://api.github.com/repos/boogy/iam-policy-validator/releases/262389982","Warn: release artifact v1.9.0 not signed: https://api.github.com/repos/boogy/iam-policy-validator/releases/262273248","Warn: release artifact v1.8.0 not signed: https://api.github.com/repos/boogy/iam-policy-validator/releases/262195059","Warn: release artifact v1.10.1 does not have provenance: https://api.github.com/repos/boogy/iam-policy-validator/releases/262807881","Warn: release artifact v1.10.0 does not have provenance: https://api.github.com/repos/boogy/iam-policy-validator/releases/262389982","Warn: release artifact v1.9.0 does not have provenance: https://api.github.com/repos/boogy/iam-policy-validator/releases/262273248","Warn: release artifact v1.8.0 does not have provenance: https://api.github.com/repos/boogy/iam-policy-validator/releases/262195059"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#signed-releases"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#license"}},{"name":"Contributors","score":0,"reason":"project has 0 contributing companies or organizations -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project has a set of contributors from multiple organizations (e.g., companies).","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#contributors"}},{"name":"CI-Tests","score":10,"reason":"9 out of 9 merged PRs checked by a CI test -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project runs tests before pull requests are merged.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#ci-tests"}}]},"last_synced_at":"2025-11-17T19:23:47.916Z","repository_id":320641655,"created_at":"2025-11-17T19:23:47.929Z","updated_at":"2025-11-17T19:23:47.929Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29379645,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T19:05:20.189Z","status":"ssl_error","status_checked_at":"2026-02-12T19:01:44.216Z","response_time":55,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","iam","security"],"created_at":"2026-01-22T14:54:39.017Z","updated_at":"2026-02-12T20:01:43.803Z","avatar_url":"https://github.com/boogy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IAM Policy Validator\n\n**Stop IAM misconfigurations before they become breaches** — Catch overprivileged permissions, dangerous wildcards, and policy errors before deployment.\n\n[![GitHub Actions](https://img.shields.io/badge/GitHub%20Actions-Ready-blue)](https://github.com/marketplace/actions/iam-policy-validator)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/boogy/iam-policy-validator/badge)](https://scorecard.dev/viewer/?uri=github.com/boogy/iam-policy-validator)\n\n**[📖 Full Documentation](https://boogy.github.io/iam-policy-validator/)**\n\n---\n\n## Why This Tool Exists\n\nSecurity teams need to **enforce organization-specific IAM requirements** and **catch dangerous patterns** before policies reach production. Manual review doesn't scale, and AWS's built-in validation in IAM console only checks more syntax and less security.\n\n**Real problems this detects:**\n\n1. **Privilege escalation chains** - Scattered actions that together grant admin access\n2. **Broken automation** - Syntactically valid but functionally wrong policies (`s3:GetObject` on bucket ARN)\n3. **Missing security controls** - No IAM conditions for sensitive AWS API actions\n4. **Overly permissive access** - Wildcard actions and resources that violate least privilege\n5. **Trust policy vulnerabilities** - Incorrect principals, missing OIDC audience, SAML misconfiguration\n6. **Typos and invalid syntax** - Invalid actions (`s3:GetObjekt`), condition keys, or ARN formats before deployment\n7. **Your own detection** - Set custom configuration file for custom detections\n\n---\n\n## Quick Start\n\n```bash\npip install iam-policy-validator\n\n# Try it with the example policies (from repository root)\niam-validator validate --path examples/quick-start/ --format enhanced\n```\n\n**Example output:**\n\n\u003cdetails\u003e\n\u003csummary\u003eSee the example policies used (examples/quick-start/)\u003c/summary\u003e\n\n**user-policy.json** - Contains typo and missing condition:\n\n```json\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": \"s3:GetObjekt\",\n      \"Resource\": \"arn:aws:s3:::my-bucket/*\"\n    },\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": \"iam:PassRole\",\n      \"Resource\": \"arn:aws:iam::123456789012:role/lambda-role\"\n    }\n  ]\n}\n```\n\n**s3-policy.json** - Sensitive action without conditions:\n\n```json\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": \"s3:GetObject\",\n      \"Resource\": \"arn:aws:s3:::my-bucket/*\"\n    }\n  ]\n}\n```\n\n**lambda-policy.json** - Valid policy:\n\n```json\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": \"lambda:InvokeFunction\",\n      \"Resource\": \"arn:aws:lambda:us-east-1:123456789012:function:my-function\"\n    }\n  ]\n}\n```\n\n\u003c/details\u003e\n\n```\n╭──────────────────────────────────────────────────────────────────────────────────────────────────╮\n│                                                                                                  │\n│                              IAM Policy Validation Report (v1.14.1)                              │\n│                                                                                                  │\n╰──────────────────────────────────────────────────────────────────────────────────────────────────╯\n───────────────────────────────────────── Detailed Results ─────────────────────────────────────────\n❌ [1/3] examples/quick-start/user-policy.json • INVALID (IAM errors + security issues)\n     2 issue(s) found\n\nIssues (2)\n├── 🔴 High\n│   └── [Statement 2 @L10] missing_required_condition\n│       └── Required: Action(s) ``iam:PassRole`` require condition `iam:PassedToService`\n│           ├── Action: iam:PassRole • Condition: iam:PassedToService\n│           └── 💡 Restrict which AWS services can assume the passed role to prevent privilege escalation\n│\n│               Note: Found 1 statement(s) with these actions in the policy.\n│               Example:\n│               \"Condition\": {\n│                 \"StringEquals\": {\n│                   \"iam:PassedToService\": [\n│                     \"lambda.amazonaws.com\",\n│                     \"ecs-tasks.amazonaws.com\",\n│                     \"ec2.amazonaws.com\",\n│                     \"glue.amazonaws.com\"\n│                   ]\n│                 }\n│               }\n└── 🔴 Error\n    └── [Statement 1 @L5] invalid_action\n        └── Action `GetObjekt` not found in service `s3`.\n            └── Action: s3:GetObjekt\n\n❌ [2/3] examples/quick-start/s3-policy.json • FAILED (critical security issues)\n     1 issue(s) found\n\nIssues (1)\n└── 🔴 High\n    └── [Statement 1 @L5] missing_required_condition_any_of\n        └── Actions `s3:GetObject` require at least ONE of these conditions: `aws:ResourceOrgID` OR `aws:ResourceOrgPaths` OR `aws:SourceIp` OR\n            `aws:SourceVpc` OR `aws:SourceVpce` OR `aws:ResourceAccount`\n            ├── Action: s3:GetObject\n            └── 💡 Add at least ONE of these conditions:\n                - **Option 1**: `aws:ResourceOrgID` - Restrict S3 operations to resources within your AWS Organization (value:\n                `${aws:PrincipalOrgID}`)\n                - **Option 2**: `aws:ResourceOrgPaths` - Restrict S3 operations to resources within your AWS Organization path (value:\n                `${aws:PrincipalOrgPaths}`)\n                - **Option 3**: `aws:SourceIp` - Restrict S3 operations by source IP address and same account\n                - **Option 4**: `aws:SourceVpc` - Restrict S3 operations by source VPC and same account\n                - **Option 5**: `aws:SourceVpce` - Restrict S3 operations by VPC endpoint and same account\n                - **Option 6**: `aws:ResourceAccount` - Restrict S3 operations to resources within the same AWS account (value:\n                `${aws:PrincipalAccount}`)\n\n                Note: Found 1 statement(s) with these actions in the policy.\n\n✅ [3/3] examples/quick-start/lambda-policy.json • VALID\n     No issues detected\n\n╭──────────────────────────────────────────────────────────────────────────────────────────────────╮\n│                                                                                                  │\n│  ❌ VALIDATION FAILED                                                                            │\n│  2 of 3 policies have critical issues that must be resolved.                                     │\n│                                                                                                  │\n╰──────────────────────────────────────────────────────────────────────────────────────────────────╯\n```\n\n### In GitHub PRs\n\n```yaml\n# .github/workflows/iam-validator.yml\n- uses: boogy/iam-policy-validator@v1\n  with:\n    path: policies/\n    github-review: true\n```\n\n**Result:** Line-specific comments on policy files showing what's wrong and how to fix it.\n\n---\n\n## What Makes This Different\n\n### 🎯 **1. Enforce Your Organization's Security Rules**\n\nDefine security requirements as code—the validator becomes your organization's policy gatekeeper:\n\n```yaml\n# .iam-validator.yaml - Your security requirements as code\naction_condition_enforcement:\n  enabled: true\n  action_condition_requirements:\n    # Require service-specific PassRole\n    - actions: [\"iam:PassRole\"]\n      required_conditions:\n        - condition_key: \"iam:PassedToService\"\n          description: \"Restrict which services can use passed roles\"\n\n    # Enforce IP restrictions for privileged actions (automation from CI/CD)\n    - actions:\n        [\"iam:AttachUserPolicy\", \"iam:PutUserPolicy\", \"iam:CreateAccessKey\"]\n      required_conditions:\n        - condition_key: \"aws:SourceIp\"\n          expected_value: [\"10.0.0.0/8\", \"172.16.0.0/12\"]\n          description: \"Only allow from corporate network or CI/CD\"\n\n    # Require encryption for S3 uploads\n    - actions: [\"s3:PutObject\"]\n      required_conditions:\n        - condition_key: \"s3:x-amz-server-side-encryption\"\n          operator: \"StringEquals\"\n          expected_value: \"AES256\"\n\n    # Enforce tagging requirements\n    - actions: [\"ec2:RunInstances\"]\n      required_conditions:\n        all_of:\n          - condition_key: \"aws:RequestTag/CostCenter\"\n          - condition_key: \"aws:RequestTag/Environment\"\n          - condition_key: \"aws:RequestTag/Owner\"\n```\n\n**Real-world use cases:**\n\n- 🏢 **Corporate network only**: Require `aws:SourceIp` for admin actions (automation from CI/CD IPs)\n- 🏷️ **Cost tracking**: Enforce resource tagging before creation\n- 🔐 **Encryption mandates**: Require encryption conditions on data operations\n- ⏰ **Time-based access**: Require `aws:CurrentTime` conditions for temporary access\n- 🔒 **Service restrictions**: Limit `iam:PassRole` to specific AWS services\n- 🌐 **VPC restrictions**: Require `aws:SourceVpc` for sensitive operations\n\n**Why this matters:** Other tools perform AWS-standard security checks but lack the flexibility to codify your organization's specific security requirements (IP restrictions, tagging mandates, encryption requirements, etc.).\n\n---\n\n### 🔍 **2. Detect Cross-Statement Privilege Escalation**\n\nPrivilege escalation often occurs when multiple actions are scattered across different statements. This validator uses `all_of` logic to detect when ALL actions in a dangerous combination exist somewhere in the policy:\n\n```json\n{\n  \"Statement\": [\n    {\n      \"Sid\": \"AllowUserManagement\",\n      \"Action\": \"iam:CreateUser\",\n      \"Resource\": \"*\"\n    },\n    { \"Sid\": \"AllowS3Read\", \"Action\": \"s3:GetObject\", \"Resource\": \"*\" },\n    {\n      \"Sid\": \"AllowPolicyAttachment\",\n      \"Action\": \"iam:AttachUserPolicy\",\n      \"Resource\": \"*\"\n    }\n  ]\n}\n```\n\n**🚨 Detected:** Statements 1 and 3 enable privilege escalation:\n\n1. Create new IAM user\n2. Attach `AdministratorAccess` policy to that user\n3. Escalate to full account access\n\n**Built-in escalation patterns** (enabled by default):\n\n- User privilege escalation (`iam:CreateUser` + `iam:AttachUserPolicy`)\n- Role privilege escalation (`iam:CreateRole` + `iam:AttachRolePolicy`)\n- Lambda function backdoor (`lambda:CreateFunction` + `lambda:InvokeFunction`)\n- Lambda code injection (`lambda:UpdateFunctionCode` + `lambda:InvokeFunction`)\n- Policy version manipulation (`iam:CreatePolicyVersion` + `iam:SetDefaultPolicyVersion`)\n- EC2 instance privilege escalation (`ec2:RunInstances` + `iam:PassRole`)\n\nAdditionally detects **[hundreds of sensitive actions](iam_validator/core/config/sensitive_actions.py)** across 4 categories (credential exposure, data access, privilege escalation, resource exposure) that should have IAM conditions.\nList of actions copied from [primeharbor/sensitive_iam_actions](https://github.com/primeharbor/sensitive_iam_actions).\n\n**Extend with custom patterns:**\n\n```yaml\nsensitive_action:\n  sensitive_actions:\n    # Add your own cross-statement patterns\n    - all_of: [\"cloudformation:CreateStack\", \"iam:PassRole\"]\n      severity: critical\n      message: \"CloudFormation + PassRole enables infrastructure privilege escalation\"\n```\n\nSee [Security Checks Documentation](docs/user-guide/checks/security-checks.md) for all built-in patterns and custom configuration.\n\n**Comparison:**\n\n- **This tool**: 6 built-in escalation patterns + hundreds of sensitive actions + extensible\n- **IAM Lens**: Runtime permission evaluator (\"what can this principal do?\"), not policy validator\n- **Policy Sentry**: Generates policies, doesn't scan for escalation\n- **IAMSpy**: Enumerates permissions, different use case\n\n---\n\n### ⚙️ **3. Catch Functionally Broken Policies**\n\nValidates that actions and resources are **compatible**—catches policies that pass AWS validation but fail at runtime:\n\n```json\n{\n  \"Effect\": \"Allow\",\n  \"Action\": \"s3:GetObject\",\n  \"Resource\": \"arn:aws:s3:::mybucket\"\n}\n```\n\n**🚨 Detected:** `s3:GetObject` operates on **objects**, not buckets. This policy does nothing.\n**💡 Fix:** `\"Resource\": \"arn:aws:s3:::mybucket/*\"`\n\n**More examples:**\n\n```json\n// BAD: s3:ListBucket with object ARN\n{\"Action\": \"s3:ListBucket\", \"Resource\": \"arn:aws:s3:::bucket/*\"}\n// ✅ FIX: s3:ListBucket needs bucket ARN\n{\"Action\": \"s3:ListBucket\", \"Resource\": \"arn:aws:s3:::bucket\"}\n\n// BAD: iam:ListUsers with user-specific ARN\n{\"Action\": \"iam:ListUsers\", \"Resource\": \"arn:aws:iam::*:user/bob\"}\n// ✅ FIX: iam:ListUsers is global, needs wildcard\n{\"Action\": \"iam:ListUsers\", \"Resource\": \"*\"}\n\n// BAD: ec2:DescribeInstances with specific instance\n{\"Action\": \"ec2:DescribeInstances\", \"Resource\": \"arn:aws:ec2:*:*:instance/i-1234\"}\n// ✅ FIX: Describe actions don't support resource-level permissions\n{\"Action\": \"ec2:DescribeInstances\", \"Resource\": \"*\"}\n```\n\n**Why this matters:** These policies look correct but fail silently in production. AWS validates syntax, not action-resource compatibility.\n\n---\n\n### 🔧 **4. Uses Official AWS Service Definitions**\n\nFetches **real AWS service data** from AWS's official IAM service definition API (JSON endpoint)—always accurate and up-to-date:\n\n- **Actions**: Validates against 250+ AWS services with complete action lists\n- **Condition keys**: Checks valid keys for each action\n- **Resource types**: Validates ARN formats and resource compatibility\n- **Auto-updating**: Fetches latest definitions on-demand or use cached versions\n\n```bash\n# Query AWS service definitions (like Policy Sentry)\niam-validator query action --service s3 --access-level write\niam-validator query condition --service s3 --name s3:prefix\niam-validator query arn --service lambda --name function\n\n# Download for offline use\niam-validator sync-services --output-dir ./aws-services\niam-validator validate --path policies/ --aws-services-dir ./aws-services\n```\n\n**Comparison:**\n\n- **This tool**: Official AWS API, auto-updates, offline mode\n- **Policy Sentry**: Official AWS API, excellent query capabilities\n- **IAM Lens**: Uses actual AWS account data (runtime analysis)\n- **IAMSpy**: Static database, may lag behind AWS updates\n\n---\n\n### 🎨 **5. Built for CI/CD and Developer Workflows**\n\n**GitHub PR Integration:**\n\n- **Diff-aware filtering**: Only comments on lines you actually changed\n- **Line-specific feedback**: Inline comments on policy files with exact line numbers\n- **Smart cleanup**: Updates existing comments, removes stale ones\n- **Severity-based reviews**: Auto-approve or request changes based on findings\n\n**Multiple output formats:**\n\n- Console (colored terminal)\n- JSON (automation/API)\n- SARIF (GitHub Code Scanning)\n- Markdown (documentation)\n- HTML (interactive reports)\n- CSV (spreadsheet analysis)\n\n**Example GitHub Action:**\n\n```yaml\n- uses: boogy/iam-policy-validator@v1\n  with:\n    path: policies/\n    github-review: true # Inline PR comments\n    github-summary: true # Actions summary tab\n    fail-on-severity: high # Block merge on high/critical\n```\n\n---\n\n## What Does It Check?\n\n### ✅ **AWS Correctness (12 checks)**\n\nValidates against official AWS IAM requirements:\n\n| Check                        | What It Does                                                                        |\n| ---------------------------- | ----------------------------------------------------------------------------------- |\n| **Policy Structure**         | Required fields (Version, Statement, Effect), valid JSON/YAML                       |\n| **Action Validation**        | Actions exist in AWS services (detects typos: `s3:GetObjekt`)                       |\n| **Condition Keys**           | Valid condition keys for actions (e.g., `s3:prefix` valid for `s3:ListBucket`)      |\n| **Condition Types**          | Values match expected types (IP for `aws:SourceIp`, Bool for `aws:SecureTransport`) |\n| **Resource ARNs**            | Correct ARN format and patterns                                                     |\n| **Principal Validation**     | Valid principals in resource/trust policies                                         |\n| **Policy Size**              | AWS limits (6144 bytes managed, 10240 inline, 20480 resource)                       |\n| **SID Uniqueness**           | Statement IDs unique within policy                                                  |\n| **Set Operators**            | Correct `ForAllValues`/`ForAnyValue` usage with arrays                              |\n| **MFA Conditions**           | Detect insecure MFA patterns (`!= false` instead of `== true`)                      |\n| **Policy Type**              | RCP/SCP-specific requirements                                                       |\n| **Action-Resource Matching** | Actions compatible with resources (catches functional errors)                       |\n\n### 🔒 **Security Best Practices (6 checks)**\n\nIdentifies overly permissive configurations:\n\n| Check                     | What It Catches                                          |\n| ------------------------- | -------------------------------------------------------- |\n| **Wildcard Action**       | `Action: \"*\"` grants all AWS permissions                 |\n| **Wildcard Resource**     | `Resource: \"*\"` applies to all resources                 |\n| **Full Wildcard**         | Both `Action: \"*\"` AND `Resource: \"*\"` (admin access)    |\n| **Service Wildcards**     | `s3:*`, `iam:*`, `ec2:*` (overly broad)                  |\n| **Sensitive Actions**     | 490+ privilege escalation patterns and dangerous actions |\n| **Condition Enforcement** | Organization-specific condition requirements             |\n\n**Note on Sensitive Actions:** This check has two modes:\n\n- `all_of`: **Policy-wide** detection (e.g., `iam:CreateUser` in statement 0 + `iam:AttachUserPolicy` in statement 2)\n- `any_of`: **Per-statement** detection (e.g., any statement with `iam:PutUserPolicy`)\n\n### 🔐 **Trust Policy Validation (opt-in)**\n\nSpecialized checks for role assumption:\n\n- Correct principal types (`AssumeRoleWithSAML` needs `Federated` principal)\n- SAML/OIDC provider ARN validation\n- Required conditions (`SAML:aud`, OIDC audience)\n- Federated identity best practices\n\n---\n\n## Installation \u0026 Usage\n\n### CLI\n\n```bash\npip install iam-policy-validator\n\n# Validate (no AWS credentials needed)\niam-validator validate --path policies/\n\n# With AWS Access Analyzer (requires AWS credentials)\niam-validator analyze --path policies/ --run-all-checks\n\n# Different policy types\niam-validator validate --path trust-policies/ --policy-type TRUST_POLICY\n\n# Output formats\niam-validator validate --path policies/ --format json --output report.json\niam-validator validate --path policies/ --format sarif --output code-scanning.sarif\n```\n\n### Python Library\n\n```python\nfrom iam_validator.core.policy_loader import PolicyLoader\nfrom iam_validator.core.policy_checks import validate_policies\n\nloader = PolicyLoader()\npolicies = loader.load_from_path(\"./policies\")\nresults = await validate_policies(policies)\n\nfor result in results:\n    if not result.is_valid:\n        for issue in result.issues:\n            print(f\"{issue.severity}: {issue.message} at line {issue.line_number}\")\n```\n\n### Configuration\n\nAll checks are customizable via `.iam-validator.yaml`:\n\n```yaml\nsettings:\n  enable_builtin_checks: true\n  fail_on_severity: high\n\n# Detect cross-statement privilege escalation\nsensitive_action:\n  enabled: true\n  sensitive_actions:\n    # Policy-wide: ALL actions must exist somewhere in policy\n    - all_of:\n        - \"iam:CreateUser\"\n        - \"iam:AttachUserPolicy\"\n    - all_of:\n        - \"lambda:CreateFunction\"\n        - \"iam:PassRole\"\n\n    # Per-statement: ANY action in a single statement\n    - any_of:\n        - \"iam:PutUserPolicy\"\n        - \"iam:PutGroupPolicy\"\n\n# Enforce your organization's conditions\naction_condition_enforcement:\n  enabled: true\n  action_condition_requirements:\n    - actions: [\"iam:PassRole\"]\n      required_conditions:\n        - condition_key: \"iam:PassedToService\"\n\n    # IP restrictions for admin actions (automation from CI/CD IPs)\n    - actions: [\"iam:CreateUser\", \"iam:DeleteUser\", \"iam:CreateAccessKey\"]\n      required_conditions:\n        - condition_key: \"aws:SourceIp\"\n          expected_value: [\"10.0.0.0/8\", \"52.94.76.0/24\"] # Corporate + GitHub Actions\n\n# Ignore patterns\nignore_patterns:\n  - filepath: \"terraform/modules/admin/*.json\"\n    reason: \"Admin policies reviewed separately\"\n```\n\n#### Understanding Configuration: Two Ways to Control Action Validation\n\nThe validator provides two complementary approaches for action-specific validation:\n\n**Option 1: Enforce Required Conditions** (`action_condition_enforcement`)\n\nUse this when you want to **mandate specific conditions** for certain actions:\n\n```yaml\naction_condition_enforcement:\n  enabled: true\n  requirements:\n    # Enforce that iam:PassRole must specify which service can use the role\n    - actions: [\"iam:PassRole\"]\n      required_conditions:\n        - condition_key: \"iam:PassedToService\"\n          description: \"Prevent privilege escalation by restricting service access\"\n\n    # Enforce MFA for credential creation\n    - actions: [\"iam:CreateAccessKey\"]\n      required_conditions:\n        - condition_key: \"aws:MultiFactorAuthPresent\"\n          expected_value: true\n```\n\n**What this does:**\n\n- ✅ **Validates** that required conditions exist in the policy\n- ✅ **Fails validation** when conditions are missing\n- ✅ **Prevents duplicate warnings** (automatically filters from `sensitive_action` check)\n- ✅ **Specific guidance** per action about which conditions are required\n\n**Option 2: Suggest Best Practices** (`sensitive_action`)\n\nUse this when you want to **flag actions without conditions** and provide ABAC guidance:\n\n```yaml\nsensitive_action:\n  enabled: true\n  # Uses built-in list of 490+ sensitive actions across 4 categories:\n  # - credential_exposure: Actions that expose credentials/secrets\n  # - data_access: Actions that retrieve sensitive data\n  # - priv_esc: Actions that enable privilege escalation\n  # - resource_exposure: Actions that modify resource policies\n\n  # Optionally add your own sensitive actions\n  sensitive_actions:\n    - \"custom:SensitiveAction\"\n```\n\n**What this does:**\n\n- ⚠️ **Suggests** that actions should have conditions (doesn't enforce specific ones)\n- ⚠️ **Generic ABAC guidance** (tag matching, MFA, IP restrictions)\n- ✅ **Automatic filtering** (skips actions already validated by `action_condition_enforcement`)\n\n**Decision Matrix:**\n\n| Your Goal                                           | Use This                       | Config Example                                   |\n| --------------------------------------------------- | ------------------------------ | ------------------------------------------------ |\n| **Must enforce** specific conditions for compliance | `action_condition_enforcement` | Require `iam:PassedToService` for `iam:PassRole` |\n| **Want to suggest** general security improvements   | `sensitive_action`             | Flag `s3:GetObject` without any conditions       |\n| **Organization-specific** rules (IP, tags, MFA)     | `action_condition_enforcement` | Require corporate IPs for admin actions          |\n| **General best practices** (ABAC)                   | `sensitive_action`             | Suggest tag-based access control                 |\n\n**How They Work Together:**\n\n1. `action_condition_enforcement` validates **specific required conditions** (strict enforcement)\n2. `sensitive_action` suggests **ABAC best practices** for actions without conditions (general guidance)\n3. **Automatic deduplication** prevents showing both warnings for the same action\n4. Actions in `action_condition_enforcement` are automatically filtered from `sensitive_action`\n\n**Example - Complete Configuration:**\n\n```yaml\n# Strict enforcement for critical actions\naction_condition_enforcement:\n  enabled: true\n  requirements:\n    - actions: [\"iam:PassRole\"]\n      required_conditions:\n        - condition_key: \"iam:PassedToService\"\n\n    - actions: [\"s3:GetObject\", \"s3:GetObjectVersion\"]\n      required_conditions:\n        any_of:\n          - condition_key: \"aws:ResourceOrgID\"\n          - condition_key: \"aws:SourceVpc\"\n\n# General suggestions for other sensitive actions\nsensitive_action:\n  enabled: true\n  # Will NOT warn about iam:PassRole or s3:GetObject (already covered above)\n  # Will warn about other sensitive actions like iam:CreateUser, s3:DeleteObject, etc.\n```\n\nFor more details, see:\n\n- [Configuration Guide](docs/user-guide/configuration.md) - How to configure condition requirements\n- [examples/configs/full-reference-config.yaml](examples/configs/full-reference-config.yaml) - Complete configuration reference\n\n---\n\n## AWS Access Analyzer (Optional)\n\nOptionally enable AWS Access Analyzer to validate policy syntax, then perform security checks on top of that validation:\n\n```bash\n# Check for public access (S3, SNS, SQS, etc.)\niam-validator analyze --path bucket-policy.json \\\n  --policy-type RESOURCE_POLICY \\\n  --check-no-public-access \\\n  --public-access-resource-type \"AWS::S3::Bucket\"\n\n# Prevent specific actions\niam-validator analyze --path policy.json \\\n  --check-access-not-granted \"s3:DeleteBucket iam:DeleteUser\"\n\n# Compare against baseline (detect permission creep)\niam-validator analyze --path new-policy.json \\\n  --check-no-new-access baseline-policy.json\n```\n\n**Note:** Access Analyzer requires AWS credentials. Built-in checks work offline.\n\n---\n\n## Comparison Matrix\n\n| Feature                        | IAM Policy Validator              | IAM Lens                      | IAMSpy                 | Policy Sentry              |\n| ------------------------------ | --------------------------------- | ----------------------------- | ---------------------- | -------------------------- |\n| **Primary Purpose**            | Pre-deployment validation         | Runtime permission analysis   | Permission enumeration | Least-privilege generation |\n| **Use Case**                   | CI/CD policy scanning             | \"What can this principal do?\" | Pentesting/audit       | Policy creation            |\n| **Custom Security Rules**      | ✅ Full support                   | ❌ No                         | ❌ No                  | ❌ No                      |\n| **Cross-Statement Patterns**   | ✅ Privilege escalation detection | N/A (different purpose)       | N/A                    | N/A                        |\n| **Action-Resource Validation** | ✅ Catches incompatible pairs     | N/A                           | ❌ No                  | ✅ Generates correct       |\n| **Organization Conditions**    | ✅ IP, tags, encryption, etc.     | ❌ No                         | ❌ No                  | ❌ No                      |\n| **CI/CD Ready**                | ✅ GitHub Actions native          | ⚠️ Manual setup               | ⚠️ Manual              | ⚠️ Manual                  |\n| **PR Line Comments**           | ✅ Diff-aware                     | ❌ No                         | ❌ No                  | ❌ No                      |\n| **AWS Service Data**           | ✅ Official API (auto-update)     | ✅ Real AWS account data      | ⚠️ Static              | ✅ Official API            |\n| **Offline Mode**               | ✅ Yes                            | ❌ Needs AWS account          | ✅ Yes                 | ❌ Needs internet          |\n| **Query Permissions**          | ✅ Yes                            | ✅ Yes (different approach)   | ⚠️ Enumerate only      | ✅ Excellent               |\n\n**Choose this tool if you:**\n\n- Need **pre-deployment validation** in CI/CD\n- Want to **enforce organization-specific security requirements**\n- Need to catch **privilege escalation patterns**\n- Want to validate **action-resource compatibility**\n- Need **PR integration with line comments**\n\n**Choose IAM Lens if you:**\n\n- Need **runtime permission analysis** (\"can this user do X?\")\n- Want to **simulate real AWS requests**\n- Need to understand **effective permissions across policies**\n\n**Choose Policy Sentry if you:**\n\n- Need to **generate least-privilege policies** from scratch\n- Want to **query AWS permissions** for policy writing\n\n**IAMSpy is for:**\n\n- **Enumerating existing permissions** in AWS accounts\n- **Security assessment** (pentesting, not validation)\n\n---\n\n## Documentation\n\n**Guides:**\n\n- [Check Reference](docs/user-guide/checks/) - All checks with examples\n- [Configuration Guide](docs/user-guide/configuration.md) - Customize checks and behavior\n- [GitHub Actions Guide](docs/integrations/github-actions.md) - CI/CD integration\n- [Python Library Guide](docs/developer-guide/sdk/) - Use as Python package\n- [Trust Policy Examples](examples/trust-policies/) - Trust policy validation examples\n- [Changelog](CHANGELOG.md) - Version history and migration guides\n\n**Examples:**\n\n- [Configuration Examples](examples/configs/) - Config file templates\n- [Workflow Examples](examples/github-actions/) - GitHub Actions workflows\n- [Custom Checks](examples/custom_checks/) - Add your own validation rules\n\n---\n\n## Related Tools \u0026 Resources\n\nOther tools in the IAM security ecosystem that serve different purposes:\n\n### Policy Analysis \u0026 Generation\n\n- **[Parliament](https://github.com/duo-labs/parliament)** - IAM policy linter that checks for syntax errors and basic security issues. This validator uses Parliament's ARN pattern matching logic.\n- **[Policy Sentry](https://github.com/salesforce/policy_sentry)** - Generates least-privilege IAM policies from AWS service definitions. Great for policy creation; this validator focuses on policy validation.\n- **[Cloudsplaining](https://github.com/salesforce/cloudsplaining)** - Scans existing AWS account policies for security issues. Runtime analysis vs. pre-deployment validation.\n\n### Permission Analysis\n\n- **[IAM Dataset](https://github.com/glassechidna/iam-dataset)** - Curated dataset of AWS IAM actions, resources, and conditions scraped from AWS documentation. Useful reference for policy authors.\n- **[IAMSpy](https://github.com/WithSecureLabs/IAMSpy)** - Enumerates IAM permissions for roles/users in an AWS account. Pentesting/audit tool, not a validator.\n- **[IAM Lens](https://github.com/welldone-cloud/aws-iam-lens)** - Runtime permission evaluator that answers \"what can this principal do?\". Complements pre-deployment validation.\n\n### AWS Official Tools\n\n- **[AWS Access Analyzer](https://aws.amazon.com/iam/access-analyzer/)** - AWS's built-in policy validation and external access detection. This validator can optionally integrate with it.\n- **[AWS IAM Policy Simulator](https://policysim.aws.amazon.com/)** - Test policies against AWS resources to see if actions are allowed.\n\n**When to use this validator vs. others:**\n\n- Use this for **pre-deployment CI/CD validation** with custom security rules\n- Use Policy Sentry for **generating** least-privilege policies\n- Use Cloudsplaining/IAMSpy for **auditing existing** AWS accounts\n- Use IAM Lens for **runtime permission analysis**\n- Use Parliament if you only need basic syntax/ARN validation\n\n---\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n```bash\ngit clone https://github.com/boogy/iam-policy-validator.git\ncd iam-policy-validator\nuv sync --extra dev\nuv run pytest\n```\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE).\n\n- **Third-party code:** ARN pattern matching derived from [Parliament](https://github.com/duo-labs/parliament) (BSD 3-Clause).\n\n---\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/boogy/iam-policy-validator/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboogy%2Fiam-policy-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboogy%2Fiam-policy-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboogy%2Fiam-policy-validator/lists"}