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

iam_validator/checks/sid_uniqueness.py

@@ -0,0 +1,170 @@
+"""Statement ID (SID) uniqueness and format check.
+
+This check validates that Statement IDs (Sids):
+1. Are unique within a policy
+2. Follow AWS naming requirements (alphanumeric, hyphens, underscores only - no spaces)
+
+According to AWS best practices, while not strictly required, having unique SIDs
+makes it easier to reference specific statements and improves policy maintainability.
+
+This is implemented as a policy-level check that runs once when processing the first
+statement, examining all statements in the policy to find duplicates and format issues.
+"""
+
+import re
+from collections import Counter
+
+from iam_validator.core.aws_fetcher import AWSServiceFetcher
+from iam_validator.core.check_registry import CheckConfig, PolicyCheck
+from iam_validator.core.models import IAMPolicy, Statement, ValidationIssue
+
+
+def _check_sid_uniqueness_impl(policy: IAMPolicy, severity: str) -> list[ValidationIssue]:
+    """Implementation of SID uniqueness and format checking.
+
+    Args:
+        policy: IAM policy to validate
+        severity: Severity level for issues found
+
+    Returns:
+        List of ValidationIssue objects for duplicate or invalid SIDs
+    """
+    issues: list[ValidationIssue] = []
+
+    # AWS SID requirements: alphanumeric characters, hyphens, and underscores only
+    # No spaces allowed
+    sid_pattern = re.compile(r"^[a-zA-Z0-9_-]+$")
+
+    # Collect all SIDs (ignoring None/empty values) and check format
+    sids_with_indices: list[tuple[str, int]] = []
+    for idx, statement in enumerate(policy.statement):
+        if statement.sid:  # Only check statements that have a SID
+            # Check SID format
+            if not sid_pattern.match(statement.sid):
+                # Identify the issue
+                if " " in statement.sid:
+                    issue_msg = f"Statement ID '{statement.sid}' contains spaces, which are not allowed by AWS"
+                    suggestion = (
+                        f"Remove spaces from the SID. Example: '{statement.sid.replace(' ', '')}'"
+                    )
+                else:
+                    invalid_chars = "".join(
+                        set(c for c in statement.sid if not c.isalnum() and c not in "_-")
+                    )
+                    issue_msg = f"Statement ID '{statement.sid}' contains invalid characters: {invalid_chars}"
+                    suggestion = (
+                        "SIDs must contain only alphanumeric characters, hyphens, and underscores"
+                    )
+
+                issues.append(
+                    ValidationIssue(
+                        severity="error",  # Invalid SID format is an error
+                        statement_sid=statement.sid,
+                        statement_index=idx,
+                        issue_type="invalid_sid_format",
+                        message=issue_msg,
+                        suggestion=suggestion,
+                        line_number=statement.line_number,
+                    )
+                )
+
+            sids_with_indices.append((statement.sid, idx))
+
+    # Find duplicates
+    sid_counts = Counter(sid for sid, _ in sids_with_indices)
+    duplicate_sids = {sid: count for sid, count in sid_counts.items() if count > 1}
+
+    # Create issues for each duplicate SID
+    for duplicate_sid, count in duplicate_sids.items():
+        # Find all statement indices with this SID
+        indices = [idx for sid, idx in sids_with_indices if sid == duplicate_sid]
+
+        # Create an issue for each occurrence except the first
+        # (the first occurrence is "original", subsequent ones are "duplicates")
+        for idx in indices[1:]:
+            statement = policy.statement[idx]
+            # Convert to 1-indexed statement numbers for user-facing message
+            statement_numbers = ", ".join(f"#{i + 1}" for i in indices)
+            issues.append(
+                ValidationIssue(
+                    severity=severity,
+                    statement_sid=duplicate_sid,
+                    statement_index=idx,
+                    issue_type="duplicate_sid",
+                    message=f"Statement ID '{duplicate_sid}' is used {count} times in this policy (found in statements {statement_numbers})",
+                    suggestion="Change this SID to a unique value. Statement IDs help identify and reference specific statements, so duplicates can cause confusion.",
+                    line_number=statement.line_number,
+                )
+            )
+
+    return issues
+
+
+class SidUniquenessCheck(PolicyCheck):
+    """Validates that Statement IDs (Sids) are unique within a policy.
+
+    This is a special policy-level check that examines all statements together.
+    It only runs once when processing the first statement to avoid duplicate work.
+    """
+
+    @property
+    def check_id(self) -> str:
+        return "sid_uniqueness"
+
+    @property
+    def description(self) -> str:
+        return "Validates that Statement IDs (Sids) are unique and follow AWS naming requirements (no spaces)"
+
+    @property
+    def default_severity(self) -> str:
+        return "warning"
+
+    async def execute(
+        self,
+        statement: Statement,
+        statement_idx: int,
+        fetcher: AWSServiceFetcher,
+        config: CheckConfig,
+    ) -> list[ValidationIssue]:
+        """Execute the SID uniqueness check at statement level.
+
+        This is a policy-level check, so statement-level execution returns empty.
+        The actual check runs in execute_policy() which has access to all statements.
+
+        Args:
+            statement: The IAM policy statement (unused)
+            statement_idx: Index of the statement in the policy (unused)
+            fetcher: AWS service fetcher (unused for this check)
+            config: Configuration for this check instance (unused)
+
+        Returns:
+            Empty list (actual check runs in execute_policy())
+        """
+        del statement, statement_idx, fetcher, config  # Unused
+        # This is a policy-level check - execution happens in execute_policy()
+        return []
+
+    async def execute_policy(
+        self,
+        policy: IAMPolicy,
+        policy_file: str,
+        fetcher: AWSServiceFetcher,
+        config: CheckConfig,
+        **kwargs,
+    ) -> list[ValidationIssue]:
+        """Execute the SID uniqueness check on the entire policy.
+
+        This method examines all statements together to find duplicate SIDs.
+
+        Args:
+            policy: The complete IAM policy to validate
+            policy_file: Path to the policy file (unused, kept for API consistency)
+            fetcher: AWS service fetcher (unused for this check)
+            config: Configuration for this check instance
+
+        Returns:
+            List of ValidationIssue objects for duplicate SIDs
+        """
+        del policy_file, fetcher  # Unused
+        severity = self.get_severity(config)
+        return _check_sid_uniqueness_impl(policy, severity)

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,294 @@
+"""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
+- LRU cache for compiled regex patterns
+- Lazy loading of default actions from modular data structure
+"""
+
+import re
+from functools import lru_cache
+from re import Pattern
+
+from iam_validator.core.check_registry import CheckConfig
+from iam_validator.core.config.sensitive_actions import get_sensitive_actions
+
+# 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()
+
+
+# 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 (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()
+
+    # 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)
+
+    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,87 @@
+"""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