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

iam_validator/core/diff_parser.py

@@ -0,0 +1,325 @@
+"""Diff Parser Module.
+
+This module parses GitHub PR diff information to extract changed line numbers.
+It supports GitHub's unified diff format and provides utilities for determining
+which lines and statements were modified in a PR.
+"""
+
+import logging
+import re
+from dataclasses import dataclass
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ParsedDiff:
+    """Parsed GitHub PR diff information for a single file.
+
+    Attributes:
+        file_path: Relative path to the file from repository root
+        changed_lines: Set of all line numbers that were added or modified (new side)
+        added_lines: Set of line numbers that were added (new side)
+        deleted_lines: Set of line numbers that were deleted (old side)
+        status: File status (added, modified, removed, renamed)
+    """
+
+    file_path: str
+    changed_lines: set[int]
+    added_lines: set[int]
+    deleted_lines: set[int]
+    status: str
+
+
+@dataclass
+class StatementLocation:
+    """Location information for a statement in a policy file.
+
+    Attributes:
+        statement_index: Zero-based index of the statement
+        start_line: First line number of the statement (1-indexed)
+        end_line: Last line number of the statement (1-indexed)
+        has_changes: True if any line in this range was modified
+    """
+
+    statement_index: int
+    start_line: int
+    end_line: int
+    has_changes: bool
+
+
+class DiffParser:
+    """Parser for GitHub PR diff information."""
+
+    @staticmethod
+    def parse_pr_files(pr_files: list[dict[str, Any]]) -> dict[str, ParsedDiff]:
+        """Parse GitHub PR files response to extract changed line information.
+
+        Args:
+            pr_files: List of file dicts from GitHub API's get_pr_files() call.
+                     Each dict contains: filename, status, patch, additions, deletions
+
+        Returns:
+            Dict mapping file paths to ParsedDiff objects
+
+        Example:
+            >>> pr_files = [{
+            ...     "filename": "policies/policy.json",
+            ...     "status": "modified",
+            ...     "patch": "@@ -5,3 +5,4 @@\\n context\\n-old\\n+new\\n+added"
+            ... }]
+            >>> result = DiffParser.parse_pr_files(pr_files)
+            >>> result["policies/policy.json"].changed_lines
+            {6, 7}
+        """
+        parsed: dict[str, ParsedDiff] = {}
+
+        for file_info in pr_files:
+            if not isinstance(file_info, dict):
+                continue
+
+            filename = file_info.get("filename")
+            if not filename or not isinstance(filename, str):
+                continue
+
+            status = file_info.get("status", "modified")
+            patch = file_info.get("patch")
+
+            # Files without patches (e.g., binary files, very large files)
+            # For added/modified files, we use a "no_patch" marker to indicate
+            # that we should allow comments on any line (handled in pr_commenter)
+            if not patch or not isinstance(patch, str):
+                logger.debug(f"No patch available for {filename} (status={status})")
+                # Mark as "no_patch" so pr_commenter can handle this specially
+                # For added/modified files without patch, we'll allow inline comments
+                # on any line since GitHub likely truncated the diff due to size
+                parsed[filename] = ParsedDiff(
+                    file_path=filename,
+                    changed_lines=set(),  # Empty, but status indicates handling
+                    added_lines=set(),
+                    deleted_lines=set(),
+                    status=f"{status}_no_patch",  # Mark as no_patch variant
+                )
+                continue
+
+            try:
+                diff = DiffParser.parse_unified_diff(patch)
+                parsed[filename] = ParsedDiff(
+                    file_path=filename,
+                    changed_lines=diff["changed_lines"],
+                    added_lines=diff["added_lines"],
+                    deleted_lines=diff["deleted_lines"],
+                    status=status,
+                )
+                logger.debug(
+                    f"Parsed diff for {filename}: {len(diff['changed_lines'])} changed lines"
+                )
+            except Exception as e:  # pylint: disable=broad-exception-caught
+                logger.warning(f"Failed to parse diff for {filename}: {e}")
+                # Track file with empty change sets on parse error
+                parsed[filename] = ParsedDiff(
+                    file_path=filename,
+                    changed_lines=set(),
+                    added_lines=set(),
+                    deleted_lines=set(),
+                    status=status,
+                )
+
+        return parsed
+
+    @staticmethod
+    def parse_unified_diff(patch: str) -> dict[str, set[int]]:
+        """Parse a unified diff patch to extract changed line numbers.
+
+        Unified diff format uses @@ headers to indicate line ranges:
+        @@ -old_start,old_count +new_start,new_count @@
+
+        Lines starting with:
+        - '-' are deletions (old side line numbers)
+        - '+' are additions (new side line numbers)
+        - ' ' are context (both sides)
+
+        Args:
+            patch: Unified diff string from GitHub API
+
+        Returns:
+            Dict with keys:
+            - changed_lines: All added/modified lines (new side)
+            - added_lines: Only added lines (new side)
+            - deleted_lines: Only deleted lines (old side)
+
+        Example:
+            >>> patch = '''@@ -5,3 +5,4 @@
+            ...  context line
+            ... -deleted line
+            ... +added line
+            ... +another added line
+            ...  context line'''
+            >>> result = DiffParser.parse_unified_diff(patch)
+            >>> result['added_lines']
+            {6, 7}
+        """
+        changed_lines: set[int] = set()
+        added_lines: set[int] = set()
+        deleted_lines: set[int] = set()
+
+        # Pattern to match @@ -old_start,old_count +new_start,new_count @@ headers
+        # Handles variations: @@ -5,3 +5,4 @@, @@ -5 +5,2 @@, etc.
+        hunk_header_pattern = re.compile(r"^@@\s+-(\d+)(?:,(\d+))?\s+\+(\d+)(?:,(\d+))?\s+@@")
+
+        lines = patch.split("\n")
+        current_new_line = 0
+        current_old_line = 0
+
+        for line in lines:
+            # Check for hunk header
+            match = hunk_header_pattern.match(line)
+            if match:
+                old_start = int(match.group(1))
+                new_start = int(match.group(3))
+                current_old_line = old_start
+                current_new_line = new_start
+                continue
+
+            # Process diff lines
+            if not line:
+                continue
+
+            first_char = line[0]
+
+            if first_char == "+":
+                # Addition (new side only)
+                added_lines.add(current_new_line)
+                changed_lines.add(current_new_line)
+                current_new_line += 1
+            elif first_char == "-":
+                # Deletion (old side only)
+                deleted_lines.add(current_old_line)
+                current_old_line += 1
+            elif first_char == " ":
+                # Context line (both sides)
+                current_new_line += 1
+                current_old_line += 1
+            # Ignore lines that don't start with +, -, or space (e.g., \ No newline)
+
+        return {
+            "changed_lines": changed_lines,
+            "added_lines": added_lines,
+            "deleted_lines": deleted_lines,
+        }
+
+    @staticmethod
+    def get_modified_statements(
+        line_mapping: dict[int, int],
+        changed_lines: set[int],
+        policy_file: str,
+    ) -> dict[int, StatementLocation]:
+        """Determine which statements were modified based on changed lines.
+
+        A statement is considered modified if ANY line within its range appears
+        in the changed_lines set.
+
+        Args:
+            line_mapping: Dict mapping statement index to statement start line
+                         (from PRCommenter._get_line_mapping())
+            changed_lines: Set of line numbers that were changed in the PR
+            policy_file: Path to the policy file (to determine statement end lines)
+
+        Returns:
+            Dict mapping statement indices to StatementLocation objects
+            Only includes statements that were modified.
+
+        Example:
+            >>> line_mapping = {0: 3, 1: 10, 2: 20}  # Statement starts
+            >>> changed_lines = {5, 6}  # Lines changed in statement 0
+            >>> result = get_modified_statements(line_mapping, changed_lines, "policy.json")
+            >>> result[0].has_changes
+            True
+            >>> 1 in result  # Statement 1 not modified
+            False
+        """
+        if not line_mapping or not changed_lines:
+            return {}
+
+        # Determine end line for each statement
+        statement_ranges: dict[int, tuple[int, int]] = {}
+        sorted_indices = sorted(line_mapping.keys())
+
+        for i, stmt_idx in enumerate(sorted_indices):
+            start_line = line_mapping[stmt_idx]
+
+            # End line is either:
+            # 1. One line before next statement starts, OR
+            # 2. EOF for the last statement
+            if i < len(sorted_indices) - 1:
+                next_start = line_mapping[sorted_indices[i + 1]]
+                end_line = next_start - 1
+            else:
+                # For last statement, try to read file to get actual end
+                end_line = DiffParser.get_statement_end_line(policy_file, start_line)
+
+            statement_ranges[stmt_idx] = (start_line, end_line)
+
+        # Check which statements have changes
+        modified_statements: dict[int, StatementLocation] = {}
+
+        for stmt_idx, (start_line, end_line) in statement_ranges.items():
+            # Check if any line in this statement's range was changed
+            statement_lines = set(range(start_line, end_line + 1))
+            has_changes = bool(statement_lines & changed_lines)
+
+            if has_changes:
+                modified_statements[stmt_idx] = StatementLocation(
+                    statement_index=stmt_idx,
+                    start_line=start_line,
+                    end_line=end_line,
+                    has_changes=True,
+                )
+                logger.debug(f"Statement {stmt_idx} (lines {start_line}-{end_line}) was modified")
+
+        return modified_statements
+
+    @staticmethod
+    def get_statement_end_line(policy_file: str, start_line: int) -> int:
+        """Find the end line of a statement block starting at start_line.
+
+        Tracks brace depth to find where the statement object closes.
+
+        Args:
+            policy_file: Path to policy file
+            start_line: Line number where statement starts (1-indexed)
+
+        Returns:
+            Line number where statement ends (1-indexed)
+        """
+        try:
+            with open(policy_file, encoding="utf-8") as f:
+                lines = f.readlines()
+
+            # Start counting from the statement's opening brace
+            brace_depth = 0
+            in_statement = False
+
+            for line_num in range(start_line - 1, len(lines)):  # Convert to 0-indexed
+                line = lines[line_num]
+
+                # Track braces
+                for char in line:
+                    if char == "{":
+                        brace_depth += 1
+                        in_statement = True
+                    elif char == "}":
+                        brace_depth -= 1
+
+                        # Found the closing brace for this statement
+                        if in_statement and brace_depth == 0:
+                            return line_num + 1  # Convert back to 1-indexed
+
+            # If we couldn't find the end, return a reasonable default
+            # (start_line + 20 or end of file)
+            return min(start_line + 20, len(lines))
+
+        except Exception as e:  # pylint: disable=broad-exception-caught
+            logger.debug(f"Could not determine statement end line: {e}")
+            return start_line + 10  # Reasonable default

iam_validator/core/finding_fingerprint.py

@@ -0,0 +1,131 @@
+"""Finding fingerprint generation for stable issue identification.
+
+This module provides a way to generate unique, deterministic identifiers
+for validation findings that survive code changes within a PR. These
+fingerprints are used to track which findings have been ignored by CODEOWNERS.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from iam_validator.core.models import ValidationIssue
+
+
+def compute_finding_hash(
+    file_path: str,
+    check_id: str | None,
+    issue_type: str,
+    statement_sid: str | None,
+    statement_index: int,
+    action: str | None = None,
+    resource: str | None = None,
+    condition_key: str | None = None,
+) -> str:
+    """Compute a deterministic 16-character hash for a finding.
+
+    This is a standalone function to avoid cyclic imports when called
+    from models.py.
+
+    Args:
+        file_path: Relative path to the policy file
+        check_id: Check that found the issue
+        issue_type: Type of issue
+        statement_sid: Statement ID if available
+        statement_index: Statement index
+        action: Specific action (optional)
+        resource: Specific resource (optional)
+        condition_key: Condition key (optional)
+
+    Returns:
+        16-character hex string uniquely identifying this finding
+    """
+    # Use SID if available, otherwise fall back to index
+    statement_id = statement_sid if statement_sid else f"idx:{statement_index}"
+
+    components = [
+        file_path,
+        check_id or "",
+        issue_type,
+        statement_id,
+        action or "",
+        resource or "",
+        condition_key or "",
+    ]
+    combined = "|".join(components)
+    return hashlib.sha256(combined.encode()).hexdigest()[:16]
+
+
+@dataclass(frozen=True, slots=True)
+class FindingFingerprint:
+    """Unique identifier for a validation finding across runs.
+
+    The fingerprint is based on stable attributes of the finding that
+    are unlikely to change when code is modified within the same PR.
+    Uses frozen=True for immutability and slots=True for memory efficiency.
+
+    Attributes:
+        file_path: Relative path to the policy file
+        check_id: Check that found the issue (e.g., "sensitive_action")
+        issue_type: Type of issue (e.g., "invalid_action")
+        statement_sid: Statement ID if available (more stable than index)
+        statement_index: Fallback when no SID is present
+        action: Specific action (for action-related issues)
+        resource: Specific resource (for resource-related issues)
+        condition_key: Specific condition key (for condition issues)
+    """
+
+    file_path: str
+    check_id: str
+    issue_type: str
+    statement_sid: str | None
+    statement_index: int
+    action: str | None
+    resource: str | None
+    condition_key: str | None
+
+    def to_hash(self) -> str:
+        """Generate deterministic 16-character hash for storage.
+
+        The hash is based on all fingerprint components joined with a
+        delimiter. Uses SHA-256 truncated to 16 characters for a good
+        balance between uniqueness and storage efficiency.
+
+        Returns:
+            16-character hex string uniquely identifying this finding
+        """
+        return compute_finding_hash(
+            file_path=self.file_path,
+            check_id=self.check_id,
+            issue_type=self.issue_type,
+            statement_sid=self.statement_sid,
+            statement_index=self.statement_index,
+            action=self.action,
+            resource=self.resource,
+            condition_key=self.condition_key,
+        )
+
+    @classmethod
+    def from_issue(cls, issue: ValidationIssue, file_path: str) -> FindingFingerprint:
+        """Create fingerprint from a ValidationIssue.
+
+        Args:
+            issue: The validation issue to fingerprint
+            file_path: Relative path to the policy file
+
+        Returns:
+            FindingFingerprint instance for the issue
+        """
+        return cls(
+            file_path=file_path,
+            check_id=issue.check_id or "",
+            issue_type=issue.issue_type,
+            statement_sid=issue.statement_sid,
+            statement_index=issue.statement_index,
+            action=issue.action,
+            resource=issue.resource,
+            condition_key=issue.condition_key,
+        )

iam_validator/core/formatters/__init__.py

@@ -0,0 +1,27 @@
+"""Output formatters for IAM Policy Validator."""
+
+from iam_validator.core.formatters.base import (
+    FormatterRegistry,
+    OutputFormatter,
+    get_global_registry,
+)
+from iam_validator.core.formatters.console import ConsoleFormatter
+from iam_validator.core.formatters.csv import CSVFormatter
+from iam_validator.core.formatters.enhanced import EnhancedFormatter
+from iam_validator.core.formatters.html import HTMLFormatter
+from iam_validator.core.formatters.json import JSONFormatter
+from iam_validator.core.formatters.markdown import MarkdownFormatter
+from iam_validator.core.formatters.sarif import SARIFFormatter
+
+__all__ = [
+    "OutputFormatter",
+    "FormatterRegistry",
+    "get_global_registry",
+    "ConsoleFormatter",
+    "EnhancedFormatter",
+    "JSONFormatter",
+    "MarkdownFormatter",
+    "SARIFFormatter",
+    "CSVFormatter",
+    "HTMLFormatter",
+]

iam_validator/core/formatters/base.py

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

iam_validator/core/formatters/console.py

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