iam-policy-validator 1.7.0__py3-none-any.whl

iam_validator/core/config/service_principals.py

@@ -0,0 +1,95 @@
+"""
+Default service principals 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.).
+"""
+
+from typing import Final
+
+# ============================================================================
+# Allowed Service Principals
+# ============================================================================
+# These AWS service principals are commonly used in resource policies
+# and are generally considered safe to allow
+
+DEFAULT_SERVICE_PRINCIPALS: Final[tuple[str, ...]] = (
+    "cloudfront.amazonaws.com",
+    "s3.amazonaws.com",
+    "sns.amazonaws.com",
+    "lambda.amazonaws.com",
+    "logs.amazonaws.com",
+    "events.amazonaws.com",
+    "elasticloadbalancing.amazonaws.com",
+    "cloudtrail.amazonaws.com",
+    "config.amazonaws.com",
+    "backup.amazonaws.com",
+    "cloudwatch.amazonaws.com",
+    "monitoring.amazonaws.com",
+    "ec2.amazonaws.com",
+    "ecs-tasks.amazonaws.com",
+    "eks.amazonaws.com",
+    "apigateway.amazonaws.com",
+)
+
+
+def get_service_principals() -> tuple[str, ...]:
+    """
+    Get tuple of allowed service principals.
+
+    Returns:
+        Tuple of AWS service principal names
+    """
+    return DEFAULT_SERVICE_PRINCIPALS
+
+
+def is_allowed_service_principal(principal: str) -> bool:
+    """
+    Check if a principal is an allowed service principal.
+
+    Args:
+        principal: Principal to check (e.g., "lambda.amazonaws.com")
+
+    Returns:
+        True if principal is in allowed list
+
+    Performance: O(n) but small list (~16 items)
+    """
+    return principal in DEFAULT_SERVICE_PRINCIPALS
+
+
+def get_service_principals_by_category() -> dict[str, tuple[str, ...]]:
+    """
+    Get service principals organized by service category.
+
+    Returns:
+        Dictionary mapping categories to service principal tuples
+    """
+    return {
+        "storage": (
+            "s3.amazonaws.com",
+            "backup.amazonaws.com",
+        ),
+        "compute": (
+            "lambda.amazonaws.com",
+            "ec2.amazonaws.com",
+            "ecs-tasks.amazonaws.com",
+            "eks.amazonaws.com",
+        ),
+        "networking": (
+            "cloudfront.amazonaws.com",
+            "elasticloadbalancing.amazonaws.com",
+            "apigateway.amazonaws.com",
+        ),
+        "monitoring": (
+            "logs.amazonaws.com",
+            "cloudwatch.amazonaws.com",
+            "monitoring.amazonaws.com",
+            "cloudtrail.amazonaws.com",
+        ),
+        "messaging": (
+            "sns.amazonaws.com",
+            "events.amazonaws.com",
+        ),
+        "management": ("config.amazonaws.com",),
+    }

iam_validator/core/config/wildcards.py

@@ -0,0 +1,124 @@
+"""
+Default wildcard configurations for security best practices checks.
+
+These wildcards define which actions are considered "safe" to use with
+Resource: "*" (e.g., read-only describe operations).
+
+Using Python tuples instead of YAML lists provides:
+- Zero parsing overhead
+- Immutable by default (tuples)
+- Better performance
+- Easy PyPI packaging
+"""
+
+from typing import Final
+
+# ============================================================================
+# Allowed Wildcards for Resource: "*"
+# ============================================================================
+# These action patterns are considered safe to use with wildcard resources
+# They are typically read-only operations that need broad resource access
+
+DEFAULT_ALLOWED_WILDCARDS: Final[tuple[str, ...]] = (
+    # Auto Scaling
+    "autoscaling:Describe*",
+    # CloudWatch
+    "cloudwatch:Describe*",
+    "cloudwatch:Get*",
+    "cloudwatch:List*",
+    # DynamoDB
+    "dynamodb:Describe*",
+    # EC2
+    "ec2:Describe*",
+    # Elastic Load Balancing
+    "elasticloadbalancing:Describe*",
+    # IAM (non-sensitive read operations)
+    "iam:Get*",
+    "iam:List*",
+    # KMS
+    "kms:Describe*",
+    # Lambda
+    "lambda:Get*",
+    "lambda:List*",
+    # CloudWatch Logs
+    "logs:Describe*",
+    "logs:Filter*",
+    "logs:Get*",
+    # RDS
+    "rds:Describe*",
+    # Route53
+    "route53:Get*",
+    "route53:List*",
+    # S3 (safe read operations only)
+    "s3:Describe*",
+    "s3:GetBucket*",
+    "s3:GetM*",
+    "s3:List*",
+    # SQS
+    "sqs:Get*",
+    "sqs:List*",
+    # API Gateway
+    "apigateway:GET",
+)
+
+# ============================================================================
+# Service-Level Wildcards (Allowed Services)
+# ============================================================================
+# Services that are allowed to use service-level wildcards like "logs:*"
+# These are typically low-risk monitoring/logging services
+
+DEFAULT_SERVICE_WILDCARDS: Final[tuple[str, ...]] = (
+    "logs",
+    "cloudwatch",
+    "xray",
+)
+
+
+def get_allowed_wildcards() -> tuple[str, ...]:
+    """
+    Get tuple of allowed wildcard action patterns.
+
+    Returns:
+        Tuple of action patterns that are safe to use with Resource: "*"
+    """
+    return DEFAULT_ALLOWED_WILDCARDS
+
+
+def get_allowed_service_wildcards() -> tuple[str, ...]:
+    """
+    Get tuple of services allowed to use service-level wildcards.
+
+    Returns:
+        Tuple of service names (e.g., "logs", "cloudwatch")
+    """
+    return DEFAULT_SERVICE_WILDCARDS
+
+
+def is_allowed_wildcard(pattern: str) -> bool:
+    """
+    Check if a wildcard pattern is in the allowed list.
+
+    Args:
+        pattern: Action pattern to check (e.g., "s3:List*")
+
+    Returns:
+        True if pattern is in allowed wildcards
+
+    Performance: O(n) but typically small list (~25 items)
+    """
+    return pattern in DEFAULT_ALLOWED_WILDCARDS
+
+
+def is_allowed_service_wildcard(service: str) -> bool:
+    """
+    Check if a service is allowed to use service-level wildcards.
+
+    Args:
+        service: Service name (e.g., "logs", "s3")
+
+    Returns:
+        True if service is in allowed list
+
+    Performance: O(n) but very small list (~3 items)
+    """
+    return service in DEFAULT_SERVICE_WILDCARDS

iam_validator/core/constants.py

@@ -0,0 +1,74 @@
+"""
+Core constants for IAM Policy Validator.
+
+This module defines constants used across the validator to ensure consistency
+and provide a single source of truth for shared values. These constants are
+based on AWS service limits and documentation.
+
+References:
+- AWS IAM Policy Size Limits: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_iam-quotas.html
+- AWS ARN Format: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html
+"""
+
+# ============================================================================
+# ARN Validation
+# ============================================================================
+
+# ARN Validation Pattern
+# This pattern is specifically designed for validation and allows wildcards (*) in region and account fields
+# Unlike the parsing pattern in CompiledPatterns, this is more lenient for validation purposes
+# Supports all AWS partitions: aws, aws-cn, aws-us-gov, aws-eusc, aws-iso*
+DEFAULT_ARN_VALIDATION_PATTERN = r"^arn:(aws|aws-cn|aws-us-gov|aws-eusc|aws-iso|aws-iso-b|aws-iso-e|aws-iso-f):[a-z0-9\-]+:[a-z0-9\-*]*:[0-9*]*:.+$"
+
+# Maximum allowed ARN length to prevent ReDoS attacks
+# AWS maximum ARN length is approximately 2048 characters
+MAX_ARN_LENGTH = 2048
+
+# ============================================================================
+# AWS IAM Policy Size Limits
+# ============================================================================
+# These limits are enforced by AWS and policies exceeding them will be rejected
+# Note: AWS does not count whitespace when calculating policy size
+
+# Managed policy maximum size (characters, excluding whitespace)
+MAX_MANAGED_POLICY_SIZE = 6144
+
+# Inline policy maximum size for IAM users (characters, excluding whitespace)
+MAX_INLINE_USER_POLICY_SIZE = 2048
+
+# Inline policy maximum size for IAM groups (characters, excluding whitespace)
+MAX_INLINE_GROUP_POLICY_SIZE = 5120
+
+# Inline policy maximum size for IAM roles (characters, excluding whitespace)
+MAX_INLINE_ROLE_POLICY_SIZE = 10240
+
+# Policy size limits dictionary (for backward compatibility and easy lookup)
+AWS_POLICY_SIZE_LIMITS = {
+    "managed": MAX_MANAGED_POLICY_SIZE,
+    "inline_user": MAX_INLINE_USER_POLICY_SIZE,
+    "inline_group": MAX_INLINE_GROUP_POLICY_SIZE,
+    "inline_role": MAX_INLINE_ROLE_POLICY_SIZE,
+}
+
+# ============================================================================
+# Configuration Defaults
+# ============================================================================
+
+# Default configuration file names (searched in order)
+DEFAULT_CONFIG_FILENAMES = [
+    "iam-validator.yaml",
+    "iam-validator.yml",
+    ".iam-validator.yaml",
+    ".iam-validator.yml",
+]
+
+# ============================================================================
+# GitHub Integration
+# ============================================================================
+
+# Bot identifier for GitHub comments and reviews
+BOT_IDENTIFIER = "🤖 IAM Policy Validator"
+
+# HTML comment markers for identifying bot-generated content (for cleanup/updates)
+SUMMARY_IDENTIFIER = "<!-- iam-policy-validator-summary -->"
+REVIEW_IDENTIFIER = "<!-- iam-policy-validator-review -->"

iam_validator/core/formatters/__init__.py

@@ -0,0 +1,27 @@
+"""Output formatters for IAM Policy Validator."""
+
+from iam_validator.core.formatters.base import (
+    FormatterRegistry,
+    OutputFormatter,
+    get_global_registry,
+)
+from iam_validator.core.formatters.console import ConsoleFormatter
+from iam_validator.core.formatters.csv import CSVFormatter
+from iam_validator.core.formatters.enhanced import EnhancedFormatter
+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
+
+__all__ = [
+    "OutputFormatter",
+    "FormatterRegistry",
+    "get_global_registry",
+    "ConsoleFormatter",
+    "EnhancedFormatter",
+    "JSONFormatter",
+    "MarkdownFormatter",
+    "SARIFFormatter",
+    "CSVFormatter",
+    "HTMLFormatter",
+]

iam_validator/core/formatters/base.py

@@ -0,0 +1,147 @@
+"""Base formatter and registry for output formatters."""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any
+
+from iam_validator.core.models import ValidationReport
+
+logger = logging.getLogger(__name__)
+
+
+class OutputFormatter(ABC):
+    """Base class for all output formatters."""
+
+    @property
+    @abstractmethod
+    def format_id(self) -> str:
+        """Unique identifier for this formatter (e.g., 'json', 'markdown')."""
+        pass
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Human-readable description of the formatter."""
+        pass
+
+    @property
+    def file_extension(self) -> str:
+        """Default file extension for this format."""
+        return "txt"
+
+    @property
+    def content_type(self) -> str:
+        """MIME content type for this format."""
+        return "text/plain"
+
+    @abstractmethod
+    def format(self, report: ValidationReport, **kwargs: Any) -> str:
+        """Format the validation report.
+
+        Args:
+            report: The validation report to format
+            **kwargs: Additional formatter-specific options
+
+        Returns:
+            Formatted string representation of the report
+        """
+        pass
+
+    def format_to_file(self, report: ValidationReport, filepath: str, **kwargs: Any) -> None:
+        """Format report and write to file.
+
+        Args:
+            report: The validation report to format
+            filepath: Path to output file
+            **kwargs: Additional formatter-specific options
+        """
+        output = self.format(report, **kwargs)
+        with open(filepath, "w", encoding="utf-8") as f:
+            f.write(output)
+        logger.info(f"Report written to {filepath} using {self.format_id} formatter")
+
+
+class FormatterRegistry:
+    """Registry for managing output formatters."""
+
+    def __init__(self) -> None:
+        """Initialize the formatter registry."""
+        self._formatters: dict[str, OutputFormatter] = {}
+
+    def register(self, formatter: OutputFormatter) -> None:
+        """Register a new formatter.
+
+        Args:
+            formatter: OutputFormatter instance to register
+        """
+        self._formatters[formatter.format_id] = formatter
+        logger.debug(f"Registered formatter: {formatter.format_id}")
+
+    def unregister(self, format_id: str) -> None:
+        """Unregister a formatter.
+
+        Args:
+            format_id: ID of the formatter to unregister
+        """
+        if format_id in self._formatters:
+            del self._formatters[format_id]
+            logger.debug(f"Unregistered formatter: {format_id}")
+
+    def get_formatter(self, format_id: str) -> OutputFormatter | None:
+        """Get a formatter by ID.
+
+        Args:
+            format_id: ID of the formatter to retrieve
+
+        Returns:
+            OutputFormatter instance or None if not found
+        """
+        return self._formatters.get(format_id)
+
+    def list_formatters(self) -> dict[str, str]:
+        """List all registered formatters.
+
+        Returns:
+            Dictionary of format_id -> description
+        """
+        return {fmt_id: formatter.description for fmt_id, formatter in self._formatters.items()}
+
+    def format_report(self, report: ValidationReport, format_id: str, **kwargs: Any) -> str:
+        """Format a report using the specified formatter.
+
+        Args:
+            report: The validation report to format
+            format_id: ID of the formatter to use
+            **kwargs: Additional formatter-specific options
+
+        Returns:
+            Formatted string representation
+
+        Raises:
+            ValueError: If formatter not found
+        """
+        formatter = self.get_formatter(format_id)
+        if not formatter:
+            available = ", ".join(self._formatters.keys())
+            raise ValueError(f"Formatter '{format_id}' not found. Available: {available}")
+
+        return formatter.format(report, **kwargs)
+
+
+# Global formatter registry
+_global_registry = FormatterRegistry()
+
+
+def get_global_registry() -> FormatterRegistry:
+    """Get the global formatter registry."""
+    return _global_registry
+
+
+def register_formatter(formatter: OutputFormatter) -> None:
+    """Register a formatter in the global registry."""
+    _global_registry.register(formatter)
+
+
+def get_formatter(format_id: str) -> OutputFormatter | None:
+    """Get a formatter from the global registry."""
+    return _global_registry.get_formatter(format_id)

iam_validator/core/formatters/console.py

@@ -0,0 +1,59 @@
+"""Console formatter - Classic console output using report.py."""
+
+from io import StringIO
+
+from rich.console import Console
+
+from iam_validator.core.formatters.base import OutputFormatter
+from iam_validator.core.models import ValidationReport
+
+
+class ConsoleFormatter(OutputFormatter):
+    """Classic console formatter - uses the standard report.py print_console_report output."""
+
+    @property
+    def format_id(self) -> str:
+        return "console"
+
+    @property
+    def description(self) -> str:
+        return "Classic console output with colors and tables"
+
+    def format(self, report: ValidationReport, **kwargs) -> str:
+        """Format validation report using the classic console output from report.py.
+
+        This delegates to the ReportGenerator.print_console_report method,
+        capturing its output to return as a string.
+
+        Args:
+            report: Validation report to format
+            **kwargs: Additional options (color: bool = True)
+
+        Returns:
+            Formatted string with classic console output
+        """
+        # Import here to avoid circular dependency
+        from iam_validator.core.report import ReportGenerator
+
+        # Allow disabling color for plain text output
+        color = kwargs.get("color", True)
+
+        # Capture the output from print_console_report
+        string_buffer = StringIO()
+        console = Console(file=string_buffer, force_terminal=color, width=120)
+
+        # Create a generator instance with our custom console
+        generator = ReportGenerator()
+
+        # Replace the console temporarily to capture output
+        original_console = generator.console
+        generator.console = console
+
+        # Call the actual print_console_report method
+        generator.print_console_report(report)
+
+        # Restore original console
+        generator.console = original_console
+
+        # Return captured output
+        return string_buffer.getvalue()

iam_validator/core/formatters/csv.py

@@ -0,0 +1,170 @@
+"""CSV formatter for IAM Policy Validator."""
+
+import csv
+import io
+from typing import Any
+
+from iam_validator.core.formatters.base import OutputFormatter
+from iam_validator.core.models import ValidationReport
+
+
+class CSVFormatter(OutputFormatter):
+    """Formats validation results as CSV for spreadsheet analysis."""
+
+    @property
+    def format_id(self) -> str:
+        return "csv"
+
+    @property
+    def description(self) -> str:
+        return "CSV format for spreadsheet import and analysis"
+
+    @property
+    def file_extension(self) -> str:
+        return "csv"
+
+    @property
+    def content_type(self) -> str:
+        return "text/csv"
+
+    def format(self, report: ValidationReport, **kwargs) -> str:
+        """Format report as CSV.
+
+        Args:
+            report: The validation report
+            **kwargs: Additional options like 'include_summary'
+
+        Returns:
+            CSV string
+        """
+        include_summary = kwargs.get("include_summary", True)
+        include_header = kwargs.get("include_header", True)
+
+        output = io.StringIO()
+        writer = csv.writer(output, quoting=csv.QUOTE_MINIMAL)
+
+        if include_summary:
+            self._write_summary_section(writer, report)
+            writer.writerow([])  # Empty row separator
+
+        self._write_issues_section(writer, report, include_header)
+
+        return output.getvalue()
+
+    def _write_summary_section(self, writer: Any, report: ValidationReport) -> None:
+        """Write summary statistics to CSV."""
+        # Count issues by severity - support both IAM validity and security severities
+        errors = sum(
+            1
+            for r in report.results
+            for i in r.issues
+            if i.severity in ("error", "critical", "high")
+        )
+        warnings = sum(
+            1 for r in report.results for i in r.issues if i.severity in ("warning", "medium")
+        )
+        infos = sum(1 for r in report.results for i in r.issues if i.severity in ("info", "low"))
+
+        writer.writerow(["Summary Statistics"])
+        writer.writerow(["Metric", "Value"])
+        writer.writerow(["Total Policies", report.total_policies])
+        writer.writerow(["Valid Policies (IAM)", report.valid_policies])
+        writer.writerow(["Invalid Policies (IAM)", report.invalid_policies])
+        writer.writerow(["Policies with Security Findings", report.policies_with_security_issues])
+        writer.writerow(["Total Issues", report.total_issues])
+        writer.writerow(["Validity Issues", report.validity_issues])
+        writer.writerow(["Security Issues", report.security_issues])
+        writer.writerow([""])
+        writer.writerow(["Legacy Severity Breakdown"])
+        writer.writerow(["Errors", errors])
+        writer.writerow(["Warnings", warnings])
+        writer.writerow(["Info", infos])
+
+    def _write_issues_section(
+        self, writer: Any, report: ValidationReport, include_header: bool
+    ) -> None:
+        """Write detailed issues to CSV."""
+        if include_header:
+            writer.writerow(
+                [
+                    "Policy File",
+                    "Statement Index",
+                    "Statement SID",
+                    "Line Number",
+                    "Severity",
+                    "Issue Type",
+                    "Action",
+                    "Resource",
+                    "Condition Key",
+                    "Message",
+                    "Suggestion",
+                ]
+            )
+
+        for policy_result in report.results:
+            for issue in policy_result.issues:
+                writer.writerow(
+                    [
+                        policy_result.policy_file,
+                        (issue.statement_index + 1 if issue.statement_index is not None else ""),
+                        issue.statement_sid or "",
+                        issue.line_number or "",
+                        issue.severity,
+                        issue.issue_type or "",
+                        issue.action or "",
+                        issue.resource or "",
+                        issue.condition_key or "",
+                        issue.message,
+                        issue.suggestion or "",
+                    ]
+                )
+
+    def format_pivot_table(self, report: ValidationReport) -> str:
+        """Format report as a pivot table CSV for analysis.
+
+        Groups issues by check_id and severity for easy analysis.
+        """
+        output = io.StringIO()
+        writer = csv.writer(output)
+
+        # Create pivot data
+        pivot_data = self._create_pivot_data(report)
+
+        # Write header
+        writer.writerow(["Issue Type", "Severity", "Count", "Policy Files"])
+
+        # Write pivot rows
+        for (issue_type, severity), data in sorted(pivot_data.items()):
+            writer.writerow(
+                [
+                    issue_type or "unknown",
+                    severity,
+                    data["count"],
+                    "; ".join(data["files"][:5]) + ("..." if len(data["files"]) > 5 else ""),
+                ]
+            )
+
+        return output.getvalue()
+
+    def _create_pivot_data(self, report: ValidationReport) -> dict[tuple, dict[str, Any]]:
+        """Create pivot table data structure."""
+        pivot_data = {}
+
+        for policy_result in report.results:
+            for issue in policy_result.issues:
+                key = (issue.issue_type or "unknown", issue.severity)
+
+                if key not in pivot_data:
+                    pivot_data[key] = {
+                        "count": 0,
+                        "files": set(),
+                    }
+
+                pivot_data[key]["count"] += 1
+                pivot_data[key]["files"].add(policy_result.policy_file)
+
+        # Convert sets to lists
+        for key in pivot_data:
+            pivot_data[key]["files"] = sorted(list(pivot_data[key]["files"]))
+
+        return pivot_data