iam-policy-validator 1.7.2__py3-none-any.whl → 1.9.0__py3-none-any.whl

iam_validator/core/check_registry.py

@@ -10,11 +10,12 @@ This module provides a pluggable check system that allows:
 """
 
 import asyncio
-from abc import ABC, abstractmethod
+from abc import ABC
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any
 
-from iam_validator.core.aws_fetcher import AWSServiceFetcher
+from iam_validator.core.aws_service import AWSServiceFetcher
+from iam_validator.core.ignore_patterns import IgnorePatternMatcher
 from iam_validator.core.models import Statement, ValidationIssue
 
 if TYPE_CHECKING:
@@ -36,107 +37,64 @@ class CheckConfig:
     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
+    - filepath: Regex to match file path
+    - action: Regex to match action name
+    - resource: Regex to match resource
+    - sid: Exact SID to match (or regex if ends with .*)
+    - condition_key: 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"
+          - filepath: "test/.*|examples/.*"
+          - filepath: "policies/readonly-.*"
+            action: ".*:(Get|List|Describe).*"
+          - sid: "AllowReadOnlyAccess"
     """
 
     def should_ignore(self, issue: ValidationIssue, filepath: str = "") -> bool:
         """
         Check if issue should be ignored based on ignore patterns.
 
+        Uses centralized IgnorePatternMatcher for high-performance filtering
+        with cached compiled regex 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
+        Performance:
+            - Cached regex compilation (LRU cache)
+            - Early exit optimization
+        """
+        return IgnorePatternMatcher.should_ignore_issue(issue, filepath, self.ignore_patterns)
 
-    def _matches_pattern(
-        self,
-        pattern: dict[str, Any],
-        issue: ValidationIssue,
-        filepath: str,
-        re_module: Any,
-    ) -> bool:
+    def filter_actions(self, actions: frozenset[str]) -> frozenset[str]:
         """
-        Check if issue matches a single ignore pattern.
+        Filter actions based on action ignore patterns.
+
+        Uses centralized IgnorePatternMatcher for high-performance filtering
+        with cached compiled regex patterns.
 
-        All fields in pattern must match (AND logic).
+        This is useful for checks that need to filter a set of actions before
+        creating ValidationIssues (e.g., sensitive_action check).
 
         Args:
-            pattern: Pattern dict with optional fields
-            issue: ValidationIssue to check
-            filepath: Path to policy file
-            re_module: re module for regex matching
+            actions: Set of actions to filter
 
         Returns:
-            True if all fields in pattern match the issue
+            Filtered set of actions (actions matching ignore patterns removed)
+
+        Performance:
+            - Cached regex compilation (LRU cache)
+            - Early exit per action on first match
         """
-        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
+        return IgnorePatternMatcher.filter_actions(actions, self.ignore_patterns)
 
 
 class PolicyCheck(ABC):
@@ -145,38 +103,101 @@ class PolicyCheck(ABC):
 
     To create a custom check:
     1. Inherit from this class
-    2. Implement check_id, description, and execute()
-    3. Register with CheckRegistry
+    2. Implement check_id and description (required)
+    3. Implement either execute() OR execute_policy() (or both)
+    4. Register with CheckRegistry
 
-    Example:
-        class MyCustomCheck(PolicyCheck):
-            check_id = "my_custom_check"
-            description = "Validates custom compliance rules"
+    Two ways to define check_id and description:
+
+    Option 1 - Class attributes (simpler, recommended for static values):
+        from typing import ClassVar
+
+        class MyCheck(PolicyCheck):
+            check_id: ClassVar[str] = "my_check"
+            description: ClassVar[str] = "My check description"
 
             async def execute(self, statement, statement_idx, fetcher, config):
+                return []
+
+        Note: ClassVar annotation is required for Pylance type checker compatibility.
+
+    Option 2 - Property decorators (more flexible, supports dynamic values):
+        class MyCheck(PolicyCheck):
+            @property
+            def check_id(self) -> str:
+                return "my_check"
+
+            @property
+            def description(self) -> str:
+                return "My check description"
+
+            async def execute(self, statement, statement_idx, fetcher, config):
+                return []
+
+    Statement-level check example:
+        from typing import ClassVar
+
+        class MyStatementCheck(PolicyCheck):
+            check_id: ClassVar[str] = "my_statement_check"
+            description: ClassVar[str] = "Validates individual statements"
+
+            async def execute(self, statement, statement_idx, fetcher, config):
+                issues = []
+                # Your validation logic here
+                return issues
+
+    Policy-level check example:
+        from typing import ClassVar
+
+        class MyPolicyCheck(PolicyCheck):
+            check_id: ClassVar[str] = "my_policy_check"
+            description: ClassVar[str] = "Validates entire policy"
+
+            async def execute_policy(self, policy, policy_file, fetcher, config, **kwargs):
                 issues = []
                 # Your validation logic here
                 return issues
     """
 
     @property
-    @abstractmethod
     def check_id(self) -> str:
         """Unique identifier for this check (e.g., 'action_validation')."""
-        pass
+        raise NotImplementedError("Subclasses must define check_id")
 
     @property
-    @abstractmethod
     def description(self) -> str:
         """Human-readable description of what this check does."""
-        pass
+        raise NotImplementedError("Subclasses must define description")
 
     @property
     def default_severity(self) -> str:
         """Default severity level for issues found by this check."""
         return "warning"
 
-    @abstractmethod
+    def __init_subclass__(cls, **kwargs):
+        """
+        Validate that subclasses override at least one execution method.
+
+        This ensures checks implement either execute() OR execute_policy() (or both).
+        If neither is overridden, the check would never produce any results.
+        """
+        super().__init_subclass__(**kwargs)
+
+        # Skip validation for abstract classes
+        if ABC in cls.__bases__:
+            return
+
+        # Check if at least one method is overridden
+        has_execute = cls.execute is not PolicyCheck.execute
+        has_execute_policy = cls.execute_policy is not PolicyCheck.execute_policy
+
+        if not has_execute and not has_execute_policy:
+            raise TypeError(
+                f"Check '{cls.__name__}' must override at least one of: "
+                "execute() for statement-level checks, or "
+                "execute_policy() for policy-level checks"
+            )
+
     async def execute(
         self,
         statement: Statement,
@@ -187,6 +208,10 @@ class PolicyCheck(ABC):
         """
         Execute the check on a policy statement.
 
+        This method is called for statement-level checks. If your check only needs
+        to examine the entire policy (not individual statements), you can leave this
+        as the default implementation and override execute_policy() instead.
+
         Args:
             statement: The IAM policy statement to check
             statement_idx: Index of the statement in the policy
@@ -196,7 +221,8 @@ class PolicyCheck(ABC):
         Returns:
             List of ValidationIssue objects found by this check
         """
-        pass
+        del statement, statement_idx, fetcher, config  # Unused in default implementation
+        return []
 
     async def execute_policy(
         self,
@@ -399,6 +425,10 @@ class CheckRegistry:
                 config = self.get_config(check.check_id)
                 if config:
                     issues = await check.execute(statement, statement_idx, fetcher, config)
+                    # Inject check_id into each issue
+                    for issue in issues:
+                        if issue.check_id is None:
+                            issue.check_id = check.check_id
                     # Filter issues based on ignore_patterns
                     filtered_issues = [
                         issue for issue in issues if not config.should_ignore(issue, filepath)
@@ -427,7 +457,12 @@ class CheckRegistry:
                 check = enabled_checks[idx]
                 print(f"Warning: Check '{check.check_id}' failed: {result}")
             elif isinstance(result, list):
+                check = enabled_checks[idx]
                 config = configs[idx]
+                # Inject check_id into each issue
+                for issue in result:
+                    if issue.check_id is None:
+                        issue.check_id = check.check_id
                 # Filter issues based on ignore_patterns
                 filtered_issues = [
                     issue for issue in result if not config.should_ignore(issue, filepath)
@@ -475,6 +510,7 @@ class CheckRegistry:
         policy_file: str,
         fetcher: AWSServiceFetcher,
         policy_type: str = "IDENTITY_POLICY",
+        **kwargs,
     ) -> list[ValidationIssue]:
         """
         Execute all enabled policy-level checks.
@@ -487,6 +523,7 @@ class CheckRegistry:
             policy_file: Path to the policy file (for context/reporting)
             fetcher: AWS service fetcher for API calls
             policy_type: Type of policy (IDENTITY_POLICY, RESOURCE_POLICY, SERVICE_CONTROL_POLICY)
+            **kwargs: Additional arguments to pass to checks (e.g., raw_policy_dict)
 
         Returns:
             List of all ValidationIssue objects from all policy-level checks
@@ -507,34 +544,61 @@ class CheckRegistry:
                 if config:
                     try:
                         issues = await check.execute_policy(
-                            policy, policy_file, fetcher, config, policy_type=policy_type
+                            policy,
+                            policy_file,
+                            fetcher,
+                            config,
+                            policy_type=policy_type,
+                            **kwargs,
                         )
-                        all_issues.extend(issues)
+                        # Inject check_id into each issue
+                        for issue in issues:
+                            if issue.check_id is None:
+                                issue.check_id = check.check_id
+                        # Filter issues based on ignore_patterns
+                        filtered_issues = [
+                            issue
+                            for issue in issues
+                            if not config.should_ignore(issue, policy_file)
+                        ]
+                        all_issues.extend(filtered_issues)
                     except Exception as e:
                         print(f"Warning: Check '{check.check_id}' failed: {e}")
             return all_issues
 
         # Execute all policy-level checks in parallel
         tasks = []
+        configs = []
         for check in policy_level_checks:
             config = self.get_config(check.check_id)
             if config:
                 task = check.execute_policy(
-                    policy, policy_file, fetcher, config, policy_type=policy_type
+                    policy, policy_file, fetcher, config, policy_type=policy_type, **kwargs
                 )
                 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
         for idx, result in enumerate(results):
             if isinstance(result, Exception):
                 # Log error but continue with other checks
                 check = policy_level_checks[idx]
                 print(f"Warning: Check '{check.check_id}' failed: {result}")
             elif isinstance(result, list):
-                all_issues.extend(result)
+                check = policy_level_checks[idx]
+                config = configs[idx]
+                # Inject check_id into each issue
+                for issue in result:
+                    if issue.check_id is None:
+                        issue.check_id = check.check_id
+                # Filter issues based on ignore_patterns
+                filtered_issues = [
+                    issue for issue in result if not config.should_ignore(issue, policy_file)
+                ]
+                all_issues.extend(filtered_issues)
 
         return all_issues
 
@@ -561,6 +625,11 @@ def create_default_registry(
         # Import and register built-in checks
         from iam_validator import checks
 
+        # 0. FUNDAMENTAL STRUCTURE (Must run FIRST - validates basic policy structure)
+        registry.register(
+            checks.PolicyStructureCheck()
+        )  # Policy-level: Validates required fields, conflicts, valid values
+
         # 1. POLICY STRUCTURE (Checks that examine the entire policy, not individual statements)
         registry.register(
             checks.SidUniquenessCheck()
@@ -600,6 +669,9 @@ def create_default_registry(
         registry.register(
             checks.PrincipalValidationCheck()
         )  # Principal validation (resource policies)
+        registry.register(
+            checks.TrustPolicyValidationCheck()
+        )  # Trust policy validation (role assumption policies)
 
         # Note: policy_type_validation is a standalone function (not a class-based check)
         # and is called separately in the validation flow

iam_validator/core/config/condition_requirements.py

@@ -54,23 +54,75 @@ IAM_PASS_ROLE_REQUIREMENT: Final[dict[str, Any]] = {
 S3_WRITE_ORG_ID: Final[dict[str, Any]] = {
     "actions": ["s3:PutObject"],
     "severity": "medium",
-    "required_conditions": [
-        {
-            "condition_key": "aws:ResourceOrgId",
-            "description": (
-                "Require aws:ResourceAccount, aws:ResourceOrgID or aws:ResourceOrgPaths condition(s) for S3 write actions to enforce organization-level access control"
-            ),
-            "example": (
-                "{\n"
-                '  "Condition": {\n'
-                '    "StringEquals": {\n'
-                '      "aws:ResourceOrgId": "${aws:PrincipalOrgID}"\n'
-                "    }\n"
-                "  }\n"
-                "}"
-            ),
-        },
-    ],
+    "required_conditions": {
+        "any_of": [
+            # Option 1: Use organization-level control with ResourceOrgID
+            {
+                "all_of": [
+                    {
+                        "condition_key": "aws:ResourceOrgID",
+                        "description": "Restrict S3 write actions to resources within your AWS Organization",
+                        "expected_value": "${aws:PrincipalOrgID}",
+                        "example": (
+                            "{\n"
+                            '  "Condition": {\n'
+                            '    "StringEquals": {\n'
+                            '      "aws:ResourceOrgID": "${aws:PrincipalOrgID}",\n'
+                            '      "aws:ResourceAccount": "${aws:PrincipalAccount}"\n'
+                            "    }\n"
+                            "  }\n"
+                            "}"
+                        ),
+                    },
+                    {
+                        "condition_key": "aws:ResourceAccount",
+                        "description": "Ensure the S3 resource belongs to the same AWS account as the principal",
+                        "expected_value": "${aws:PrincipalAccount}",
+                    },
+                ]
+            },
+            # Option 2: Use organization path-based control
+            {
+                "all_of": [
+                    {
+                        "condition_key": "aws:ResourceOrgPaths",
+                        "description": "Restrict S3 write actions to resources within your AWS Organization path",
+                        "expected_value": "${aws:PrincipalOrgPaths}",
+                        "example": (
+                            "{\n"
+                            '  "Condition": {\n'
+                            '    "StringEquals": {\n'
+                            '      "aws:ResourceOrgPaths": "${aws:PrincipalOrgPaths}",\n'
+                            '      "aws:ResourceAccount": "${aws:PrincipalAccount}"\n'
+                            "    }\n"
+                            "  }\n"
+                            "}"
+                        ),
+                    },
+                    {
+                        "condition_key": "aws:ResourceAccount",
+                        "description": "Ensure the S3 resource belongs to the same AWS account as the principal",
+                        "expected_value": "${aws:PrincipalAccount}",
+                    },
+                ]
+            },
+            # Option 3: Account-only control (less restrictive, but still secure)
+            {
+                "condition_key": "aws:ResourceAccount",
+                "description": "Restrict S3 write actions to resources within the same AWS account",
+                "expected_value": "${aws:PrincipalAccount}",
+                "example": (
+                    "{\n"
+                    '  "Condition": {\n'
+                    '    "StringEquals": {\n'
+                    '      "aws:ResourceAccount": "${aws:PrincipalAccount}"\n'
+                    "    }\n"
+                    "  }\n"
+                    "}"
+                ),
+            },
+        ],
+    },
 }
 
 # IP Restrictions - Source IP requirements