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

iam_validator/checks/utils/sensitive_action_matcher.py

@@ -38,6 +38,31 @@ def _get_default_sensitive_actions() -> frozenset[str]:
     return _DEFAULT_SENSITIVE_ACTIONS_CACHE
 
 
+def get_sensitive_actions_by_categories(categories: list[str] | None = None) -> frozenset[str]:
+    """
+    Get sensitive actions filtered by categories.
+
+    Args:
+        categories: List of category IDs to include. If None, returns all actions.
+                   Valid categories: 'credential_exposure', 'data_access',
+                   'priv_esc', 'resource_exposure'
+
+    Returns:
+        Frozenset of sensitive actions matching the specified categories
+
+    Examples:
+        >>> # Get all sensitive actions (default behavior)
+        >>> all_actions = get_sensitive_actions_by_categories()
+
+        >>> # Get only privilege escalation actions
+        >>> priv_esc = get_sensitive_actions_by_categories(['priv_esc'])
+
+        >>> # Get credential exposure and data access actions
+        >>> sensitive = get_sensitive_actions_by_categories(['credential_exposure', 'data_access'])
+    """
+    return get_sensitive_actions(categories)
+
+
 # Export for backward compatibility
 DEFAULT_SENSITIVE_ACTIONS = _get_default_sensitive_actions()
 
@@ -79,7 +104,16 @@ def check_sensitive_actions(
         - Uses lazy-loaded defaults (only loaded on first use)
         - O(1) frozenset lookups for action matching
     """
-    if default_actions is None:
+    # Check if categories are specified in config
+    categories = config.config.get("categories")
+    if categories is not None:
+        # If categories is an empty list, disable the check
+        if len(categories) == 0:
+            return False, []
+        # Get sensitive actions filtered by categories
+        default_actions = get_sensitive_actions_by_categories(categories)
+    elif default_actions is None:
+        # Use all categories if no specific categories configured
         default_actions = _get_default_sensitive_actions()
 
     # Filter out wildcards

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/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",
@@ -198,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)
@@ -258,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
@@ -384,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
@@ -436,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,7 +27,6 @@ import os
 import re
 import sys
 import time
-from collections import OrderedDict
 from pathlib import Path
 from typing import Any
 
@@ -35,57 +34,11 @@ 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."""
 
@@ -120,7 +73,69 @@ class CompiledPatterns:
 
 
 class AWSServiceFetcher:
-    """Fetches AWS service information from the AWS service reference API with enhanced performance features."""
+    """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
 
@@ -797,9 +812,15 @@ class AWSServiceFetcher:
         return True, None
 
     async def validate_condition_key(
-        self, action: str, condition_key: str
+        self, action: str, condition_key: str, resources: list[str] | None = None
     ) -> tuple[bool, str | None, str | None]:
-        """Validate condition key with optimized caching.
+        """
+        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)
@@ -808,7 +829,9 @@ class AWSServiceFetcher:
             - 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)
 
@@ -841,6 +864,20 @@ class AWSServiceFetcher:
                 ):
                     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,
                 # 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:

iam_validator/core/check_registry.py

@@ -31,6 +31,112 @@ class CheckConfig:
     config: dict[str, Any] = field(default_factory=dict)  # Check-specific config
     description: str = ""
     root_config: dict[str, Any] = field(default_factory=dict)  # Full config for cross-check access
+    ignore_patterns: list[dict[str, Any]] = field(default_factory=list)  # NEW: Ignore patterns
+    """
+    List of patterns to ignore findings.
+
+    Each pattern is a dict with optional fields:
+    - filepath_regex: Regex to match file path
+    - action_matches: Regex to match action name
+    - resource_matches: Regex to match resource
+    - statement_sid: Exact SID to match (or regex if ends with .*)
+    - condition_key_matches: Regex to match condition key
+
+    Multiple fields in one pattern = AND logic
+    Multiple patterns = OR logic (any pattern matches → ignore)
+
+    Example:
+        ignore_patterns:
+          - filepath_regex: "test/.*|examples/.*"
+          - filepath_regex: "policies/readonly-.*"
+            action_matches: ".*:(Get|List|Describe).*"
+          - statement_sid: "AllowReadOnlyAccess"
+    """
+
+    def should_ignore(self, issue: ValidationIssue, filepath: str = "") -> bool:
+        """
+        Check if issue should be ignored based on ignore patterns.
+
+        Args:
+            issue: The validation issue to check
+            filepath: Path to the policy file
+
+        Returns:
+            True if the issue should be ignored
+        """
+        if not self.ignore_patterns:
+            return False
+
+        import re
+
+        for pattern in self.ignore_patterns:
+            if self._matches_pattern(pattern, issue, filepath, re):
+                return True
+
+        return False
+
+    def _matches_pattern(
+        self,
+        pattern: dict[str, Any],
+        issue: ValidationIssue,
+        filepath: str,
+        re_module: Any,
+    ) -> bool:
+        """
+        Check if issue matches a single ignore pattern.
+
+        All fields in pattern must match (AND logic).
+
+        Args:
+            pattern: Pattern dict with optional fields
+            issue: ValidationIssue to check
+            filepath: Path to policy file
+            re_module: re module for regex matching
+
+        Returns:
+            True if all fields in pattern match the issue
+        """
+        for field_name, regex_pattern in pattern.items():
+            actual_value = None
+
+            if field_name == "filepath_regex":
+                actual_value = filepath
+            elif field_name == "action_matches":
+                actual_value = issue.action or ""
+            elif field_name == "resource_matches":
+                actual_value = issue.resource or ""
+            elif field_name == "statement_sid":
+                # For SID, support both exact match and regex
+                if isinstance(regex_pattern, str) and "*" in regex_pattern:
+                    # Treat as regex if contains wildcard
+                    actual_value = issue.statement_sid or ""
+                else:
+                    # Exact match
+                    if issue.statement_sid != regex_pattern:
+                        return False
+                    continue
+            elif field_name == "condition_key_matches":
+                actual_value = issue.condition_key or ""
+            else:
+                # Unknown field, skip
+                continue
+
+            # Check regex match (case-insensitive)
+            if actual_value is None:
+                return False
+
+            try:
+                if not re_module.search(
+                    str(regex_pattern),
+                    str(actual_value),
+                    re_module.IGNORECASE,
+                ):
+                    return False
+            except re_module.error:
+                # Invalid regex, don't match
+                return False
+
+        return True  # All fields matched
 
 
 class PolicyCheck(ABC):
@@ -264,6 +370,7 @@ class CheckRegistry:
         statement: Statement,
         statement_idx: int,
         fetcher: AWSServiceFetcher,
+        filepath: str = "",
     ) -> list[ValidationIssue]:
         """
         Execute all enabled checks in parallel for maximum performance.
@@ -275,9 +382,10 @@ class CheckRegistry:
             statement: The IAM policy statement to validate
             statement_idx: Index of the statement in the policy
             fetcher: AWS service fetcher for API calls
+            filepath: Path to the policy file (for ignore_patterns filtering)
 
         Returns:
-            List of all ValidationIssue objects from all checks
+            List of all ValidationIssue objects from all checks (filtered by ignore_patterns)
         """
         enabled_checks = self.get_enabled_checks()
 
@@ -291,21 +399,27 @@ class CheckRegistry:
                 config = self.get_config(check.check_id)
                 if config:
                     issues = await check.execute(statement, statement_idx, fetcher, config)
-                    all_issues.extend(issues)
+                    # Filter issues based on ignore_patterns
+                    filtered_issues = [
+                        issue for issue in issues if not config.should_ignore(issue, filepath)
+                    ]
+                    all_issues.extend(filtered_issues)
             return all_issues
 
         # Execute all checks in parallel
         tasks = []
+        configs = []
         for check in enabled_checks:
             config = self.get_config(check.check_id)
             if config:
                 task = check.execute(statement, statement_idx, fetcher, config)
                 tasks.append(task)
+                configs.append(config)
 
         # Wait for all checks to complete
         results = await asyncio.gather(*tasks, return_exceptions=True)
 
-        # Collect all issues, handling any exceptions
+        # Collect all issues, handling any exceptions and applying ignore_patterns
         all_issues = []
         for idx, result in enumerate(results):
             if isinstance(result, Exception):
@@ -313,7 +427,12 @@ class CheckRegistry:
                 check = enabled_checks[idx]
                 print(f"Warning: Check '{check.check_id}' failed: {result}")
             elif isinstance(result, list):
-                all_issues.extend(result)
+                config = configs[idx]
+                # Filter issues based on ignore_patterns
+                filtered_issues = [
+                    issue for issue in result if not config.should_ignore(issue, filepath)
+                ]
+                all_issues.extend(filtered_issues)
 
         return all_issues
 
@@ -442,22 +561,47 @@ def create_default_registry(
         # Import and register built-in checks
         from iam_validator import checks
 
-        registry.register(checks.ActionValidationCheck())
-        registry.register(checks.ConditionKeyValidationCheck())
-        registry.register(checks.ResourceValidationCheck())
-        registry.register(checks.WildcardActionCheck())
-        registry.register(checks.WildcardResourceCheck())
-        registry.register(checks.FullWildcardCheck())
-        registry.register(checks.ServiceWildcardCheck())
-        registry.register(checks.SensitiveActionCheck())
-        registry.register(checks.ActionConditionEnforcementCheck())
-        registry.register(checks.ActionResourceConstraintCheck())
-        registry.register(checks.SidUniquenessCheck())
-        registry.register(checks.PolicySizeCheck())
-        registry.register(checks.PrincipalValidationCheck())
-
-        # Note: SID uniqueness check is registered above but its actual execution
-        # happens at the policy level in _validate_policy_with_registry() since it
-        # needs to see all statements together to find duplicates
+        # 1. POLICY STRUCTURE (Checks that examine the entire policy, not individual statements)
+        registry.register(
+            checks.SidUniquenessCheck()
+        )  # Policy-level: Duplicate SID detection across statements
+        registry.register(checks.PolicySizeCheck())  # Policy-level: Size limit validation
+
+        # 2. IAM VALIDITY (AWS syntax validation - must pass before deeper checks)
+        registry.register(checks.ActionValidationCheck())  # Validate actions against AWS API
+        registry.register(checks.ResourceValidationCheck())  # Validate resource ARNs
+        registry.register(checks.ConditionKeyValidationCheck())  # Validate condition keys
+
+        # 3. TYPE VALIDATION (Condition operator type checking)
+        registry.register(checks.ConditionTypeMismatchCheck())  # Operator-value type compatibility
+        registry.register(checks.SetOperatorValidationCheck())  # ForAllValues/ForAnyValue usage
+
+        # 4. RESOURCE MATCHING (Action-resource relationship validation)
+        registry.register(
+            checks.ActionResourceMatchingCheck()
+        )  # ARN type matching and resource constraints
+
+        # 5. SECURITY - WILDCARDS (Security best practices for wildcards)
+        registry.register(checks.WildcardActionCheck())  # Wildcard action detection
+        registry.register(checks.WildcardResourceCheck())  # Wildcard resource detection
+        registry.register(checks.FullWildcardCheck())  # Full wildcard (*) detection
+        registry.register(checks.ServiceWildcardCheck())  # Service-level wildcard detection
+
+        # 6. SECURITY - ADVANCED (Sensitive actions and condition enforcement)
+        registry.register(
+            checks.SensitiveActionCheck()
+        )  # Policy-level: Privilege escalation detection (all_of across statements)
+        registry.register(
+            checks.ActionConditionEnforcementCheck()
+        )  # Statement + Policy-level: Condition enforcement (any_of/all_of/none_of)
+        registry.register(checks.MFAConditionCheck())  # MFA anti-pattern detection
+
+        # 7. PRINCIPAL VALIDATION (Resource policy specific)
+        registry.register(
+            checks.PrincipalValidationCheck()
+        )  # Principal validation (resource policies)
+
+        # Note: policy_type_validation is a standalone function (not a class-based check)
+        # and is called separately in the validation flow
 
     return registry