gitrupt 0.1.0__py3-none-any.whl

gitrupt/models.py

@@ -0,0 +1,190 @@
+"""
+Data models for Gitrupt.
+
+All scanners return Finding objects.
+The Risk Engine consumes Finding objects and produces a PolicyDecision.
+"""
+
+from __future__ import annotations
+
+import uuid
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Severity(str, Enum):
+    """Finding severity level."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+    @property
+    def score(self) -> int:
+        """Numeric score for this severity level."""
+        return {
+            Severity.LOW: 20,
+            Severity.MEDIUM: 50,
+            Severity.HIGH: 70,
+            Severity.CRITICAL: 90,
+        }[self]
+
+    def __lt__(self, other: str) -> bool:
+        if not isinstance(other, Severity):
+            return NotImplemented
+        order = [Severity.LOW, Severity.MEDIUM, Severity.HIGH, Severity.CRITICAL]
+        return order.index(self) < order.index(other)
+
+    def __le__(self, other: str) -> bool:
+        if not isinstance(other, Severity):
+            return NotImplemented
+        return self == other or self < other
+
+    def __gt__(self, other: str) -> bool:
+        if not isinstance(other, Severity):
+            return NotImplemented
+        order = [Severity.LOW, Severity.MEDIUM, Severity.HIGH, Severity.CRITICAL]
+        return order.index(self) > order.index(other)
+
+    def __ge__(self, other: str) -> bool:
+        if not isinstance(other, Severity):
+            return NotImplemented
+        return self == other or self > other
+
+
+class PolicyAction(str, Enum):
+    """Action to take when a finding is at a given severity level."""
+
+    ALLOW = "allow"
+    WARN = "warn"
+    BLOCK = "block"
+
+
+class Finding(BaseModel):
+    """
+    A security finding from any scanner.
+
+    Scanners return Finding objects; they do not make blocking decisions.
+    The Risk Engine + Policy Engine make the blocking decision.
+    """
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4())[:8].upper())
+    scanner: str
+    rule_id: str
+    severity: Severity
+    confidence: float = Field(ge=0.0, le=1.0)
+    file: str
+    line: int | None = None
+    message: str
+    description: str = ""
+    evidence: str = ""  # Always redacted — never the raw secret
+    recommendation: str = ""
+    can_override: bool = True
+
+    model_config = {"frozen": True}
+
+    def __hash__(self) -> int:
+        return hash((self.scanner, self.rule_id, self.file, self.line))
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, Finding):
+            return NotImplemented
+        return (
+            self.scanner == other.scanner
+            and self.rule_id == other.rule_id
+            and self.file == other.file
+            and self.line == other.line
+        )
+
+
+class StagedFile(BaseModel):
+    """A file that is staged for commit."""
+
+    path: str
+    status: str  # A=added, M=modified, D=deleted, R=renamed, C=copied
+    old_path: str | None = None  # Only for renames
+    is_binary: bool = False
+    size_bytes: int = 0
+
+    model_config = {"frozen": True}
+
+
+class ScanTarget(BaseModel):
+    """The target of a scan: staged files and their content."""
+
+    staged_files: list[StagedFile] = Field(default_factory=list)
+    staged_diff: str = ""
+    repo_root: str = ""
+
+    model_config = {"frozen": False}
+
+    @property
+    def file_paths(self) -> list[str]:
+        return [f.path for f in self.staged_files]
+
+
+class ScanResult(BaseModel):
+    """The aggregated result of running all scanners."""
+
+    findings: list[Finding] = Field(default_factory=list)
+    files_scanned: int = 0
+    scan_duration_ms: float = 0.0
+    scanners_run: list[str] = Field(default_factory=list)
+
+    model_config = {"frozen": False}
+
+    @property
+    def has_findings(self) -> bool:
+        return len(self.findings) > 0
+
+    @property
+    def critical_findings(self) -> list[Finding]:
+        return [f for f in self.findings if f.severity == Severity.CRITICAL]
+
+    @property
+    def high_findings(self) -> list[Finding]:
+        return [f for f in self.findings if f.severity == Severity.HIGH]
+
+    @property
+    def medium_findings(self) -> list[Finding]:
+        return [f for f in self.findings if f.severity == Severity.MEDIUM]
+
+    @property
+    def low_findings(self) -> list[Finding]:
+        return [f for f in self.findings if f.severity == Severity.LOW]
+
+    @property
+    def max_severity(self) -> Severity | None:
+        if not self.findings:
+            return None
+        return max(f.severity for f in self.findings)
+
+
+class PolicyDecision(BaseModel):
+    """The final policy decision after applying rules to scan results."""
+
+    action: PolicyAction
+    scan_result: ScanResult
+    blocking_findings: list[Finding] = Field(default_factory=list)
+    warning_findings: list[Finding] = Field(default_factory=list)
+
+    model_config = {"frozen": True}
+
+    @property
+    def blocked(self) -> bool:
+        return self.action == PolicyAction.BLOCK
+
+    @property
+    def allowed(self) -> bool:
+        return self.action == PolicyAction.ALLOW
+
+    @property
+    def has_warnings(self) -> bool:
+        return len(self.warning_findings) > 0
+
+    @property
+    def exit_code(self) -> int:
+        return 1 if self.blocked else 0

gitrupt/policy.py

@@ -0,0 +1,36 @@
+"""
+Policy engine for Gitrupt.
+
+Converts configuration into policy decisions.
+Thin wrapper that makes policy intent explicit.
+"""
+
+from __future__ import annotations
+
+from gitrupt.config import PolicyConfig
+from gitrupt.models import Finding, PolicyAction, Severity
+
+
+def get_action_for_finding(finding: Finding, policy: PolicyConfig) -> PolicyAction:
+    """Return the policy action for a given finding."""
+    return policy.action_for(finding.severity)
+
+
+def is_blocking(finding: Finding, policy: PolicyConfig) -> bool:
+    """Return True if this finding should block a commit."""
+    return get_action_for_finding(finding, policy) == PolicyAction.BLOCK
+
+
+def is_warning(finding: Finding, policy: PolicyConfig) -> bool:
+    """Return True if this finding should produce a warning (but not block)."""
+    return get_action_for_finding(finding, policy) == PolicyAction.WARN
+
+
+def get_severity_label(severity: Severity) -> str:
+    """Return a human-readable label for a severity level."""
+    return {
+        Severity.LOW: "Low",
+        Severity.MEDIUM: "Medium",
+        Severity.HIGH: "High",
+        Severity.CRITICAL: "Critical",
+    }[severity]

gitrupt/reporting.py

@@ -0,0 +1,316 @@
+"""
+Terminal reporter for Gitrupt.
+
+Produces human-readable, colored output for the developer.
+
+Security rule: secrets are NEVER printed in full.
+All evidence fields are already redacted before reaching this module.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich import box
+from rich.text import Text
+
+from gitrupt.models import Finding, PolicyDecision, PolicyAction, ScanResult, Severity
+
+# Force UTF-8 output on Windows to avoid cp1252 encoding errors with special chars
+if sys.platform == "win32":
+    os.environ.setdefault("PYTHONIOENCODING", "utf-8")
+
+# Create console instances — one for stdout, one for stderr
+# force_terminal=True ensures colored output; highlight=False avoids auto-detection issues
+console = Console(force_terminal=True, highlight=False)
+error_console = Console(stderr=True, force_terminal=True, highlight=False)
+
+# Severity color map
+SEVERITY_COLORS = {
+    Severity.CRITICAL: "bold red",
+    Severity.HIGH: "red",
+    Severity.MEDIUM: "yellow",
+    Severity.LOW: "cyan",
+}
+
+SEVERITY_ICONS = {
+    Severity.CRITICAL: "[CRIT]",
+    Severity.HIGH: "[HIGH]",
+    Severity.MEDIUM: "[MED] ",
+    Severity.LOW: "[LOW] ",
+}
+
+
+def print_header() -> None:
+    """Print the Gitrupt header."""
+    console.print()
+    console.print("[bold blue][Gitrupt][/bold blue]")
+    console.print()
+
+
+def print_scanning(file_count: int) -> None:
+    """Print the 'scanning...' status."""
+    console.print(f"[dim]Scanning {file_count} staged file{'s' if file_count != 1 else ''}...[/dim]")
+    console.print()
+
+
+def print_decision(decision: PolicyDecision) -> None:
+    """Print the full scan result and policy decision."""
+    scan = decision.scan_result
+
+    if decision.blocked:
+        _print_blocked(decision)
+    elif decision.has_warnings:
+        _print_warnings(decision)
+    else:
+        _print_pass(scan)
+
+
+def print_scan_stats(scan: ScanResult) -> None:
+    """Print scan statistics."""
+    duration = scan.scan_duration_ms
+    console.print(
+        f"[dim]Scanned {scan.files_scanned} file{'s' if scan.files_scanned != 1 else ''} "
+        f"in {duration:.0f}ms[/dim]"
+    )
+
+
+def _print_blocked(decision: PolicyDecision) -> None:
+    """Print a BLOCKED result."""
+    error_console.print(
+        Panel(
+            "[bold red]COMMIT BLOCKED[/bold red]",
+            border_style="red",
+            expand=False,
+        )
+    )
+    error_console.print()
+
+    all_findings = decision.blocking_findings + decision.warning_findings
+
+    for finding in all_findings:
+        _print_finding(finding, is_blocking=finding in decision.blocking_findings)
+
+    error_console.print()
+    error_console.print("[dim]Fix the findings above and try again.[/dim]")
+    error_console.print(
+        "[dim]To bypass (not recommended): [bold]git commit --no-verify[/bold][/dim]"
+    )
+    error_console.print()
+
+
+def _print_warnings(decision: PolicyDecision) -> None:
+    """Print a WARN result (commit proceeds but warnings shown)."""
+    console.print(
+        Panel(
+            "[yellow]WARNINGS -- commit proceeding[/yellow]",
+            border_style="yellow",
+            expand=False,
+        )
+    )
+    console.print()
+
+    for finding in decision.warning_findings:
+        _print_finding(finding, is_blocking=False)
+
+    console.print()
+    _print_pass_line(decision.scan_result)
+
+
+def _print_pass(scan: ScanResult) -> None:
+    """Print a PASS result."""
+    _print_pass_line(scan)
+
+
+def _print_pass_line(scan: ScanResult) -> None:
+    """Print the pass summary line."""
+    console.print(
+        f"[bold green][+][/bold green] Files checked: [bold]{scan.files_scanned}[/bold]"
+    )
+    console.print("[bold green][+][/bold green] No issues found")
+    console.print()
+    console.print(
+        Panel(
+            "[bold green]PASS -- commit allowed[/bold green]",
+            border_style="green",
+            expand=False,
+        )
+    )
+    console.print()
+
+
+def _print_finding(finding: Finding, is_blocking: bool) -> None:
+    """Print a single finding."""
+    color = SEVERITY_COLORS.get(finding.severity, "white")
+    icon = SEVERITY_ICONS.get(finding.severity, "[???] ")
+
+    # Location string
+    location = finding.file
+    if finding.line:
+        location += f":{finding.line}"
+
+    # Severity badge
+    severity_label = f"[{color}]{finding.severity.value.upper():8}[/{color}]"
+
+    error_console.print(f"  {icon} {severity_label}  {location}")
+    error_console.print(f"  {'':12}  [bold]{finding.message}[/bold]")
+
+    if finding.description:
+        error_console.print(f"  {'':12}  [dim]{finding.description}[/dim]")
+
+    if finding.evidence:
+        error_console.print(f"  {'':12}  Evidence: [dim]{finding.evidence}[/dim]")
+
+    if finding.recommendation:
+        # Format multi-line recommendations
+        lines = finding.recommendation.strip().split("\n")
+        for i, line in enumerate(lines):
+            prefix = "  " if i > 0 else ""
+            error_console.print(f"  {'':12}  [dim]{prefix}{line}[/dim]")
+
+    error_console.print()
+
+
+
+
+
+
+
+def print_status(
+    repo_root: str | None,
+    git_available: bool,
+    hook_installed: bool,
+    hook_path: str | None,
+    config_path: str | None,
+    git_version: str | None,
+    git_binary: str | None = None,
+    hooks_dir: str | None = None,
+    core_hooks_path: str | None = None,
+    yara_available: bool | None = None,
+    dependency_ecosystems: tuple[str, ...] | None = None,
+    pre_push_installed: bool | None = None,
+    pre_push_path: str | None = None,
+) -> None:
+    """Print the status of Gitrupt installation."""
+    print_header()
+
+    table = Table(box=box.SIMPLE, show_header=False, padding=(0, 2))
+    table.add_column("Item", style="dim", no_wrap=True)
+    table.add_column("Status", overflow="fold")
+
+    def status_row(label: str, ok: bool, value: str = "") -> None:
+        icon = "[green][+][/green]" if ok else "[red][-][/red]"
+        display = f"{icon}  {value}" if value else icon
+        table.add_row(label, display)
+
+    status_row("Git available", git_available, git_version or "not found")
+    status_row("Git binary", bool(git_binary), git_binary or "not on PATH")
+    status_row("Inside Git repo", repo_root is not None, repo_root or "")
+
+    if hooks_dir:
+        hooks_note = hooks_dir
+        if core_hooks_path:
+            hooks_note = f"{hooks_dir}  [yellow](core.hooksPath override)[/yellow]"
+        status_row("Hooks directory", True, hooks_note)
+
+    status_row(
+        "core.hooksPath",
+        core_hooks_path is None,
+        core_hooks_path if core_hooks_path else "not set (using default)",
+    )
+    status_row("pre-commit hook", hook_installed, hook_path or "not installed")
+
+    if pre_push_installed is not None:
+        status_row(
+            "pre-push hook",
+            pre_push_installed,
+            pre_push_path if pre_push_installed else "not installed",
+        )
+
+    if yara_available is not None:
+        yara_note = "available (full rule engine)" if yara_available else "not installed (fallback mode)"
+        status_row("YARA engine", True, yara_note)
+
+    if dependency_ecosystems is not None:
+        if dependency_ecosystems:
+            status_row("Dependency ecosystems", True, ", ".join(dependency_ecosystems))
+        else:
+            status_row("Dependency ecosystems", False, "none registered")
+
+    status_row("Configuration", config_path is not None, config_path or "using defaults")
+
+    console.print(table)
+
+    if core_hooks_path:
+        console.print(
+            "[yellow]Note:[/yellow] [bold]core.hooksPath[/bold] is set. Git reads hooks from "
+            f"[dim]{core_hooks_path}[/dim], not the default [dim].git/hooks[/dim]."
+        )
+        console.print()
+
+    if hook_installed and repo_root:
+        console.print("[bold green]Protection is active.[/bold green]")
+    elif repo_root:
+        console.print(
+            "[yellow]Hook not installed. Run [bold]gitrupt init[/bold] to enable protection.[/yellow]"
+        )
+    else:
+        console.print("[red]Not inside a Git repository.[/red]")
+    console.print()
+
+
+def print_init_result(
+    repo_root: str,
+    hook_paths: list[str],
+    was_existing_hook: bool,
+    config_exists: bool,
+) -> None:
+    """Print the result of gitrupt init."""
+    print_header()
+    console.print("Installing security firewall...")
+    console.print()
+    console.print("[green][+][/green]  Repository detected")
+    console.print("[green][+][/green]  Existing hooks checked")
+    if was_existing_hook:
+        console.print("[green][+][/green]  Existing hook(s) preserved and chained")
+    for hp in hook_paths:
+        console.print(f"[green][+][/green]  Hook installed: [dim]{hp}[/dim]")
+    if config_exists:
+        console.print("[green][+][/green]  Gitrupt configuration found")
+    else:
+        console.print("[dim]  No .gitrupt.yml found -- using defaults[/dim]")
+    console.print()
+    console.print("[bold green]Protection enabled.[/bold green]")
+    console.print()
+
+
+
+
+def print_uninstall_result(hook_path: str, success: bool) -> None:
+    """Print the result of gitrupt uninstall."""
+    print_header()
+    if success:
+        console.print(f"[green][+][/green]  Hook removed: [dim]{hook_path}[/dim]")
+        console.print()
+        console.print("[yellow]Protection disabled.[/yellow]")
+    else:
+        console.print("[yellow]No Gitrupt hook found to remove.[/yellow]")
+    console.print()
+
+
+def print_error(message: str) -> None:
+    """Print an error message."""
+    error_console.print(f"[red]Error:[/red] {message}")
+
+
+def print_config(config_dict: dict) -> None:
+    """Print the current configuration."""
+    print_header()
+    import yaml  # type: ignore[import-untyped]
+    console.print("[bold]Current configuration:[/bold]")
+    console.print()
+    console.print(yaml.dump(config_dict, default_flow_style=False, sort_keys=False))