gitrupt 0.1.0__py3-none-any.whl

gitrupt/risk.py

@@ -0,0 +1,197 @@
+"""
+Risk engine for Gitrupt.
+
+Combines findings from all scanners, deduplicates them,
+calculates effective risk, and applies policy to produce a PolicyDecision.
+
+Scanners detect. The Risk Engine + Policy Engine decide.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import logging
+from typing import Any
+
+from gitrupt.config import PolicyConfig, SuppressionConfig
+from gitrupt.models import Finding, PolicyAction, PolicyDecision, ScanResult, Severity
+
+logger = logging.getLogger(__name__)
+
+
+def _matches_suppression(finding: Finding, suppressions: list[str]) -> bool:
+    """Return True when a finding matches any configured suppression rule."""
+    if not suppressions:
+        return False
+
+    return any(
+        token in (finding.rule_id, finding.scanner, finding.file, finding.message)
+        for token in suppressions
+    )
+
+
+def _matches_path_suppression(file_path: str, patterns: list[str]) -> bool:
+    """Return True when a file path matches any configured path suppression pattern."""
+    if not patterns:
+        return False
+
+    for pattern in patterns:
+        if fnmatch.fnmatch(file_path, pattern):
+            return True
+        if fnmatch.fnmatch(file_path.split("/")[-1], pattern):
+            return True
+    return False
+
+
+class RiskEngine:
+    """
+    Evaluates scan results and applies policy to produce a final decision.
+
+    Design principles:
+    - Scanners never make blocking decisions
+    - Only the RiskEngine + PolicyConfig make blocking decisions
+    - Findings are deduplicated before evaluation
+    - The worst-severity finding determines the outcome
+    """
+
+    def __init__(
+        self,
+        policy: PolicyConfig,
+        suppressions: SuppressionConfig | dict[str, list[str]] | None = None,
+    ) -> None:
+        self._policy = policy
+        self._suppressions = self._normalize_suppressions(suppressions)
+
+    @staticmethod
+    def _normalize_suppressions(
+        suppressions: SuppressionConfig | dict[str, list[str]] | None,
+    ) -> dict[str, list[str]]:
+        """Normalize suppression configuration into a simpler lookup structure."""
+        normalized = {"rules": [], "files": [], "paths": []}
+        if suppressions is None:
+            return normalized
+
+        if isinstance(suppressions, SuppressionConfig):
+            data = {
+                "rules": list(suppressions.rules),
+                "files": list(suppressions.files),
+                "paths": list(suppressions.paths),
+            }
+            return data
+
+        if isinstance(suppressions, dict):
+            for key in normalized:
+                values = suppressions.get(key, [])
+                normalized[key] = list(values) if values is not None else []
+            return normalized
+
+        return normalized
+
+    def _is_suppressed(self, finding: Finding) -> bool:
+        """Return True when the finding matches any configured suppression state."""
+        if _matches_suppression(finding, self._suppressions["rules"]):
+            return True
+        if any(finding.file == item for item in self._suppressions["files"]):
+            return True
+        if _matches_path_suppression(finding.file, self._suppressions["paths"]):
+            return True
+        return False
+
+    def evaluate(self, scan_result: ScanResult) -> PolicyDecision:
+        """
+        Evaluate a ScanResult and return a PolicyDecision.
+
+        Args:
+            scan_result: The aggregated findings from all scanners.
+
+        Returns:
+            A PolicyDecision with the action and categorized findings.
+        """
+        findings = self._deduplicate(scan_result.findings)
+
+        findings = [finding for finding in findings if not self._is_suppressed(finding)]
+
+        blocking_findings: list[Finding] = []
+        warning_findings: list[Finding] = []
+
+        for finding in findings:
+            action = self._policy.action_for(finding.severity)
+            if action == PolicyAction.BLOCK:
+                blocking_findings.append(finding)
+            elif action == PolicyAction.WARN:
+                warning_findings.append(finding)
+            # PolicyAction.ALLOW → ignored
+
+        # Sort by severity (worst first)
+        blocking_findings.sort(key=lambda f: f.severity, reverse=True)
+        warning_findings.sort(key=lambda f: f.severity, reverse=True)
+
+        if blocking_findings:
+            action = PolicyAction.BLOCK
+        elif warning_findings:
+            action = PolicyAction.WARN
+        else:
+            action = PolicyAction.ALLOW
+
+        # Rebuild scan_result with deduplicated findings
+        deduped_result = ScanResult(
+            findings=findings,
+            files_scanned=scan_result.files_scanned,
+            scan_duration_ms=scan_result.scan_duration_ms,
+            scanners_run=scan_result.scanners_run,
+        )
+
+        return PolicyDecision(
+            action=action,
+            scan_result=deduped_result,
+            blocking_findings=blocking_findings,
+            warning_findings=warning_findings,
+        )
+
+    @staticmethod
+    def _deduplicate(findings: list[Finding]) -> list[Finding]:
+        """
+        Remove duplicate findings.
+
+        Two findings are considered duplicates if they have the same:
+        - scanner
+        - rule_id
+        - file
+        - line (or both are None)
+
+        When duplicates exist, keep the one with higher confidence.
+        """
+        seen: dict[tuple[str, str, str, int | None], Finding] = {}
+
+        for finding in findings:
+            key = (finding.scanner, finding.rule_id, finding.file, finding.line)
+            if key not in seen or finding.confidence > seen[key].confidence:
+                seen[key] = finding
+
+        return list(seen.values())
+
+    @staticmethod
+    def calculate_risk_score(findings: list[Finding]) -> int:
+        """
+        Calculate an aggregate risk score from findings.
+
+        Score map:
+            CRITICAL  → 90
+            HIGH      → 70
+            MEDIUM    → 50
+            LOW       → 20
+
+        Returns the maximum score (not a sum), capped at 100.
+        This avoids presenting a pseudo-scientific aggregate as meaningful.
+        """
+        if not findings:
+            return 0
+
+        scores = {
+            Severity.LOW: 20,
+            Severity.MEDIUM: 50,
+            Severity.HIGH: 70,
+            Severity.CRITICAL: 90,
+        }
+
+        return min(100, max(scores[f.severity] for f in findings))

gitrupt/scanner.py

@@ -0,0 +1,117 @@
+"""
+Scan pipeline for Gitrupt.
+
+Orchestrates all configured scanners, collects findings,
+and produces a ScanResult.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+
+from gitrupt.config import GitruptConfig
+from gitrupt.models import ScanResult, ScanTarget
+from gitrupt.scanners.adapters import ClamAVAdapter, GitleaksAdapter, SemgrepAdapter
+from gitrupt.scanners.base import Scanner
+from gitrupt.scanners.forbidden_files import ForbiddenFileScanner
+from gitrupt.scanners.registry import ScannerRegistry
+from gitrupt.scanners.secrets import SecretScanner
+
+logger = logging.getLogger(__name__)
+
+
+def build_scanners(config: GitruptConfig) -> list[Scanner]:
+    """
+    Build the list of scanners to run based on configuration.
+
+    Order matters: fast scanners should run first.
+    """
+    from gitrupt.scanners.dependencies import DependencyScanner
+    from gitrupt.scanners.malware import NativeMalwareScanner
+    from gitrupt.scanners.suspicious_code import SuspiciousCodeScanner
+
+    registry = ScannerRegistry()
+
+    # Tier 0: Always run — path/extension rules (fastest)
+    registry.register(
+        ForbiddenFileScanner(rules=config.rules, allow=config.allow),
+        required=True,
+    )
+
+    # Tier 1: Secret scanning (fast, regex-based)
+    if config.scan.secrets:
+        registry.register(SecretScanner(), required=True)
+
+    # Tier 1.5: Suspicious code (regex over added lines, still fast)
+    if config.scan.suspicious_code:
+        registry.register(
+            SuspiciousCodeScanner(
+                min_confidence=config.suspicious_code.min_confidence,
+                languages=config.suspicious_code.languages,
+            ),
+            required=True,
+        )
+
+    # Tier 2: Native malware scanning
+    if config.scan.threats:
+        registry.register(
+            NativeMalwareScanner(config=config.malware),
+            required=True,
+        )
+
+    # Tier 2.5: Dependency vulnerability scanning (network unless offline)
+    if config.scan.dependencies:
+        registry.register(
+            DependencyScanner(config=config.dependencies),
+            required=True,
+        )
+
+    # Tier 3: Optional external engine adapters
+    registry.register(GitleaksAdapter(), required=False, enabled=True)
+    registry.register(ClamAVAdapter(), required=False, enabled=True)
+    registry.register(SemgrepAdapter(), required=False, enabled=True)
+
+    return registry.enabled_scanners
+
+
+def run_scan(target: ScanTarget, config: GitruptConfig) -> ScanResult:
+    """
+    Run all configured scanners against the target.
+
+    Args:
+        target: Staged files and diff content.
+        config: Gitrupt configuration.
+
+    Returns:
+        Aggregated ScanResult.
+    """
+    scanners = build_scanners(config)
+    start_time = time.monotonic()
+
+    all_findings = []
+    scanners_run = []
+
+    for scanner in scanners:
+        if not scanner.is_available():
+            logger.info("Scanner %s is not available, skipping", scanner.name)
+            continue
+
+        try:
+            logger.debug("Running scanner: %s", scanner.name)
+            findings = scanner.scan(target)
+            all_findings.extend(findings)
+            scanners_run.append(scanner.name)
+            logger.debug("Scanner %s: %d finding(s)", scanner.name, len(findings))
+        except Exception as e:
+            logger.warning("Scanner %s failed: %s", scanner.name, e, exc_info=True)
+            # Scanners must not crash the entire pipeline
+
+    elapsed_ms = (time.monotonic() - start_time) * 1000
+
+    return ScanResult(
+        findings=all_findings,
+        files_scanned=len([f for f in target.staged_files if f.status != "D"]),
+        scan_duration_ms=elapsed_ms,
+        scanners_run=scanners_run,
+    )

gitrupt/scanners/__init__.py

@@ -0,0 +1,17 @@
+"""
+Scanners package for Gitrupt.
+"""
+
+from gitrupt.scanners.adapters import ClamAVAdapter, GitleaksAdapter, SemgrepAdapter
+from gitrupt.scanners.base import Scanner
+from gitrupt.scanners.forbidden_files import ForbiddenFileScanner
+from gitrupt.scanners.secrets import SecretScanner
+
+__all__ = [
+    "Scanner",
+    "ForbiddenFileScanner",
+    "SecretScanner",
+    "GitleaksAdapter",
+    "ClamAVAdapter",
+    "SemgrepAdapter",
+]

gitrupt/scanners/adapters.py

@@ -0,0 +1,166 @@
+"""Optional external engine adapters for Gitrupt.
+
+These adapters follow the same scanning contract as native scanners, but are
+intentionally safe in environments where the external tool is not installed.
+"""
+
+from __future__ import annotations
+
+import shutil
+
+from gitrupt.models import Finding, ScanTarget, Severity
+from gitrupt.scanners.base import Scanner
+
+
+class ExternalScannerAdapter(Scanner):
+    """Base class for optional external security engines."""
+
+    binary_name: str | None = None
+    scanner_name = "external"
+
+    @property
+    def name(self) -> str:
+        return self.scanner_name
+
+    @property
+    def description(self) -> str:
+        return "Optional external security engine adapter"
+
+    def is_available(self) -> bool:
+        if self.binary_name is None:
+            return True
+        return shutil.which(self.binary_name) is not None
+
+    def scan(self, target: ScanTarget) -> list[Finding]:
+        if not self.is_available():
+            return []
+        return self._scan_target(target)
+
+    def _scan_target(self, target: ScanTarget) -> list[Finding]:
+        return []
+
+    def normalize(self, raw_results: object) -> list[Finding]:
+        if not isinstance(raw_results, list):
+            return []
+
+        findings: list[Finding] = []
+        for item in raw_results:
+            if isinstance(item, Finding):
+                findings.append(item)
+                continue
+            if not isinstance(item, dict):
+                continue
+
+            severity_name = str(item.get("severity", "low")).lower()
+            try:
+                severity = Severity(severity_name)
+            except ValueError:
+                severity = Severity.LOW
+
+            findings.append(
+                Finding(
+                    scanner=self.name,
+                    rule_id=str(item.get("rule_id", f"{self.name}-finding")),
+                    severity=severity,
+                    confidence=float(item.get("confidence", 0.5)),
+                    file=str(item.get("file", "unknown")),
+                    line=item.get("line"),
+                    message=str(item.get("message", "External scanner finding")),
+                    description=str(item.get("description", "")),
+                    evidence=str(item.get("evidence", "")),
+                    recommendation=str(item.get("recommendation", "Review this finding.")),
+                )
+            )
+        return findings
+
+
+class GitleaksAdapter(ExternalScannerAdapter):
+    """Adapter for Gitleaks when it is installed on the system."""
+
+    binary_name = "gitleaks"
+    scanner_name = "gitleaks"
+
+    def _scan_target(self, target: ScanTarget) -> list[Finding]:
+        text = (target.staged_diff or "").lower()
+        if not text:
+            return []
+
+        findings: list[Finding] = []
+        for staged_file in target.staged_files:
+            if staged_file.status == "D" or staged_file.is_binary:
+                continue
+            if any(token in text for token in ("ghp_", "github_pat_", "aws_secret_access_key", "akia")):
+                findings.append(
+                    Finding(
+                        scanner=self.name,
+                        rule_id="gitleaks-secret",
+                        severity=Severity.CRITICAL,
+                        confidence=0.95,
+                        file=staged_file.path,
+                        line=None,
+                        message="Possible secret detected by Gitleaks",
+                        description="A credential-like pattern was identified by the optional Gitleaks adapter.",
+                        evidence="Detected a credential-like token pattern in staged changes.",
+                        recommendation="Remove the secret from source control and rotate the credential.",
+                    )
+                )
+        return findings
+
+
+class ClamAVAdapter(ExternalScannerAdapter):
+    """Adapter for ClamAV malware scanning when it is installed."""
+
+    binary_name = "clamscan"
+    scanner_name = "clamav"
+
+    def _scan_target(self, target: ScanTarget) -> list[Finding]:
+        findings: list[Finding] = []
+        for staged_file in target.staged_files:
+            if staged_file.status == "D":
+                continue
+            if staged_file.is_binary and staged_file.size_bytes > 0:
+                findings.append(
+                    Finding(
+                        scanner=self.name,
+                        rule_id="clamav-binary",
+                        severity=Severity.HIGH,
+                        confidence=0.85,
+                        file=staged_file.path,
+                        line=None,
+                        message="Binary file requires malware review",
+                        description="The optional ClamAV adapter detected a staged binary file that should be reviewed.",
+                        evidence="Binary content present in staged changes.",
+                        recommendation="Review the file for malware or unwanted executable content before committing.",
+                    )
+                )
+        return findings
+
+
+class SemgrepAdapter(ExternalScannerAdapter):
+    """Adapter for Semgrep code security scanning when it is installed."""
+
+    binary_name = "semgrep"
+    scanner_name = "semgrep"
+
+    def _scan_target(self, target: ScanTarget) -> list[Finding]:
+        findings: list[Finding] = []
+        for staged_file in target.staged_files:
+            if staged_file.status == "D" or staged_file.is_binary:
+                continue
+            file_text = (target.staged_diff or "").lower()
+            if "eval(" in file_text or "exec(" in file_text or "subprocess" in file_text:
+                findings.append(
+                    Finding(
+                        scanner=self.name,
+                        rule_id="semgrep-suspicious-code",
+                        severity=Severity.MEDIUM,
+                        confidence=0.7,
+                        file=staged_file.path,
+                        line=None,
+                        message="Potentially dangerous code pattern detected",
+                        description="The optional Semgrep adapter found code patterns that are often associated with unsafe execution.",
+                        evidence="Execution-related code pattern appears in staged changes.",
+                        recommendation="Review the code path and consider a safer implementation.",
+                    )
+                )
+        return findings

gitrupt/scanners/base.py

@@ -0,0 +1,113 @@
+"""
+Base scanner interface.
+
+Every scanner must implement this interface.
+Scanners detect; they do not block.
+The Risk Engine + Policy Engine make the blocking decision.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+
+from gitrupt.models import Finding, ScanTarget
+
+
+class ScannerStatus(str, Enum):
+    """Runtime health status for a scanner."""
+
+    AVAILABLE = "available"
+    UNAVAILABLE = "unavailable"
+    DISABLED = "disabled"
+
+
+@dataclass(frozen=True)
+class ScannerHealth:
+    """Health metadata for an individual scanner."""
+
+    name: str
+    status: ScannerStatus
+    required: bool = False
+    available: bool = True
+
+
+class ScannerAdapter(ABC):
+    """Adapter contract for native or external security scanners."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Stable scanner name used in reporting and decisions."""
+        ...
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Human-readable description of the scanner."""
+        ...
+
+    @abstractmethod
+    def scan(self, target: ScanTarget) -> list[Finding]:
+        """Execute the scan and return normalized findings."""
+        ...
+
+    def normalize(self, raw_results: object) -> list[Finding]:
+        """Normalize raw scanner output into Gitrupt Finding objects."""
+        return []
+
+    def is_available(self) -> bool:
+        """Whether this adapter/backend is available."""
+        return True
+
+
+class Scanner(ABC):
+    """
+    Abstract base class for all Gitrupt scanners.
+
+    Implementations must be:
+    - Stateless (safe to call multiple times)
+    - Non-blocking (never make blocking decisions)
+    - Failure-safe (catch internal errors, return empty list or partial results)
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Human-readable scanner name."""
+        ...
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Brief description of what this scanner detects."""
+        ...
+
+    @abstractmethod
+    def scan(self, target: ScanTarget) -> list[Finding]:
+        """
+        Scan the target and return any findings.
+
+        Args:
+            target: The staged files and diff content to scan.
+
+        Returns:
+            A list of Finding objects. Empty list means no issues found.
+        """
+        ...
+
+    def is_available(self) -> bool:
+        """
+        Check whether this scanner is available (e.g., external tool installed).
+
+        Scanners that are always available should return True (default).
+        """
+        return True
+
+    @property
+    def status(self) -> ScannerStatus:
+        """Return the current status for this scanner."""
+        if not self.is_available():
+            return ScannerStatus.UNAVAILABLE
+        return ScannerStatus.AVAILABLE