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

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.

iam_validator/core/constants.py

@@ -123,6 +123,23 @@ DEFAULT_HTTP_TIMEOUT_SECONDS = 30.0
 # Time conversion constants
 SECONDS_PER_HOUR = 3600
 
+# ============================================================================
+# Policy Type Restrictions
+# ============================================================================
+
+# AWS services that support Resource Control Policies (RCP)
+# These services can have wildcard actions in RCP policy statements
+# Reference: https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_rcps.html
+RCP_SUPPORTED_SERVICES = frozenset(
+    {
+        "s3",
+        "sts",
+        "sqs",
+        "secretsmanager",
+        "kms",
+    }
+)
+
 # ============================================================================
 # AWS Documentation URLs
 # ============================================================================

iam_validator/core/ignore_patterns.py

@@ -0,0 +1,297 @@
+"""
+Centralized ignore patterns utility with caching and performance optimization.
+
+This module provides high-performance pattern matching for ignore_patterns across
+all checks. Uses LRU caching and compiled regex patterns for optimal performance.
+"""
+
+import re
+from functools import lru_cache
+from typing import Any
+
+from iam_validator.core.models import ValidationIssue
+
+
+# Global regex pattern cache (shared across all checks for maximum efficiency)
+@lru_cache(maxsize=512)
+def compile_pattern(pattern: str) -> re.Pattern[str] | None:
+    """
+    Compile and cache regex patterns.
+
+    Uses LRU cache to avoid recompiling the same patterns across multiple calls.
+    This is critical for performance when the same patterns are used repeatedly.
+
+    This is a public API function used across multiple modules for consistent
+    regex caching.
+
+    Args:
+        pattern: Regex pattern string
+
+    Returns:
+        Compiled pattern or None if invalid
+
+    Performance:
+        - First call: O(n) compile time
+        - Cached calls: O(1) lookup
+    """
+    try:
+        return re.compile(str(pattern), re.IGNORECASE)
+    except re.error:
+        return None
+
+
+class IgnorePatternMatcher:
+    """
+    High-performance pattern matcher for ignore_patterns.
+
+    Features:
+    - Cached compiled regex patterns (LRU cache)
+    - Support for new (simple) and old (verbose) field names
+    - Efficient filtering with early exit optimization
+    - Field-specific validation logic
+
+    Thread-safe: Yes (regex compilation is cached globally)
+    """
+
+    # Supported field name mappings (new -> old for backward compatibility)
+    FIELD_ALIASES = {
+        "filepath": "filepath_regex",
+        "action": "action_matches",
+        "resource": "resource_matches",
+        "sid": "statement_sid",
+        "condition_key": "condition_key_matches",
+    }
+
+    @staticmethod
+    def should_ignore_issue(
+        issue: ValidationIssue,
+        filepath: str,
+        ignore_patterns: list[dict[str, Any]],
+    ) -> bool:
+        """
+        Check if a ValidationIssue should be ignored based on patterns.
+
+        Pattern Matching Logic:
+        - Multiple fields in ONE pattern = AND logic (all must match)
+        - Multiple patterns = OR logic (any pattern matches → ignore)
+
+        Args:
+            issue: The validation issue to check
+            filepath: Path to the policy file
+            ignore_patterns: List of pattern dictionaries
+
+        Returns:
+            True if the issue should be ignored
+
+        Performance:
+            - Early exit on first match (OR logic)
+            - Cached regex compilation
+            - O(p * f) where p=patterns, f=fields per pattern
+        """
+        if not ignore_patterns:
+            return False
+
+        for pattern in ignore_patterns:
+            if IgnorePatternMatcher._matches_pattern(pattern, issue, filepath):
+                return True  # Early exit on first match
+
+        return False
+
+    @staticmethod
+    def filter_actions(
+        actions: frozenset[str],
+        ignore_patterns: list[dict[str, Any]],
+    ) -> frozenset[str]:
+        """
+        Filter actions based on action ignore patterns.
+
+        Only considers patterns that contain an "action" or "action_matches" field.
+        This is optimized for the sensitive_action check which needs to filter
+        actions before creating ValidationIssues.
+
+        Supports both single action patterns and lists:
+        - action: "s3:.*"  # Single regex pattern
+        - action: ["s3:GetObject", "s3:PutObject"]  # List of patterns
+
+        Args:
+            actions: Set of actions to filter
+            ignore_patterns: List of pattern dictionaries
+
+        Returns:
+            Filtered set of actions (actions matching patterns removed)
+
+        Performance:
+            - Extracts action patterns once: O(p) where p=patterns
+            - Filters with cached regex: O(a * p) where a=actions, p=patterns
+            - Early exit per action when match found
+        """
+        if not ignore_patterns:
+            return actions
+
+        # Extract action patterns once (cache-friendly)
+        action_patterns = []
+        for pattern in ignore_patterns:
+            # Support both new and old field names
+            action_regex = pattern.get("action") or pattern.get("action_matches")
+            if action_regex:
+                # Support both single string and list of strings
+                if isinstance(action_regex, list):
+                    action_patterns.extend(action_regex)
+                else:
+                    action_patterns.append(action_regex)
+
+        if not action_patterns:
+            return actions
+
+        # Filter actions with compiled patterns (cached)
+        filtered = set()
+        for action in actions:
+            should_keep = True
+            for pattern_str in action_patterns:
+                compiled = compile_pattern(pattern_str)
+                if compiled and compiled.search(str(action)):
+                    should_keep = False
+                    break  # Early exit on first match
+
+            if should_keep:
+                filtered.add(action)
+
+        return frozenset(filtered)
+
+    @staticmethod
+    def _matches_pattern(
+        pattern: dict[str, Any],
+        issue: ValidationIssue,
+        filepath: str,
+    ) -> bool:
+        """
+        Check if issue matches a single ignore pattern.
+
+        All fields in pattern must match (AND logic).
+        For list-based fields (like action), ANY match from the list counts (OR logic).
+
+        Args:
+            pattern: Pattern dict with optional fields
+            issue: ValidationIssue to check
+            filepath: Path to policy file
+
+        Returns:
+            True if all fields in pattern match the issue
+
+        Performance:
+            - Early exit on first non-match (AND logic)
+            - Uses cached compiled patterns
+        """
+        for field_name, regex_pattern in pattern.items():
+            # Get actual value from issue based on field name
+            actual_value = IgnorePatternMatcher._get_field_value(field_name, issue, filepath)
+
+            # Handle special case: SID with exact match (no regex)
+            if field_name in ("sid", "statement_sid"):
+                # Support both single string and list of strings
+                if isinstance(regex_pattern, list):
+                    # List of SIDs - exact match or regex
+                    matched = False
+                    for single_sid in regex_pattern:
+                        if isinstance(single_sid, str) and "*" not in single_sid:
+                            # Exact match
+                            if issue.statement_sid == single_sid:
+                                matched = True
+                                break
+                        else:
+                            # Regex match
+                            compiled = compile_pattern(str(single_sid))
+                            if compiled and compiled.search(str(issue.statement_sid or "")):
+                                matched = True
+                                break
+                    if not matched:
+                        return False
+                    continue
+                elif isinstance(regex_pattern, str) and "*" not in regex_pattern:
+                    # Single SID - exact match (not a regex)
+                    if issue.statement_sid != regex_pattern:
+                        return False  # Early exit on non-match
+                    continue
+
+            # Regex match for all other cases
+            if actual_value is None:
+                return False  # Early exit on missing value
+
+            # Support list of patterns (OR logic - any match succeeds)
+            if isinstance(regex_pattern, list):
+                matched = False
+                for single_pattern in regex_pattern:
+                    compiled = compile_pattern(str(single_pattern))
+                    if compiled and compiled.search(str(actual_value)):
+                        matched = True
+                        break  # Found a match in the list
+                if not matched:
+                    return False  # None of the patterns matched
+            else:
+                # Single pattern
+                compiled = compile_pattern(str(regex_pattern))
+                if not compiled or not compiled.search(str(actual_value)):
+                    return False  # Early exit on non-match
+
+        return True  # All fields matched
+
+    @staticmethod
+    def _get_field_value(
+        field_name: str,
+        issue: ValidationIssue,
+        filepath: str,
+    ) -> str | None:
+        """
+        Extract field value from issue or filepath.
+
+        Supports both new (simple) and old (verbose) field names for
+        backward compatibility.
+
+        Args:
+            field_name: Name of the field to extract
+            issue: ValidationIssue to extract from
+            filepath: Policy file path
+
+        Returns:
+            Field value as string, or None if field not recognized
+        """
+        # Normalize field name (support both old and new names)
+        if field_name in ("filepath", "filepath_regex"):
+            return filepath
+        elif field_name in ("action", "action_matches"):
+            return issue.action or ""
+        elif field_name in ("resource", "resource_matches"):
+            return issue.resource or ""
+        elif field_name in ("sid", "statement_sid"):
+            return issue.statement_sid or ""
+        elif field_name in ("condition_key", "condition_key_matches"):
+            return issue.condition_key or ""
+        else:
+            # Unknown field - skip (don't fail)
+            return None
+
+
+# Convenience functions for backward compatibility
+def should_ignore_issue(
+    issue: ValidationIssue,
+    filepath: str,
+    ignore_patterns: list[dict[str, Any]],
+) -> bool:
+    """
+    Convenience function for checking if an issue should be ignored.
+
+    See IgnorePatternMatcher.should_ignore_issue() for details.
+    """
+    return IgnorePatternMatcher.should_ignore_issue(issue, filepath, ignore_patterns)
+
+
+def filter_actions(
+    actions: frozenset[str],
+    ignore_patterns: list[dict[str, Any]],
+) -> frozenset[str]:
+    """
+    Convenience function for filtering actions.
+
+    See IgnorePatternMatcher.filter_actions() for details.
+    """
+    return IgnorePatternMatcher.filter_actions(actions, ignore_patterns)

iam_validator/core/models.py

@@ -14,6 +14,7 @@ from iam_validator.core import constants
 PolicyType = Literal[
     "IDENTITY_POLICY",
     "RESOURCE_POLICY",
+    "TRUST_POLICY",  # Trust policies (role assumption policies - subtype of resource policies)
     "SERVICE_CONTROL_POLICY",
     "RESOURCE_CONTROL_POLICY",
 ]
@@ -105,10 +106,10 @@ class ServiceDetail(BaseModel):
 class Statement(BaseModel):
     """IAM policy statement."""
 
-    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
 
     sid: str | None = Field(default=None, alias="Sid")
-    effect: str = Field(alias="Effect")
+    effect: str | None = Field(default=None, alias="Effect")
     action: list[str] | str | None = Field(default=None, alias="Action")
     not_action: list[str] | str | None = Field(default=None, alias="NotAction")
     resource: list[str] | str | None = Field(default=None, alias="Resource")
@@ -135,10 +136,10 @@ class Statement(BaseModel):
 class IAMPolicy(BaseModel):
     """IAM policy document."""
 
-    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
 
-    version: str = Field(alias="Version")
-    statement: list[Statement] = Field(alias="Statement")
+    version: str | None = Field(default=None, alias="Version")
+    statement: list[Statement] | None = Field(default=None, alias="Statement")
     id: str | None = Field(default=None, alias="Id")
 
 
@@ -164,6 +165,9 @@ class ValidationIssue(BaseModel):
     suggestion: str | None = None
     example: str | None = None  # Code example (JSON/YAML) - formatted separately for GitHub
     line_number: int | None = None  # Line number in the policy file (if available)
+    check_id: str | None = (
+        None  # Check that triggered this issue (e.g., "policy_size", "sensitive_action")
+    )
 
     # Severity level constants (ClassVar to avoid Pydantic treating them as fields)
     VALID_SEVERITIES: ClassVar[frozenset[str]] = frozenset(
@@ -282,6 +286,12 @@ class ValidationIssue(BaseModel):
             parts.append("")
             parts.append("</details>")
 
+        # Add check ID at the bottom if available
+        if self.check_id:
+            parts.append("")
+            parts.append("---")
+            parts.append(f"*Check: `{self.check_id}`*")
+
         return "\n".join(parts)