iam-policy-validator 1.14.0__py3-none-any.whl

iam_validator/checks/utils/policy_level_checks.py

@@ -0,0 +1,190 @@
+"""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"],
+                    item,  # Pass the entire item config (includes severity, message, suggestion)
+                    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"],
+            config,  # Pass the entire config dict (includes severity, message, suggestion)
+            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],
+    item_config: dict,
+    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
+        item_config: Configuration for this specific pattern (includes severity, message, suggestion)
+        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
+    """
+    # Filter out actions that match ignore_patterns BEFORE checking for privilege escalation
+    # This allows users to exclude specific actions from privilege escalation detection
+    # by adding them to ignore_patterns in sensitive_action config
+    filtered_actions = check_config.filter_actions(frozenset(all_actions))
+    all_actions_filtered = list(filtered_actions)
+
+    matched_actions = []
+
+    if check_type == "actions":
+        # Exact matching
+        matched_actions = [a for a in all_actions_filtered 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_filtered:
+                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!
+        # Use severity from item_config if available, otherwise use default from check
+        severity = item_config.get("severity") or get_severity_func(check_config)
+
+        # Collect which statements these actions appear in
+        statement_refs = []
+        action_to_statements = {}  # Map action -> list of statement references
+
+        for action in matched_actions:
+            action_to_statements[action] = []
+            if action in statement_map:
+                for stmt_idx, sid in statement_map[action]:
+                    # Use index notation instead of # to avoid GitHub PR link interpretation
+                    sid_str = f"'{sid}'" if sid else f"[{stmt_idx}]"
+                    statement_refs.append(f"Statement {sid_str}: {action}")
+                    action_to_statements[action].append(f"Statement {sid_str}")
+
+        # Format actions with backticks and statement references
+        action_list = "`, `".join(matched_actions)
+        stmt_details = "\n  - ".join(statement_refs)
+
+        # Build a compact statement summary for the message
+        action_stmt_summary = []
+        for action in matched_actions:
+            stmts = action_to_statements.get(action, [])
+            if stmts:
+                action_stmt_summary.append(f"`{action}` in {', '.join(stmts)}")
+
+        stmt_summary = "; ".join(action_stmt_summary)
+
+        # Use custom message if provided in item_config, otherwise use default
+        # Support {actions} and {statements} placeholders in custom messages
+        message_template = item_config.get(
+            "message",
+            f"Policy grants [`{action_list}`] across statements - enables privilege escalation. Found: {stmt_summary}",
+        )
+        # Replace placeholders if present in custom message
+        message = message_template.replace("{actions}", f"`{action_list}`").replace(
+            "{statements}", stmt_summary
+        )
+
+        # Use custom suggestion if provided in item_config, otherwise use default
+        suggestion = item_config.get(
+            "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}",
+        )
+
+        # Use custom example if provided in item_config
+        example = item_config.get("example")
+
+        return ValidationIssue(
+            severity=severity,
+            statement_sid=None,  # Policy-level issue
+            statement_index=-1,  # -1 indicates policy-level issue
+            issue_type="privilege_escalation",
+            message=message,
+            suggestion=suggestion,
+            example=example,
+            line_number=1,  # Policy-level issues point to line 1 (top of policy)
+        )
+
+    return None

iam_validator/checks/utils/sensitive_action_matcher.py

@@ -0,0 +1,293 @@
+"""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.
+
+Performance optimizations:
+- Uses frozenset for O(1) lookups
+- Centralized LRU cache for compiled regex patterns (from ignore_patterns module)
+- Lazy loading of default actions from modular data structure
+"""
+
+from iam_validator.core.check_registry import CheckConfig
+from iam_validator.core.config.sensitive_actions import get_sensitive_actions
+from iam_validator.core.ignore_patterns import compile_pattern
+
+# Lazy-loaded default set of sensitive actions
+# This will be loaded only when first accessed
+_DEFAULT_SENSITIVE_ACTIONS_CACHE: frozenset[str] | None = None
+
+
+def _get_default_sensitive_actions() -> frozenset[str]:
+    """
+    Get default sensitive actions with lazy loading and caching.
+
+    Returns:
+        Frozenset of all default sensitive actions
+
+    Performance:
+        - First call: Loads from sensitive actions list
+        - Subsequent calls: O(1) cached lookup
+    """
+    global _DEFAULT_SENSITIVE_ACTIONS_CACHE
+    if _DEFAULT_SENSITIVE_ACTIONS_CACHE is None:
+        _DEFAULT_SENSITIVE_ACTIONS_CACHE = get_sensitive_actions()
+    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()
+
+
+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 (lazy-loaded)
+
+    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
+
+    Performance:
+        - Uses lazy-loaded defaults (only loaded on first use)
+        - O(1) frozenset lookups for action matching
+    """
+    # 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()
+
+    # Apply ignore_patterns to filter out default actions
+    # This allows users to exclude specific actions from the default 490 actions
+    default_actions = config.filter_actions(default_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
+    # Config is now flat (no longer nested under sensitive_action_check)
+    sensitive_actions_config = config.config.get("sensitive_actions")
+    sensitive_patterns_config = config.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)
+
+    # Apply ignore_patterns to filter the final matched actions
+    # This ensures ignore_patterns work for:
+    # 1. Default actions (490 actions from Python modules)
+    # 2. Custom sensitive_actions configuration
+    # 3. Custom sensitive_action_patterns configuration
+    if matched_actions and config.ignore_patterns:
+        filtered_matched = config.filter_actions(frozenset(matched_actions))
+        matched_actions = list(filtered_matched)
+        # Update is_sensitive based on filtered results
+        is_sensitive = len(matched_actions) > 0
+
+    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 from centralized ignore_patterns module
+                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 using centralized cache
+            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 using centralized cache
+            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,86 @@
+"""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 iam_validator.core.aws_service 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) -> re.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/checks/wildcard_action.py

@@ -0,0 +1,58 @@
+"""Wildcard action check - detects Action: '*' in IAM policies."""
+
+from typing import ClassVar
+
+from iam_validator.core.aws_service 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."""
+
+    check_id: ClassVar[str] = "wildcard_action"
+    description: ClassVar[str] = "Checks for wildcard actions (*)"
+    default_severity: ClassVar[str] = "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 `"*"` (wildcard action).'
+            )
+            suggestion = config.config.get(
+                "suggestion",
+                "Replace wildcard with specific actions needed for your use case",
+            )
+            example = config.config.get("example", "")
+
+            issues.append(
+                ValidationIssue(
+                    severity=self.get_severity(config),
+                    statement_sid=statement.sid,
+                    statement_index=statement_idx,
+                    issue_type="overly_permissive",
+                    message=message,
+                    suggestion=suggestion,
+                    example=example if example else None,
+                    line_number=statement.line_number,
+                    field_name="action",
+                )
+            )
+
+        return issues