iam-policy-validator 1.4.0__py3-none-any.whl → 1.6.0__py3-none-any.whl

iam_validator/checks/wildcard_action.py

@@ -0,0 +1,62 @@
+"""Wildcard action check - detects Action: '*' in IAM policies."""
+
+from iam_validator.core.aws_fetcher import AWSServiceFetcher
+from iam_validator.core.check_registry import CheckConfig, PolicyCheck
+from iam_validator.core.models import Statement, ValidationIssue
+
+
+class WildcardActionCheck(PolicyCheck):
+    """Checks for wildcard actions (Action: '*') which grant all permissions."""
+
+    @property
+    def check_id(self) -> str:
+        return "wildcard_action"
+
+    @property
+    def description(self) -> str:
+        return "Checks for wildcard actions (*)"
+
+    @property
+    def default_severity(self) -> str:
+        return "medium"
+
+    async def execute(
+        self,
+        statement: Statement,
+        statement_idx: int,
+        fetcher: AWSServiceFetcher,
+        config: CheckConfig,
+    ) -> list[ValidationIssue]:
+        """Execute wildcard action check on a statement."""
+        issues = []
+
+        # Only check Allow statements
+        if statement.effect != "Allow":
+            return issues
+
+        actions = statement.get_actions()
+
+        # Check for wildcard action (Action: "*")
+        if "*" in actions:
+            message = config.config.get("message", "Statement allows all actions (*)")
+            suggestion_text = config.config.get(
+                "suggestion", "Replace wildcard with specific actions needed for your use case"
+            )
+            example = config.config.get("example", "")
+
+            # Combine suggestion + example
+            suggestion = f"{suggestion_text}\nExample:\n{example}" if example else suggestion_text
+
+            issues.append(
+                ValidationIssue(
+                    severity=self.get_severity(config),
+                    statement_sid=statement.sid,
+                    statement_index=statement_idx,
+                    issue_type="overly_permissive",
+                    message=message,
+                    suggestion=suggestion,
+                    line_number=statement.line_number,
+                )
+            )
+
+        return issues

iam_validator/checks/wildcard_resource.py

@@ -0,0 +1,131 @@
+"""Wildcard resource check - detects Resource: '*' in IAM policies."""
+
+from iam_validator.checks.utils.wildcard_expansion import expand_wildcard_actions
+from iam_validator.core.aws_fetcher import AWSServiceFetcher
+from iam_validator.core.check_registry import CheckConfig, PolicyCheck
+from iam_validator.core.models import Statement, ValidationIssue
+
+
+class WildcardResourceCheck(PolicyCheck):
+    """Checks for wildcard resources (Resource: '*') which grant access to all resources."""
+
+    @property
+    def check_id(self) -> str:
+        return "wildcard_resource"
+
+    @property
+    def description(self) -> str:
+        return "Checks for wildcard resources (*)"
+
+    @property
+    def default_severity(self) -> str:
+        return "medium"
+
+    async def execute(
+        self,
+        statement: Statement,
+        statement_idx: int,
+        fetcher: AWSServiceFetcher,
+        config: CheckConfig,
+    ) -> list[ValidationIssue]:
+        """Execute wildcard resource check on a statement."""
+        issues = []
+
+        # Only check Allow statements
+        if statement.effect != "Allow":
+            return issues
+
+        actions = statement.get_actions()
+        resources = statement.get_resources()
+
+        # Check for wildcard resource (Resource: "*")
+        if "*" in resources:
+            # Check if all actions are in the allowed_wildcards list
+            # allowed_wildcards works by expanding wildcard patterns (like "ec2:Describe*")
+            # to all matching AWS actions using the AWS API, then checking if the policy's
+            # actions are in that expanded list. This ensures only validated AWS actions
+            # are allowed with Resource: "*".
+            allowed_wildcards_expanded = await self._get_expanded_allowed_wildcards(config, fetcher)
+
+            # Check if ALL actions (excluding full wildcard "*") are in the expanded list
+            non_wildcard_actions = [a for a in actions if a != "*"]
+
+            if allowed_wildcards_expanded and non_wildcard_actions:
+                # Check if all actions are in the expanded allowed list (exact match)
+                all_actions_allowed = all(
+                    action in allowed_wildcards_expanded for action in non_wildcard_actions
+                )
+
+                # If all actions are in the expanded list, skip the wildcard resource warning
+                if all_actions_allowed:
+                    # All actions are safe, Resource: "*" is acceptable
+                    return issues
+
+            # Flag the issue if actions are not all allowed or no allowed_wildcards configured
+            message = config.config.get("message", "Statement applies to all resources (*)")
+            suggestion_text = config.config.get(
+                "suggestion", "Replace wildcard with specific resource ARNs"
+            )
+            example = config.config.get("example", "")
+
+            # Combine suggestion + example
+            suggestion = f"{suggestion_text}\nExample:\n{example}" if example else suggestion_text
+
+            issues.append(
+                ValidationIssue(
+                    severity=self.get_severity(config),
+                    statement_sid=statement.sid,
+                    statement_index=statement_idx,
+                    issue_type="overly_permissive",
+                    message=message,
+                    suggestion=suggestion,
+                    line_number=statement.line_number,
+                )
+            )
+
+        return issues
+
+    async def _get_expanded_allowed_wildcards(
+        self, config: CheckConfig, fetcher: AWSServiceFetcher
+    ) -> frozenset[str]:
+        """Get and expand allowed_wildcards configuration.
+
+        This method retrieves wildcard patterns from the allowed_wildcards config
+        and expands them using the AWS API to get all matching actual AWS actions.
+
+        How it works:
+        1. Retrieves patterns from config (e.g., ["ec2:Describe*", "s3:List*"])
+        2. Expands each pattern using AWS API:
+           - "ec2:Describe*" → ["ec2:DescribeInstances", "ec2:DescribeImages", ...]
+           - "s3:List*" → ["s3:ListBucket", "s3:ListObjects", ...]
+        3. Returns a set of all expanded actions
+
+        This allows you to:
+        - Specify patterns like "ec2:Describe*" in config
+        - Have the validator allow specific actions like "ec2:DescribeInstances" with Resource: "*"
+        - Ensure only real AWS actions (validated via API) are allowed
+
+        Example:
+            Config: allowed_wildcards: ["ec2:Describe*"]
+            Expands to: ["ec2:DescribeInstances", "ec2:DescribeImages", ...]
+            Policy: "Action": ["ec2:DescribeInstances"], "Resource": "*"
+            Result: ✅ Allowed (ec2:DescribeInstances is in expanded list)
+
+        Args:
+            config: The check configuration
+            fetcher: AWS service fetcher for expanding wildcards via AWS API
+
+        Returns:
+            A frozenset of all expanded action names from the configured patterns
+        """
+        patterns_to_expand = config.config.get("allowed_wildcards", [])
+
+        # If no patterns configured, return empty set
+        if not patterns_to_expand or not isinstance(patterns_to_expand, list):
+            return frozenset()
+
+        # Expand the wildcard patterns using the AWS API
+        # This converts patterns like "ec2:Describe*" to actual AWS actions
+        expanded_actions = await expand_wildcard_actions(patterns_to_expand, fetcher)
+
+        return frozenset(expanded_actions)

iam_validator/commands/cache.py

@@ -9,7 +9,7 @@ from rich.table import Table
 
 from iam_validator.commands.base import Command
 from iam_validator.core.aws_fetcher import AWSServiceFetcher
-from iam_validator.core.config_loader import ConfigLoader
+from iam_validator.core.config.config_loader import ConfigLoader
 
 logger = logging.getLogger(__name__)
 console = Console()

iam_validator/commands/download_services.py

@@ -9,20 +9,15 @@ from pathlib import Path
 
 import httpx
 from rich.console import Console
-from rich.progress import (
-    BarColumn,
-    Progress,
-    TaskID,
-    TextColumn,
-    TimeRemainingColumn,
-)
+from rich.progress import BarColumn, Progress, TaskID, TextColumn, TimeRemainingColumn
 
 from iam_validator.commands.base import Command
+from iam_validator.core.config import AWS_SERVICE_REFERENCE_BASE_URL
 
 logger = logging.getLogger(__name__)
 console = Console()
 
-BASE_URL = "https://servicereference.us-east-1.amazonaws.com/"
+BASE_URL = AWS_SERVICE_REFERENCE_BASE_URL
 DEFAULT_OUTPUT_DIR = Path("aws_services")
 
 

iam_validator/commands/validate.py

@@ -37,6 +37,10 @@ Examples:
   # Validate multiple paths (files and directories)
   iam-validator validate --path policy1.json --path ./policies/ --path ./more-policies/
 
+  # Read policy from stdin
+  cat policy.json | iam-validator validate --stdin
+  echo '{"Version":"2012-10-17","Statement":[...]}' | iam-validator validate --stdin
+
   # Use custom checks from a directory
   iam-validator validate --path ./policies/ --custom-checks-dir ./my-checks
 
@@ -61,15 +65,23 @@ Examples:
 
     def add_arguments(self, parser: argparse.ArgumentParser) -> None:
         """Add validate command arguments."""
-        parser.add_argument(
+        # Create mutually exclusive group for input sources
+        input_group = parser.add_mutually_exclusive_group(required=True)
+
+        input_group.add_argument(
             "--path",
             "-p",
-            required=True,
             action="append",
             dest="paths",
             help="Path to IAM policy file or directory (can be specified multiple times)",
         )
 
+        input_group.add_argument(
+            "--stdin",
+            action="store_true",
+            help="Read policy from stdin (JSON format)",
+        )
+
         parser.add_argument(
             "--format",
             "-f",
@@ -166,6 +178,18 @@ Examples:
             help="Number of policies to process per batch (default: 10, only with --stream)",
         )
 
+        parser.add_argument(
+            "--no-summary",
+            action="store_true",
+            help="Hide Executive Summary section in enhanced format output",
+        )
+
+        parser.add_argument(
+            "--no-severity-breakdown",
+            action="store_true",
+            help="Hide Issue Severity Breakdown section in enhanced format output",
+        )
+
     async def execute(self, args: argparse.Namespace) -> int:
         """Execute the validate command."""
         # Check if streaming mode is enabled
@@ -186,15 +210,36 @@ Examples:
 
     async def _execute_batch(self, args: argparse.Namespace) -> int:
         """Execute validation by loading all policies at once (original behavior)."""
-        # Load policies from all specified paths
+        # Load policies from all specified paths or stdin
         loader = PolicyLoader()
-        policies = loader.load_from_paths(args.paths, recursive=not args.no_recursive)
 
-        if not policies:
-            logging.error(f"No valid IAM policies found in: {', '.join(args.paths)}")
-            return 1
+        if args.stdin:
+            # Read from stdin
+            import json
+            import sys
+
+            stdin_content = sys.stdin.read()
+            if not stdin_content.strip():
+                logging.error("No policy data provided on stdin")
+                return 1
+
+            try:
+                policy_data = json.loads(stdin_content)
+                # Create a synthetic policy entry
+                policies = [("stdin", policy_data)]
+                logging.info("Loaded policy from stdin")
+            except json.JSONDecodeError as e:
+                logging.error(f"Invalid JSON from stdin: {e}")
+                return 1
+        else:
+            # Load from paths
+            policies = loader.load_from_paths(args.paths, recursive=not args.no_recursive)
+
+            if not policies:
+                logging.error(f"No valid IAM policies found in: {', '.join(args.paths)}")
+                return 1
 
-        logging.info(f"Loaded {len(policies)} policies from {len(args.paths)} path(s)")
+            logging.info(f"Loaded {len(policies)} policies from {len(args.paths)} path(s)")
 
         # Validate policies
         use_registry = not getattr(args, "no_registry", False)
@@ -229,7 +274,14 @@ Examples:
                 print(generator.generate_github_comment(report))
         else:
             # Use formatter registry for other formats (enhanced, html, csv, sarif)
-            output_content = generator.format_report(report, args.format)
+            # Pass options for enhanced format
+            format_options = {}
+            if args.format == "enhanced":
+                format_options["show_summary"] = not getattr(args, "no_summary", False)
+                format_options["show_severity_breakdown"] = not getattr(
+                    args, "no_severity_breakdown", False
+                )
+            output_content = generator.format_report(report, args.format, **format_options)
             if args.output:
                 with open(args.output, "w", encoding="utf-8") as f:
                     f.write(output_content)
@@ -239,7 +291,7 @@ Examples:
 
         # Post to GitHub if configured
         if args.github_comment or getattr(args, "github_review", False):
-            from iam_validator.core.config_loader import ConfigLoader
+            from iam_validator.core.config.config_loader import ConfigLoader
             from iam_validator.core.pr_commenter import PRCommenter
 
             # Load config to get fail_on_severity setting
@@ -348,7 +400,14 @@ Examples:
                 print(generator.generate_github_comment(report))
         else:
             # Use formatter registry for other formats (enhanced, html, csv, sarif)
-            output_content = generator.format_report(report, args.format)
+            # Pass options for enhanced format
+            format_options = {}
+            if args.format == "enhanced":
+                format_options["show_summary"] = not getattr(args, "no_summary", False)
+                format_options["show_severity_breakdown"] = not getattr(
+                    args, "no_severity_breakdown", False
+                )
+            output_content = generator.format_report(report, args.format, **format_options)
             if args.output:
                 with open(args.output, "w", encoding="utf-8") as f:
                     f.write(output_content)
@@ -358,7 +417,7 @@ Examples:
 
         # Post summary comment to GitHub (if requested and not already posted per-file reviews)
         if args.github_comment:
-            from iam_validator.core.config_loader import ConfigLoader
+            from iam_validator.core.config.config_loader import ConfigLoader
             from iam_validator.core.pr_commenter import PRCommenter
 
             # Load config to get fail_on_severity setting
@@ -410,7 +469,7 @@ Examples:
         This provides progressive feedback in PRs as files are processed.
         """
         try:
-            from iam_validator.core.config_loader import ConfigLoader
+            from iam_validator.core.config.config_loader import ConfigLoader
             from iam_validator.core.pr_commenter import PRCommenter
 
             async with GitHubIntegration() as github:

iam_validator/core/aws_fetcher.py

@@ -27,64 +27,18 @@ import os
 import re
 import sys
 import time
-from collections import OrderedDict
 from pathlib import Path
 from typing import Any
 
 import httpx
 
+from iam_validator.core.config import AWS_SERVICE_REFERENCE_BASE_URL
 from iam_validator.core.models import ServiceDetail, ServiceInfo
+from iam_validator.utils.cache import LRUCache
 
 logger = logging.getLogger(__name__)
 
 
-class LRUCache:
-    """Thread-safe LRU cache implementation with TTL support."""
-
-    def __init__(self, maxsize: int = 128, ttl: int = 3600):
-        """Initialize LRU cache.
-
-        Args:
-            maxsize: Maximum number of items in cache
-            ttl: Time to live in seconds (default: 1 hour)
-        """
-        self.cache: OrderedDict[str, tuple[Any, float]] = OrderedDict()
-        self.maxsize = maxsize
-        self.ttl = ttl
-        self._lock = asyncio.Lock()
-
-    async def get(self, key: str) -> Any | None:
-        """Get item from cache if not expired."""
-        async with self._lock:
-            if key in self.cache:
-                value, timestamp = self.cache[key]
-                if time.time() - timestamp < self.ttl:
-                    # Move to end (most recently used)
-                    self.cache.move_to_end(key)
-                    return value
-                else:
-                    # Expired, remove it
-                    del self.cache[key]
-        return None
-
-    async def set(self, key: str, value: Any) -> None:
-        """Set item in cache with current timestamp."""
-        async with self._lock:
-            if key in self.cache:
-                # Move to end if exists
-                self.cache.move_to_end(key)
-            elif len(self.cache) >= self.maxsize:
-                # Remove least recently used
-                self.cache.popitem(last=False)
-
-            self.cache[key] = (value, time.time())
-
-    async def clear(self) -> None:
-        """Clear the cache."""
-        async with self._lock:
-            self.cache.clear()
-
-
 class CompiledPatterns:
     """Pre-compiled regex patterns for validation."""
 
@@ -119,9 +73,71 @@ class CompiledPatterns:
 
 
 class AWSServiceFetcher:
-    """Fetches AWS service information from the AWS service reference API with enhanced performance features."""
-
-    BASE_URL = "https://servicereference.us-east-1.amazonaws.com/"
+    """Fetches AWS service information from the AWS service reference API with enhanced performance features.
+
+    This class provides a comprehensive interface for retrieving AWS service metadata,
+    including actions, resources, and condition keys. It includes multiple layers of
+    caching and optimization for high-performance policy validation.
+
+    Features:
+    - Multi-layer caching (memory LRU + disk with TTL)
+    - Service pre-fetching for common AWS services
+    - Request batching and coalescing
+    - Offline mode support with local AWS service files
+    - HTTP/2 connection pooling
+    - Automatic retry with exponential backoff
+
+    Example:
+        >>> async with AWSServiceFetcher() as fetcher:
+        ...     # Fetch service list
+        ...     services = await fetcher.fetch_services()
+        ...
+        ...     # Fetch specific service details
+        ...     s3_service = await fetcher.fetch_service_by_name("s3")
+        ...
+        ...     # Validate actions
+        ...     is_valid = await fetcher.validate_action("s3:GetObject", s3_service)
+
+    Method Organization:
+        Lifecycle Management:
+            - __init__: Initialize fetcher with configuration
+            - __aenter__, __aexit__: Context manager support
+
+        Caching (Private):
+            - _get_cache_directory: Determine cache location
+            - _get_cache_path: Generate cache file path
+            - _read_from_cache: Read from disk cache
+            - _write_to_cache: Write to disk cache
+            - clear_caches: Clear all caches
+
+        HTTP Operations (Private):
+            - _make_request: Core HTTP request handler
+            - _make_request_with_batching: Request coalescing
+            - _prefetch_common_services: Pre-load common services
+
+        File I/O (Private):
+            - _load_services_from_file: Load service list from local file
+            - _load_service_from_file: Load service details from local file
+
+        Public API - Fetching:
+            - fetch_services: Get list of all AWS services
+            - fetch_service_by_name: Get details for one service
+            - fetch_multiple_services: Batch fetch multiple services
+
+        Public API - Validation:
+            - validate_action: Check if action exists in service
+            - validate_arn: Validate ARN format
+            - validate_condition_key: Check condition key validity
+
+        Public API - Parsing:
+            - parse_action: Split action into service and name
+            - _match_wildcard_action: Match wildcard patterns
+
+        Utilities:
+            - get_stats: Get cache statistics
+    """
+
+    BASE_URL = AWS_SERVICE_REFERENCE_BASE_URL
 
     # Common AWS services to pre-fetch
     # All other services will be fetched on-demand (lazy loading if found in policies)
@@ -796,11 +812,26 @@ class AWSServiceFetcher:
         return True, None
 
     async def validate_condition_key(
-        self, action: str, condition_key: str
-    ) -> tuple[bool, str | None]:
-        """Validate condition key with optimized caching."""
+        self, action: str, condition_key: str, resources: list[str] | None = None
+    ) -> tuple[bool, str | None, str | None]:
+        """
+        Validate condition key against action and optionally resource types.
+
+        Args:
+            action: IAM action (e.g., "s3:GetObject")
+            condition_key: Condition key to validate (e.g., "s3:prefix")
+            resources: Optional list of resource ARNs to validate against
+
+        Returns:
+            Tuple of (is_valid, error_message, warning_message)
+            - is_valid: True if key is valid (even with warning)
+            - error_message: Error message if invalid (is_valid=False)
+            - warning_message: Warning message if valid but not recommended
+        """
         try:
-            from iam_validator.core.aws_global_conditions import get_global_conditions
+            from iam_validator.core.config.aws_global_conditions import (
+                get_global_conditions,
+            )
 
             service_prefix, action_name = self.parse_action(action)
 
@@ -814,6 +845,7 @@ class AWSServiceFetcher:
                     return (
                         False,
                         f"Invalid AWS global condition key: '{condition_key}'.",
+                        None,
                     )
 
             # Fetch service detail (cached)
@@ -821,7 +853,7 @@ class AWSServiceFetcher:
 
             # Check service-specific condition keys
             if condition_key in service_detail.condition_keys:
-                return True, None
+                return True, None, None
 
             # Check action-specific condition keys
             if action_name in service_detail.actions:
@@ -830,29 +862,47 @@ class AWSServiceFetcher:
                     action_detail.action_condition_keys
                     and condition_key in action_detail.action_condition_keys
                 ):
-                    return True, None
+                    return True, None, None
+
+                # Check resource-specific condition keys
+                # Get resource types required by this action
+                if resources and action_detail.resources:
+                    for res_req in action_detail.resources:
+                        resource_name = res_req.get("Name", "")
+                        if not resource_name:
+                            continue
+
+                        # Look up resource type definition
+                        resource_type = service_detail.resources.get(resource_name)
+                        if resource_type and resource_type.condition_keys:
+                            if condition_key in resource_type.condition_keys:
+                                return True, None, None
 
                 # If it's a global key but the action has specific condition keys defined,
-                # check if the global key is explicitly listed in the action's supported keys
+                # AWS allows it but the key may not be available in every request context
                 if is_global_key and action_detail.action_condition_keys is not None:
-                    return (
-                        False,
-                        f"Condition key '{condition_key}' is not supported by action '{action}'. "
-                        f"This action has a specific set of supported condition keys.",
+                    warning_msg = (
+                        f"Global condition key '{condition_key}' is used with action '{action}'. "
+                        f"While global condition keys can be used across all AWS services, "
+                        f"the key may not be available in every request context. "
+                        f"Verify that '{condition_key}' is available for this specific action's request context. "
+                        f"Consider using '*IfExists' operators (e.g., StringEqualsIfExists) if the key might be missing."
                     )
+                    return True, None, warning_msg
 
             # If it's a global key and action doesn't define specific keys, allow it
             if is_global_key:
-                return True, None
+                return True, None, None
 
             return (
                 False,
                 f"Condition key '{condition_key}' is not valid for action '{action}'",
+                None,
             )
 
         except Exception as e:
             logger.error(f"Error validating condition key {condition_key} for {action}: {e}")
-            return False, f"Failed to validate condition key: {str(e)}"
+            return False, f"Failed to validate condition key: {str(e)}", None
 
     async def clear_caches(self) -> None:
         """Clear all caches (memory and disk)."""