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

iam_validator/core/check_registry.py

@@ -15,6 +15,7 @@ from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any
 
 from iam_validator.core.aws_fetcher 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.
 
-        All fields in pattern must match (AND logic).
+        Uses centralized IgnorePatternMatcher for high-performance filtering
+        with cached compiled regex patterns.
+
+        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):
@@ -399,6 +357,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 +389,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 +442,7 @@ class CheckRegistry:
         policy_file: str,
         fetcher: AWSServiceFetcher,
         policy_type: str = "IDENTITY_POLICY",
+        **kwargs,
     ) -> list[ValidationIssue]:
         """
         Execute all enabled policy-level checks.
@@ -487,6 +455,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 +476,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 +557,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 +601,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

iam_validator/core/config/defaults.py

@@ -22,7 +22,6 @@ from iam_validator.core.config.condition_requirements import CONDITION_REQUIREME
 from iam_validator.core.config.principal_requirements import (
     get_default_principal_requirements,
 )
-from iam_validator.core.config.service_principals import DEFAULT_SERVICE_PRINCIPALS
 from iam_validator.core.config.wildcards import (
     DEFAULT_ALLOWED_WILDCARDS,
     DEFAULT_SERVICE_WILDCARDS,
@@ -195,61 +194,68 @@ DEFAULT_CONFIG = {
     # 9. PRINCIPAL VALIDATION
     # ========================================================================
     # Validates Principal elements in resource-based policies
-    # (S3 buckets, SNS topics, SQS queues, etc.)
-    # Only runs when --policy-type RESOURCE_POLICY is specified
+    # Applies to: S3 buckets, SNS topics, SQS queues, Lambda functions, etc.
+    # Only runs when: --policy-type RESOURCE_POLICY
     #
-    # See: iam_validator/core/config/service_principals.py for defaults
+    # Three control mechanisms:
+    #   1. blocked_principals - Block specific principals (deny list)
+    #   2. allowed_principals - Allow only specific principals (whitelist mode)
+    #   3. principal_condition_requirements - Require conditions for principals
+    #   4. allowed_service_principals - Always allow AWS service principals
     "principal_validation": {
         "enabled": True,
         "severity": "high",  # Security issue, not IAM validity error
         "description": "Validates Principal elements in resource policies for security best practices",
-        # blocked_principals: Principals that should NEVER be allowed (deny list)
-        # Default: ["*"] blocks public access to everyone
-        # Examples:
-        #   ["*"]  - Block public access
-        #   ["*", "arn:aws:iam::*:root"]  - Block public + all AWS accounts
+        # blocked_principals: Deny list - these principals are never allowed
+        # Default: ["*"] blocks public access
         "blocked_principals": ["*"],
-        # allowed_principals: When set, ONLY these principals are allowed (whitelist mode)
-        # Leave empty to allow all except blocked principals
-        # Examples:
-        #   []  - Allow all (except blocked)
-        #   ["arn:aws:iam::123456789012:root"]  - Only allow specific account
-        #   ["arn:aws:iam::*:role/OrgAccessRole"]  - Allow specific role in any account
+        # allowed_principals: Whitelist mode - when set, ONLY these are allowed
+        # Default: [] allows all (except blocked)
         "allowed_principals": [],
-        # require_conditions_for: Principals that MUST have specific IAM conditions
-        # Format: {principal_pattern: [required_condition_keys]}
-        # Default: Public access (*) must specify source to limit scope
-        # Examples:
-        #   "*": ["aws:SourceArn"]  - Public access must specify source ARN
-        #   "arn:aws:iam::*:root": ["aws:PrincipalOrgID"]  - Cross-account must be from org
-        "require_conditions_for": {
-            "*": [
-                "aws:SourceArn",
-                "aws:SourceAccount",
-                "aws:SourceVpce",
-                "aws:SourceIp",
-                "aws:SourceOrgID",
-                "aws:SourceOrgPaths",
-            ],
-        },
-        # principal_condition_requirements: Advanced condition requirements for principals
-        # Similar to action_condition_enforcement but for principals
-        # Supports all_of/any_of/none_of logic with rich metadata
-        # Default: 2 critical requirements enabled (public_access, prevent_insecure_transport)
+        # principal_condition_requirements: Require conditions for specific principals
+        # Supports all_of/any_of/none_of logic like action_condition_enforcement
+        # Default: 2 enabled (public_access, prevent_insecure_transport)
         # See: iam_validator/core/config/principal_requirements.py
-        # To customize requirements, use Python API:
-        #   from iam_validator.core.config import get_principal_requirements_by_names
-        #   requirements = get_principal_requirements_by_names(['public_access', 'cross_account_org'])
-        # To disable: set to empty list []
         "principal_condition_requirements": get_default_principal_requirements(),
-        # allowed_service_principals: AWS service principals that are always allowed
-        # Default: 16 common AWS services (cloudfront, s3, lambda, logs, etc.)
-        # These are typically safe as AWS services need access to resources
-        # See: iam_validator/core/config/service_principals.py
-        "allowed_service_principals": list(DEFAULT_SERVICE_PRINCIPALS),
+        # allowed_service_principals: AWS service principals (*.amazonaws.com)
+        # Default: ["aws:*"] allows ALL AWS service principals
+        # Note: "aws:*" is different from "*" (public access)
+        "allowed_service_principals": ["aws:*"],
+    },
+    # ========================================================================
+    # 10. TRUST POLICY VALIDATION
+    # ========================================================================
+    # Validate trust policies (role assumption policies) for security best practices
+    # Ensures assume role actions have appropriate principals and conditions
+    #
+    # Key validations:
+    #   - Action-Principal type matching (e.g., AssumeRoleWithSAML needs Federated)
+    #   - Provider ARN format validation (SAML vs OIDC provider patterns)
+    #   - Required conditions per assume method
+    #
+    # Complements principal_validation check (which validates principal allowlists/blocklists)
+    # This check focuses on action-principal coupling specific to trust policies
+    #
+    # Auto-detection: Only runs on statements with assume role actions
+    "trust_policy_validation": {
+        "enabled": True,  # Enabled by default (auto-detects trust policies)
+        "severity": "high",  # Security issue
+        "description": "Validates trust policies for role assumption security and action-principal coupling",
+        # validation_rules: Custom rules override defaults
+        # Default rules validate:
+        #   - sts:AssumeRole → AWS or Service principals
+        #   - sts:AssumeRoleWithSAML → Federated (SAML provider) with SAML:aud
+        #   - sts:AssumeRoleWithWebIdentity → Federated (OIDC provider)
+        # Example custom rules:
+        # "validation_rules": {
+        #     "sts:AssumeRole": {
+        #         "allowed_principal_types": ["AWS"],  # Only AWS, not Service
+        #         "required_conditions": ["sts:ExternalId"],  # Always require ExternalId
+        #     }
+        # }
     },
     # ========================================================================
-    # 10. POLICY TYPE VALIDATION
+    # 11. POLICY TYPE VALIDATION
     # ========================================================================
     # Validate policy type requirements (new in v1.3.0)
     # Ensures policies conform to the declared type (IDENTITY vs RESOURCE_POLICY)
@@ -264,7 +270,7 @@ DEFAULT_CONFIG = {
         "description": "Validates policies match declared type and enforces RCP requirements",
     },
     # ========================================================================
-    # 11. ACTION-RESOURCE MATCHING
+    # 12. ACTION-RESOURCE MATCHING
     # ========================================================================
     # Validate action-resource matching
     # Ensures resources match the required resource types for actions
@@ -304,7 +310,7 @@ DEFAULT_CONFIG = {
     # See: iam_validator/core/config/sensitive_actions.py for sensitive actions
     # ========================================================================
     # ========================================================================
-    # 12. WILDCARD ACTION
+    # 13. WILDCARD ACTION
     # ========================================================================
     # Check for wildcard actions (Action: "*")
     # Flags statements that allow all actions
@@ -323,7 +329,7 @@ DEFAULT_CONFIG = {
         ),
     },
     # ========================================================================
-    # 13. WILDCARD RESOURCE
+    # 14. WILDCARD RESOURCE
     # ========================================================================
     # Check for wildcard resources (Resource: "*")
     # Flags statements that apply to all resources
@@ -350,7 +356,7 @@ DEFAULT_CONFIG = {
         ),
     },
     # ========================================================================
-    # 14. FULL WILDCARD (CRITICAL)
+    # 15. FULL WILDCARD (CRITICAL)
     # ========================================================================
     # Check for BOTH Action: "*" AND Resource: "*" (CRITICAL)
     # This grants full administrative access (AdministratorAccess equivalent)
@@ -374,7 +380,7 @@ DEFAULT_CONFIG = {
         ),
     },
     # ========================================================================
-    # 15. SERVICE WILDCARD
+    # 16. SERVICE WILDCARD
     # ========================================================================
     # Check for service-level wildcards (e.g., "iam:*", "s3:*", "ec2:*")
     # These grant ALL permissions for a service (often too permissive)
@@ -404,7 +410,7 @@ DEFAULT_CONFIG = {
         ),
     },
     # ========================================================================
-    # 16. SENSITIVE ACTION
+    # 17. SENSITIVE ACTION
     # ========================================================================
     # Check for sensitive actions without IAM conditions
     # Sensitive actions: IAM changes, secrets access, destructive operations
@@ -479,7 +485,7 @@ DEFAULT_CONFIG = {
         ],
     },
     # ========================================================================
-    # 17. ACTION CONDITION ENFORCEMENT
+    # 18. ACTION CONDITION ENFORCEMENT
     # ========================================================================
     # Enforce specific IAM condition requirements for actions
     # Examples: iam:PassRole must specify iam:PassedToService,

iam_validator/core/config/service_principals.py

@@ -1,8 +1,15 @@
 """
-Default service principals for resource policy validation.
+Service principals utilities for resource policy validation.
 
-These are AWS service principals that are commonly used and considered safe
-in resource-based policies (S3 bucket policies, SNS topic policies, etc.).
+This module provides:
+- Default list of common AWS service principals
+- Utility to check if a principal is any AWS service principal
+- Functions to categorize service principals by type
+
+Configuration:
+- Use "*" in allowed_service_principals to allow ALL AWS service principals
+- Use explicit list to restrict to specific services only
+- AWS service principals end with .amazonaws.com or .amazonaws.com.cn
 """
 
 from typing import Final
@@ -58,6 +65,36 @@ def is_allowed_service_principal(principal: str) -> bool:
     return principal in DEFAULT_SERVICE_PRINCIPALS
 
 
+def is_aws_service_principal(principal: str) -> bool:
+    """
+    Check if a principal is an AWS service principal (any AWS service).
+
+    This checks if the principal matches the AWS service principal pattern.
+    AWS service principals typically end with ".amazonaws.com" or ".amazonaws.com.cn"
+
+    Args:
+        principal: Principal to check (e.g., "lambda.amazonaws.com", "s3.amazonaws.com.cn")
+
+    Returns:
+        True if principal matches AWS service principal pattern
+
+    Examples:
+        >>> is_aws_service_principal("lambda.amazonaws.com")
+        True
+        >>> is_aws_service_principal("s3.amazonaws.com.cn")
+        True
+        >>> is_aws_service_principal("arn:aws:iam::123456789012:root")
+        False
+        >>> is_aws_service_principal("*")
+        False
+    """
+    if not isinstance(principal, str):
+        return False
+
+    # AWS service principals end with .amazonaws.com or .amazonaws.com.cn
+    return principal.endswith(".amazonaws.com") or principal.endswith(".amazonaws.com.cn")
+
+
 def get_service_principals_by_category() -> dict[str, tuple[str, ...]]:
     """
     Get service principals organized by service category.