iam-policy-validator 1.7.2__tar.gz → 1.9.0__tar.gz

{iam_policy_validator-1.7.2 → iam_policy_validator-1.9.0}/CONTRIBUTING.md

@@ -121,8 +121,7 @@ iam-policy-auditor/
 │   └── conftest.py             # Pytest configuration and fixtures
 │
 ├── docs/                       # Documentation
-│   ├── check-reference.md      # Complete reference for all 18 checks
-│   ├── CHECKS.md               # Deprecated - migration guide
+│   ├── check-reference.md      # Complete reference for all 19 checks
 │   ├── SDK.md                  # Python SDK documentation
 │   ├── configuration.md        # Configuration guide
 │   ├── condition-requirements.md  # Action condition enforcement
@@ -305,15 +304,22 @@ This runs linting, type checking, and tests.
 
 - **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/check-reference.md**: Complete reference for all 19 checks with pass/fail examples
 - **docs/SDK.md**: Python library documentation and API reference
+- **docs/README.md**: Documentation hub with navigation and quick links
 - **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
+  - **github-actions-workflows.md**: CI/CD integration guide
+  - **python-library-usage.md**: Python SDK usage
   - **development/**: Contributor documentation
+- **examples/**: Practical examples
+  - **configs/**: 9+ configuration templates
+  - **trust-policies/**: Trust policy validation examples
+  - **custom_checks/**: Custom check implementations
+  - **github-actions/**: Workflow examples
 
 ### Building Documentation
 

{iam_policy_validator-1.7.2 → iam_policy_validator-1.9.0}/DOCS.md

@@ -1,6 +1,6 @@
 # IAM Policy Validator - Complete Documentation
 
-> High-performance AWS IAM policy validation using AWS Access Analyzer and 18 built-in security checks
+> High-performance AWS IAM policy validation using AWS Access Analyzer and 19 built-in security checks
 
 **Quick Links:** [Installation](#installation) • [Quick Start](#quick-start) • [GitHub Actions](#github-actions) • [Validation Checks](#validation-checks) • [CLI Reference](#cli-reference) • [Configuration](#configuration)
 
@@ -405,33 +405,40 @@ 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.
+IAM Policy Validator performs **19 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
+1. **Policy Structure Check (1 check)** - Always runs first
+   - Policy Structure - Validates fundamental IAM policy grammar (Version, Effect, required fields, conflicts)
+
+2. **AWS Validation Checks (11 checks)** - Ensure policies conform to AWS IAM requirements
    - Action Validation
    - Condition Key Validation
    - Condition Type Mismatch
    - MFA Condition Anti-Patterns
    - Resource ARN Validation
+   - Principal Validation
    - SID Uniqueness
+   - Set Operator Validation
+   - Policy Type Validation
+   - Action-Resource Matching
+   - Policy Size
 
-2. **Security Best Practice Checks (7 checks)** - Identify security anti-patterns
+3. **Security Best Practice Checks (6 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
+
+4. **Trust Policy Validation (1 check - Opt-in)** - Disabled by default
+   - Trust Policy Validation - Validates action-principal coupling for role assumption policies
+     - Ensures correct principal types for assume role actions
+     - Validates SAML/OIDC provider ARN formats
+     - Enforces required conditions (SAML:aud, etc.)
+     - Use with `--policy-type TRUST_POLICY` flag
 
 ### Quick Examples
 
@@ -448,7 +455,7 @@ 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)**
+**📚 For complete documentation of all 19 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
@@ -456,6 +463,7 @@ The check-reference.md file provides:
 - Fail examples (invalid policies with error messages)
 - Configuration options for each check
 - How to use ignore patterns to filter findings
+- Trust policy validation (opt-in check)
 
 ---
 
@@ -1023,35 +1031,38 @@ See [examples/configs/](examples/configs/) directory for configurations:
 
 ## Built-in Validation Checks
 
-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.
+IAM Policy Validator includes **19 comprehensive validation checks** across four 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
+- **Policy Structure (1)** - Validates fundamental IAM policy grammar (always runs first)
+- **AWS Validation Checks (11)** - Ensure policies meet AWS IAM requirements
+- **Security Best Practices (6)** - Identify anti-patterns and security risks
+- **Trust Policy Validation (1)** - Validates role assumption policies (opt-in, disabled by default)
 
 ### 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 |
+| Check                        | Category       | Severity     | What It Does                                                 |
+| ---------------------------- | -------------- | ------------ | ------------------------------------------------------------ |
+| policy_structure             | Structure      | error        | Validates fundamental IAM policy grammar (always runs first) |
+| 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                                         |
+| principal_validation         | AWS            | high         | Validates resource policy principals                         |
+| sid_uniqueness               | AWS            | error        | Ensures unique statement IDs                                 |
+| set_operator_validation      | AWS            | error        | Validates ForAllValues/ForAnyValue                           |
+| policy_type_validation       | AWS            | error        | Validates policy matches declared type                       |
+| action_resource_matching     | AWS            | medium       | Validates resource types and account-level actions           |
+| policy_size                  | AWS            | error        | Validates against AWS size limits                            |
+| 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                    |
+| action_condition_enforcement | Security       | high         | Requires conditions for actions                              |
+| trust_policy_validation      | Trust (opt-in) | high         | Validates action-principal coupling for role assumption      |
 
 ### Examples
 
@@ -1084,7 +1095,7 @@ IAM Policy Validator includes **18 comprehensive validation checks** across thre
 
 ### Complete Documentation
 
-**📚 For detailed documentation of all 18 checks with comprehensive pass/fail examples:**
+**📚 For detailed documentation of all 19 checks with comprehensive pass/fail examples:**
 
 **[→ View Complete Checks Reference](docs/check-reference.md)**
 
@@ -1095,6 +1106,7 @@ The check-reference.md file includes:
 - ✅ Configuration options
 - ✅ Ignore patterns and filtering
 - ✅ Best practices and recommendations
+- ✅ Trust policy validation (opt-in)
 
 ---
 

{iam_policy_validator-1.7.2 → iam_policy_validator-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iam-policy-validator
-Version: 1.7.2
+Version: 1.9.0
 Summary: Validate AWS IAM policies for correctness and security using AWS Service Reference API
 Project-URL: Homepage, https://github.com/boogy/iam-policy-validator
 Project-URL: Documentation, https://github.com/boogy/iam-policy-validator/tree/main/docs
@@ -242,8 +242,13 @@ results = await validate_policies(policies)
 
 **All checks are fully configurable** - Enable/disable checks, adjust severity levels, add custom requirements, and define ignore patterns through the configuration file.
 
+### Core Checks (18 always-on + 1 opt-in)
+
+The validator includes **19 built-in checks** organized into three categories:
+
 ### AWS Correctness Checks (12)
 Validates policies against AWS IAM requirements:
+- **Policy structure** - Validates fundamental IAM policy grammar (Version, Effect, required fields, conflicts)
 - **Action validation** - Verify actions exist in AWS services
 - **Condition key validation** - Check condition keys are valid for actions
 - **Condition type matching** - Ensure condition values match expected types
@@ -255,7 +260,6 @@ Validates policies against AWS IAM requirements:
 - **MFA condition patterns** - Detect common MFA anti-patterns
 - **Policy type validation** - Enforce policy type requirements (RCP, SCP, etc.)
 - **Action-resource matching** - Detect impossible action-resource combinations
-- **Action-resource constraints** - Validate service-specific constraints
 
 ### Security Best Practices (6)
 Identifies security risks and overly permissive permissions:
@@ -266,6 +270,15 @@ Identifies security risks and overly permissive permissions:
 - **Sensitive actions** - ~490 actions across 4 risk categories requiring conditions
 - **Action condition enforcement** - Enforce required conditions (MFA, IP, SourceArn, etc.)
 
+### Trust Policy Validation (1 - Opt-in, Disabled by Default)
+Specialized validation for role assumption policies:
+- **Trust policy validation** - Validates action-principal coupling for assume role actions
+  - Ensures correct principal types (`AssumeRoleWithSAML` → Federated, etc.)
+  - Validates SAML/OIDC provider ARN formats
+  - Enforces required conditions (`SAML:aud`, OIDC audience, etc.)
+  - Use with `--policy-type TRUST_POLICY` flag
+  - See [Trust Policy Examples](examples/trust-policies/README.md)
+
 ### Configuration & Customization
 
 All checks can be customized via a yaml configuration file ex: `.iam-validator.yaml`:
@@ -325,10 +338,11 @@ ignore_patterns:
 ```
 
 **📖 Complete documentation:**
-- [Check Reference Guide](docs/check-reference.md) - All 18 checks with examples
+- [Check Reference Guide](docs/check-reference.md) - All 19 checks with examples
 - [Configuration Guide](docs/configuration.md) - Full configuration options
 - [Condition Requirements](docs/condition-requirements.md) - Action-specific requirements
 - [Privilege Escalation Detection](docs/privilege-escalation.md) - How privilege escalation works
+- [Trust Policy Validation](examples/trust-policies/README.md) - Trust policy examples and validation
 
 ## Output Formats & GitHub Integration
 
@@ -355,9 +369,114 @@ ignore_patterns:
 
 **📖 See [GitHub Integration Guide](docs/github-actions-workflows.md) for detailed examples**
 
+## Cache Management & Offline Mode
+
+### Offline Validation (No AWS API Calls)
+
+Validate policies without AWS API access using pre-downloaded service definitions. Useful for:
+- **Air-gapped environments** - No internet access required
+- **Rate limiting avoidance** - No AWS API throttling (429 errors)
+- **CI/CD performance** - Faster validation with local files
+- **Development** - Work offline without AWS credentials
+
+**Download AWS service definitions once:**
+```bash
+# Download all AWS service definitions to local directory
+iam-validator download-services --output-dir ./aws-services
+
+# Directory structure:
+# aws-services/
+#   ├── _services.json       # List of all services
+#   ├── s3.json             # S3 service definition
+#   ├── iam.json            # IAM service definition
+#   └── ... (250+ services)
+```
+
+**Use offline mode:**
+```bash
+# CLI: Use --aws-services-dir flag
+iam-validator validate --path policies/ --aws-services-dir ./aws-services
+
+# Config file: Set aws_services_dir
+# .iam-validator.yaml
+settings:
+  aws_services_dir: ./aws-services
+```
+
+**Python library:**
+```python
+from iam_validator.core.policy_checks import validate_policies
+from iam_validator.core.policy_loader import PolicyLoader
+
+loader = PolicyLoader()
+policies = loader.load_from_path("./policies")
+
+# Pass aws_services_dir to enable offline mode
+results = await validate_policies(
+    policies,
+    aws_services_dir="./aws-services"
+)
+```
+
+### Cache Directory Control
+
+Control where AWS service definitions are cached (for library users):
+
+```python
+from iam_validator.core.aws_service import AWSServiceFetcher
+
+async with AWSServiceFetcher() as fetcher:
+    # Get current cache location
+    cache_path = fetcher.get_cache_directory()
+    print(f"Cache at: {cache_path}")
+    # macOS: ~/Library/Caches/iam-validator/aws_services
+    # Linux: ~/.cache/iam-validator/aws_services
+    # Windows: %LOCALAPPDATA%/iam-validator/cache/aws_services
+
+    # Change cache directory at runtime
+    fetcher.set_cache_directory("/tmp/custom-cache")
+
+    # All future cache operations use the new directory
+    await fetcher.fetch_services()
+```
+
+### Cache Management CLI
+
+Manage the cache directly:
+
+```bash
+# Show cache information and statistics
+iam-validator cache info
+
+# List all cached services
+iam-validator cache list
+iam-validator cache list --format columns
+
+# Show cache directory location
+iam-validator cache location
+
+# Clear cache
+iam-validator cache clear
+
+# Refresh cache (clear + re-download common services)
+iam-validator cache refresh
+
+# Pre-fetch common services (without clearing)
+iam-validator cache prefetch
+```
+
+**Cache configuration:**
+```yaml
+# .iam-validator.yaml
+settings:
+  cache_enabled: true              # Enable/disable caching
+  cache_ttl_hours: 168            # Cache lifetime (7 days default)
+  cache_directory: /custom/path    # Custom cache location
+```
+
 ## AWS Access Analyzer (Optional)
 
-In addition to the 18 built-in checks, optionally enable AWS Access Analyzer for additional validation capabilities that require AWS credentials:
+In addition to the 19 built-in checks, optionally enable AWS Access Analyzer for additional validation capabilities that require AWS credentials:
 
 ### Access Analyzer Capabilities
 
@@ -394,16 +513,18 @@ iam-validator analyze --path bucket-policy.json \
 ## 📚 Documentation
 
 **Guides:**
-- [Check Reference](docs/check-reference.md) - All 18 checks with examples
+- [Check Reference](docs/check-reference.md) - All 19 checks with examples
 - [Configuration Guide](docs/configuration.md) - Customize checks and behavior
 - [GitHub Actions Guide](docs/github-actions-workflows.md) - CI/CD integration
 - [Python Library Guide](docs/python-library-usage.md) - Use as Python package
+- [Trust Policy Guide](examples/trust-policies/README.md) - Trust policy validation
 - [Contributing Guide](CONTRIBUTING.md) - How to contribute
 
 **Examples:**
-- [Configuration Examples](examples/configs/) - 9 config file templates
+- [Configuration Examples](examples/configs/) - 9+ config file templates
 - [Workflow Examples](examples/github-actions/) - GitHub Actions workflows
 - [Custom Checks](examples/custom_checks/) - Add your own validation rules
+- [Trust Policies](examples/trust-policies/) - Trust policy examples
 
 ## 🤝 Contributing
 

{iam_policy_validator-1.7.2 → iam_policy_validator-1.9.0}/README.md

@@ -200,8 +200,13 @@ results = await validate_policies(policies)
 
 **All checks are fully configurable** - Enable/disable checks, adjust severity levels, add custom requirements, and define ignore patterns through the configuration file.
 
+### Core Checks (18 always-on + 1 opt-in)
+
+The validator includes **19 built-in checks** organized into three categories:
+
 ### AWS Correctness Checks (12)
 Validates policies against AWS IAM requirements:
+- **Policy structure** - Validates fundamental IAM policy grammar (Version, Effect, required fields, conflicts)
 - **Action validation** - Verify actions exist in AWS services
 - **Condition key validation** - Check condition keys are valid for actions
 - **Condition type matching** - Ensure condition values match expected types
@@ -213,7 +218,6 @@ Validates policies against AWS IAM requirements:
 - **MFA condition patterns** - Detect common MFA anti-patterns
 - **Policy type validation** - Enforce policy type requirements (RCP, SCP, etc.)
 - **Action-resource matching** - Detect impossible action-resource combinations
-- **Action-resource constraints** - Validate service-specific constraints
 
 ### Security Best Practices (6)
 Identifies security risks and overly permissive permissions:
@@ -224,6 +228,15 @@ Identifies security risks and overly permissive permissions:
 - **Sensitive actions** - ~490 actions across 4 risk categories requiring conditions
 - **Action condition enforcement** - Enforce required conditions (MFA, IP, SourceArn, etc.)
 
+### Trust Policy Validation (1 - Opt-in, Disabled by Default)
+Specialized validation for role assumption policies:
+- **Trust policy validation** - Validates action-principal coupling for assume role actions
+  - Ensures correct principal types (`AssumeRoleWithSAML` → Federated, etc.)
+  - Validates SAML/OIDC provider ARN formats
+  - Enforces required conditions (`SAML:aud`, OIDC audience, etc.)
+  - Use with `--policy-type TRUST_POLICY` flag
+  - See [Trust Policy Examples](examples/trust-policies/README.md)
+
 ### Configuration & Customization
 
 All checks can be customized via a yaml configuration file ex: `.iam-validator.yaml`:
@@ -283,10 +296,11 @@ ignore_patterns:
 ```
 
 **📖 Complete documentation:**
-- [Check Reference Guide](docs/check-reference.md) - All 18 checks with examples
+- [Check Reference Guide](docs/check-reference.md) - All 19 checks with examples
 - [Configuration Guide](docs/configuration.md) - Full configuration options
 - [Condition Requirements](docs/condition-requirements.md) - Action-specific requirements
 - [Privilege Escalation Detection](docs/privilege-escalation.md) - How privilege escalation works
+- [Trust Policy Validation](examples/trust-policies/README.md) - Trust policy examples and validation
 
 ## Output Formats & GitHub Integration
 
@@ -313,9 +327,114 @@ ignore_patterns:
 
 **📖 See [GitHub Integration Guide](docs/github-actions-workflows.md) for detailed examples**
 
+## Cache Management & Offline Mode
+
+### Offline Validation (No AWS API Calls)
+
+Validate policies without AWS API access using pre-downloaded service definitions. Useful for:
+- **Air-gapped environments** - No internet access required
+- **Rate limiting avoidance** - No AWS API throttling (429 errors)
+- **CI/CD performance** - Faster validation with local files
+- **Development** - Work offline without AWS credentials
+
+**Download AWS service definitions once:**
+```bash
+# Download all AWS service definitions to local directory
+iam-validator download-services --output-dir ./aws-services
+
+# Directory structure:
+# aws-services/
+#   ├── _services.json       # List of all services
+#   ├── s3.json             # S3 service definition
+#   ├── iam.json            # IAM service definition
+#   └── ... (250+ services)
+```
+
+**Use offline mode:**
+```bash
+# CLI: Use --aws-services-dir flag
+iam-validator validate --path policies/ --aws-services-dir ./aws-services
+
+# Config file: Set aws_services_dir
+# .iam-validator.yaml
+settings:
+  aws_services_dir: ./aws-services
+```
+
+**Python library:**
+```python
+from iam_validator.core.policy_checks import validate_policies
+from iam_validator.core.policy_loader import PolicyLoader
+
+loader = PolicyLoader()
+policies = loader.load_from_path("./policies")
+
+# Pass aws_services_dir to enable offline mode
+results = await validate_policies(
+    policies,
+    aws_services_dir="./aws-services"
+)
+```
+
+### Cache Directory Control
+
+Control where AWS service definitions are cached (for library users):
+
+```python
+from iam_validator.core.aws_service import AWSServiceFetcher
+
+async with AWSServiceFetcher() as fetcher:
+    # Get current cache location
+    cache_path = fetcher.get_cache_directory()
+    print(f"Cache at: {cache_path}")
+    # macOS: ~/Library/Caches/iam-validator/aws_services
+    # Linux: ~/.cache/iam-validator/aws_services
+    # Windows: %LOCALAPPDATA%/iam-validator/cache/aws_services
+
+    # Change cache directory at runtime
+    fetcher.set_cache_directory("/tmp/custom-cache")
+
+    # All future cache operations use the new directory
+    await fetcher.fetch_services()
+```
+
+### Cache Management CLI
+
+Manage the cache directly:
+
+```bash
+# Show cache information and statistics
+iam-validator cache info
+
+# List all cached services
+iam-validator cache list
+iam-validator cache list --format columns
+
+# Show cache directory location
+iam-validator cache location
+
+# Clear cache
+iam-validator cache clear
+
+# Refresh cache (clear + re-download common services)
+iam-validator cache refresh
+
+# Pre-fetch common services (without clearing)
+iam-validator cache prefetch
+```
+
+**Cache configuration:**
+```yaml
+# .iam-validator.yaml
+settings:
+  cache_enabled: true              # Enable/disable caching
+  cache_ttl_hours: 168            # Cache lifetime (7 days default)
+  cache_directory: /custom/path    # Custom cache location
+```
+
 ## AWS Access Analyzer (Optional)
 
-In addition to the 18 built-in checks, optionally enable AWS Access Analyzer for additional validation capabilities that require AWS credentials:
+In addition to the 19 built-in checks, optionally enable AWS Access Analyzer for additional validation capabilities that require AWS credentials:
 
 ### Access Analyzer Capabilities
 
@@ -352,16 +471,18 @@ iam-validator analyze --path bucket-policy.json \
 ## 📚 Documentation
 
 **Guides:**
-- [Check Reference](docs/check-reference.md) - All 18 checks with examples
+- [Check Reference](docs/check-reference.md) - All 19 checks with examples
 - [Configuration Guide](docs/configuration.md) - Customize checks and behavior
 - [GitHub Actions Guide](docs/github-actions-workflows.md) - CI/CD integration
 - [Python Library Guide](docs/python-library-usage.md) - Use as Python package
+- [Trust Policy Guide](examples/trust-policies/README.md) - Trust policy validation
 - [Contributing Guide](CONTRIBUTING.md) - How to contribute
 
 **Examples:**
-- [Configuration Examples](examples/configs/) - 9 config file templates
+- [Configuration Examples](examples/configs/) - 9+ config file templates
 - [Workflow Examples](examples/github-actions/) - GitHub Actions workflows
 - [Custom Checks](examples/custom_checks/) - Add your own validation rules
+- [Trust Policies](examples/trust-policies/) - Trust policy examples
 
 ## 🤝 Contributing
 

iam_policy_validator-1.9.0/docs/README.md

@@ -0,0 +1,82 @@
+# IAM Policy Validator Documentation
+
+Comprehensive documentation for validating AWS IAM policies with confidence.
+
+## 🚀 Start Here
+
+| Document                      | Purpose                  | Audience  |
+| ----------------------------- | ------------------------ | --------- |
+| **[README.md](../README.md)** | Quick start and overview | New users |
+| **[DOCS.md](../DOCS.md)**     | Complete reference guide | All users |
+
+## 📖 Core Documentation
+
+### Validation & Checks
+- **[Check Reference Guide](check-reference.md)** - All 19 checks with pass/fail examples
+  - Policy structure validation
+  - AWS correctness checks (11)
+  - Security best practices (6)
+  - Trust policy validation (opt-in)
+- **[Configuration Reference](configuration.md)** - Customize validation rules and behavior
+- **[Condition Requirements](condition-requirements.md)** - Enforce IAM conditions on sensitive actions
+- **[Privilege Escalation Detection](privilege-escalation.md)** - Detect cross-statement risks
+
+### Integration & Usage
+- **[GitHub Actions Workflows](github-actions-workflows.md)** - CI/CD integration guide
+- **[GitHub Actions Examples](github-actions-examples.md)** - Workflow patterns and examples
+- **[Python Library Usage](python-library-usage.md)** - Programmatic validation in Python
+- **[Custom Checks Guide](custom-checks.md)** - Write organization-specific checks
+
+### Advanced Topics
+- **[Modular Configuration](modular-configuration.md)** - Python-based configuration architecture
+- **[Smart Filtering](smart-filtering.md)** - Automatic IAM policy detection
+- **[AWS Services Backup](aws-services-backup.md)** - Offline validation setup
+- **[AWS API Configuration](aws-api-configuration.md)** - AWS Access Analyzer integration
+
+## 👨‍💻 Developer Resources
+
+### Development
+- **[Contributing Guide](../CONTRIBUTING.md)** - Development setup and guidelines
+- **[Publishing Guide](development/PUBLISHING.md)** - Release process
+- **[Pre-release Guide](development/pre-release-guide.md)** - Pre-release workflow
+- **[Roadmap](ROADMAP.md)** - Planned features and improvements
+
+### SDK & API
+- **[SDK Documentation](SDK.md)** - Python SDK reference
+
+## 📚 Examples
+
+Find practical examples in [examples/](../examples/):
+
+### Configuration Examples
+- [Configuration Files](../examples/configs/) - 9+ config templates
+  - Basic, strict security, offline, CI/CD configs
+  - Principal validation variants
+  - Privilege escalation focus
+
+### Code Examples
+- [GitHub Actions](../examples/github-actions/) - 7+ workflow examples
+- [Custom Checks](../examples/custom_checks/) - 8+ custom check implementations
+- [Library Usage](../examples/library-usage/) - 5 Python examples
+
+### Test Cases
+- [Test Policies](../examples/iam-test-policies/) - 50+ test policies
+- [Trust Policies](../examples/trust-policies/) - Trust policy examples
+  - AWS service roles
+  - Cross-account access
+  - SAML federation
+  - OIDC federation (GitHub Actions)
+
+## 🔗 Quick Links by Task
+
+**I want to...**
+- **Get started quickly** → [README.md](../README.md) → [Quick Start](../DOCS.md#quick-start)
+- **Understand all checks** → [Check Reference Guide](check-reference.md)
+- **Configure the validator** → [Configuration Reference](configuration.md)
+- **Use in GitHub Actions** → [GitHub Actions Guide](github-actions-workflows.md)
+- **Use as Python library** → [Python Library Guide](python-library-usage.md)
+- **Validate trust policies** → [Trust Policy Examples](../examples/trust-policies/README.md)
+- **Write custom checks** → [Custom Checks Guide](custom-checks.md)
+- **Detect privilege escalation** → [Privilege Escalation Guide](privilege-escalation.md)
+- **Work offline** → [AWS Services Backup](aws-services-backup.md)
+- **Contribute** → [Contributing Guide](../CONTRIBUTING.md)