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

iam_validator/sdk/context.py

@@ -0,0 +1,222 @@
+"""
+Context managers for common validation workflows.
+
+This module provides context managers that handle resource lifecycle
+and make the validation API more convenient to use.
+"""
+
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from iam_validator.core.aws_fetcher import AWSServiceFetcher
+from iam_validator.core.models import PolicyValidationResult
+from iam_validator.core.policy_checks import validate_policies
+from iam_validator.core.policy_loader import PolicyLoader
+from iam_validator.core.report import ReportGenerator
+
+
+class ValidationContext:
+    """
+    Validation context that provides convenience methods with shared resources.
+
+    This class maintains a shared AWSServiceFetcher and configuration
+    across multiple validation operations, improving performance.
+    """
+
+    def __init__(
+        self,
+        fetcher: AWSServiceFetcher,
+        config_path: str | None = None,
+    ):
+        """
+        Initialize validation context.
+
+        Args:
+            fetcher: AWS service fetcher instance
+            config_path: Optional path to configuration file
+        """
+        self.fetcher = fetcher
+        self.config_path = config_path
+        self.loader = PolicyLoader()
+
+    async def validate_file(self, file_path: str | Path) -> PolicyValidationResult:
+        """
+        Validate a single IAM policy file.
+
+        Args:
+            file_path: Path to the policy file
+
+        Returns:
+            PolicyValidationResult for the policy
+        """
+        policies = self.loader.load_from_path(str(file_path))
+
+        if not policies:
+            raise ValueError(f"No IAM policies found in {file_path}")
+
+        results = await validate_policies(
+            policies,
+            config_path=self.config_path,
+        )
+
+        return (
+            results[0]
+            if results
+            else PolicyValidationResult(
+                policy_file=str(file_path),
+                is_valid=False,
+                issues=[],
+            )
+        )
+
+    async def validate_directory(self, dir_path: str | Path) -> list[PolicyValidationResult]:
+        """
+        Validate all IAM policies in a directory.
+
+        Args:
+            dir_path: Path to directory containing policy files
+
+        Returns:
+            List of PolicyValidationResults for all policies found
+        """
+        policies = self.loader.load_from_path(str(dir_path))
+
+        if not policies:
+            raise ValueError(f"No IAM policies found in {dir_path}")
+
+        return await validate_policies(
+            policies,
+            config_path=self.config_path,
+        )
+
+    async def validate_json(
+        self, policy_json: dict, policy_name: str = "inline-policy"
+    ) -> PolicyValidationResult:
+        """
+        Validate an IAM policy from a Python dictionary.
+
+        Args:
+            policy_json: IAM policy as a Python dict
+            policy_name: Name to identify this policy in results
+
+        Returns:
+            PolicyValidationResult for the policy
+        """
+        from iam_validator.core.models import IAMPolicy
+
+        # Parse the dict into an IAMPolicy
+        policy = IAMPolicy(**policy_json)
+
+        results = await validate_policies(
+            [(policy_name, policy)],
+            config_path=self.config_path,
+        )
+
+        return (
+            results[0]
+            if results
+            else PolicyValidationResult(
+                policy_file=policy_name,
+                is_valid=False,
+                issues=[],
+            )
+        )
+
+    def generate_report(
+        self, results: list[PolicyValidationResult], format: str = "console"
+    ) -> str:
+        """
+        Generate a report from validation results.
+
+        Args:
+            results: List of validation results
+            format: Output format (console, json, html, csv, markdown, sarif)
+
+        Returns:
+            Formatted report as string
+        """
+        generator = ReportGenerator()
+        report = generator.generate_report(results)
+
+        if format == "console":
+            # Return empty string for console (it prints directly)
+            generator.print_console_report(report)
+            return ""
+        elif format == "json":
+            from iam_validator.core.formatters.json import JSONFormatter
+
+            return JSONFormatter().format(report)
+        elif format == "html":
+            from iam_validator.core.formatters.html import HTMLFormatter
+
+            return HTMLFormatter().format(report)
+        elif format == "csv":
+            from iam_validator.core.formatters.csv import CSVFormatter
+
+            return CSVFormatter().format(report)
+        elif format == "markdown":
+            from iam_validator.core.formatters.markdown import MarkdownFormatter
+
+            return MarkdownFormatter().format(report)
+        elif format == "sarif":
+            from iam_validator.core.formatters.sarif import SARIFFormatter
+
+            return SARIFFormatter().format(report)
+        else:
+            raise ValueError(f"Unknown format: {format}")
+
+
+@asynccontextmanager
+async def validator(
+    config_path: str | None = None,
+):
+    """
+    Context manager that handles AWS fetcher lifecycle.
+
+    This context manager creates an AWS service fetcher, provides a validation
+    context for performing multiple validations efficiently, and ensures proper
+    cleanup when done.
+
+    Args:
+        config_path: Optional path to configuration file
+
+    Yields:
+        ValidationContext for performing validations
+
+    Example:
+        >>> async with validator() as v:
+        ...     result = await v.validate_file("policy.json")
+        ...     report = v.generate_report([result], format="json")
+        ...
+        ...     # Can do multiple validations with same context
+        ...     result2 = await v.validate_directory("./policies")
+
+    Example with configuration:
+        >>> async with validator(config_path="./iam-validator.yaml") as v:
+        ...     results = await v.validate_directory("./policies")
+        ...     v.generate_report(results, format="console")
+    """
+    fetcher = AWSServiceFetcher()
+    yield ValidationContext(fetcher, config_path)
+
+
+@asynccontextmanager
+async def validator_from_config(config_path: str):
+    """
+    Context manager that loads configuration and creates a validator.
+
+    Convenience wrapper around validator() that loads config from a file.
+
+    Args:
+        config_path: Path to configuration file
+
+    Yields:
+        ValidationContext configured from the config file
+
+    Example:
+        >>> async with validator_from_config("./iam-validator.yaml") as v:
+        ...     results = await v.validate_directory("./policies")
+        ...     v.generate_report(results)
+    """
+    fetcher = AWSServiceFetcher()
+    yield ValidationContext(fetcher, config_path=config_path)

iam_validator/sdk/exceptions.py

@@ -0,0 +1,48 @@
+"""
+Public exception types for the IAM Policy Validator SDK.
+
+This module defines user-facing exceptions that library users might want to catch
+and handle in their code.
+"""
+
+
+class IAMValidatorError(Exception):
+    """Base exception for all IAM Validator errors."""
+
+    pass
+
+
+class PolicyLoadError(IAMValidatorError):
+    """Raised when a policy file cannot be loaded or parsed."""
+
+    pass
+
+
+class PolicyValidationError(IAMValidatorError):
+    """Raised when policy validation fails critically."""
+
+    pass
+
+
+class ConfigurationError(IAMValidatorError):
+    """Raised when configuration is invalid or cannot be loaded."""
+
+    pass
+
+
+class AWSServiceError(IAMValidatorError):
+    """Raised when AWS service data cannot be fetched."""
+
+    pass
+
+
+class InvalidPolicyFormatError(PolicyLoadError):
+    """Raised when policy format is invalid (not valid JSON/YAML or missing required fields)."""
+
+    pass
+
+
+class UnsupportedPolicyTypeError(PolicyLoadError):
+    """Raised when policy type is not supported."""
+
+    pass

iam_validator/sdk/helpers.py

@@ -0,0 +1,177 @@
+"""
+Helper utilities for custom check development.
+
+This module provides high-level helper classes and functions that make it
+easy to develop custom IAM policy checks.
+"""
+
+from iam_validator.checks.utils.wildcard_expansion import expand_wildcard_actions
+from iam_validator.core.aws_fetcher import AWSServiceFetcher
+from iam_validator.core.models import ValidationIssue
+from iam_validator.sdk.arn_matching import arn_matches, arn_strictly_valid
+
+
+class CheckHelper:
+    """
+    All-in-one helper class for custom check development.
+
+    This class provides convenient methods for common check operations like
+    ARN matching, action expansion, and issue creation.
+
+    Example:
+        >>> helper = CheckHelper(fetcher)
+        >>> actions = await helper.expand_actions(["s3:Get*"])
+        >>> if helper.arn_matches("arn:*:s3:::secret-*", resource):
+        ...     issue = helper.create_issue(
+        ...         severity="high",
+        ...         statement_idx=0,
+        ...         message="Sensitive bucket access"
+        ...     )
+    """
+
+    def __init__(self, fetcher: AWSServiceFetcher):
+        """
+        Initialize helper with AWS service fetcher.
+
+        Args:
+            fetcher: AWS service fetcher for retrieving service definitions
+        """
+        self.fetcher = fetcher
+
+    async def expand_actions(
+        self,
+        actions: list[str],
+    ) -> list[str]:
+        """
+        Expand action wildcards to concrete actions.
+
+        Args:
+            actions: List of actions that may contain wildcards (e.g., ["s3:Get*"])
+
+        Returns:
+            List of expanded action strings (e.g., ["s3:GetObject", "s3:GetObjectVersion"])
+
+        Example:
+            >>> actions = await helper.expand_actions(["s3:Get*"])
+            >>> # Returns: ["s3:GetObject", "s3:GetObjectVersion", ...]
+        """
+        return await expand_wildcard_actions(actions, self.fetcher)
+
+    def arn_matches(
+        self,
+        pattern: str,
+        arn: str,
+        resource_type: str | None = None,
+    ) -> bool:
+        """
+        Check if ARN matches pattern with glob support.
+
+        Args:
+            pattern: ARN pattern (can have wildcards)
+            arn: ARN to check (can have wildcards)
+            resource_type: Optional resource type for special handling
+
+        Returns:
+            True if ARN matches pattern
+
+        Example:
+            >>> helper.arn_matches("arn:*:s3:::secret-*", "arn:aws:s3:::secret-bucket/key")
+            True
+        """
+        return arn_matches(pattern, arn, resource_type)
+
+    def arn_strictly_valid(
+        self,
+        pattern: str,
+        arn: str,
+        resource_type: str | None = None,
+    ) -> bool:
+        """
+        Strictly validate ARN against pattern.
+
+        Args:
+            pattern: ARN pattern from AWS service definition
+            arn: ARN to validate
+            resource_type: Optional resource type
+
+        Returns:
+            True if ARN strictly matches pattern
+        """
+        return arn_strictly_valid(pattern, arn, resource_type)
+
+    def create_issue(
+        self,
+        severity: str,
+        statement_idx: int,
+        message: str,
+        statement_sid: str | None = None,
+        issue_type: str = "custom",
+        action: str | None = None,
+        resource: str | None = None,
+        condition_key: str | None = None,
+        suggestion: str | None = None,
+        line_number: int | None = None,
+    ) -> ValidationIssue:
+        """
+        Create a validation issue with all necessary fields.
+
+        Args:
+            severity: Severity level (critical, high, medium, low, error, warning, info)
+            statement_idx: Index of the statement in the policy
+            message: Human-readable error message
+            statement_sid: Optional statement ID
+            issue_type: Type of issue (default: "custom")
+            action: Optional action that caused the issue
+            resource: Optional resource that caused the issue
+            condition_key: Optional condition key that caused the issue
+            suggestion: Optional suggestion for fixing the issue
+            line_number: Optional line number in source file
+
+        Returns:
+            ValidationIssue object
+        """
+        return ValidationIssue(
+            severity=severity,
+            statement_sid=statement_sid,
+            statement_index=statement_idx,
+            issue_type=issue_type,
+            message=message,
+            action=action,
+            resource=resource,
+            condition_key=condition_key,
+            suggestion=suggestion,
+            line_number=line_number,
+        )
+
+
+async def expand_actions(
+    actions: list[str],
+    fetcher: AWSServiceFetcher | None = None,
+) -> list[str]:
+    """
+    Expand action wildcards to concrete actions.
+
+    This is a standalone function that can be used without CheckHelper.
+
+    Args:
+        actions: List of actions that may contain wildcards
+        fetcher: Optional AWS service fetcher (created if not provided)
+
+    Returns:
+        List of expanded action strings (e.g., ["s3:GetObject", "s3:GetObjectVersion"])
+
+    Example:
+        >>> from iam_validator.sdk import expand_actions
+        >>> actions = await expand_actions(["s3:Get*"])
+        >>> # Returns: ["s3:GetObject", "s3:GetObjectVersion", ...]
+
+    Note:
+        If no fetcher is provided, a temporary one will be created.
+        For better performance when making multiple calls, create a
+        fetcher once and pass it to this function or use CheckHelper.
+    """
+    if fetcher is None:
+        # Create temporary fetcher
+        fetcher = AWSServiceFetcher()
+
+    return await expand_wildcard_actions(actions, fetcher)