iam-policy-validator 1.4.0__py3-none-any.whl → 1.6.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/formatters/enhanced.py

@@ -36,13 +36,18 @@ class EnhancedFormatter(OutputFormatter):
 
         Args:
             report: Validation report to format
-            **kwargs: Additional options (color: bool = True)
+            **kwargs: Additional options:
+                - color (bool): Enable color output (default: True)
+                - show_summary (bool): Show Executive Summary panel (default: True)
+                - show_severity_breakdown (bool): Show Issue Severity Breakdown panel (default: True)
 
         Returns:
             Formatted string with ANSI codes for console display
         """
         # Allow disabling color for plain text output
         color = kwargs.get("color", True)
+        show_summary = kwargs.get("show_summary", True)
+        show_severity_breakdown = kwargs.get("show_severity_breakdown", True)
 
         # Use StringIO to capture Rich console output
         string_buffer = StringIO()
@@ -58,11 +63,12 @@ class EnhancedFormatter(OutputFormatter):
         console.print(Panel(title, border_style="bright_blue", padding=(1, 0)))
         console.print()
 
-        # Executive Summary with progress bars
-        self._print_summary_panel(console, report)
+        # Executive Summary with progress bars (optional)
+        if show_summary:
+            self._print_summary_panel(console, report)
 
-        # Severity breakdown if there are issues
-        if report.total_issues > 0:
+        # Severity breakdown if there are issues (optional)
+        if show_severity_breakdown and report.total_issues > 0:
             console.print()
             self._print_severity_breakdown(console, report)
 

iam_validator/core/formatters/sarif.py

@@ -100,7 +100,7 @@ class SARIFFormatter(OutputFormatter):
                     "text": "The specified condition key is not valid for this action"
                 },
                 "helpUri": "https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html",
-                "defaultConfiguration": {"level": "warning"},
+                "defaultConfiguration": {"level": "error"},
             },
             {
                 "id": "invalid-resource",
@@ -110,18 +110,55 @@ class SARIFFormatter(OutputFormatter):
                 "defaultConfiguration": {"level": "error"},
             },
             {
-                "id": "security-wildcard",
-                "shortDescription": {"text": "Overly Permissive Wildcard"},
+                "id": "duplicate-sid",
+                "shortDescription": {"text": "Duplicate Statement ID"},
+                "fullDescription": {
+                    "text": "Multiple statements use the same Statement ID (Sid), which can cause confusion"
+                },
+                "helpUri": "https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_sid.html",
+                "defaultConfiguration": {"level": "error"},
+            },
+            {
+                "id": "overly-permissive",
+                "shortDescription": {"text": "Overly Permissive Policy"},
                 "fullDescription": {
-                    "text": "Using wildcards in actions or resources can be a security risk"
+                    "text": "Policy grants overly broad permissions using wildcards in actions or resources"
                 },
-                "helpUri": "https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html",
+                "helpUri": "https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege",
                 "defaultConfiguration": {"level": "warning"},
             },
             {
-                "id": "security-sensitive-action",
-                "shortDescription": {"text": "Sensitive Action Without Conditions"},
-                "fullDescription": {"text": "Sensitive actions should have condition restrictions"},
+                "id": "missing-condition",
+                "shortDescription": {"text": "Missing Condition Restrictions"},
+                "fullDescription": {
+                    "text": "Sensitive actions should include condition restrictions to limit when they can be used"
+                },
+                "helpUri": "https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#use-policy-conditions",
+                "defaultConfiguration": {"level": "warning"},
+            },
+            {
+                "id": "missing-required-condition",
+                "shortDescription": {"text": "Missing Required Condition"},
+                "fullDescription": {
+                    "text": "Specific actions require certain conditions to prevent privilege escalation or security issues"
+                },
+                "helpUri": "https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html",
+                "defaultConfiguration": {"level": "error"},
+            },
+            {
+                "id": "invalid-principal",
+                "shortDescription": {"text": "Invalid Principal"},
+                "fullDescription": {
+                    "text": "The specified principal is invalid or improperly formatted"
+                },
+                "helpUri": "https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html",
+                "defaultConfiguration": {"level": "error"},
+            },
+            {
+                "id": "general-issue",
+                "shortDescription": {"text": "IAM Policy Issue"},
+                "fullDescription": {"text": "General IAM policy validation issue"},
+                "helpUri": "https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html",
                 "defaultConfiguration": {"level": "warning"},
             },
         ]
@@ -170,18 +207,45 @@ class SARIFFormatter(OutputFormatter):
         return results
 
     def _get_rule_id(self, issue: ValidationIssue) -> str:
-        """Map issue to SARIF rule ID."""
+        """Map issue to SARIF rule ID.
+
+        Uses the issue_type field directly, converting underscores to hyphens
+        for SARIF rule ID format. Falls back to heuristic matching for unknown types.
+        """
+        # Map common issue types directly
+        issue_type_map = {
+            "invalid_action": "invalid-action",
+            "invalid_condition_key": "invalid-condition-key",
+            "invalid_resource": "invalid-resource",
+            "duplicate_sid": "duplicate-sid",
+            "overly_permissive": "overly-permissive",
+            "missing_condition": "missing-condition",
+            "missing_required_condition": "missing-required-condition",
+            "invalid_principal": "invalid-principal",
+        }
+
+        # Try direct mapping from issue_type
+        if issue.issue_type in issue_type_map:
+            return issue_type_map[issue.issue_type]
+
+        # Fallback: heuristic matching based on message
         message_lower = issue.message.lower()
 
         if "action" in message_lower and "not found" in message_lower:
             return "invalid-action"
         elif "condition key" in message_lower:
             return "invalid-condition-key"
-        elif "arn" in message_lower or "resource" in message_lower:
+        elif "duplicate" in message_lower and "sid" in message_lower:
+            return "duplicate-sid"
+        elif "wildcard" in message_lower or "overly permissive" in message_lower:
+            return "overly-permissive"
+        elif "missing" in message_lower and "condition" in message_lower:
+            if "required" in message_lower:
+                return "missing-required-condition"
+            return "missing-condition"
+        elif "principal" in message_lower:
+            return "invalid-principal"
+        elif "resource" in message_lower or "arn" in message_lower:
             return "invalid-resource"
-        elif "wildcard" in message_lower or "*" in issue.message:
-            return "security-wildcard"
-        elif "sensitive" in message_lower:
-            return "security-sensitive-action"
         else:
             return "general-issue"

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"