iam-policy-validator 1.8.0__tar.gz → 1.10.0__tar.gz

{iam_policy_validator-1.8.0 → iam_policy_validator-1.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iam-policy-validator
-Version: 1.8.0
+Version: 1.10.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
@@ -369,6 +369,111 @@ 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 19 built-in checks, optionally enable AWS Access Analyzer for additional validation capabilities that require AWS credentials:

{iam_policy_validator-1.8.0 → iam_policy_validator-1.10.0}/README.md

@@ -327,6 +327,111 @@ 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 19 built-in checks, optionally enable AWS Access Analyzer for additional validation capabilities that require AWS credentials:

{iam_policy_validator-1.8.0 → iam_policy_validator-1.10.0}/examples/configs/full-reference-config.yaml

@@ -154,6 +154,45 @@ settings:
     # - medium  # Uncomment to fail on medium severity
     # - warning  # Uncomment to fail on IAM validity warnings
 
+  # GitHub PR label mapping based on severity findings
+  # When issues with these severities are found, apply the corresponding labels to the PR
+  # If no issues with these severities exist, remove the labels if present
+  # This helps signal to reviewers if the PR is ready for final review
+  #
+  # Supports both single labels and lists of labels per severity:
+  #
+  # Single label per severity:
+  #   severity_labels:
+  #     error: "iam-validity-error"
+  #     critical: "security-critical"
+  #
+  # Multiple labels per severity:
+  #   severity_labels:
+  #     error: ["iam-error", "needs-fix"]
+  #     critical: ["security-critical", "needs-security-review"]
+  #
+  # Mixed (some single, some multiple):
+  #   severity_labels:
+  #     error: "iam-validity-error"
+  #     critical: ["security-critical", "needs-security-review"]
+  #
+  # Example use cases:
+  #   - Apply multiple labels for better categorization
+  #   - Apply "needs-security-review" when critical/high issues are found
+  #   - Apply "needs-fix" for any validation errors
+  #   - Remove all labels when issues are fixed
+  #
+  # Note: Requires GitHub integration (--github-comment or --github-review flags)
+  # Default: [] (empty list = disabled)
+  severity_labels:
+    error: "iam-validity-error"
+    critical: "iam-security-critical"
+    high: "iam-security-high"
+    # medium: "security-medium"  # Uncomment to label medium severity issues
+    # Multiple labels example:
+    # error: ["iam-validity-error", "needs-fix"]
+    # critical: ["security-critical", "needs-security-review"]
+
   # Template Variable Support (applies to all ARN validation checks)
   #
   # When enabled, the validator is POSITION-AWARE and supports ANY variable name

iam_policy_validator-1.10.0/examples/configs/github-labels-config.yaml

@@ -0,0 +1,116 @@
+# ============================================================================
+# IAM Policy Validator - GitHub PR Labels Configuration
+# ============================================================================
+# This configuration demonstrates automatic GitHub PR label management based
+# on validation severity findings.
+#
+# When validation finds issues with configured severities, it automatically
+# applies the corresponding labels to the PR. When those issues are fixed,
+# the labels are removed. This helps reviewers quickly understand the status
+# of the PR without reading through all the validation comments.
+# ============================================================================
+
+settings:
+  # Define which severities should cause the build to fail
+  fail_on_severity:
+    - error      # IAM validity errors (invalid actions, malformed ARNs, etc.)
+    - critical   # Critical security risks (e.g., full wildcard policies)
+    - high       # High severity security issues
+
+  # Map severity levels to GitHub PR labels
+  # When validation finds issues with these severities, it will:
+  #   1. Apply the corresponding label(s) to the PR
+  #   2. Remove the label(s) if no issues with that severity exist
+  #
+  # Supports both single labels and lists of labels per severity:
+  #   - Single: error: "iam-validity-error"
+  #   - Multiple: error: ["iam-validity-error", "needs-fix"]
+  #
+  # This provides visual feedback to reviewers about the PR status:
+  #   - Labels present = issues need to be fixed
+  #   - Labels removed = issues resolved, ready for review
+  severity_labels:
+    error: "iam-validity-error"      # Applied when IAM validity errors found
+    critical: "security-critical"    # Applied when critical security issues found
+    high: "security-high"            # Applied when high severity issues found
+
+    # Example with multiple labels per severity:
+    # error: ["iam-validity-error", "needs-fix"]
+    # critical: ["security-critical", "needs-security-review", "high-priority"]
+    # high: ["security-high", "needs-review"]
+
+# ============================================================================
+# Example GitHub Actions Workflow
+# ============================================================================
+# To use this feature in GitHub Actions:
+#
+# name: Validate IAM Policies
+#
+# on:
+#   pull_request:
+#     paths:
+#       - 'policies/**/*.json'
+#
+# permissions:
+#   contents: read
+#   pull-requests: write    # Required for labels
+#   issues: write          # Required for labels
+#
+# jobs:
+#   validate:
+#     runs-on: ubuntu-latest
+#     steps:
+#       - uses: actions/checkout@v4
+#
+#       - name: Validate IAM Policies
+#         env:
+#           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+#           GITHUB_REPOSITORY: ${{ github.repository }}
+#           GITHUB_PR_NUMBER: ${{ github.event.pull_request.number }}
+#         run: |
+#           pip install iam-policy-validator
+#           iam-validator validate \
+#             --path ./policies/ \
+#             --config examples/configs/github-labels-config.yaml \
+#             --github-comment \
+#             --github-review
+# ============================================================================
+
+# ============================================================================
+# Label Behavior Examples
+# ============================================================================
+# Scenario 1: Initial validation finds issues
+#   - Policy has invalid action (severity: error)
+#   - Policy has wildcard resource (severity: high)
+#   → Labels applied: "iam-validity-error", "security-high"
+#   → Reviewer sees: This PR needs fixes before review
+#
+# Scenario 2: Developer fixes the invalid action
+#   - Only wildcard resource remains (severity: high)
+#   → Labels applied: "security-high"
+#   → Labels removed: "iam-validity-error"
+#   → Reviewer sees: IAM validity is good, but security issue remains
+#
+# Scenario 3: Developer fixes all issues
+#   - No issues found
+#   → All labels removed
+#   → Reviewer sees: Clean PR, ready for final review
+# ============================================================================
+
+# ============================================================================
+# Additional Configuration
+# ============================================================================
+# You can customize individual checks below. For a comprehensive list of
+# all available checks and options, see:
+#   - examples/configs/full-reference-config.yaml
+#   - examples/configs/basic-config.yaml
+#   - examples/configs/strict-security.yaml
+# ============================================================================
+
+# Example: Disable specific checks
+# wildcard_resource:
+#   enabled: false
+
+# Example: Adjust severity levels
+# service_wildcard:
+#   severity: medium  # Default is "high"

{iam_policy_validator-1.8.0 → iam_policy_validator-1.10.0}/iam_validator/__init__.py

@@ -1,6 +1,6 @@
 """IAM Policy Validator - Validate AWS IAM policies for correctness and security."""
 
-from iam_validator.core.aws_fetcher import AWSServiceFetcher
+from iam_validator.core.aws_service import AWSServiceFetcher
 from iam_validator.core.cli import main
 from iam_validator.core.models import (
     IAMPolicy,

{iam_policy_validator-1.8.0 → iam_policy_validator-1.10.0}/iam_validator/__version__.py

@@ -3,7 +3,7 @@
 This file is the single source of truth for the package version.
 """
 
-__version__ = "1.8.0"
+__version__ = "1.10.0"
 # Parse version, handling pre-release suffixes like -rc, -alpha, -beta
 _version_base = __version__.split("-")[0]  # Remove pre-release suffix if present
 __version_info__ = tuple(int(part) for part in _version_base.split("."))