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

iam_validator/checks/policy_size.py

@@ -16,6 +16,7 @@ from typing import TYPE_CHECKING
 
 from iam_validator.core.aws_fetcher import AWSServiceFetcher
 from iam_validator.core.check_registry import CheckConfig, PolicyCheck
+from iam_validator.core.constants import AWS_POLICY_SIZE_LIMITS
 from iam_validator.core.models import Statement, ValidationIssue
 
 if TYPE_CHECKING:
@@ -25,13 +26,8 @@ if TYPE_CHECKING:
 class PolicySizeCheck(PolicyCheck):
     """Validates that IAM policies don't exceed AWS size limits."""
 
-    # AWS IAM policy size limits (in characters, excluding whitespace)
-    DEFAULT_LIMITS = {
-        "managed": 6144,
-        "inline_user": 2048,
-        "inline_group": 5120,
-        "inline_role": 10240,
-    }
+    # AWS IAM policy size limits (loaded from constants module)
+    DEFAULT_LIMITS = AWS_POLICY_SIZE_LIMITS
 
     @property
     def check_id(self) -> str:

iam_validator/checks/policy_type_validation.py

@@ -71,6 +71,7 @@ async def execute_policy(
                         line_number=statement.line_number,
                         suggestion="Add a Principal element to specify who can access this resource.\n"
                         "Example:\n"
+                        "```json\n"
                         "{\n"
                         '  "Effect": "Allow",\n'
                         '  "Principal": {\n'
@@ -78,7 +79,8 @@ async def execute_policy(
                         "  },\n"
                         '  "Action": "s3:GetObject",\n'
                         '  "Resource": "arn:aws:s3:::bucket/*"\n'
-                        "}",
+                        "}\n"
+                        "```",
                     )
                 )
 
@@ -101,11 +103,13 @@ async def execute_policy(
                         line_number=statement.line_number,
                         suggestion="Remove the Principal element from this identity policy statement.\n"
                         "Example:\n"
+                        "```json\n"
                         "{\n"
                         '  "Effect": "Allow",\n'
                         '  "Action": "s3:GetObject",\n'
                         '  "Resource": "arn:aws:s3:::bucket/*"\n'
-                        "}",
+                        "}\n"
+                        "```",
                     )
                 )
 
@@ -127,6 +131,7 @@ async def execute_policy(
                         line_number=statement.line_number,
                         suggestion="Remove the Principal element from this SCP statement.\n"
                         "Example:\n"
+                        "```json\n"
                         "{\n"
                         '  "Effect": "Deny",\n'
                         '  "Action": "ec2:*",\n'
@@ -136,7 +141,8 @@ async def execute_policy(
                         '      "ec2:Region": ["us-east-1", "us-west-2"]\n'
                         "    }\n"
                         "  }\n"
-                        "}",
+                        "}\n"
+                        "```",
                     )
                 )
 

iam_validator/checks/principal_validation.py

@@ -668,7 +668,7 @@ class PrincipalValidationCheck(PolicyCheck):
 
         # Build example based on condition key type
         if example:
-            parts.append(f"Example:\n{example}")
+            parts.append(f"Example:\n```json\n{example}\n```")
         else:
             # Auto-generate example
             example_lines = ['Add to "Condition" block:', f'  "{operator}": {{']

iam_validator/checks/resource_validation.py

@@ -4,15 +4,17 @@ import re
 
 from iam_validator.core.aws_fetcher import AWSServiceFetcher
 from iam_validator.core.check_registry import CheckConfig, PolicyCheck
+from iam_validator.core.constants import DEFAULT_ARN_VALIDATION_PATTERN, MAX_ARN_LENGTH
 from iam_validator.core.models import Statement, ValidationIssue
+from iam_validator.sdk.arn_matching import (
+    has_template_variables,
+    normalize_template_variables,
+)
 
 
 class ResourceValidationCheck(PolicyCheck):
     """Validates ARN format for resources."""
 
-    # Maximum allowed length for ARN to prevent ReDoS attacks
-    MAX_ARN_LENGTH = 2048  # AWS max ARN length is ~2048 characters
-
     @property
     def check_id(self) -> str:
         return "resource_validation"
@@ -42,17 +44,21 @@ class ResourceValidationCheck(PolicyCheck):
 
         # Get ARN pattern from config, or use default
         # Pattern allows wildcards (*) in region and account fields
-        arn_pattern_str = config.config.get(
-            "arn_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*]*:.+$",
-        )
+        arn_pattern_str = config.config.get("arn_pattern", DEFAULT_ARN_VALIDATION_PATTERN)
 
-        # Compile pattern with timeout protection (available in Python 3.11+)
+        # Compile pattern
         try:
             arn_pattern = re.compile(arn_pattern_str)
         except re.error:
-            # Fallback to using fetcher's pre-compiled pattern
-            arn_pattern = fetcher._patterns.arn_pattern
+            # Fallback to default pattern if custom pattern is invalid
+            arn_pattern = re.compile(DEFAULT_ARN_VALIDATION_PATTERN)
+
+        # Check if template variable support is enabled (default: true)
+        # Try global settings first, then check-specific config
+        allow_template_variables = config.root_config.get("settings", {}).get(
+            "allow_template_variables",
+            config.config.get("allow_template_variables", True),
+        )
 
         for resource in resources:
             # Skip wildcard resources (handled by security checks)
@@ -60,14 +66,14 @@ class ResourceValidationCheck(PolicyCheck):
                 continue
 
             # Validate ARN length to prevent ReDoS attacks
-            if len(resource) > self.MAX_ARN_LENGTH:
+            if len(resource) > MAX_ARN_LENGTH:
                 issues.append(
                     ValidationIssue(
                         severity=self.get_severity(config),
                         statement_sid=statement_sid,
                         statement_index=statement_idx,
                         issue_type="invalid_resource",
-                        message=f"Resource ARN exceeds maximum length ({len(resource)} > {self.MAX_ARN_LENGTH}): {resource[:100]}...",
+                        message=f"Resource ARN exceeds maximum length ({len(resource)} > {MAX_ARN_LENGTH}): {resource[:100]}...",
                         resource=resource[:100] + "...",
                         suggestion="ARN is too long and may be invalid",
                         line_number=line_number,
@@ -75,21 +81,45 @@ class ResourceValidationCheck(PolicyCheck):
                 )
                 continue
 
+            # Check if resource contains template variables
+            has_templates = has_template_variables(resource)
+
+            # If template variables are found and allowed, normalize them for validation
+            validation_resource = resource
+            if has_templates and allow_template_variables:
+                validation_resource = normalize_template_variables(resource)
+
             # Validate ARN format
             try:
-                if not arn_pattern.match(resource):
-                    issues.append(
-                        ValidationIssue(
-                            severity=self.get_severity(config),
-                            statement_sid=statement_sid,
-                            statement_index=statement_idx,
-                            issue_type="invalid_resource",
-                            message=f"Invalid ARN format: {resource}",
-                            resource=resource,
-                            suggestion="ARN should follow format: arn:partition:service:region:account-id:resource",
-                            line_number=line_number,
+                if not arn_pattern.match(validation_resource):
+                    # If original resource had templates and normalization didn't help,
+                    # provide a more informative message
+                    if has_templates and allow_template_variables:
+                        issues.append(
+                            ValidationIssue(
+                                severity=self.get_severity(config),
+                                statement_sid=statement_sid,
+                                statement_index=statement_idx,
+                                issue_type="invalid_resource",
+                                message=f"Invalid ARN format even after normalizing template variables: {resource}",
+                                resource=resource,
+                                suggestion="ARN should follow format: arn:partition:service:region:account-id:resource (template variables like ${aws_account_id} are supported)",
+                                line_number=line_number,
+                            )
+                        )
+                    else:
+                        issues.append(
+                            ValidationIssue(
+                                severity=self.get_severity(config),
+                                statement_sid=statement_sid,
+                                statement_index=statement_idx,
+                                issue_type="invalid_resource",
+                                message=f"Invalid ARN format: {resource}",
+                                resource=resource,
+                                suggestion="ARN should follow format: arn:partition:service:region:account-id:resource",
+                                line_number=line_number,
+                            )
                         )
-                    )
             except Exception:
                 # If regex matching fails (shouldn't happen with length check), treat as invalid
                 issues.append(

iam_validator/checks/sensitive_action.py

@@ -143,7 +143,11 @@ class SensitiveActionCheck(PolicyCheck):
             )
 
             # Combine suggestion + example
-            suggestion = f"{suggestion_text}\n\nExample:\n{example}" if example else suggestion_text
+            suggestion = (
+                f"{suggestion_text}\n\nExample:\n```json\n{example}\n```"
+                if example
+                else suggestion_text
+            )
 
             # Determine severity based on the highest severity action in the list
             # If single action, use its category severity

iam_validator/checks/service_wildcard.py

@@ -69,7 +69,9 @@ class ServiceWildcardCheck(PolicyCheck):
 
                     # Combine suggestion + example
                     suggestion = (
-                        f"{suggestion_text}\nExample:\n{example}" if example else suggestion_text
+                        f"{suggestion_text}\nExample:\n```json\n{example}\n```"
+                        if example
+                        else suggestion_text
                     )
 
                     issues.append(

iam_validator/checks/utils/sensitive_action_matcher.py

@@ -11,7 +11,6 @@ Performance optimizations:
 
 import re
 from functools import lru_cache
-from re import Pattern
 
 from iam_validator.core.check_registry import CheckConfig
 from iam_validator.core.config.sensitive_actions import get_sensitive_actions
@@ -69,7 +68,7 @@ DEFAULT_SENSITIVE_ACTIONS = _get_default_sensitive_actions()
 
 # Global regex pattern cache for performance
 @lru_cache(maxsize=256)
-def compile_pattern(pattern: str) -> Pattern[str] | None:
+def compile_pattern(pattern: str) -> re.Pattern[str] | None:
     """Compile and cache regex patterns.
 
     Args:

iam_validator/checks/utils/wildcard_expansion.py

@@ -6,7 +6,6 @@ to their actual action names using the AWS Service Reference API.
 
 import re
 from functools import lru_cache
-from re import Pattern
 
 from iam_validator.core.aws_fetcher import AWSServiceFetcher
 
@@ -14,7 +13,7 @@ from iam_validator.core.aws_fetcher import AWSServiceFetcher
 # Global cache for compiled wildcard patterns (shared across checks)
 # Using lru_cache for O(1) pattern reuse and 20-30x performance improvement
 @lru_cache(maxsize=512)
-def compile_wildcard_pattern(pattern: str) -> Pattern[str]:
+def compile_wildcard_pattern(pattern: str) -> re.Pattern[str]:
     """Compile and cache wildcard patterns for O(1) reuse.
 
     Args:

iam_validator/checks/wildcard_action.py

@@ -40,12 +40,17 @@ class WildcardActionCheck(PolicyCheck):
         if "*" in actions:
             message = config.config.get("message", "Statement allows all actions (*)")
             suggestion_text = config.config.get(
-                "suggestion", "Replace wildcard with specific actions needed for your use case"
+                "suggestion",
+                "Replace wildcard with specific actions needed for your use case",
             )
             example = config.config.get("example", "")
 
             # Combine suggestion + example
-            suggestion = f"{suggestion_text}\nExample:\n{example}" if example else suggestion_text
+            suggestion = (
+                f"{suggestion_text}\nExample:\n```json\n{example}\n```"
+                if example
+                else suggestion_text
+            )
 
             issues.append(
                 ValidationIssue(

iam_validator/checks/wildcard_resource.py

@@ -69,7 +69,11 @@ class WildcardResourceCheck(PolicyCheck):
             example = config.config.get("example", "")
 
             # Combine suggestion + example
-            suggestion = f"{suggestion_text}\nExample:\n{example}" if example else suggestion_text
+            suggestion = (
+                f"{suggestion_text}\nExample:\n```json\n{example}\n```"
+                if example
+                else suggestion_text
+            )
 
             issues.append(
                 ValidationIssue(

iam_validator/commands/analyze.py

@@ -136,6 +136,12 @@ Examples:
             help="Create line-specific review comments on PR (requires --github-comment)",
         )
 
+        parser.add_argument(
+            "--github-summary",
+            action="store_true",
+            help="Write validation summary to GitHub Actions job summary (works for all workflow runs)",
+        )
+
         parser.add_argument(
             "--run-all-checks",
             action="store_true",
@@ -265,6 +271,10 @@ Examples:
                     if not success:
                         logging.error("Failed to post Access Analyzer results to GitHub PR")
 
+            # Write to GitHub Actions job summary if configured
+            if getattr(args, "github_summary", False):
+                self._write_github_actions_summary(report)
+
             # Determine exit code based on validation results
             if args.fail_on_warnings:
                 exit_code = 0 if report.total_findings == 0 else 1
@@ -405,7 +415,8 @@ Examples:
         if not github.is_configured():
             logging.error(
                 "GitHub integration not configured. "
-                "Set GITHUB_TOKEN, GITHUB_REPOSITORY, and GITHUB_PR_NUMBER"
+                "Required: GITHUB_TOKEN, GITHUB_REPOSITORY, and GITHUB_PR_NUMBER environment variables. "
+                "Ensure your workflow is triggered by a pull_request event."
             )
             return False
 
@@ -432,3 +443,89 @@ Examples:
             logging.error("Failed to post Access Analyzer results to PR")
 
         return success
+
+    def _write_github_actions_summary(self, report: AccessAnalyzerReport) -> None:
+        """Write a high-level summary to GitHub Actions job summary.
+
+        This appears in the Actions tab and provides a quick overview of Access Analyzer results.
+        Uses GITHUB_STEP_SUMMARY environment variable.
+
+        Args:
+            report: Access Analyzer report to summarize
+        """
+        import os
+
+        summary_file = os.getenv("GITHUB_STEP_SUMMARY")
+        if not summary_file:
+            logging.warning(
+                "--github-summary specified but GITHUB_STEP_SUMMARY env var not found. "
+                "This feature only works in GitHub Actions."
+            )
+            return
+
+        try:
+            # Generate high-level summary
+            summary_parts = []
+
+            # Header with status
+            if report.total_findings == 0:
+                summary_parts.append("# ✅ IAM Policy Validation (Access Analyzer) - Passed")
+            elif report.total_errors > 0:
+                summary_parts.append("# ❌ IAM Policy Validation (Access Analyzer) - Failed")
+            else:
+                summary_parts.append("# ⚠️ IAM Policy Validation (Access Analyzer) - Issues Found")
+
+            summary_parts.append("")
+
+            # Summary table
+            summary_parts.append("## Summary")
+            summary_parts.append("")
+            summary_parts.append("| Metric | Count |")
+            summary_parts.append("|--------|-------|")
+            summary_parts.append(f"| Total Policies Analyzed | {report.total_policies} |")
+            summary_parts.append(f"| Policies with Findings | {report.policies_with_findings} |")
+            summary_parts.append(f"| Total Findings | {report.total_findings} |")
+            summary_parts.append(f"| Errors | {report.total_errors} |")
+            summary_parts.append(f"| Warnings | {report.total_warnings} |")
+            summary_parts.append(f"| Suggestions | {report.total_suggestions} |")
+
+            # Finding breakdown by type if there are findings
+            if report.total_findings > 0:
+                summary_parts.append("")
+                summary_parts.append("## 📊 Findings by Type")
+                summary_parts.append("")
+
+                # Count findings by type
+                finding_types: dict[str, int] = {}
+                for result in report.results:
+                    for finding in result.findings:
+                        finding_type = finding.finding_type
+                        finding_types[finding_type] = finding_types.get(finding_type, 0) + 1
+
+                # Sort by count (highest first)
+                sorted_types = sorted(finding_types.items(), key=lambda x: x[1], reverse=True)
+
+                summary_parts.append("| Finding Type | Count |")
+                summary_parts.append("|--------------|-------|")
+                for finding_type, count in sorted_types:
+                    summary_parts.append(f"| {finding_type} | {count} |")
+
+            # Add footer with links
+            summary_parts.append("")
+            summary_parts.append("---")
+            summary_parts.append("")
+            summary_parts.append(
+                "📝 For detailed findings, check the PR comments or review the workflow logs."
+            )
+            summary_parts.append("")
+            summary_parts.append("*Powered by AWS IAM Access Analyzer*")
+
+            # Write to summary file (append mode)
+            with open(summary_file, "a", encoding="utf-8") as f:
+                f.write("\n".join(summary_parts))
+                f.write("\n")
+
+            logging.info("Wrote Access Analyzer summary to GitHub Actions job summary")
+
+        except Exception as e:
+            logging.warning(f"Failed to write GitHub Actions summary: {e}")

iam_validator/commands/validate.py

@@ -484,7 +484,9 @@ Examples:
                 # In streaming mode, don't cleanup comments (we want to keep earlier files)
                 # Cleanup will happen once at the end
                 commenter = PRCommenter(
-                    github, cleanup_old_comments=False, fail_on_severities=fail_on_severities
+                    github,
+                    cleanup_old_comments=False,
+                    fail_on_severities=fail_on_severities,
                 )
 
                 # Create a mini-report for just this file
@@ -547,7 +549,7 @@ Examples:
             # Issue breakdown by severity if there are issues
             if report.total_issues > 0:
                 summary_parts.append("")
-                summary_parts.append("## Issues by Severity")
+                summary_parts.append("## 📊 Issues by Severity")
                 summary_parts.append("")
 
                 # Count issues by severity

iam_validator/core/access_analyzer.py

@@ -197,6 +197,11 @@ class AccessAnalyzerReport:
         """Total number of suggestions across all policies."""
         return sum(r.suggestion_count for r in self.results)
 
+    @property
+    def policies_with_findings(self) -> int:
+        """Number of policies that have at least one finding."""
+        return sum(1 for r in self.results if r.findings)
+
 
 class AccessAnalyzerValidator:
     """Validates IAM policies using AWS IAM Access Analyzer."""

iam_validator/core/access_analyzer_report.py

@@ -338,11 +338,8 @@ class AccessAnalyzerReportFormatter:
             "---",
             "",
             "<div align='center'>",
-            "",
-            "**🤖 Generated by IAM Policy Validator**",
-            "",
-            "_Powered by AWS IAM Access Analyzer_",
-            "",
+            "🤖 <em>Generated by <strong>IAM Policy Validator</strong></em><br>",
+            "<sub>Powered by AWS IAM Access Analyzer</sub>",
             "</div>",
         ]
         footer_content = "\n".join(footer_lines)

iam_validator/core/aws_fetcher.py

@@ -40,18 +40,28 @@ logger = logging.getLogger(__name__)
 
 
 class CompiledPatterns:
-    """Pre-compiled regex patterns for validation."""
+    """Pre-compiled regex patterns for validation.
+
+    This class implements the Singleton pattern to ensure patterns are compiled only once
+    and reused across all instances for better performance.
+    """
 
     _instance = None
+    _initialized = False
 
     def __new__(cls) -> "CompiledPatterns":
         if cls._instance is None:
             cls._instance = super().__new__(cls)
-            cls._instance._initialize()
         return cls._instance
 
-    def _initialize(self) -> None:
-        """Initialize compiled patterns."""
+    def __init__(self) -> None:
+        """Initialize compiled patterns (only once due to Singleton pattern)."""
+        # Only initialize once, even if __init__ is called multiple times
+        if CompiledPatterns._initialized:
+            return
+
+        CompiledPatterns._initialized = True
+
         # ARN validation pattern
         self.arn_pattern = re.compile(
             r"^arn:(?P<partition>(aws|aws-cn|aws-us-gov|aws-eusc|aws-iso|aws-iso-b|aws-iso-e|aws-iso-f)):"

iam_validator/core/config/config_loader.py

@@ -16,6 +16,7 @@ import yaml
 
 from iam_validator.core.check_registry import CheckConfig, CheckRegistry, PolicyCheck
 from iam_validator.core.config.defaults import get_default_config
+from iam_validator.core.constants import DEFAULT_CONFIG_FILENAMES
 
 logger = logging.getLogger(__name__)
 
@@ -127,12 +128,8 @@ class ValidatorConfig:
 class ConfigLoader:
     """Loads configuration from various sources."""
 
-    DEFAULT_CONFIG_NAMES = [
-        "iam-validator.yaml",
-        "iam-validator.yml",
-        ".iam-validator.yaml",  # Support hidden files as fallback
-        ".iam-validator.yml",
-    ]
+    # Load default config names from constants module
+    DEFAULT_CONFIG_NAMES = DEFAULT_CONFIG_FILENAMES
 
     @staticmethod
     def find_config_file(

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 -->"