iam-policy-validator 1.5.0__py3-none-any.whl → 1.6.0__py3-none-any.whl

iam_validator/core/models.py

@@ -45,9 +45,22 @@ class ResourceType(BaseModel):
     model_config = ConfigDict(populate_by_name=True)
 
     name: str = Field(alias="Name")
-    arn_pattern: str | None = Field(default=None, alias="ARNPattern")
+    arn_formats: list[str] | None = Field(default=None, alias="ARNFormats")
     condition_keys: list[str] | None = Field(default_factory=list, alias="ConditionKeys")
 
+    @property
+    def arn_pattern(self) -> str | None:
+        """
+        Get the first ARN format for backwards compatibility.
+
+        AWS provides ARN formats as an array (ARNFormats), but most code
+        just needs a single pattern. This property returns the first one.
+
+        Returns:
+            First ARN format string, or None if no formats are defined
+        """
+        return self.arn_formats[0] if self.arn_formats else None
+
 
 class ConditionKey(BaseModel):
     """Details about an AWS condition key."""

iam_validator/core/policy_checks.py

@@ -491,7 +491,7 @@ async def validate_policies(
     if not use_registry:
         # Legacy path - use old PolicyValidator
         # Load config for cache settings even in legacy mode
-        from iam_validator.core.config_loader import ConfigLoader
+        from iam_validator.core.config.config_loader import ConfigLoader
 
         config = ConfigLoader.load_config(explicit_path=config_path, allow_missing=True)
         cache_enabled = config.get_setting("cache_enabled", True)
@@ -519,7 +519,7 @@ async def validate_policies(
 
     # New path - use CheckRegistry system
     from iam_validator.core.check_registry import create_default_registry
-    from iam_validator.core.config_loader import ConfigLoader
+    from iam_validator.core.config.config_loader import ConfigLoader
 
     # Load configuration
     config = ConfigLoader.load_config(explicit_path=config_path, allow_missing=True)
@@ -630,8 +630,8 @@ async def _validate_policy_with_registry(
 
     # Execute all statement-level checks for each statement
     for idx, statement in enumerate(policy.statement):
-        # Execute all registered checks in parallel
-        issues = await registry.execute_checks_parallel(statement, idx, fetcher)
+        # Execute all registered checks in parallel (with ignore_patterns filtering)
+        issues = await registry.execute_checks_parallel(statement, idx, fetcher, policy_file)
 
         # Add issues to result
         result.issues.extend(issues)

iam_validator/core/pr_commenter.py

@@ -313,7 +313,7 @@ async def post_report_to_pr(
         report = ValidationReport.model_validate(report_data)
 
         # Load config to get fail_on_severity setting
-        from iam_validator.core.config_loader import ConfigLoader
+        from iam_validator.core.config.config_loader import ConfigLoader
 
         config = ConfigLoader.load_config(config_path)
         fail_on_severities = config.get_setting("fail_on_severity", ["error", "critical"])

iam_validator/sdk/__init__.py

@@ -0,0 +1,187 @@
+"""
+IAM Policy Validator SDK - Public API for library usage.
+
+This module provides the complete public API for using IAM Policy Validator
+as a Python library. It exposes both high-level convenience functions and
+low-level components for custom integrations.
+
+Quick Start:
+    Basic validation:
+    >>> from iam_validator.sdk import validate_file
+    >>> result = await validate_file("policy.json")
+    >>> print(f"Valid: {result.is_valid}")
+
+    With context manager:
+    >>> from iam_validator.sdk import validator
+    >>> async with validator() as v:
+    ...     result = await v.validate_file("policy.json")
+    ...     v.generate_report([result])
+
+    Policy manipulation:
+    >>> from iam_validator.sdk import parse_policy, get_policy_summary
+    >>> policy = parse_policy(policy_json)
+    >>> summary = get_policy_summary(policy)
+    >>> print(f"Actions: {summary['action_count']}")
+
+    Custom check development:
+    >>> from iam_validator.sdk import PolicyCheck, CheckHelper
+    >>> class MyCheck(PolicyCheck):
+    ...     @property
+    ...     def check_id(self) -> str:
+    ...         return "my_check"
+    ...     async def execute(self, statement, idx, fetcher, config):
+    ...         helper = CheckHelper(fetcher)
+    ...         # Use helper.arn_matches(), helper.create_issue(), etc.
+    ...         return []
+"""
+
+# === High-level validation functions (shortcuts) ===
+# === AWS utilities ===
+from iam_validator.core.aws_fetcher import AWSServiceFetcher
+
+# === Core validation components (for advanced usage) ===
+from iam_validator.core.check_registry import CheckRegistry, PolicyCheck
+
+# === ValidatorConfiguration ===
+from iam_validator.core.config.config_loader import ValidatorConfig, load_validator_config
+
+# === Reporting ===
+from iam_validator.core.formatters.csv import CSVFormatter
+from iam_validator.core.formatters.html import HTMLFormatter
+from iam_validator.core.formatters.json import JSONFormatter
+from iam_validator.core.formatters.markdown import MarkdownFormatter
+from iam_validator.core.formatters.sarif import SARIFFormatter
+
+# === Models (for type hints and inspection) ===
+from iam_validator.core.models import (
+    IAMPolicy,
+    PolicyValidationResult,
+    Statement,
+    ValidationIssue,
+)
+from iam_validator.core.policy_checks import validate_policies
+from iam_validator.core.policy_loader import PolicyLoader
+from iam_validator.core.report import ReportGenerator
+
+# === ARN matching utilities ===
+from iam_validator.sdk.arn_matching import (
+    arn_matches,
+    arn_strictly_valid,
+    convert_aws_pattern_to_wildcard,
+    is_glob_match,
+)
+
+# === Context managers ===
+from iam_validator.sdk.context import (
+    ValidationContext,
+    validator,
+    validator_from_config,
+)
+
+# === Public exceptions ===
+from iam_validator.sdk.exceptions import (
+    AWSServiceError,
+    ConfigurationError,
+    IAMValidatorError,
+    InvalidPolicyFormatError,
+    PolicyLoadError,
+    PolicyValidationError,
+    UnsupportedPolicyTypeError,
+)
+
+# === Custom check development ===
+from iam_validator.sdk.helpers import CheckHelper, expand_actions
+
+# === Policy manipulation utilities ===
+from iam_validator.sdk.policy_utils import (
+    extract_actions,
+    extract_condition_keys,
+    extract_resources,
+    find_statements_with_action,
+    find_statements_with_resource,
+    get_policy_summary,
+    has_public_access,
+    is_resource_policy,
+    merge_policies,
+    normalize_policy,
+    parse_policy,
+    policy_to_dict,
+    policy_to_json,
+)
+from iam_validator.sdk.shortcuts import (
+    count_issues_by_severity,
+    get_issues,
+    quick_validate,
+    validate_directory,
+    validate_file,
+    validate_json,
+)
+
+__all__ = [
+    # === High-level shortcuts ===
+    "validate_file",
+    "validate_directory",
+    "validate_json",
+    "quick_validate",
+    "get_issues",
+    "count_issues_by_severity",
+    # === Context managers ===
+    "validator",
+    "validator_from_config",
+    "ValidationContext",
+    # === Policy utilities ===
+    "parse_policy",
+    "normalize_policy",
+    "extract_actions",
+    "extract_resources",
+    "extract_condition_keys",
+    "find_statements_with_action",
+    "find_statements_with_resource",
+    "merge_policies",
+    "get_policy_summary",
+    "policy_to_json",
+    "policy_to_dict",
+    "is_resource_policy",
+    "has_public_access",
+    # === ARN utilities ===
+    "arn_matches",
+    "arn_strictly_valid",
+    "is_glob_match",
+    "convert_aws_pattern_to_wildcard",
+    # === Custom check development ===
+    "PolicyCheck",
+    "CheckRegistry",
+    "CheckHelper",
+    "expand_actions",
+    # === Core validation (advanced) ===
+    "validate_policies",
+    "PolicyLoader",
+    # === Reporting ===
+    "ReportGenerator",
+    "JSONFormatter",
+    "HTMLFormatter",
+    "CSVFormatter",
+    "MarkdownFormatter",
+    "SARIFFormatter",
+    # === Models ===
+    "ValidationIssue",
+    "PolicyValidationResult",
+    "IAMPolicy",
+    "Statement",
+    # === ValidatorConfiguration ===
+    "ValidatorConfig",
+    "load_validator_config",
+    # === AWS utilities ===
+    "AWSServiceFetcher",
+    # === Exceptions ===
+    "IAMValidatorError",
+    "PolicyLoadError",
+    "PolicyValidationError",
+    "ConfigurationError",
+    "AWSServiceError",
+    "InvalidPolicyFormatError",
+    "UnsupportedPolicyTypeError",
+]
+
+# SDK version
+__version__ = "0.1.0"

iam_validator/sdk/arn_matching.py

@@ -0,0 +1,274 @@
+"""
+ARN pattern matching utilities for IAM policy validation.
+
+This module provides functions for matching ARN patterns with glob support.
+Portions of this code are derived from or inspired by Parliament's ARN matching
+implementation.
+
+Original work Copyright 2019 Duo Security (BSD 3-Clause License)
+Modifications and additions Copyright 2024 (MIT License)
+
+Parliament: https://github.com/duo-labs/parliament
+License: https://github.com/duo-labs/parliament/blob/master/LICENSE
+
+The is_glob_match() function is adapted from Parliament's implementation.
+See: https://github.com/duo-labs/parliament/issues/36#issuecomment-574001764
+"""
+
+import re
+
+
+def arn_matches(
+    arn_pattern: str,
+    arn: str,
+    resource_type: str | None = None,
+) -> bool:
+    """
+    Check if an ARN matches a pattern with glob support.
+
+    Both the pattern and ARN can contain wildcards (*). This is useful for
+    validating that policy resources match the required format for actions.
+
+    Args:
+        arn_pattern: ARN pattern (e.g., from AWS docs), can have wildcards
+        arn: ARN from policy, can have wildcards
+        resource_type: Optional resource type (e.g., "bucket", "object") for special handling
+
+    Returns:
+        True if ARN could match the pattern
+
+    Examples:
+        >>> arn_matches("arn:*:s3:::*/*", "arn:aws:s3:::bucket/key")
+        True
+
+        >>> arn_matches("arn:*:s3:::*/*", "arn:aws:s3:::bucket")
+        False
+
+        >>> # Both can have wildcards
+        >>> arn_matches("arn:*:s3:::*/*", "arn:aws:s3:::*personalize*")
+        True  # Could match "arn:aws:s3:::personalize/file"
+
+        >>> # Special case: S3 buckets can't have /
+        >>> arn_matches("arn:*:s3:::*", "arn:aws:s3:::bucket/key", resource_type="bucket")
+        False
+    """
+    # Wildcard shortcuts
+    if arn_pattern == "*" or arn == "*":
+        return True
+
+    # Special case for S3 buckets - no "/" allowed
+    if resource_type and "bucket" in resource_type.lower():
+        # Strip variables like ${aws:username} before checking
+        arn_without_vars = _strip_variables_from_arn(arn)
+        if "/" in arn_without_vars:
+            return False
+
+    # Parse ARN into parts
+    pattern_parts = arn_pattern.split(":")
+    arn_parts = arn.split(":")
+
+    # ARN must have at least 6 parts: arn:partition:service:region:account:resource
+    if len(pattern_parts) < 6 or len(arn_parts) < 6:
+        # Invalid ARN format
+        return False
+
+    # Match first 5 parts (arn:partition:service:region:account)
+    for i in range(5):
+        pattern_part = pattern_parts[i]
+        arn_part = arn_parts[i]
+
+        # Pattern wildcard matches any non-empty value
+        if pattern_part == "*" and arn_part != "":
+            continue
+        # ARN wildcard matches anything
+        elif arn_part == "*":
+            continue
+        # Exact match
+        elif pattern_part == arn_part:
+            continue
+        else:
+            # No match
+            return False
+
+    # Match resource ID (everything after 5th colon)
+    pattern_id = ":".join(pattern_parts[5:])
+    arn_id = ":".join(arn_parts[5:])
+
+    # Replace variables like [key] with wildcard
+    arn_id = re.sub(r"\[.+?\]", "*", arn_id)
+
+    return is_glob_match(pattern_id, arn_id)
+
+
+def arn_strictly_valid(
+    arn_pattern: str,
+    arn: str,
+    resource_type: str | None = None,
+) -> bool:
+    """
+    Strictly validate ARN against pattern with resource type checking.
+
+    This is stricter than arn_matches() and enforces:
+    - Resource type must be present and match
+    - No wildcards in resource type portion
+    - No extra colons in resource ID
+
+    Args:
+        arn_pattern: ARN pattern from AWS service definition
+        arn: ARN from policy
+        resource_type: Optional resource type for additional validation
+
+    Returns:
+        True if ARN strictly matches the pattern
+
+    Examples:
+        >>> # Valid: has resource type "user"
+        >>> arn_strictly_valid("arn:*:iam::*:user/*", "arn:aws:iam::123456789012:user/alice")
+        True
+
+        >>> # Invalid: missing resource type
+        >>> arn_strictly_valid("arn:*:iam::*:user/*", "arn:aws:iam::123456789012:u*")
+        False
+    """
+    # First check basic match
+    if not arn_matches(arn_pattern, arn, resource_type):
+        return False
+
+    # Parse ARNs
+    pattern_parts = arn_pattern.split(":")
+    arn_parts = arn.split(":")
+
+    pattern_id = ":".join(pattern_parts[5:])
+    arn_id = ":".join(arn_parts[5:])
+
+    # Check if pattern has a resource type component
+    # Example: "user/alice" has resource type "user"
+    # Regex: resource type word followed by : or / (excluding patterns starting with *)
+    resource_type_match = re.match(r"(^[^\*][\w-]+)[\/\:](.+)", pattern_id)
+
+    if resource_type_match and arn_id != "*":
+        expected_resource_type = resource_type_match.group(1)
+
+        # ARN must start with the same resource type
+        # Invalid: arn:aws:iam::123456789012:u* (wildcards not allowed in resource type)
+        if not arn_id.startswith(expected_resource_type):
+            return False
+
+    # Check for invalid colons in resource ID
+    # Strip variables first
+    arn_id_without_vars = _strip_variables_from_arn(arn_id)
+
+    # If ARN has colons but pattern doesn't, it's invalid
+    if ":" in arn_id_without_vars and ":" not in pattern_id:
+        return False
+
+    return True
+
+
+def is_glob_match(s1: str, s2: str) -> bool:
+    """
+    Recursive glob pattern matching for two strings.
+
+    Both strings can contain wildcards (*). This implements a recursive
+    algorithm that handles all combinations of wildcard positions.
+
+    Args:
+        s1: First string (can contain *)
+        s2: Second string (can contain *)
+
+    Returns:
+        True if strings could match
+
+    Examples:
+        >>> is_glob_match("*/*", "*personalize*")
+        True
+
+        >>> is_glob_match("*/*", "mybucket")
+        False
+
+        >>> is_glob_match("*mybucket", "*myotherthing")
+        False
+
+        >>> is_glob_match("test*", "test123")
+        True
+
+    Note:
+        This is adapted from Parliament's implementation:
+        https://github.com/duo-labs/parliament/issues/36#issuecomment-574001764
+    """
+    # If strings are equal, TRUE
+    if s1 == s2:
+        return True
+
+    # If either string is all wildcards, TRUE
+    if (s1 and all(c == "*" for c in s1)) or (s2 and all(c == "*" for c in s2)):
+        return True
+
+    # If either string is empty, FALSE (already handled both empty above)
+    if not s1 or not s2:
+        return False
+
+    # At this point, both strings are non-empty
+    # If both start with *, TRUE if match first with remainder of second
+    # or second with remainder of first
+    if s1[0] == s2[0] == "*":
+        return is_glob_match(s1[1:], s2) or is_glob_match(s1, s2[1:])
+
+    # If s1 starts with *, TRUE if remainder of s1 matches any suffix of s2
+    if s1[0] == "*":
+        return any(is_glob_match(s1[1:], s2[i:]) for i in range(len(s2) + 1))
+
+    # If s2 starts with *, TRUE if remainder of s2 matches any suffix of s1
+    if s2[0] == "*":
+        return any(is_glob_match(s1[i:], s2[1:]) for i in range(len(s1) + 1))
+
+    # TRUE if both have same first character and remainders match
+    return s1[0] == s2[0] and is_glob_match(s1[1:], s2[1:])
+
+
+def _strip_variables_from_arn(arn: str, replace_with: str = "") -> str:
+    """
+    Strip AWS policy variables from ARN.
+
+    Examples:
+        ${aws:username} → ""
+        bucket-${aws:username} → "bucket-"
+
+    Args:
+        arn: ARN string that may contain variables
+        replace_with: What to replace variables with (default: empty string)
+
+    Returns:
+        ARN with variables replaced
+    """
+    # Match ${aws.whatever} or ${aws:whatever}
+    return re.sub(r"\$\{aws[\.:][\w\/]+\}", replace_with, arn)
+
+
+def convert_aws_pattern_to_wildcard(pattern: str) -> str:
+    """
+    Convert AWS ARN pattern format to wildcard pattern for matching.
+
+    AWS provides ARN patterns with placeholders like ${Partition}, ${BucketName},
+    etc. This function converts them to wildcard (*) patterns that can be used
+    with arn_matches() and arn_strictly_valid().
+
+    Args:
+        pattern: ARN pattern from AWS service definition
+
+    Returns:
+        ARN pattern with placeholders replaced by wildcards
+
+    Examples:
+        >>> convert_aws_pattern_to_wildcard("arn:${Partition}:s3:::${BucketName}/${ObjectName}")
+        "arn:*:s3:::*/*"
+
+        >>> convert_aws_pattern_to_wildcard("arn:${Partition}:iam::${Account}:user/${UserNameWithPath}")
+        "arn:*:iam::*:user/*"
+
+        >>> convert_aws_pattern_to_wildcard("arn:${Partition}:ec2:${Region}:${Account}:instance/${InstanceId}")
+        "arn:*:ec2:*:*:instance/*"
+    """
+    # Replace all ${...} placeholders with *
+    # Matches ${Partition}, ${BucketName}, ${Account}, etc.
+    return re.sub(r"\$\{[^}]+\}", "*", pattern)