iam-policy-validator 1.0.4__py3-none-any.whl → 1.1.1__py3-none-any.whl

iam_validator/checks/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility modules for IAM policy checks."""

iam_validator/checks/utils/policy_level_checks.py

@@ -0,0 +1,143 @@
+"""Policy-level privilege escalation detection for IAM policy checks.
+
+This module provides functionality to detect privilege escalation patterns
+that span multiple statements in a policy.
+"""
+
+import re
+
+from iam_validator.core.check_registry import CheckConfig
+from iam_validator.core.models import ValidationIssue
+
+
+def check_policy_level_actions(
+    all_actions: list[str],
+    statement_map: dict[str, list[tuple[int, str | None]]],
+    config,
+    check_config: CheckConfig,
+    check_type: str,
+    get_severity_func,
+) -> list[ValidationIssue]:
+    """
+    Check for policy-level privilege escalation patterns.
+
+    This function detects when a policy grants a dangerous combination of
+    permissions across multiple statements (e.g., iam:CreateUser + iam:AttachUserPolicy).
+
+    Args:
+        all_actions: All actions across the entire policy
+        statement_map: Mapping of action -> [(statement_idx, sid), ...]
+        config: The sensitive_actions or sensitive_action_patterns configuration
+        check_config: Full check configuration
+        check_type: Either "actions" (exact match) or "patterns" (regex match)
+        get_severity_func: Function to get severity for the check
+
+    Returns:
+        List of ValidationIssue objects
+    """
+    issues = []
+
+    if not config:
+        return issues
+
+    # Handle list of items (could be simple strings or dicts with all_of/any_of)
+    if isinstance(config, list):
+        for item in config:
+            if isinstance(item, dict) and "all_of" in item:
+                # This is a privilege escalation pattern - all actions must be present
+                issue = _check_all_of_pattern(
+                    all_actions,
+                    statement_map,
+                    item["all_of"],
+                    check_config,
+                    check_type,
+                    get_severity_func,
+                )
+                if issue:
+                    issues.append(issue)
+
+    # Handle dict with all_of at the top level
+    elif isinstance(config, dict) and "all_of" in config:
+        issue = _check_all_of_pattern(
+            all_actions,
+            statement_map,
+            config["all_of"],
+            check_config,
+            check_type,
+            get_severity_func,
+        )
+        if issue:
+            issues.append(issue)
+
+    return issues
+
+
+def _check_all_of_pattern(
+    all_actions: list[str],
+    statement_map: dict[str, list[tuple[int, str | None]]],
+    required_actions: list[str],
+    check_config: CheckConfig,
+    check_type: str,
+    get_severity_func,
+) -> ValidationIssue | None:
+    """
+    Check if all required actions/patterns are present in the policy.
+
+    Args:
+        all_actions: All actions across the entire policy
+        statement_map: Mapping of action -> [(statement_idx, sid), ...]
+        required_actions: List of required actions or patterns
+        check_config: Full check configuration
+        check_type: Either "actions" (exact match) or "patterns" (regex match)
+        get_severity_func: Function to get severity for the check
+
+    Returns:
+        ValidationIssue if privilege escalation detected, None otherwise
+    """
+    matched_actions = []
+
+    if check_type == "actions":
+        # Exact matching
+        matched_actions = [a for a in all_actions if a in required_actions]
+    else:
+        # Pattern matching - for each pattern, find actions that match
+        for pattern in required_actions:
+            for action in all_actions:
+                try:
+                    if re.match(pattern, action):
+                        matched_actions.append(action)
+                        break  # Found at least one match for this pattern
+                except re.error:
+                    continue
+
+    # Check if ALL required actions/patterns are present
+    if len(matched_actions) >= len(required_actions):
+        # Privilege escalation detected!
+        severity = get_severity_func(check_config, "sensitive_action_check", "error")
+
+        # Collect which statements these actions appear in
+        statement_refs = []
+        for action in matched_actions:
+            if action in statement_map:
+                for stmt_idx, sid in statement_map[action]:
+                    sid_str = f"'{sid}'" if sid else f"#{stmt_idx}"
+                    statement_refs.append(f"Statement {sid_str}: {action}")
+
+        action_list = "', '".join(matched_actions)
+        stmt_details = "\n  - ".join(statement_refs)
+
+        return ValidationIssue(
+            severity=severity,
+            statement_sid=None,  # Policy-level issue
+            statement_index=-1,  # -1 indicates policy-level issue
+            issue_type="privilege_escalation",
+            message=f"Policy-level privilege escalation detected: grants all of ['{action_list}'] across multiple statements",
+            suggestion=f"These actions combined allow privilege escalation. Consider:\n"
+            f"  1. Splitting into separate policies for different users/roles\n"
+            f"  2. Adding strict conditions to limit when these actions can be used together\n"
+            f"  3. Reviewing if all these permissions are truly necessary\n\n"
+            f"Actions found in:\n  - {stmt_details}",
+            line_number=None,
+        )
+
+    return None

iam_validator/checks/utils/sensitive_action_matcher.py

@@ -0,0 +1,252 @@
+"""Sensitive action matching utilities for IAM policy checks.
+
+This module provides functionality to match actions against sensitive action
+configurations, supporting exact matches, regex patterns, and any_of/all_of logic.
+"""
+
+import re
+from functools import lru_cache
+from re import Pattern
+
+from iam_validator.core.check_registry import CheckConfig
+
+# Default set of sensitive actions for backward compatibility
+# Using frozenset for O(1) lookups and immutability
+DEFAULT_SENSITIVE_ACTIONS = frozenset(
+    {
+        "ec2:DeleteVolume"
+        "ec2:TerminateInstances"
+        "eks:DeleteCluster"
+        "iam:AttachRolePolicy"
+        "iam:AttachUserPolicy"
+        "iam:CreateAccessKey"
+        "iam:CreateRole"
+        "iam:CreateUser"
+        "iam:DeleteRole"
+        "iam:DeleteUser"
+        "iam:PutRolePolicy"
+        "iam:PutUserPolicy"
+        "lambda:DeleteFunction"
+        "rds:DeleteDBInstance"
+        "s3:DeleteBucket"
+        "s3:DeleteBucketPolicy"
+        "s3:PutBucketPolicy"
+    }
+)
+
+
+# Global regex pattern cache for performance
+@lru_cache(maxsize=256)
+def compile_pattern(pattern: str) -> Pattern[str] | None:
+    """Compile and cache regex patterns.
+
+    Args:
+        pattern: Regex pattern string
+
+    Returns:
+        Compiled pattern or None if invalid
+    """
+    try:
+        return re.compile(pattern)
+    except re.error:
+        return None
+
+
+def check_sensitive_actions(
+    actions: list[str], config: CheckConfig, default_actions: frozenset[str] | None = None
+) -> tuple[bool, list[str]]:
+    """
+    Check if actions match sensitive action criteria with any_of/all_of support.
+
+    Args:
+        actions: List of actions to check
+        config: Check configuration
+        default_actions: Default sensitive actions to use if no config (defaults to DEFAULT_SENSITIVE_ACTIONS)
+
+    Returns:
+        tuple[bool, list[str]]: (is_sensitive, matched_actions)
+            - is_sensitive: True if the actions match the sensitive criteria
+            - matched_actions: List of actions that matched the criteria
+    """
+    if default_actions is None:
+        default_actions = DEFAULT_SENSITIVE_ACTIONS
+
+    # Filter out wildcards
+    filtered_actions = [a for a in actions if a != "*"]
+    if not filtered_actions:
+        return False, []
+
+    # Get configuration for both sensitive_actions and sensitive_action_patterns
+    sub_check_config = config.config.get("sensitive_action_check", {})
+    if not isinstance(sub_check_config, dict):
+        return False, []
+
+    sensitive_actions_config = sub_check_config.get("sensitive_actions")
+    sensitive_patterns_config = sub_check_config.get("sensitive_action_patterns")
+
+    # Check sensitive_actions (exact matches)
+    actions_match, actions_matched = check_actions_config(
+        filtered_actions, sensitive_actions_config, default_actions
+    )
+
+    # Check sensitive_action_patterns (regex patterns)
+    patterns_match, patterns_matched = check_patterns_config(
+        filtered_actions, sensitive_patterns_config
+    )
+
+    # Combine results - if either matched, we consider it sensitive
+    is_sensitive = actions_match or patterns_match
+    # Use set operations for efficient deduplication
+    matched_set = set(actions_matched) | set(patterns_matched)
+    matched_actions = list(matched_set)
+
+    return is_sensitive, matched_actions
+
+
+def check_actions_config(
+    actions: list[str], config, default_actions: frozenset[str]
+) -> tuple[bool, list[str]]:
+    """
+    Check actions against sensitive_actions configuration.
+
+    Supports:
+    - Simple list: ["action1", "action2"] (backward compatible, any_of logic)
+    - any_of: {"any_of": ["action1", "action2"]}
+    - all_of: {"all_of": ["action1", "action2"]}
+    - Multiple groups: [{"all_of": [...]}, {"all_of": [...]}, "action3"]
+
+    Args:
+        actions: List of actions to check
+        config: Sensitive actions configuration
+        default_actions: Default sensitive actions to use if no config
+
+    Returns:
+        tuple[bool, list[str]]: (matches, matched_actions)
+    """
+    if not config:
+        # If no config, fall back to defaults with any_of logic
+        # default_actions is already a frozenset for O(1) lookups
+        matched = [a for a in actions if a in default_actions]
+        return len(matched) > 0, matched
+
+    # Handle simple list with potential mixed items
+    if isinstance(config, list):
+        # Use set for O(1) membership checks
+        all_matched = set()
+        actions_set = set(actions)  # Convert once for O(1) lookups
+
+        for item in config:
+            # Each item can be a string, or a dict with any_of/all_of
+            if isinstance(item, str):
+                # Simple string - check if action matches (O(1) lookup)
+                if item in actions_set:
+                    all_matched.add(item)
+            elif isinstance(item, dict):
+                # Recurse for dict items
+                matches, matched = check_actions_config(actions, item, default_actions)
+                if matches:
+                    all_matched.update(matched)
+
+        return len(all_matched) > 0, list(all_matched)
+
+    # Handle dict with any_of/all_of
+    if isinstance(config, dict):
+        # any_of: at least one action must match
+        if "any_of" in config:
+            # Convert once for O(1) intersection
+            any_of_set = set(config["any_of"])
+            actions_set = set(actions)
+            matched = list(any_of_set & actions_set)
+            return len(matched) > 0, matched
+
+        # all_of: all specified actions must be present in the statement
+        if "all_of" in config:
+            all_of_set = set(config["all_of"])
+            actions_set = set(actions)
+            matched = list(all_of_set & actions_set)
+            # All required actions must be present
+            return all_of_set.issubset(actions_set), matched
+
+    return False, []
+
+
+def check_patterns_config(actions: list[str], config) -> tuple[bool, list[str]]:
+    """
+    Check actions against sensitive_action_patterns configuration.
+
+    Supports:
+    - Simple list: ["^pattern1.*", "^pattern2.*"] (backward compatible, any_of logic)
+    - any_of: {"any_of": ["^pattern1.*", "^pattern2.*"]}
+    - all_of: {"all_of": ["^pattern1.*", "^pattern2.*"]}
+    - Multiple groups: [{"all_of": [...]}, {"any_of": [...]}, "^pattern.*"]
+
+    Args:
+        actions: List of actions to check
+        config: Sensitive action patterns configuration
+
+    Returns:
+        tuple[bool, list[str]]: (matches, matched_actions)
+
+    Performance:
+        Uses cached compiled regex patterns for 10-50x speedup
+    """
+    if not config:
+        return False, []
+
+    # Handle simple list with potential mixed items
+    if isinstance(config, list):
+        # Use set for O(1) membership checks instead of list
+        all_matched = set()
+
+        for item in config:
+            # Each item can be a string pattern, or a dict with any_of/all_of
+            if isinstance(item, str):
+                # Simple string pattern - check if any action matches
+                # Use cached compiled pattern
+                compiled = compile_pattern(item)
+                if compiled:
+                    for action in actions:
+                        if compiled.match(action):
+                            all_matched.add(action)
+            elif isinstance(item, dict):
+                # Recurse for dict items
+                matches, matched = check_patterns_config(actions, item)
+                if matches:
+                    all_matched.update(matched)
+
+        return len(all_matched) > 0, list(all_matched)
+
+    # Handle dict with any_of/all_of
+    if isinstance(config, dict):
+        # any_of: at least one action must match at least one pattern
+        if "any_of" in config:
+            matched = set()
+            # Pre-compile all patterns
+            compiled_patterns = [compile_pattern(p) for p in config["any_of"]]
+
+            for action in actions:
+                for compiled in compiled_patterns:
+                    if compiled and compiled.match(action):
+                        matched.add(action)
+                        break
+            return len(matched) > 0, list(matched)
+
+        # all_of: at least one action must match ALL patterns
+        if "all_of" in config:
+            # Pre-compile all patterns
+            compiled_patterns = [compile_pattern(p) for p in config["all_of"]]
+            # Filter out invalid patterns
+            compiled_patterns = [p for p in compiled_patterns if p]
+
+            if not compiled_patterns:
+                return False, []
+
+            matched = set()
+            for action in actions:
+                # Check if this action matches ALL patterns
+                if all(compiled.match(action) for compiled in compiled_patterns):
+                    matched.add(action)
+
+            return len(matched) > 0, list(matched)
+
+    return False, []

iam_validator/checks/utils/wildcard_expansion.py

@@ -0,0 +1,89 @@
+"""Wildcard action expansion utilities for IAM policy checks.
+
+This module provides functionality to expand wildcard actions (like ec2:*, iam:Delete*)
+to their actual action names using the AWS Service Reference API.
+"""
+
+import re
+from functools import lru_cache
+from re import Pattern
+
+from iam_validator.core.aws_fetcher import AWSServiceFetcher
+
+
+# Global cache for compiled wildcard patterns (shared across checks)
+# Using lru_cache for O(1) pattern reuse and 20-30x performance improvement
+@lru_cache(maxsize=512)
+def compile_wildcard_pattern(pattern: str) -> Pattern[str]:
+    """Compile and cache wildcard patterns for O(1) reuse.
+
+    Args:
+        pattern: Wildcard pattern (e.g., "s3:Get*")
+
+    Returns:
+        Compiled regex pattern
+
+    Performance:
+        20-30x speedup by avoiding repeated pattern compilation
+    """
+    regex_pattern = "^" + re.escape(pattern).replace(r"\*", ".*") + "$"
+    return re.compile(regex_pattern, re.IGNORECASE)
+
+
+async def expand_wildcard_actions(
+    actions: list[str], fetcher: AWSServiceFetcher
+) -> list[str]:
+    """
+    Expand wildcard actions to their actual action names using AWS API.
+
+    This function expands wildcard patterns like "s3:*", "ec2:Delete*", "iam:*User*"
+    to the actual action names they grant. This is crucial for sensitive action
+    detection to catch wildcards that include sensitive actions.
+
+    Examples:
+        ["s3:GetObject", "ec2:*"] -> ["s3:GetObject", "ec2:DeleteVolume", "ec2:TerminateInstances", ...]
+        ["iam:Delete*"] -> ["iam:DeleteUser", "iam:DeleteRole", "iam:DeleteAccessKey", ...]
+
+    Args:
+        actions: List of action patterns (may include wildcards)
+        fetcher: AWS service fetcher for API lookups
+
+    Returns:
+        List of expanded action names (wildcards replaced with actual actions)
+    """
+    expanded = []
+
+    for action in actions:
+        # Skip full wildcard "*" - it's too broad to expand
+        if action == "*":
+            expanded.append(action)
+            continue
+
+        # Check if action contains wildcards
+        if "*" not in action:
+            # No wildcard, keep as-is
+            expanded.append(action)
+            continue
+
+        # Action has wildcard - expand it using AWS API
+        try:
+            # Parse action to get service and action name
+            service_prefix, action_name = fetcher.parse_action(action)
+
+            # Fetch service detail to get all available actions
+            service_detail = await fetcher.fetch_service_by_name(service_prefix)
+            available_actions = list(service_detail.actions.keys())
+
+            # Match wildcard pattern against available actions
+            _, matched_actions = fetcher._match_wildcard_action(action_name, available_actions)
+
+            # Add expanded actions with service prefix
+            for matched_action in matched_actions:
+                expanded.append(f"{service_prefix}:{matched_action}")
+
+        except Exception:
+            # If expansion fails (invalid service, etc.), keep original action
+            # This ensures we don't lose actions due to API errors
+            expanded.append(action)
+
+    return expanded

iam_validator/commands/__init__.py

@@ -1,6 +1,7 @@
 """CLI commands for IAM Policy Validator."""
 
 from .analyze import AnalyzeCommand
+from .cache import CacheCommand
 from .post_to_pr import PostToPRCommand
 from .validate import ValidateCommand
 
@@ -9,6 +10,7 @@ ALL_COMMANDS = [
     ValidateCommand(),
     PostToPRCommand(),
     AnalyzeCommand(),
+    CacheCommand(),
 ]
 
-__all__ = ["ValidateCommand", "PostToPRCommand", "AnalyzeCommand", "ALL_COMMANDS"]
+__all__ = ["ValidateCommand", "PostToPRCommand", "AnalyzeCommand", "CacheCommand", "ALL_COMMANDS"]