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

iam_validator/core/aws_fetcher.py

@@ -27,11 +27,13 @@ import os
 import re
 import sys
 import time
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
 import httpx
 
+from iam_validator.core import constants
 from iam_validator.core.config import AWS_SERVICE_REFERENCE_BASE_URL
 from iam_validator.core.models import ServiceDetail, ServiceInfo
 from iam_validator.utils.cache import LRUCache
@@ -39,6 +41,23 @@ from iam_validator.utils.cache import LRUCache
 logger = logging.getLogger(__name__)
 
 
+@dataclass
+class ConditionKeyValidationResult:
+    """Result of condition key validation.
+
+    Attributes:
+        is_valid: True if the condition key is valid for the action
+        error_message: Short error message if invalid (shown prominently)
+        warning_message: Warning message if valid but not recommended
+        suggestion: Detailed suggestion with valid keys (shown in collapsible section)
+    """
+
+    is_valid: bool
+    error_message: str | None = None
+    warning_message: str | None = None
+    suggestion: str | None = None
+
+
 class CompiledPatterns:
     """Pre-compiled regex patterns for validation.
 
@@ -199,10 +218,10 @@ class AWSServiceFetcher:
 
     def __init__(
         self,
-        timeout: float = 30.0,
+        timeout: float = constants.DEFAULT_HTTP_TIMEOUT_SECONDS,
         retries: int = 3,
         enable_cache: bool = True,
-        cache_ttl: int = 604800,
+        cache_ttl: int = constants.DEFAULT_CACHE_TTL_SECONDS,
         memory_cache_size: int = 256,
         connection_pool_size: int = 50,
         keepalive_connections: int = 20,
@@ -303,7 +322,7 @@ class AWSServiceFetcher:
             limits=httpx.Limits(
                 max_keepalive_connections=self.keepalive_connections,
                 max_connections=self.connection_pool_size,
-                keepalive_expiry=30.0,  # Keep connections alive for 30 seconds
+                keepalive_expiry=constants.DEFAULT_HTTP_TIMEOUT_SECONDS,  # Keep connections alive
             ),
             http2=True,  # Enable HTTP/2 for multiplexing
         )
@@ -658,7 +677,7 @@ class AWSServiceFetcher:
                             return service_detail
                         except FileNotFoundError:
                             pass
-                raise ValueError(f"Service '{service_name}' not found in {self.aws_services_dir}")
+                raise ValueError(f"Service `{service_name}` not found in {self.aws_services_dir}")
 
         # Fetch service list and find URL from API
         services = await self.fetch_services()
@@ -676,7 +695,7 @@ class AWSServiceFetcher:
 
                 return service_detail
 
-        raise ValueError(f"Service '{service_name}' not found")
+        raise ValueError(f"Service `{service_name}` not found")
 
     async def fetch_multiple_services(self, service_names: list[str]) -> dict[str, ServiceDetail]:
         """Fetch multiple services concurrently with optimized batching."""
@@ -823,7 +842,7 @@ class AWSServiceFetcher:
 
     async def validate_condition_key(
         self, action: str, condition_key: str, resources: list[str] | None = None
-    ) -> tuple[bool, str | None, str | None]:
+    ) -> ConditionKeyValidationResult:
         """
         Validate condition key against action and optionally resource types.
 
@@ -833,10 +852,11 @@ class AWSServiceFetcher:
             resources: Optional list of resource ARNs to validate against
 
         Returns:
-            Tuple of (is_valid, error_message, warning_message)
+            ConditionKeyValidationResult with:
             - is_valid: True if key is valid (even with warning)
-            - error_message: Error message if invalid (is_valid=False)
+            - error_message: Short error message if invalid (shown prominently)
             - warning_message: Warning message if valid but not recommended
+            - suggestion: Detailed suggestion with valid keys (shown in collapsible section)
         """
         try:
             from iam_validator.core.config.aws_global_conditions import (
@@ -852,10 +872,9 @@ class AWSServiceFetcher:
                 if global_conditions.is_valid_global_key(condition_key):
                     is_global_key = True
                 else:
-                    return (
-                        False,
-                        f"Invalid AWS global condition key: '{condition_key}'.",
-                        None,
+                    return ConditionKeyValidationResult(
+                        is_valid=False,
+                        error_message=f"Invalid AWS global condition key: `{condition_key}`.",
                     )
 
             # Fetch service detail (cached)
@@ -863,7 +882,7 @@ class AWSServiceFetcher:
 
             # Check service-specific condition keys
             if condition_key in service_detail.condition_keys:
-                return True, None, None
+                return ConditionKeyValidationResult(is_valid=True)
 
             # Check action-specific condition keys
             if action_name in service_detail.actions:
@@ -872,7 +891,7 @@ class AWSServiceFetcher:
                     action_detail.action_condition_keys
                     and condition_key in action_detail.action_condition_keys
                 ):
-                    return True, None, None
+                    return ConditionKeyValidationResult(is_valid=True)
 
                 # Check resource-specific condition keys
                 # Get resource types required by this action
@@ -886,7 +905,7 @@ class AWSServiceFetcher:
                         resource_type = service_detail.resources.get(resource_name)
                         if resource_type and resource_type.condition_keys:
                             if condition_key in resource_type.condition_keys:
-                                return True, None, None
+                                return ConditionKeyValidationResult(is_valid=True)
 
                 # If it's a global key but the action has specific condition keys defined,
                 # AWS allows it but the key may not be available in every request context
@@ -898,21 +917,95 @@ class AWSServiceFetcher:
                         f"Verify that '{condition_key}' is available for this specific action's request context. "
                         f"Consider using '*IfExists' operators (e.g., StringEqualsIfExists) if the key might be missing."
                     )
-                    return True, None, warning_msg
+                    return ConditionKeyValidationResult(is_valid=True, warning_message=warning_msg)
 
             # If it's a global key and action doesn't define specific keys, allow it
             if is_global_key:
-                return True, None, None
+                return ConditionKeyValidationResult(is_valid=True)
+
+            # Short error message
+            error_msg = f"Condition key `{condition_key}` is not valid for action `{action}`"
+
+            # Collect valid condition keys for this action
+            valid_keys = set()
 
-            return (
-                False,
-                f"Condition key '{condition_key}' is not valid for action '{action}'",
-                None,
+            # Add service-level condition keys
+            if service_detail.condition_keys:
+                if isinstance(service_detail.condition_keys, dict):
+                    valid_keys.update(service_detail.condition_keys.keys())
+                elif isinstance(service_detail.condition_keys, list):
+                    valid_keys.update(service_detail.condition_keys)
+
+            # Add action-specific condition keys
+            if action_name in service_detail.actions:
+                action_detail = service_detail.actions[action_name]
+                if action_detail.action_condition_keys:
+                    if isinstance(action_detail.action_condition_keys, dict):
+                        valid_keys.update(action_detail.action_condition_keys.keys())
+                    elif isinstance(action_detail.action_condition_keys, list):
+                        valid_keys.update(action_detail.action_condition_keys)
+
+                # Add resource-specific condition keys
+                if action_detail.resources:
+                    for res_req in action_detail.resources:
+                        resource_name = res_req.get("Name", "")
+                        if resource_name:
+                            resource_type = service_detail.resources.get(resource_name)
+                            if resource_type and resource_type.condition_keys:
+                                if isinstance(resource_type.condition_keys, dict):
+                                    valid_keys.update(resource_type.condition_keys.keys())
+                                elif isinstance(resource_type.condition_keys, list):
+                                    valid_keys.update(resource_type.condition_keys)
+
+            # Build detailed suggestion with valid keys (goes in collapsible section)
+            suggestion_parts = []
+
+            if valid_keys:
+                # Sort and limit to first 10 keys for readability
+                sorted_keys = sorted(valid_keys)
+                suggestion_parts.append("**Valid condition keys for this action:**")
+                if len(sorted_keys) <= 10:
+                    for key in sorted_keys:
+                        suggestion_parts.append(f"- `{key}`")
+                else:
+                    for key in sorted_keys[:10]:
+                        suggestion_parts.append(f"- `{key}`")
+                    suggestion_parts.append(f"- ... and {len(sorted_keys) - 10} more")
+
+                suggestion_parts.append("")
+                suggestion_parts.append(
+                    "**Global condition keys** (e.g., `aws:ResourceOrgID`, `aws:RequestedRegion`, `aws:SourceIp`, `aws:SourceVpce`) "
+                    "can also be used with any AWS action"
+                )
+            else:
+                # No action-specific keys - mention global keys
+                suggestion_parts.append(
+                    "This action does not have specific condition keys defined.\n\n"
+                    "However, you can use **global condition keys** such as:\n"
+                    "- `aws:RequestedRegion`\n"
+                    "- `aws:SourceIp`\n"
+                    "- `aws:SourceVpce`\n"
+                    "- `aws:UserAgent`\n"
+                    "- `aws:CurrentTime`\n"
+                    "- `aws:SecureTransport`\n"
+                    "- `aws:PrincipalArn`\n"
+                    "- And many others"
+                )
+
+            suggestion = "\n".join(suggestion_parts)
+
+            return ConditionKeyValidationResult(
+                is_valid=False,
+                error_message=error_msg,
+                suggestion=suggestion,
             )
 
         except Exception as e:
             logger.error(f"Error validating condition key {condition_key} for {action}: {e}")
-            return False, f"Failed to validate condition key: {str(e)}", None
+            return ConditionKeyValidationResult(
+                is_valid=False,
+                error_message=f"Failed to validate condition key: {str(e)}",
+            )
 
     async def clear_caches(self) -> None:
         """Clear all caches (memory and disk)."""

iam_validator/core/config/config_loader.py

@@ -5,6 +5,7 @@ Loads and parses configuration from YAML files, environment variables,
 and command-line arguments.
 """
 
+import importlib
 import importlib.util
 import inspect
 import logging
@@ -314,8 +315,6 @@ class ConfigLoader:
                 module_name, class_name = parts
 
                 # Import the module
-                import importlib
-
                 module = importlib.import_module(module_name)
                 check_class = getattr(module, class_name)
 

iam_validator/core/config/defaults.py

@@ -16,6 +16,7 @@ Benefits of code-first approach:
 - 5-10x faster than YAML parsing
 """
 
+from iam_validator.core import constants
 from iam_validator.core.config.category_suggestions import get_category_suggestions
 from iam_validator.core.config.condition_requirements import CONDITION_REQUIREMENTS
 from iam_validator.core.config.principal_requirements import (
@@ -70,11 +71,11 @@ DEFAULT_CONFIG = {
         # Cache AWS service definitions locally (persists between runs)
         "cache_enabled": True,
         # Cache TTL in hours (default: 168 = 7 days)
-        "cache_ttl_hours": 168,
+        "cache_ttl_hours": constants.DEFAULT_CACHE_TTL_HOURS,
         # Severity levels that cause validation to fail
         # IAM Validity: error, warning, info
         # Security: critical, high, medium, low
-        "fail_on_severity": ["error", "critical", "high"],
+        "fail_on_severity": list(constants.HIGH_SEVERITY_LEVELS),
     },
     # ========================================================================
     # AWS IAM Validation Checks (17 checks total)
@@ -188,7 +189,7 @@ DEFAULT_CONFIG = {
         "enabled": True,
         "severity": "error",  # IAM validity error
         "description": "Validates ARN format for resources",
-        "arn_pattern": "^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": constants.DEFAULT_ARN_VALIDATION_PATTERN,
     },
     # ========================================================================
     # 9. PRINCIPAL VALIDATION
@@ -389,6 +390,18 @@ DEFAULT_CONFIG = {
         # Services that are allowed to use wildcards (default: logs, cloudwatch, xray)
         # See: iam_validator/core/config/wildcards.py
         "allowed_services": list(DEFAULT_SERVICE_WILDCARDS),
+        "message": "Service wildcard '{action}' grants all permissions for the {service} service",
+        "suggestion": (
+            "Replace '{action}' with specific actions needed for your use case to follow least-privilege principle.\n"
+            "Find valid {service} actions: https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resources-contextkeys.html"
+        ),
+        "example": (
+            "Replace:\n"
+            '  "Action": ["{action}"]\n'
+            "\n"
+            "With specific actions:\n"
+            '  "Action": ["{service}:Describe*", "{service}:List*"]\n'
+        ),
     },
     # ========================================================================
     # 16. SENSITIVE ACTION
@@ -482,10 +495,6 @@ DEFAULT_CONFIG = {
     #     - prevent_public_ip: Prevents 0.0.0.0/0 IP ranges
     #
     # See: iam_validator/core/config/condition_requirements.py
-    # Python API:
-    #   from iam_validator.core.config import CONDITION_REQUIREMENTS
-    #   import copy
-    #   requirements = copy.deepcopy(CONDITION_REQUIREMENTS)
     "action_condition_enforcement": {
         "enabled": True,
         "severity": "high",  # Default severity (can be overridden per-requirement)

iam_validator/core/constants.py

@@ -62,6 +62,21 @@ DEFAULT_CONFIG_FILENAMES = [
     ".iam-validator.yml",
 ]
 
+# ============================================================================
+# Severity Levels
+# ============================================================================
+# Severity level groupings for filtering and categorization
+# Used across formatters and report generation
+
+# High severity issues that typically fail validation
+HIGH_SEVERITY_LEVELS = ("error", "critical", "high")
+
+# Medium severity issues (warnings)
+MEDIUM_SEVERITY_LEVELS = ("warning", "medium")
+
+# Low severity issues (informational)
+LOW_SEVERITY_LEVELS = ("info", "low")
+
 # ============================================================================
 # GitHub Integration
 # ============================================================================
@@ -72,3 +87,45 @@ 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 -->"
+
+# GitHub comment size limits
+# GitHub's actual limit is 65536 characters, but we use a smaller limit for safety
+GITHUB_MAX_COMMENT_LENGTH = 65000  # Maximum single comment length
+GITHUB_COMMENT_SPLIT_LIMIT = 60000  # Target size when splitting into multiple parts
+
+# Comment size estimation parameters (used for multi-part comment splitting)
+COMMENT_BASE_OVERHEAD_CHARS = 2000  # Base overhead for headers/footers
+COMMENT_CHARS_PER_ISSUE_ESTIMATE = 500  # Average characters per issue
+COMMENT_CONTINUATION_OVERHEAD_CHARS = 200  # Overhead for continuation markers
+FORMATTING_SAFETY_BUFFER = 100  # Safety buffer for formatting calculations
+
+# ============================================================================
+# Console Display Settings
+# ============================================================================
+
+# Panel width for formatted console output
+CONSOLE_PANEL_WIDTH = 100
+
+# Rich console color styles
+CONSOLE_HEADER_COLOR = "bright_blue"
+
+# ============================================================================
+# Cache and Timeout Settings
+# ============================================================================
+
+# Cache TTL (Time To Live) - 7 days
+DEFAULT_CACHE_TTL_HOURS = 168  # 7 days in hours
+DEFAULT_CACHE_TTL_SECONDS = 604800  # 7 days in seconds (168 * 3600)
+
+# HTTP request timeout in seconds
+DEFAULT_HTTP_TIMEOUT_SECONDS = 30.0
+
+# Time conversion constants
+SECONDS_PER_HOUR = 3600
+
+# ============================================================================
+# AWS Documentation URLs
+# ============================================================================
+
+# AWS Service Authorization Reference (for finding valid actions, resources, and condition keys)
+AWS_SERVICE_AUTH_REF_URL = "https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_actions-resources-contextkeys.html"

iam_validator/core/formatters/console.py

@@ -39,8 +39,17 @@ class ConsoleFormatter(OutputFormatter):
         color = kwargs.get("color", True)
 
         # Capture the output from print_console_report
+        from iam_validator.utils import get_terminal_width
+
         string_buffer = StringIO()
-        console = Console(file=string_buffer, force_terminal=color, width=120)
+        # Get terminal width for proper table column spacing
+        terminal_width = get_terminal_width()
+        console = Console(
+            file=string_buffer,
+            force_terminal=color,
+            width=terminal_width,
+            legacy_windows=False,
+        )
 
         # Create a generator instance with our custom console
         generator = ReportGenerator()

iam_validator/core/formatters/csv.py

@@ -4,6 +4,7 @@ import csv
 import io
 from typing import Any
 
+from iam_validator.core import constants
 from iam_validator.core.formatters.base import OutputFormatter
 from iam_validator.core.models import ValidationReport
 
@@ -58,7 +59,7 @@ class CSVFormatter(OutputFormatter):
             1
             for r in report.results
             for i in r.issues
-            if i.severity in ("error", "critical", "high")
+            if i.severity in constants.HIGH_SEVERITY_LEVELS
         )
         warnings = sum(
             1 for r in report.results for i in r.issues if i.severity in ("warning", "medium")

iam_validator/core/formatters/enhanced.py

@@ -10,6 +10,7 @@ from rich.text import Text
 from rich.tree import Tree
 
 from iam_validator.__version__ import __version__
+from iam_validator.core import constants
 from iam_validator.core.formatters.base import OutputFormatter
 from iam_validator.core.models import PolicyValidationResult, ValidationReport
 
@@ -50,8 +51,14 @@ class EnhancedFormatter(OutputFormatter):
         show_severity_breakdown = kwargs.get("show_severity_breakdown", True)
 
         # Use StringIO to capture Rich console output
+        from iam_validator.utils import get_terminal_width
+
         string_buffer = StringIO()
-        console = Console(file=string_buffer, force_terminal=color, width=120)
+        # Get terminal width for proper text wrapping
+        terminal_width = get_terminal_width()
+        console = Console(
+            file=string_buffer, force_terminal=color, width=terminal_width, legacy_windows=False
+        )
 
         # Header with title
         console.print()
@@ -60,7 +67,14 @@ class EnhancedFormatter(OutputFormatter):
             style="bold cyan",
             justify="center",
         )
-        console.print(Panel(title, border_style="bright_blue", padding=(1, 0)))
+        console.print(
+            Panel(
+                title,
+                border_style=constants.CONSOLE_HEADER_COLOR,
+                padding=(1, 0),
+                width=constants.CONSOLE_PANEL_WIDTH,
+            )
+        )
         console.print()
 
         # Executive Summary with progress bars (optional)
@@ -73,7 +87,7 @@ class EnhancedFormatter(OutputFormatter):
             self._print_severity_breakdown(console, report)
 
         console.print()
-        console.print(Rule(title="[bold]Detailed Results", style="bright_blue"))
+        console.print(Rule(title="[bold]Detailed Results", style=constants.CONSOLE_HEADER_COLOR))
         console.print()
 
         # Detailed results using tree structure
@@ -140,8 +154,9 @@ class EnhancedFormatter(OutputFormatter):
             Panel(
                 metrics_table,
                 title="📊 Executive Summary",
-                border_style="bright_blue",
+                border_style=constants.CONSOLE_HEADER_COLOR,
                 padding=(1, 2),
+                width=constants.CONSOLE_PANEL_WIDTH,
             )
         )
 
@@ -225,7 +240,12 @@ class EnhancedFormatter(OutputFormatter):
             )
 
         console.print(
-            Panel(severity_table, title="🎯 Issue Severity Breakdown", border_style="bright_blue")
+            Panel(
+                severity_table,
+                title="🎯 Issue Severity Breakdown",
+                border_style=constants.CONSOLE_HEADER_COLOR,
+                width=constants.CONSOLE_PANEL_WIDTH,
+            )
         )
 
     def _format_policy_result_modern(
@@ -247,7 +267,7 @@ class EnhancedFormatter(OutputFormatter):
         elif result.is_valid and result.issues:
             # Valid IAM policy but has security findings
             # Check severity to determine the appropriate status
-            has_critical = any(i.severity in ("error", "critical", "high") for i in result.issues)
+            has_critical = any(i.severity in constants.HIGH_SEVERITY_LEVELS for i in result.issues)
             if has_critical:
                 icon = "⚠️"
                 color = "red"
@@ -386,6 +406,13 @@ class EnhancedFormatter(OutputFormatter):
             suggestion_text.append(issue.suggestion, style="italic yellow")
             msg_node.add(suggestion_text)
 
+        # Example (if present, show with indentation)
+        if issue.example:
+            msg_node.add(Text("Example:", style="bold cyan"))
+            # Show example code with syntax highlighting
+            example_text = Text(issue.example, style="dim")
+            msg_node.add(example_text)
+
     def _print_final_status(self, console: Console, report: ValidationReport) -> None:
         """Print final status panel."""
         if report.invalid_policies == 0 and report.total_issues == 0:
@@ -400,7 +427,7 @@ class EnhancedFormatter(OutputFormatter):
             # Valid IAM policies but may have security findings
             # Check if there are critical/high security issues
             has_critical = any(
-                i.severity in ("error", "critical", "high")
+                i.severity in constants.HIGH_SEVERITY_LEVELS
                 for r in report.results
                 for i in r.issues
             )
@@ -437,4 +464,11 @@ class EnhancedFormatter(OutputFormatter):
         final_text.append("\n\n")
         final_text.append(message)
 
-        console.print(Panel(final_text, border_style=border_color, padding=(1, 2)))
+        console.print(
+            Panel(
+                final_text,
+                border_style=border_color,
+                padding=(1, 2),
+                width=constants.CONSOLE_PANEL_WIDTH,
+            )
+        )

iam_validator/core/formatters/markdown.py

@@ -1,5 +1,6 @@
 """Markdown formatter - placeholder for existing functionality."""
 
+from iam_validator.core import constants
 from iam_validator.core.formatters.base import OutputFormatter
 from iam_validator.core.models import ValidationReport
 
@@ -34,7 +35,7 @@ class MarkdownFormatter(OutputFormatter):
             1
             for r in report.results
             for i in r.issues
-            if i.severity in ("error", "critical", "high")
+            if i.severity in constants.HIGH_SEVERITY_LEVELS
         )
         warnings = sum(
             1 for r in report.results for i in r.issues if i.severity in ("warning", "medium")

iam_validator/core/models.py

@@ -8,6 +8,8 @@ from typing import Any, ClassVar, Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
+from iam_validator.core import constants
+
 # Policy Type Constants
 PolicyType = Literal[
     "IDENTITY_POLICY",
@@ -89,9 +91,8 @@ class ServiceDetail(BaseModel):
     resources_list: list[ResourceType] = Field(default_factory=list, alias="Resources")
     condition_keys_list: list[ConditionKey] = Field(default_factory=list, alias="ConditionKeys")
 
-    def model_post_init(self, __context: Any) -> None:
+    def model_post_init(self, __context: Any, /) -> None:
         """Convert lists to dictionaries for easier lookup."""
-        del __context  # Unused
         # Convert actions list to dict
         self.actions = {action.name: action for action in self.actions_list}
         # Convert resources list to dict
@@ -104,7 +105,7 @@ class ServiceDetail(BaseModel):
 class Statement(BaseModel):
     """IAM policy statement."""
 
-    model_config = ConfigDict(populate_by_name=True)
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
     sid: str | None = Field(default=None, alias="Sid")
     effect: str = Field(alias="Effect")
@@ -134,7 +135,7 @@ class Statement(BaseModel):
 class IAMPolicy(BaseModel):
     """IAM policy document."""
 
-    model_config = ConfigDict(populate_by_name=True)
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
 
     version: str = Field(alias="Version")
     statement: list[Statement] = Field(alias="Statement")
@@ -161,6 +162,7 @@ class ValidationIssue(BaseModel):
     resource: str | None = None
     condition_key: str | None = None
     suggestion: str | None = None
+    example: str | None = None  # Code example (JSON/YAML) - formatted separately for GitHub
     line_number: int | None = None  # Line number in the policy file (if available)
 
     # Severity level constants (ClassVar to avoid Pydantic treating them as fields)
@@ -225,8 +227,8 @@ class ValidationIssue(BaseModel):
 
         # Add identifier for bot comment cleanup (HTML comment - not visible to users)
         if include_identifier:
-            parts.append("<!-- iam-policy-validator-review -->\n")
-            parts.append("🤖 **IAM Policy Validator**\n")
+            parts.append(f"{constants.REVIEW_IDENTIFIER}\n")
+            parts.append(f"{constants.BOT_IDENTIFIER}\n")
 
         # Build statement context for better navigation
         statement_context = f"Statement[{self.statement_index}]"
@@ -241,7 +243,9 @@ class ValidationIssue(BaseModel):
         parts.append(self.message)
 
         # Put additional details in collapsible section if there are any
-        has_details = bool(self.action or self.resource or self.condition_key or self.suggestion)
+        has_details = bool(
+            self.action or self.resource or self.condition_key or self.suggestion or self.example
+        )
 
         if has_details:
             parts.append("")
@@ -266,6 +270,14 @@ class ValidationIssue(BaseModel):
                 parts.append("**💡 Suggested Fix:**")
                 parts.append("")
                 parts.append(self.suggestion)
+                parts.append("")
+
+            # Add example if present (formatted as JSON code block for GitHub)
+            if self.example:
+                parts.append("**Example:**")
+                parts.append("```json")
+                parts.append(self.example)
+                parts.append("```")
 
             parts.append("")
             parts.append("</details>")
@@ -298,6 +310,9 @@ class ValidationReport(BaseModel):
     validity_issues: int = 0  # Count of IAM validity issues (error/warning/info)
     security_issues: int = 0  # Count of security issues (critical/high/medium/low)
     results: list[PolicyValidationResult] = Field(default_factory=list)
+    parsing_errors: list[tuple[str, str]] = Field(
+        default_factory=list
+    )  # (file_path, error_message)
 
     def get_summary(self) -> str:
         """Generate a human-readable summary."""