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

iam_validator/core/models.py

@@ -236,23 +236,39 @@ class ValidationIssue(BaseModel):
         # Main issue header with statement context
         parts.append(f"{emoji} **{self.severity.upper()}** in **{statement_context}**")
         parts.append("")
+
+        # Show message immediately (not collapsed)
         parts.append(self.message)
 
-        # Add affected fields section if any are present
-        if self.action or self.resource or self.condition_key:
+        # 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)
+
+        if has_details:
             parts.append("")
-            parts.append("**Affected Fields:**")
-            if self.action:
-                parts.append(f"  - Action: `{self.action}`")
-            if self.resource:
-                parts.append(f"  - Resource: `{self.resource}`")
-            if self.condition_key:
-                parts.append(f"  - Condition Key: `{self.condition_key}`")
-
-        # Add suggestion if present
-        if self.suggestion:
+            parts.append("<details>")
+            parts.append("<summary>📋 <b>View Details</b></summary>")
+            parts.append("")
+            parts.append("")  # Extra spacing after opening
+
+            # Add affected fields section if any are present
+            if self.action or self.resource or self.condition_key:
+                parts.append("**Affected Fields:**")
+                if self.action:
+                    parts.append(f"  - Action: `{self.action}`")
+                if self.resource:
+                    parts.append(f"  - Resource: `{self.resource}`")
+                if self.condition_key:
+                    parts.append(f"  - Condition Key: `{self.condition_key}`")
+                parts.append("")
+
+            # Add suggestion if present
+            if self.suggestion:
+                parts.append("**💡 Suggested Fix:**")
+                parts.append("")
+                parts.append(self.suggestion)
+
             parts.append("")
-            parts.append(f"💡 **Suggestion**: {self.suggestion}")
+            parts.append("</details>")
 
         return "\n".join(parts)
 

iam_validator/core/pr_commenter.py

@@ -8,6 +8,11 @@ import json
 import logging
 from typing import Any
 
+from iam_validator.core.constants import (
+    BOT_IDENTIFIER,
+    REVIEW_IDENTIFIER,
+    SUMMARY_IDENTIFIER,
+)
 from iam_validator.core.models import ValidationIssue, ValidationReport
 from iam_validator.integrations.github_integration import GitHubIntegration, ReviewEvent
 
@@ -17,10 +22,10 @@ logger = logging.getLogger(__name__)
 class PRCommenter:
     """Posts validation findings as PR comments."""
 
-    # Identifier for bot comments (used for cleanup/updates)
-    BOT_IDENTIFIER = "🤖 IAM Policy Validator"
-    SUMMARY_IDENTIFIER = "<!-- iam-policy-validator-summary -->"
-    REVIEW_IDENTIFIER = "<!-- iam-policy-validator-review -->"
+    # Load identifiers from constants module for consistency
+    BOT_IDENTIFIER = BOT_IDENTIFIER
+    SUMMARY_IDENTIFIER = SUMMARY_IDENTIFIER
+    REVIEW_IDENTIFIER = REVIEW_IDENTIFIER
 
     def __init__(
         self,
@@ -60,7 +65,11 @@ class PRCommenter:
             self.github = GitHubIntegration()
 
         if not self.github.is_configured():
-            logger.error("GitHub integration not configured")
+            logger.error(
+                "GitHub integration not configured. "
+                "Required: GITHUB_TOKEN, GITHUB_REPOSITORY, and GITHUB_PR_NUMBER environment variables. "
+                "Ensure your workflow is triggered by a pull_request event."
+            )
             return False
 
         success = True
@@ -116,6 +125,14 @@ class PRCommenter:
             if not result.issues:
                 continue
 
+            # Convert absolute path to relative path for GitHub
+            relative_path = self._make_relative_path(result.policy_file)
+            if not relative_path:
+                logger.warning(
+                    f"Could not determine relative path for {result.policy_file}, skipping review comments"
+                )
+                continue
+
             # Try to determine line numbers from the policy file
             line_mapping = self._get_line_mapping(result.policy_file)
 
@@ -125,14 +142,21 @@ class PRCommenter:
 
                 if line_number:
                     comment = {
-                        "path": result.policy_file,
+                        "path": relative_path,  # Use relative path for GitHub
                         "line": line_number,
                         "body": issue.to_pr_comment(),
                     }
 
-                    if result.policy_file not in comments_by_file:
-                        comments_by_file[result.policy_file] = []
-                    comments_by_file[result.policy_file].append(comment)
+                    if relative_path not in comments_by_file:
+                        comments_by_file[relative_path] = []
+                    comments_by_file[relative_path].append(comment)
+                    logger.debug(
+                        f"Prepared review comment for {relative_path}:{line_number} - {issue.issue_type}"
+                    )
+                else:
+                    logger.debug(
+                        f"Could not determine line number for issue in {relative_path}: {issue.issue_type}"
+                    )
 
         # If no line-specific comments, skip
         if not comments_by_file:
@@ -144,6 +168,14 @@ class PRCommenter:
         for file_comments in comments_by_file.values():
             all_comments.extend(file_comments)
 
+        logger.info(
+            f"Posting {len(all_comments)} review comments across {len(comments_by_file)} file(s)"
+        )
+
+        # Log files that will receive comments (for debugging)
+        for file_path, file_comments in comments_by_file.items():
+            logger.debug(f"  {file_path}: {len(file_comments)} comment(s)")
+
         # Determine review event based on fail_on_severities config
         # Check if any issue has a severity that should trigger REQUEST_CHANGES
         has_blocking_issues = any(
@@ -154,22 +186,76 @@ class PRCommenter:
 
         # Set review event: request changes if any blocking issues, else comment
         event = ReviewEvent.REQUEST_CHANGES if has_blocking_issues else ReviewEvent.COMMENT
+        logger.info(f"Creating PR review with event: {event.value}")
 
-        # Post review with comments (include identifier in review body for cleanup)
-        review_body = (
-            f"{self.REVIEW_IDENTIFIER}\n\n"
-            f"🤖 **IAM Policy Validator**\n\n"
-            f"## Validation Results\n\n"
-            f"Found {report.total_issues} issues across {report.total_policies} policies.\n"
-            f"See inline comments for details."
-        )
+        # Post review with comments (use minimal body since summary comment has the details)
+        # Only include the identifier for cleanup purposes
+        review_body = f"{self.REVIEW_IDENTIFIER}"
 
-        return await self.github.create_review_with_comments(
+        success = await self.github.create_review_with_comments(
             comments=all_comments,
             body=review_body,
             event=event,
         )
 
+        if success:
+            logger.info(f"Successfully created PR review with {len(all_comments)} comments")
+        else:
+            logger.error("Failed to create PR review")
+
+        return success
+
+    def _make_relative_path(self, policy_file: str) -> str | None:
+        """Convert absolute path to relative path for GitHub.
+
+        GitHub PR review comments require paths relative to the repository root.
+
+        Args:
+            policy_file: Absolute or relative path to policy file
+
+        Returns:
+            Relative path from repository root, or None if cannot be determined
+        """
+        import os
+        from pathlib import Path
+
+        # If already relative, use as-is
+        if not os.path.isabs(policy_file):
+            return policy_file
+
+        # Try to get workspace path from environment
+        workspace = os.getenv("GITHUB_WORKSPACE")
+        if workspace:
+            try:
+                # Convert to Path objects for proper path handling
+                abs_file_path = Path(policy_file).resolve()
+                workspace_path = Path(workspace).resolve()
+
+                # Check if file is within workspace
+                if abs_file_path.is_relative_to(workspace_path):
+                    relative = abs_file_path.relative_to(workspace_path)
+                    # Use forward slashes for GitHub (works on all platforms)
+                    return str(relative).replace("\\", "/")
+            except (ValueError, OSError) as e:
+                logger.debug(f"Could not compute relative path for {policy_file}: {e}")
+
+        # Fallback: try current working directory
+        try:
+            cwd = Path.cwd()
+            abs_file_path = Path(policy_file).resolve()
+            if abs_file_path.is_relative_to(cwd):
+                relative = abs_file_path.relative_to(cwd)
+                return str(relative).replace("\\", "/")
+        except (ValueError, OSError) as e:
+            logger.debug(f"Could not compute relative path from CWD for {policy_file}: {e}")
+
+        # If all else fails, return None
+        logger.warning(
+            f"Could not determine relative path for {policy_file}. "
+            "Ensure GITHUB_WORKSPACE is set or file is in current directory."
+        )
+        return None
+
     def _get_line_mapping(self, policy_file: str) -> dict[int, int]:
         """Get mapping of statement indices to line numbers.
 

iam_validator/core/report.py

@@ -126,7 +126,8 @@ class ReportGenerator:
         # Show policies with security findings (separate from validity)
         if report.policies_with_security_issues > 0:
             summary_text.append(
-                f"Security Findings: {report.policies_with_security_issues} ", style="yellow"
+                f"Security Findings: {report.policies_with_security_issues} ",
+                style="yellow",
             )
 
         summary_text.append("\n")
@@ -418,8 +419,7 @@ class ReportGenerator:
                 1 for r in report.results for i in r.issues if i.severity in ("info", "low")
             )
 
-            lines.append("<details>")
-            lines.append("<summary><b>🔍 Issue Breakdown</b></summary>")
+            lines.append("### 🔍 Issue Breakdown")
             lines.append("")
             lines.append("| Severity | Count |")
             lines.append("|----------|------:|")
@@ -430,8 +430,6 @@ class ReportGenerator:
             if infos > 0:
                 lines.append(f"| 🔵 **Info** | {infos} |")
             lines.append("")
-            lines.append("</details>")
-            lines.append("")
 
         return lines
 
@@ -442,11 +440,7 @@ class ReportGenerator:
                 "---",
                 "",
                 "<div align='center'>",
-                "",
-                "**🤖 Generated by IAM Policy Validator**",
-                "",
-                "_Powered by AWS IAM Access Analyzer and custom policy checks_",
-                "",
+                "🤖 <em>Generated by <strong>IAM Policy Validator</strong></em><br>",
                 "</div>",
             ]
         )
@@ -455,9 +449,9 @@ class ReportGenerator:
         """Format a single policy's issues for the comment."""
         lines = []
 
-        lines.append("<details open>")
+        lines.append("<details>")
         lines.append(
-            f"<summary><b>{idx}. <code>{result.policy_file}</code></b> - {len(result.issues)} issue(s) found</summary>"
+            f"<summary>📋 <b>{idx}. <code>{result.policy_file}</code></b> - {len(result.issues)} issue(s) found</summary>"
         )
         lines.append("")
 
@@ -470,21 +464,21 @@ class ReportGenerator:
             lines.append("### 🔴 Errors")
             lines.append("")
             for issue in errors:
-                lines.append(self._format_issue_markdown(issue))
+                lines.append(self._format_issue_markdown(issue, result.policy_file))
             lines.append("")
 
         if warnings:
             lines.append("### 🟡 Warnings")
             lines.append("")
             for issue in warnings:
-                lines.append(self._format_issue_markdown(issue))
+                lines.append(self._format_issue_markdown(issue, result.policy_file))
             lines.append("")
 
         if infos:
             lines.append("### 🔵 Info")
             lines.append("")
             for issue in infos:
-                lines.append(self._format_issue_markdown(issue))
+                lines.append(self._format_issue_markdown(issue, result.policy_file))
             lines.append("")
 
         lines.append("</details>")
@@ -573,8 +567,7 @@ class ReportGenerator:
                 1 for r in report.results for i in r.issues if i.severity in ("info", "low")
             )
 
-            lines.append("<details>")
-            lines.append("<summary><b>🔍 Issue Breakdown</b></summary>")
+            lines.append("### 🔍 Issue Breakdown")
             lines.append("")
             lines.append("| Severity | Count |")
             lines.append("|----------|------:|")
@@ -585,22 +578,17 @@ class ReportGenerator:
             if infos > 0:
                 lines.append(f"| 🔵 **Info** | {infos} |")
             lines.append("")
-            lines.append("</details>")
-            lines.append("")
 
         # Store header for later (we always include this)
         header_content = "\n".join(lines)
 
         # Footer (we always include this)
         footer_lines = [
+            "",
             "---",
             "",
             "<div align='center'>",
-            "",
-            "**🤖 Generated by IAM Policy Validator**",
-            "",
-            "_Powered by AWS IAM Access Analyzer and custom policy checks_",
-            "",
+            "🤖 <em>Generated by <strong>IAM Policy Validator</strong></em><br>",
             "</div>",
         ]
         footer_content = "\n".join(footer_lines)
@@ -650,8 +638,8 @@ class ReportGenerator:
                 severity_summary = " · ".join(severity_parts)
 
                 # Only open first 3 policy details by default to avoid wall of text
-                is_open = " open" if policies_shown < 3 else ""
-                policy_lines.append(f"<details{is_open}>")
+                # is_open = " open" if policies_shown < 3 else ""
+                policy_lines.append("<details>")
                 policy_lines.append(
                     f"<summary><b>{idx}. <code>{result.policy_file}</code></b> - {severity_summary}</summary>"
                 )
@@ -662,7 +650,7 @@ class ReportGenerator:
                     policy_lines.append("### 🔴 Errors")
                     policy_lines.append("")
                     for i, issue in enumerate(errors):
-                        issue_content = self._format_issue_markdown(issue)
+                        issue_content = self._format_issue_markdown(issue, result.policy_file)
                         test_length = len("\n".join(details_lines + policy_lines)) + len(
                             issue_content
                         )
@@ -685,7 +673,7 @@ class ReportGenerator:
                     policy_lines.append("### 🟡 Warnings")
                     policy_lines.append("")
                     for i, issue in enumerate(warnings):
-                        issue_content = self._format_issue_markdown(issue)
+                        issue_content = self._format_issue_markdown(issue, result.policy_file)
                         test_length = len("\n".join(details_lines + policy_lines)) + len(
                             issue_content
                         )
@@ -708,7 +696,7 @@ class ReportGenerator:
                     policy_lines.append("### 🔵 Info")
                     policy_lines.append("")
                     for i, issue in enumerate(infos):
-                        issue_content = self._format_issue_markdown(issue)
+                        issue_content = self._format_issue_markdown(issue, result.policy_file)
                         test_length = len("\n".join(details_lines + policy_lines)) + len(
                             issue_content
                         )
@@ -728,8 +716,6 @@ class ReportGenerator:
 
                 policy_lines.append("</details>")
                 policy_lines.append("")
-                policy_lines.append("---")
-                policy_lines.append("")
 
                 # Check if adding this policy would exceed limit
                 test_length = len("\n".join(details_lines + policy_lines))
@@ -740,6 +726,15 @@ class ReportGenerator:
                 details_lines.extend(policy_lines)
                 policies_shown += 1
 
+                # Add separator between policies (but not after the last one)
+                # The footer will add its own separator
+                if (
+                    policies_shown < len([r for r in sorted_results if r[1].issues])
+                    and not truncated
+                ):
+                    details_lines.append("---")
+                    details_lines.append("")
+
             # Add truncation warning if needed
             if truncated:
                 remaining_policies = len([r for r in report.results if r.issues]) - policies_shown
@@ -776,13 +771,31 @@ class ReportGenerator:
 
         return "\n".join(lines)
 
-    def _format_issue_markdown(self, issue: ValidationIssue) -> str:
-        """Format a single issue as markdown."""
+    def _format_issue_markdown(self, issue: ValidationIssue, policy_file: str | None = None) -> str:
+        """Format a single issue as markdown.
+
+        Args:
+            issue: The validation issue to format
+            policy_file: Optional policy file path (currently unused, kept for compatibility)
+        """
         # Use 1-indexed statement numbers for user-facing output
         statement_num = issue.statement_index + 1
-        location = f"Statement {statement_num}"
-        if issue.statement_sid:
-            location = f"`{issue.statement_sid}` (statement #{statement_num})"
+
+        # Build statement location reference
+        # Note: We show plain text here instead of links because:
+        # 1. GitHub's diff anchor format only works for files in the PR diff
+        # 2. Inline review comments (posted separately) already provide perfect navigation
+        # 3. Summary comment is for overview, not detailed navigation
+        if issue.line_number:
+            location = f"Statement {statement_num} (Line {issue.line_number})"
+            if issue.statement_sid:
+                location = (
+                    f"`{issue.statement_sid}` (statement {statement_num}, line {issue.line_number})"
+                )
+        else:
+            location = f"Statement {statement_num}"
+            if issue.statement_sid:
+                location = f"`{issue.statement_sid}` (statement {statement_num})"
 
         parts = []
 

iam_validator/integrations/github_integration.py

@@ -238,7 +238,27 @@ class GitHubIntegration:
         Returns:
             True if all required environment variables are set
         """
-        return all([self.token, self.repository, self.pr_number])
+        is_valid = all([self.token, self.repository, self.pr_number])
+
+        # Provide helpful debug info when not configured
+        if not is_valid:
+            missing = []
+            if not self.token:
+                missing.append("GITHUB_TOKEN")
+            if not self.repository:
+                missing.append("GITHUB_REPOSITORY")
+            if not self.pr_number:
+                missing.append("GITHUB_PR_NUMBER")
+
+            logger.debug(f"GitHub integration missing: {', '.join(missing)}")
+            if not self.pr_number and self.token and self.repository:
+                logger.info(
+                    "GitHub PR integration requires GITHUB_PR_NUMBER. "
+                    "This is only available when running on pull request events. "
+                    "Current event may not have PR context."
+                )
+
+        return is_valid
 
     async def _make_request(
         self, method: str, endpoint: str, **kwargs: Any

iam_validator/sdk/arn_matching.py

@@ -245,6 +245,114 @@ def _strip_variables_from_arn(arn: str, replace_with: str = "") -> str:
     return re.sub(r"\$\{aws[\.:][\w\/]+\}", replace_with, arn)
 
 
+def normalize_template_variables(arn: str) -> str:
+    """
+    Normalize template variables in ARN to valid placeholders for validation.
+
+    This function is POSITION-AWARE and handles ANY variable name by determining
+    the appropriate replacement based on where the variable appears in the ARN structure.
+    It correctly handles variables with colons inside them (e.g., ${AWS::AccountId}).
+
+    Supports template variables from:
+    - Terraform/Terragrunt: ${var.name}, ${local.value}, ${data.source.attr}, etc.
+    - CloudFormation: ${AWS::AccountId}, ${AWS::Region}, ${MyParameter}, etc.
+    - AWS policy variables: ${aws:username}, ${aws:PrincipalTag/tag-key}, etc.
+
+    Args:
+        arn: ARN string that may contain template variables
+
+    Returns:
+        ARN with template variables replaced with valid placeholders based on position
+
+    Examples:
+        >>> normalize_template_variables("arn:aws:iam::${my_account}:role/name")
+        'arn:aws:iam::123456789012:role/name'
+
+        >>> normalize_template_variables("arn:aws:iam::${AWS::AccountId}:role/name")
+        'arn:aws:iam::123456789012:role/name'
+
+        >>> normalize_template_variables("arn:${var.partition}:s3:::${var.bucket}/*")
+        'arn:aws:s3:::placeholder/*'
+    """
+    # Strategy: Use a simpler, more robust approach
+    # First protect template variables by temporarily replacing them with markers,
+    # then split the ARN, then replace based on position
+
+    # Step 1: Find all template variables and temporarily replace them with position markers
+    # This handles variables with colons inside them (like ${AWS::AccountId})
+    variables = []
+
+    def save_variable(match):
+        variables.append(match.group(0))
+        return f"__VAR{len(variables) - 1}__"
+
+    # Save all template variables (including those with colons, dots, slashes, etc.)
+    temp_arn = re.sub(r"\$\{[^}]+\}", save_variable, arn)
+
+    # Step 2: Now we can safely split by colons
+    parts = temp_arn.split(":", 5)
+
+    if len(parts) < 6:
+        # Not a valid ARN format, restore variables with generic placeholder
+        result = arn
+        for var in variables:
+            if re.match(r"\$\{aws[\.:]", var, re.IGNORECASE):
+                result = result.replace(var, "placeholder", 1)
+            else:
+                result = result.replace(var, "placeholder", 1)
+        return result
+
+    # Step 3: Restore variables based on their position in the ARN
+    # ARN format: arn:partition:service:region:account:resource
+    replacements = {
+        1: "aws",  # partition
+        2: "s3",  # service (generic placeholder)
+        3: "us-east-1",  # region
+        4: "123456789012",  # account
+        5: "placeholder",  # resource
+    }
+
+    for i, part in enumerate(parts):
+        if "__VAR" in part:
+            # Find all variable markers in this part
+            for j, var in enumerate(variables):
+                marker = f"__VAR{j}__"
+                if marker in part:
+                    # Determine replacement based on position
+                    if i in replacements:
+                        parts[i] = parts[i].replace(marker, replacements[i])
+                    else:
+                        parts[i] = parts[i].replace(marker, "placeholder")
+
+    # Reconstruct ARN
+    return ":".join(parts)
+
+
+def has_template_variables(arn: str) -> bool:
+    """
+    Check if an ARN contains template variables.
+
+    Detects template variables from:
+    - Terraform/Terragrunt: ${var_name}
+    - CloudFormation: ${AWS::AccountId}
+    - AWS policy variables: ${aws:username}
+
+    Args:
+        arn: ARN string to check
+
+    Returns:
+        True if ARN contains template variables, False otherwise
+
+    Examples:
+        >>> has_template_variables("arn:aws:iam::${aws_account_id}:role/name")
+        True
+
+        >>> has_template_variables("arn:aws:iam::123456789012:role/name")
+        False
+    """
+    return bool(re.search(r"\$\{[\w\-\.\_:\/]+\}", arn))
+
+
 def convert_aws_pattern_to_wildcard(pattern: str) -> str:
     """
     Convert AWS ARN pattern format to wildcard pattern for matching.

iam_validator/utils/regex.py

@@ -13,13 +13,12 @@ Performance benefits:
 import re
 from collections.abc import Callable
 from functools import wraps
-from re import Pattern
 
 
 def cached_pattern(
     flags: int = 0,
     maxsize: int = 128,
-) -> Callable[[Callable[[], str]], Callable[[], Pattern]]:
+) -> Callable[[Callable[[], str]], Callable[[], re.Pattern]]:
     r"""Decorator that caches compiled regex patterns.
 
     This decorator transforms a function that returns a regex pattern string
@@ -60,12 +59,12 @@ def cached_pattern(
         Cached calls: ~0.1-0.5μs (cache lookup) → 20-100x faster
     """
 
-    def decorator(func: Callable[[], str]) -> Callable[[], Pattern]:
+    def decorator(func: Callable[[], str]) -> Callable[[], re.Pattern]:
         # Use a cache per function to avoid key collisions
         cache = {}
 
         @wraps(func)
-        def wrapper() -> Pattern:
+        def wrapper() -> re.Pattern:
             # Use function name as cache key (since each decorated function
             # returns the same pattern string)
             cache_key = func.__name__
@@ -84,7 +83,7 @@ def cached_pattern(
     return decorator
 
 
-def compile_and_cache(pattern: str, flags: int = 0, maxsize: int = 512) -> Pattern:
+def compile_and_cache(pattern: str, flags: int = 0, maxsize: int = 512) -> re.Pattern:
     """Compile a regex pattern with automatic caching.
 
     This is a functional interface (not a decorator) that compiles and caches
@@ -116,17 +115,17 @@ def compile_and_cache(pattern: str, flags: int = 0, maxsize: int = 512) -> Patte
     from functools import lru_cache
 
     @lru_cache(maxsize=maxsize)
-    def _compile(pattern_str: str, flags: int) -> Pattern:
+    def _compile(pattern_str: str, flags: int) -> re.Pattern:
         return re.compile(pattern_str, flags)
 
     return _compile(pattern, flags)
 
 
 # Singleton instance for shared pattern compilation
-_pattern_cache: dict[tuple[str, int], Pattern] = {}
+_pattern_cache: dict[tuple[str, int], re.Pattern] = {}
 
 
-def get_cached_pattern(pattern: str, flags: int = 0) -> Pattern:
+def get_cached_pattern(pattern: str, flags: int = 0) -> re.Pattern:
     """Get a compiled pattern from the shared cache.
 
     This provides a simple, stateless way to get cached patterns without