iam-policy-validator 1.5.0__tar.gz → 1.7.0__tar.gz

{iam_policy_validator-1.5.0 → iam_policy_validator-1.7.0}/.github/workflows/ci.yml

@@ -7,6 +7,9 @@ on:
     branches: [main, develop]
   workflow_dispatch:
 
+env:
+  DEFAULT_PYTHON_VERSION: "3.13"
+
 jobs:
   lint:
     name: Lint with Ruff
@@ -18,7 +21,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6
         with:
-          python-version: "3.12"
+          python-version: "${{ env.DEFAULT_PYTHON_VERSION }}"
 
       - name: Install uv
         uses: astral-sh/setup-uv@5dbc9fba7434435c4cd0268139340fa3696d98f3 # v7
@@ -40,7 +43,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
     steps:
       - name: Checkout code
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
@@ -72,7 +75,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6
         with:
-          python-version: "3.12"
+          python-version: "${{ env.DEFAULT_PYTHON_VERSION }}"
 
       - name: Install uv
         uses: astral-sh/setup-uv@5dbc9fba7434435c4cd0268139340fa3696d98f3 # v7
@@ -96,7 +99,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6
         with:
-          python-version: "3.12"
+          python-version: "${{ env.DEFAULT_PYTHON_VERSION }}"
 
       - name: Install uv
         uses: astral-sh/setup-uv@5dbc9fba7434435c4cd0268139340fa3696d98f3 # v7
@@ -106,17 +109,12 @@ jobs:
       - name: Install dependencies
         run: uv sync
 
-      - name: Run validator on example policies
-        run: |
-          if [ -d "examples" ]; then
-            uv run iam-validator --path examples/ --format console --verbose || true
-          else
-            echo "No examples directory found, skipping integration test"
-          fi
-
       - name: Test CLI help
         run: uv run iam-validator --help
 
+      - name: Test CLI version
+        run: uv run iam-validator --version
+
   all-checks-pass:
     name: All Checks Pass
     runs-on: ubuntu-latest

{iam_policy_validator-1.5.0 → iam_policy_validator-1.7.0}/.github/workflows/release.yml

@@ -9,6 +9,9 @@ permissions:
   contents: write
   id-token: write
 
+env:
+  PYTHON_VERSION: "3.13"
+
 jobs:
   build-and-release:
     name: Build and Create Release
@@ -24,7 +27,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6
         with:
-          python-version: "3.12"
+          python-version: ${{ env.PYTHON_VERSION }}
 
       - name: Install uv
         uses: astral-sh/setup-uv@5dbc9fba7434435c4cd0268139340fa3696d98f3 # v7
@@ -32,7 +35,7 @@ jobs:
           enable-cache: true
 
       - name: Install dependencies
-        run: uv sync
+        run: uv sync --frozen
 
       - name: Build package
         run: uv build

{iam_policy_validator-1.5.0 → iam_policy_validator-1.7.0}/CONTRIBUTING.md

@@ -23,7 +23,7 @@ This project follows a code of conduct to ensure a welcoming environment for all
 
 ### Prerequisites
 
-- Python 3.11 or higher
+- Python 3.12 or higher
 - [uv](https://github.com/astral-sh/uv) package manager
 - Git
 - AWS account (optional, for testing AWS integrations)
@@ -33,8 +33,8 @@ This project follows a code of conduct to ensure a welcoming environment for all
 1. **Fork and Clone the Repository**
 
    ```bash
-   git clone https://github.com/YOUR-USERNAME/iam-policy-auditor.git
-   cd iam-policy-auditor
+   git clone https://github.com/boogy/iam-policy-validator.git
+   cd iam-policy-validator
    ```
 
 2. **Install uv (if not already installed)**
@@ -103,36 +103,46 @@ uv run mypy iam_validator
 ```
 iam-policy-auditor/
 ├── iam_validator/              # Main package
-│   ├── cli.py                  # CLI entry point
-│   ├── checks/                 # Built-in validation checks
+│   ├── checks/                 # Built-in validation checks (18 checks)
 │   ├── commands/               # CLI command implementations
 │   ├── core/                   # Core validation engine
+│   │   ├── cli.py              # CLI entry point
 │   │   ├── formatters/         # Output formatters
-│   │   └── data/               # Static data files
-│   └── integrations/           # External integrations
+│   │   ├── config/             # Configuration system (modular Python configs)
+│   │   ├── models.py           # Data models
+│   │   ├── policy_checks.py   # Policy validation orchestrator
+│   │   └── aws_fetcher.py     # AWS service definition fetcher
+│   ├── integrations/           # External integrations (Access Analyzer, PR comments)
+│   ├── sdk/                    # Python SDK for library usage
+│   └── utils/                  # Utility functions
 │
 ├── tests/                      # Test suite
-│   ├── test_policy_checks.py   # Core validation tests
-│   ├── test_aws_fetcher.py     # AWS integration tests
-│   ├── test_cache_and_optimizations.py  # Cache/optimization tests
-│   └── test_benchmarks.py      # Performance benchmarks
+│   ├── test_*.py               # Test files for each check/module
+│   └── conftest.py             # Pytest configuration and fixtures
 │
 ├── docs/                       # Documentation
-│   ├── getting-started/        # Quick start guides
-│   ├── guides/                 # User guides
-│   ├── reference/              # Reference documentation
-│   ├── advanced/               # Advanced topics
-│   └── development/            # Development docs
+│   ├── check-reference.md      # Complete reference for all 18 checks
+│   ├── CHECKS.md               # Deprecated - migration guide
+│   ├── SDK.md                  # Python SDK documentation
+│   ├── configuration.md        # Configuration guide
+│   ├── condition-requirements.md  # Action condition enforcement
+│   ├── privilege-escalation.md    # Privilege escalation detection
+│   ├── custom-checks.md        # Custom check development guide
+│   └── development/            # Development documentation
 │
-├── examples/                   # Example policies and configs
-│   ├── configs/                # Configuration examples
+├── examples/                   # Examples and sample files
+│   ├── configs/                # 9+ configuration examples
 │   ├── custom_checks/          # Custom check examples
-│   └── github-actions/         # GitHub Actions examples
+│   ├── library-usage/          # Python SDK examples
+│   ├── github-actions/         # GitHub Actions workflow examples
+│   └── iam-test-policies/      # Sample IAM policies for testing
 │
+├── scripts/                    # Development and utility scripts
+├── aws_services/               # Cached AWS service definitions
 ├── .github/workflows/          # CI/CD workflows
-├── pyproject.toml              # Project metadata and dependencies
+├── pyproject.toml              # Project metadata and dependencies (uv)
 ├── Makefile                    # Development commands
-└── default-config.yaml         # Example configuration file
+└── CONTRIBUTING.md             # This file
 ```
 
 ## Development Workflow
@@ -293,11 +303,17 @@ This runs linting, type checking, and tests.
 
 ### Documentation Structure
 
-- **Getting Started**: Quick start guides for new users
-- **Guides**: In-depth tutorials and how-tos
-- **Reference**: API and configuration reference
-- **Advanced**: Advanced topics and patterns
-- **Development**: Contributor documentation
+- **README.md**: Project overview, quick start, and feature highlights
+- **DOCS.md**: Complete usage guide, CLI reference, and configuration
+- **docs/check-reference.md**: Complete validation checks reference with pass/fail examples
+- **docs/CHECKS.md**: (Deprecated) Migration guide to new check documentation
+- **docs/SDK.md**: Python library documentation and API reference
+- **docs/**: Additional guides and advanced topics
+  - **configuration.md**: Configuration guide
+  - **condition-requirements.md**: Action condition enforcement
+  - **privilege-escalation.md**: Privilege escalation detection
+  - **custom-checks.md**: Custom check development
+  - **development/**: Contributor documentation
 
 ### Building Documentation
 
@@ -371,6 +387,7 @@ Releases are managed by project maintainers. The process includes:
 1. **Version Bump**
    ```bash
    # Update version in pyproject.toml
+   # Update version in __version__.py
    # Update CHANGELOG.md
    ```
 
@@ -474,9 +491,16 @@ See the comprehensive [Custom Checks Guide](docs/custom-checks.md) for detailed
 
 ## Getting Help
 
-- **Documentation**: Check [docs/](docs/)
-- **Issues**: Search [existing issues](https://github.com/Boogy/iam-policy-auditor/issues)
-- **Discussions**: Start a [discussion](https://github.com/Boogy/iam-policy-auditor/discussions)
+### Documentation Resources
+- **[Complete Usage Guide](../DOCS.md)** - CLI, GitHub Actions, configuration
+- **[Validation Checks](docs/check-reference.md)** - All 18 checks with examples
+- **[Python SDK](docs/SDK.md)** - Library usage and API reference
+- **[Additional Docs](docs/)** - Guides and advanced topics
+
+### Support Channels
+- **Issues**: Search [existing issues](https://github.com/boogy/iam-policy-validator/issues)
+- **Discussions**: Start a [discussion](https://github.com/boogy/iam-policy-validator/discussions)
+- **Examples**: Check [examples/](examples/) directory for code samples
 
 ## Recognition
 

{iam_policy_validator-1.5.0 → iam_policy_validator-1.7.0}/DOCS.md

@@ -1,8 +1,8 @@
-# IAM Policy Auditor - Complete Documentation
+# IAM Policy Validator - Complete Documentation
 
-> High-performance AWS IAM policy validation using AWS Access Analyzer and custom checks
+> High-performance AWS IAM policy validation using AWS Access Analyzer and 18 built-in security checks
 
-**Quick Links:** [Installation](#installation) • [Quick Start](#quick-start) • [GitHub Actions](#github-actions) • [Custom Checks](#custom-policy-checks) • [CLI Reference](#cli-reference) • [Configuration](#configuration)
+**Quick Links:** [Installation](#installation) • [Quick Start](#quick-start) • [GitHub Actions](#github-actions) • [Validation Checks](#validation-checks) • [CLI Reference](#cli-reference) • [Configuration](#configuration)
 
 ---
 
@@ -11,10 +11,10 @@
 1. [Installation](#installation)
 2. [Quick Start](#quick-start)
 3. [GitHub Actions Integration](#github-actions)
-4. [CLI Usage](#cli-reference)
-5. [Custom Policy Checks](#custom-policy-checks)
-6. [Configuration](#configuration)
-7. [Built-in Checks](#built-in-validation-checks)
+4. [Validation Checks](#validation-checks)
+5. [CLI Usage](#cli-reference)
+6. [Custom Policy Checks (AWS Access Analyzer)](#custom-policy-checks)
+7. [Configuration](#configuration)
 8. [Custom Validation Rules](#creating-custom-checks)
 9. [Performance & Optimization](#performance-optimization)
 10. [Cache Management](#cache-command)
@@ -403,6 +403,62 @@ See `examples/github-actions/` for more workflow examples.
 
 ---
 
+## Validation Checks
+
+IAM Policy Validator performs **18 built-in validation checks** to ensure your IAM policies are correct, secure, and follow best practices.
+
+### Check Categories
+
+1. **AWS Validation Checks (6 checks)** - Ensure policies conform to AWS IAM requirements
+   - Action Validation
+   - Condition Key Validation
+   - Condition Type Mismatch
+   - MFA Condition Anti-Patterns
+   - Resource ARN Validation
+   - SID Uniqueness
+
+2. **Security Best Practice Checks (7 checks)** - Identify security anti-patterns
+   - Wildcard Action
+   - Wildcard Resource
+   - Full Wildcard (CRITICAL)
+   - Service Wildcard
+   - Sensitive Action (490 actions across 4 categories)
+   - Principal Validation (resource policies)
+   - Policy Size
+
+3. **Advanced Enforcement Checks (5 checks)** - Enforce org-specific requirements
+   - Action Condition Enforcement (MFA, IP, tags, etc.)
+   - Action-Resource Matching
+   - Action-Resource Constraint
+   - Set Operator Validation
+   - Policy Type Validation
+
+### Quick Examples
+
+```bash
+# Run all built-in checks
+iam-validator validate --path ./policies/
+
+# Run only specific severity levels
+iam-validator validate --path ./policies/ --fail-on-warnings
+
+# Use custom configuration
+iam-validator validate --path ./policies/ --config my-config.yaml
+```
+
+### Detailed Documentation
+
+**📚 For complete documentation of all 18 checks with detailed pass/fail examples, see [Check Reference Guide](docs/check-reference.md)**
+
+The check-reference.md file provides:
+- Detailed explanation of what each check validates
+- Pass examples (valid policies)
+- Fail examples (invalid policies with error messages)
+- Configuration options for each check
+- How to use ignore patterns to filter findings
+
+---
+
 ## Custom Policy Checks
 
 AWS IAM Access Analyzer provides specialized checks beyond basic validation:
@@ -834,7 +890,7 @@ permissions:
 
 ### Configuration File
 
-Create a configuration file (e.g., `my-config.yaml`) based on [default-config.yaml](default-config.yaml):
+Create a configuration file (e.g., `my-config.yaml`) based on [examples/configs/full-reference-config.yaml](examples/configs/full-reference-config.yaml):
 
 ```yaml
 # ============================================================================
@@ -882,10 +938,14 @@ action_validation:
   description: "Validates that actions exist in AWS services"
   # Note: Wildcard security checks are handled by security_best_practices
 
-# Validate condition keys
+# Validate condition keys (validates against action and resource definitions)
 condition_key_validation:
   enabled: true
   severity: error
+  config:
+    # Warn when global condition keys are used with actions that have specific keys
+    # Set to false to disable these warnings
+    warn_on_global_condition_keys: true
 
 # Validate resource ARN format
 resource_validation:
@@ -930,7 +990,7 @@ action_condition_enforcement:
 
 Use with: `iam-validator validate --path policy.json --config my-config.yaml`
 
-See [default-config.yaml](default-config.yaml) for full documentation with all available options.
+See [examples/configs/full-reference-config.yaml](examples/configs/full-reference-config.yaml) for full documentation with all available options.
 
 ### Severity Levels
 
@@ -963,163 +1023,78 @@ See [examples/configs/](examples/configs/) directory for configurations:
 
 ## Built-in Validation Checks
 
-### 1. Action Validation
-
-Verifies IAM actions exist in AWS service definitions. This check focuses **solely on validity** - security concerns like wildcards are handled by [Security Best Practices](#4-security-best-practices).
-
-```json
-{
-  "Effect": "Allow",
-  "Action": "s3:GetObject",  // ✅ Valid action
-  "Resource": "*"
-}
-```
-
-```json
-{
-  "Effect": "Allow",
-  "Action": "s3:InvalidAction",  // ❌ Invalid - action doesn't exist
-  "Resource": "*"
-}
-```
-
-```json
-{
-  "Effect": "Allow",
-  "Action": "s3:List*",  // ✅ Valid - wildcards skipped (checked by security_best_practices)
-  "Resource": "*"
-}
-```
-
-### 2. Condition Key Validation
+IAM Policy Validator includes **18 comprehensive validation checks** across three categories. Each check can be individually configured, enabled/disabled, and customized to match your organization's security requirements.
+
+### Overview
+
+- **AWS Validation Checks (6)** - Ensure policies meet AWS IAM requirements
+- **Security Best Practices (7)** - Identify anti-patterns and security risks
+- **Advanced Enforcement (5)** - Enforce organization-specific security policies
+
+### Quick Reference
+
+| Check | Category | Severity | What It Does |
+|-------|----------|----------|--------------|
+| action_validation | AWS | error | Validates actions exist in AWS services |
+| condition_key_validation | AWS | error | Validates condition keys for actions/resources |
+| condition_type_mismatch | AWS | error | Validates operator/key type matching |
+| mfa_condition_antipattern | AWS | warning | Detects dangerous MFA patterns |
+| resource_validation | AWS | error | Validates ARN format |
+| sid_uniqueness | AWS | error | Ensures unique statement IDs |
+| wildcard_action | Security | medium | Detects `Action: "*"` |
+| wildcard_resource | Security | medium | Detects `Resource: "*"` |
+| full_wildcard | Security | **critical** | Detects both wildcards (admin access) |
+| service_wildcard | Security | high | Detects `service:*` patterns |
+| sensitive_action | Security | medium | 490 sensitive actions across 4 categories |
+| principal_validation | Security | high | Validates resource policy principals |
+| policy_size | AWS | error | Validates against AWS size limits |
+| action_condition_enforcement | Enforcement | high | Requires conditions for actions |
+| action_resource_matching | Enforcement | medium | Validates resource types and account-level actions |
+| set_operator_validation | AWS | error | Validates ForAllValues/ForAnyValue |
+| policy_type_validation | Enforcement | error | Validates policy matches declared type |
 
-Checks condition keys are valid for specified actions:
+### Examples
 
+**Pass Example (Specific permissions):**
 ```json
 {
-  "Effect": "Allow",
-  "Action": "s3:GetObject",
-  "Resource": "*",
-  "Condition": {
-    "StringEquals": {
-      "aws:RequestedRegion": "us-east-1"  // ✅ Valid global condition
+  "Version": "2012-10-17",
+  "Statement": [{
+    "Effect": "Allow",
+    "Action": ["s3:GetObject", "s3:PutObject"],
+    "Resource": "arn:aws:s3:::my-bucket/*",
+    "Condition": {
+      "StringEquals": {"aws:RequestedRegion": "us-east-1"}
     }
-  }
+  }]
 }
 ```
 
-### 3. Resource ARN Validation
-
-Ensures ARNs follow proper AWS format:
-
-```json
-{
-  "Effect": "Allow",
-  "Action": "s3:GetObject",
-  "Resource": "arn:aws:s3:::my-bucket/*"  // ✅ Valid ARN
-}
-```
-
-### 4. Security Best Practices
-
-Identifies security risks:
-
-- **Overly permissive wildcards**: `Action: "*"` with `Resource: "*"`
-- **Sensitive actions without conditions**: Administrative permissions
-- **Missing MFA requirements**: For privileged operations
-
-### 5. SID Uniqueness
-
-Ensures Statement IDs are unique within a policy:
-
+**Fail Example (Administrative access):**
 ```json
 {
-  "Statement": [
-    { "Sid": "AllowRead", "Effect": "Allow", "Action": "s3:GetObject" },
-    { "Sid": "AllowRead", "Effect": "Allow", "Action": "s3:ListBucket" }  // ❌ Duplicate SID
-  ]
+  "Version": "2012-10-17",
+  "Statement": [{
+    "Effect": "Allow",
+    "Action": "*",        // ❌ CRITICAL: All actions
+    "Resource": "*"       // ❌ CRITICAL: All resources
+  }]
 }
 ```
 
-### 6. Wildcard Action Validation
-
-The `security_best_practices` handles all wildcard security validation with customizable allowlists:
-
-```yaml
-security_best_practices:
-  enabled: true
-
-  # Define allowed wildcard patterns (e.g., safe read-only operations)
-  # These patterns are considered acceptable and won't trigger warnings
-  allowed_wildcards:
-    - "s3:List*"        # Safe: listing resources
-    - "s3:Describe*"    # Safe: describing configurations
-    - "ec2:Describe*"   # Safe: read-only operations
-    - "iam:Get*"        # Safe: non-sensitive IAM reads
-    - "iam:List*"       # Safe: listing IAM entities
-    - "cloudwatch:Describe*"
-    - "logs:Describe*"
-
-  # Wildcard resource check uses allowed_wildcards
-  # Resource: "*" is acceptable if ALL actions match allowed_wildcards
-  wildcard_resource_check:
-    enabled: true
-    severity: medium
-    # Optionally override parent allowed_wildcards for this check:
-    # allowed_wildcards:
-    #   - "s3:List*"
-
-  # Flag service-level wildcards (e.g., "s3:*")
-  service_wildcard_check:
-    enabled: true
-    severity: high
-    # Allow specific services to use wildcards
-    allowed_services:
-      - "logs"
-      - "cloudwatch"
-```
-
-**Note:** The `action_validation` now focuses solely on validating that actions exist in AWS service definitions. All wildcard security concerns are handled by `security_best_practices`.
-
-### Configuration Migration
-
-If you have a custom configuration file from before v1.1.0, update it as follows:
-
-**Before (v1.0.x):**
-```yaml
-action_validation:
-  enabled: true
-  severity: error
-  allowed_wildcards:
-    - "s3:List*"
-    - "ec2:Describe*"
-  disable_wildcard_warnings: true
-```
-
-**After (v1.1.0+):**
-```yaml
-action_validation:
-  enabled: true
-  severity: error
-  # allowed_wildcards removed - moved to security_best_practices
-  # disable_wildcard_warnings removed - no longer needed
+### Complete Documentation
 
-security_best_practices:
-  enabled: true
-  # Move allowed_wildcards here
-  allowed_wildcards:
-    - "s3:List*"
-    - "ec2:Describe*"
+**📚 For detailed documentation of all 18 checks with comprehensive pass/fail examples:**
 
-  wildcard_resource_check:
-    enabled: true
-    # Automatically inherits allowed_wildcards from parent
-```
+**[→ View Complete Checks Reference](docs/check-reference.md)**
 
-**Why this change?**
-- **Clearer separation**: Action validation checks **validity**, security checks handle **safety**
-- **Less confusion**: No overlap between validation and security concerns
-- **Better architecture**: Wildcard security logic is centralized in one place
+The check-reference.md file includes:
+- ✅ What each check validates
+- ✅ Pass examples (valid policies)
+- ✅ Fail examples with error messages
+- ✅ Configuration options
+- ✅ Ignore patterns and filtering
+- ✅ Best practices and recommendations
 
 ---