patchi 0.7.5__py3-none-any.whl

patchi/core/assurance/invariants.py

@@ -0,0 +1,168 @@
+"""
+Invariant engine — what should be impossible, checked statically.
+
+Each Invariant pairs a property statement with a static verifier that runs
+over project data (routes, findings, config). Verification produces Evidence;
+the AssuranceGraph decides the verdict.
+
+InvariantType mirrors UNIFIED_UPGRADE_PLAN.md's semantics:
+    MUST          — property must hold unconditionally
+    MUST_NOT      — named condition must never occur
+    ONLY_IF       — action permitted only under stated precondition
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+_log = logging.getLogger("patchi.core.assurance.invariants")
+
+
+class InvariantType(StrEnum):
+    MUST = "must"
+    MUST_NOT = "must_not"
+    ONLY_IF = "only_if"
+
+
+@dataclass
+class Invariant:
+    """One provable property about the project."""
+
+    id: str  # stable slug
+    invariant_type: InvariantType
+    statement: str  # human-readable property
+    domain: str  # owning domain tag
+    severity_if_disproved: str = "high"
+
+    # verifier(project_data) -> (supports: bool, detail: str, artifact: dict)
+    # project_data keys available: routes(IntentReport|None), findings(list[dict]),
+    #                              config(dict), files(set[str])
+    verifier: Callable[[dict], tuple[bool, str, dict]] | None = None
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "type": self.invariant_type.value,
+            "statement": self.statement,
+            "domain": self.domain,
+            "severity_if_disproved": self.severity_if_disproved,
+        }
+
+
+def verify_invariants(
+    invariants: list[Invariant],
+    project_data: dict[str, Any],
+):
+    """
+    Run every invariant's verifier against project_data.
+
+    Returns list of (invariant, supports, detail, artifact) tuples.
+    Invariants without a verifier yield NOT_PROVED evidence (never silently
+    proved — honesty rule).
+    """
+    results = []
+    for inv in invariants:
+        if inv.verifier is None:
+            results.append((inv, False, "no verifier registered for this invariant", {}))
+            continue
+        try:
+            supports, detail, artifact = inv.verifier(project_data)
+            results.append((inv, bool(supports), detail, artifact))
+        except Exception as e:  # noqa: BLE001 — a broken check is NOT_PROVED
+            _log.warning("invariant %s verifier failed: %s", inv.id, e)
+            results.append((inv, False, f"verifier error: {e}", {}))
+    return results
+
+
+# ── Built-in invariant library ────────────────────────────────────────────────
+
+
+def _check_all_writes_authenticated(data: dict) -> tuple[bool, str, dict]:
+    """Every state-changing route must carry an auth guard."""
+    report = data.get("routes")
+    if report is None or not getattr(report, "routes", None):
+        return False, "no route data available", {}
+    bad = [
+        r
+        for r in report.routes
+        if r.method.lower() in ("post", "put", "delete", "patch") and not r.has_auth_guard
+    ]
+    total_writes = sum(
+        1 for r in report.routes if r.method.lower() in ("post", "put", "delete", "patch")
+    )
+    if not total_writes:
+        return False, "no state-changing routes discovered", {}
+    artifact = {"unguarded": [r.file + ":" + str(r.line) for r in bad]}
+    if bad:
+        names = ", ".join(f"{r.path or '?'}" for r in bad[:3])
+        return (
+            False,
+            f"{len(bad)}/{total_writes} write endpoints lack auth ({names}...)",
+            artifact,
+        )
+    return True, f"all {total_writes} write endpoints carry auth guards", {}
+
+
+def _check_no_hardcoded_secrets(data: dict) -> tuple[bool, str, dict]:
+    """No finding of type hardcoded_secret may exist."""
+    findings = data.get("findings", [])
+    hits = [f for f in findings if "hardcoded_secret" in str(f.get("type", ""))]
+    artifact = {"count": len(hits)}
+    if hits:
+        first = hits[0]
+        return (
+            False,
+            f"{len(hits)} hardcoded secret(s), e.g. {first.get('file', '?')}:{first.get('line', 0)}",
+            artifact,
+        )
+    return True, "no hardcoded secrets detected by scanners", {}
+
+
+def _check_no_debug_mode(data: dict) -> tuple[bool, str, dict]:
+    """Application must not run with debug enabled."""
+    findings = data.get("findings", [])
+    hits = [
+        f
+        for f in findings
+        if "debug" in str(f.get("type", "")).lower()
+        and f.get("severity", "").lower() in ("high", "critical")
+    ]
+    if hits:
+        return (
+            False,
+            f"{len(hits)} debug-enabled finding(s) at high+ severity",
+            {"count": len(hits)},
+        )
+    return True, "no high+ debug-mode findings", {}
+
+
+BUILTIN_INVARIANTS: list[Invariant] = [
+    Invariant(
+        id="auth-all-writes",
+        invariant_type=InvariantType.MUST,
+        statement="All state-changing endpoints require authentication",
+        domain="access-control-authz",
+        severity_if_disproved="critical",
+        verifier=_check_all_writes_authenticated,
+    ),
+    Invariant(
+        id="secrets-none-hardcoded",
+        invariant_type=InvariantType.MUST_NOT,
+        statement="No credentials committed to source",
+        domain="secrets-runtime-management",
+        severity_if_disproved="critical",
+        verifier=_check_no_hardcoded_secrets,
+    ),
+    Invariant(
+        id="debug-not-in-prod",
+        invariant_type=InvariantType.MUST_NOT,
+        statement="Debug mode is never enabled in production configuration",
+        domain="configuration-hardening",
+        severity_if_disproved="high",
+        verifier=_check_no_debug_mode,
+    ),
+]

patchi/core/atomic.py

@@ -0,0 +1,61 @@
+"""
+Atomic file operations for Patchi.
+
+All persistent writes go through these helpers to prevent data loss on crash.
+The pattern is: write to a temp file, then atomically rename to the target.
+
+On Windows, ``Path.replace()`` fails if the target exists, so we unlink first.
+Retries handle transient PermissionError from antivirus or indexer locks.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from pathlib import Path
+
+
+def atomic_replace(src: Path, dst: Path, retries: int = 3) -> None:
+    """Replace *dst* with *src* atomically, with retries for Windows file-lock races.
+
+    This is the single source of truth for atomic file replacement across Patchi.
+    Every module that writes persistent JSON or source files should use this.
+    """
+    for attempt in range(retries):
+        try:
+            if sys.platform == "win32":
+                if dst.exists():
+                    dst.unlink()
+            src.replace(dst)
+            return
+        except PermissionError:
+            if attempt < retries - 1:
+                time.sleep(0.05 * (attempt + 1))
+                continue
+            raise
+
+
+def atomic_write_json(path: Path, data, indent: int = 2, **dump_kwargs) -> None:
+    """Write *data* as JSON to *path* atomically (tmp + rename).
+
+    Convenience wrapper: serializes to JSON, writes to a sibling ``.tmp`` file,
+    then calls :func:`atomic_replace`.
+    """
+    import json
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    with tmp.open("w", encoding="utf-8") as f:
+        json.dump(data, f, indent=indent, **dump_kwargs)
+    atomic_replace(tmp, path)
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    """Write *text* to *path* atomically (tmp + rename).
+
+    Used by the patch applier to write source files without risk of partial writes.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(text, encoding="utf-8")
+    atomic_replace(tmp, path)

patchi/core/attackers/__init__.py

@@ -0,0 +1,17 @@
+"""Attackers module — adversarial personalities for security testing."""
+
+from .api_abuse import ApiAbuseAttacker
+from .auth_bypass import AuthBypassAttacker
+from .business_logic import BusinessLogicAttacker
+from .planner import AttackPlanner
+from .priv_escalation import PrivEscAttacker
+from .recon import ReconAttacker
+
+__all__ = [
+    "AttackPlanner",
+    "ReconAttacker",
+    "AuthBypassAttacker",
+    "PrivEscAttacker",
+    "BusinessLogicAttacker",
+    "ApiAbuseAttacker",
+]

patchi/core/attackers/api_abuse.py

@@ -0,0 +1,89 @@
+"""ApiAbuseAttacker — test API abuse (injection, rate limiting, info disclosure)."""
+
+from __future__ import annotations
+
+from .base import AttackResult, BaseAttacker, Hypothesis
+
+
+class ApiAbuseAttacker(BaseAttacker):
+    """Tests for injection risks, missing rate limits, information disclosure."""
+
+    name = "api_abuse"
+    objective = "api_abuse"
+
+    def hypothesize(self) -> list[Hypothesis]:
+        hypotheses: list[Hypothesis] = []
+
+        for claim in self._graph.claims.values():
+            # Injection risks
+            if any(kw in claim.statement.lower() for kw in ["inject", "sanitiz", "validat"]):
+                if claim.verdict.value in ("not_proved", "unproven"):
+                    hypotheses.append(
+                        Hypothesis(
+                            attacker=self.name,
+                            objective=self.objective,
+                            target=claim.id,
+                            risk="high",
+                            confidence=0.7,
+                            description=f"Injection risk unverified: {claim.statement}",
+                        )
+                    )
+
+            # Rate limiting
+            if "rate" in claim.statement.lower() and "limit" in claim.statement.lower():
+                hypotheses.append(
+                    Hypothesis(
+                        attacker=self.name,
+                        objective=self.objective,
+                        target=claim.id,
+                        risk="medium",
+                        confidence=0.5,
+                        description=f"Rate limiting unverified: {claim.statement}",
+                    )
+                )
+
+            # Information disclosure
+            if "error" in claim.statement.lower() and (
+                "detail" in claim.statement.lower() or "disclose" in claim.statement.lower()
+            ):
+                hypotheses.append(
+                    Hypothesis(
+                        attacker=self.name,
+                        objective=self.objective,
+                        target=claim.id,
+                        risk="medium",
+                        confidence=0.4,
+                        description=f"Info disclosure unverified: {claim.statement}",
+                    )
+                )
+
+        return hypotheses
+
+    def test(self, hypothesis: Hypothesis) -> AttackResult:
+        claim = self._graph.claims.get(hypothesis.target)
+        if claim is None:
+            return AttackResult(hypothesis=hypothesis, confirmed=False, evidence="Claim not found")
+
+        refuting = [e for e in claim.evidence if not e.supports]
+        if refuting:
+            return AttackResult(
+                hypothesis=hypothesis,
+                confirmed=False,
+                evidence=f"API protection verified: {refuting[0].detail}",
+            )
+
+        supporting = [e for e in claim.evidence if e.supports]
+        if supporting:
+            return AttackResult(
+                hypothesis=hypothesis,
+                confirmed=True,
+                evidence=f"API abuse confirmed: {supporting[0].detail}",
+                severity=hypothesis.risk,
+                remediation="Add input validation, rate limiting, or error sanitization",
+            )
+
+        return AttackResult(
+            hypothesis=hypothesis,
+            confirmed=False,
+            evidence="Insufficient evidence",
+        )

patchi/core/attackers/auth_bypass.py

@@ -0,0 +1,73 @@
+"""AuthBypassAttacker — test authentication bypass vulnerabilities."""
+
+from __future__ import annotations
+
+from .base import AttackResult, BaseAttacker, Hypothesis
+
+
+class AuthBypassAttacker(BaseAttacker):
+    """Tests for unauthenticated access, unguarded state transitions, weak auth mechanisms."""
+
+    name = "auth_bypass"
+    objective = "authentication_bypass"
+
+    def hypothesize(self) -> list[Hypothesis]:
+        hypotheses: list[Hypothesis] = []
+
+        for claim in self._graph.claims.values():
+            if "auth" in claim.domain.lower() or "session" in claim.domain.lower():
+                if claim.verdict.value in ("not_proved", "unproven"):
+                    hypotheses.append(
+                        Hypothesis(
+                            attacker=self.name,
+                            objective=self.objective,
+                            target=claim.id,
+                            risk="high",
+                            confidence=0.7,
+                            description=f"Auth property unverified: {claim.statement}",
+                        )
+                    )
+
+            # State transitions without auth guards
+            if "transition" in claim.statement.lower() and "guard" not in claim.statement.lower():
+                hypotheses.append(
+                    Hypothesis(
+                        attacker=self.name,
+                        objective=self.objective,
+                        target=claim.id,
+                        risk="high",
+                        confidence=0.5,
+                        description=f"State transition may lack auth guard: {claim.statement}",
+                    )
+                )
+
+        return hypotheses
+
+    def test(self, hypothesis: Hypothesis) -> AttackResult:
+        claim = self._graph.claims.get(hypothesis.target)
+        if claim is None:
+            return AttackResult(hypothesis=hypothesis, confirmed=False, evidence="Claim not found")
+
+        refuting = [e for e in claim.evidence if not e.supports]
+        if refuting:
+            return AttackResult(
+                hypothesis=hypothesis,
+                confirmed=False,
+                evidence=f"Auth verified: {refuting[0].detail}",
+            )
+
+        supporting = [e for e in claim.evidence if e.supports]
+        if supporting:
+            return AttackResult(
+                hypothesis=hypothesis,
+                confirmed=True,
+                evidence=f"Auth bypass confirmed: {supporting[0].detail}",
+                severity="critical",
+                remediation="Add authentication check before this operation",
+            )
+
+        return AttackResult(
+            hypothesis=hypothesis,
+            confirmed=False,
+            evidence="Insufficient evidence",
+        )

patchi/core/attackers/base.py

@@ -0,0 +1,91 @@
+"""Base attacker — shared types and ABC for adversarial personalities."""
+
+from __future__ import annotations
+
+import abc
+import logging
+from dataclasses import dataclass, field
+
+from patchi.core.assurance.graph import AssuranceGraph
+
+_log = logging.getLogger("patchi.core.attackers")
+
+
+@dataclass
+class Hypothesis:
+    """An attacker's hypothesis about where a vulnerability exists."""
+
+    attacker: str
+    objective: str
+    target: str  # file, endpoint, or state
+    risk: str  # "critical", "high", "medium", "low"
+    confidence: float  # 0.0–1.0
+    description: str = ""
+    evidence_required: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "attacker": self.attacker,
+            "objective": self.objective,
+            "target": self.target,
+            "risk": self.risk,
+            "confidence": self.confidence,
+            "description": self.description,
+        }
+
+
+@dataclass
+class AttackResult:
+    """Result of testing a hypothesis."""
+
+    hypothesis: Hypothesis
+    confirmed: bool
+    evidence: str = ""
+    severity: str = ""
+    remediation: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "hypothesis": self.hypothesis.to_dict(),
+            "confirmed": self.confirmed,
+            "evidence": self.evidence,
+            "severity": self.severity,
+            "remediation": self.remediation,
+        }
+
+
+class BaseAttacker(abc.ABC):
+    """Base class for adversarial personalities."""
+
+    name: str = "base"
+    objective: str = "unknown"
+
+    def __init__(self, graph: AssuranceGraph):
+        self._graph = graph
+
+    @abc.abstractmethod
+    def hypothesize(self) -> list[Hypothesis]:
+        """Generate hypotheses about where vulnerabilities might exist."""
+
+    @abc.abstractmethod
+    def test(self, hypothesis: Hypothesis) -> AttackResult:
+        """Test a specific hypothesis."""
+
+    def run(self) -> list[AttackResult]:
+        """Generate and test all hypotheses."""
+        hypotheses = self.hypothesize()
+        results: list[AttackResult] = []
+        for h in hypotheses:
+            try:
+                result = self.test(h)
+                results.append(result)
+            except Exception as e:
+                _log.warning("Attacker %s failed testing %s: %s", self.name, h.target, e)
+                results.append(
+                    AttackResult(
+                        hypothesis=h,
+                        confirmed=False,
+                        evidence=f"Test error: {e}",
+                    )
+                )
+        return results

patchi/core/attackers/business_logic.py

@@ -0,0 +1,88 @@
+"""BusinessLogicAttacker — test business logic abuse (replay, race conditions)."""
+
+from __future__ import annotations
+
+from .base import AttackResult, BaseAttacker, Hypothesis
+
+
+class BusinessLogicAttacker(BaseAttacker):
+    """Tests for replay attacks, concurrent races, unprotected business flows."""
+
+    name = "business_logic"
+    objective = "business_logic_abuse"
+
+    def hypothesize(self) -> list[Hypothesis]:
+        hypotheses: list[Hypothesis] = []
+
+        for claim in self._graph.claims.values():
+            # Idempotency concerns
+            if "idempoten" in claim.statement.lower():
+                if claim.verdict.value in ("not_proved", "unproven"):
+                    hypotheses.append(
+                        Hypothesis(
+                            attacker=self.name,
+                            objective=self.objective,
+                            target=claim.id,
+                            risk="medium",
+                            confidence=0.6,
+                            description=f"Idempotency unverified: {claim.statement}",
+                        )
+                    )
+
+            # Race conditions
+            if "concurrent" in claim.statement.lower() or "race" in claim.statement.lower():
+                hypotheses.append(
+                    Hypothesis(
+                        attacker=self.name,
+                        objective=self.objective,
+                        target=claim.id,
+                        risk="high",
+                        confidence=0.5,
+                        description=f"Race condition unverified: {claim.statement}",
+                    )
+                )
+
+            # State machine integrity
+            if "state" in claim.domain.lower() and "transition" in claim.statement.lower():
+                if claim.verdict.value == "unproven":
+                    hypotheses.append(
+                        Hypothesis(
+                            attacker=self.name,
+                            objective=self.objective,
+                            target=claim.id,
+                            risk="medium",
+                            confidence=0.4,
+                            description=f"State machine integrity unverified: {claim.statement}",
+                        )
+                    )
+
+        return hypotheses
+
+    def test(self, hypothesis: Hypothesis) -> AttackResult:
+        claim = self._graph.claims.get(hypothesis.target)
+        if claim is None:
+            return AttackResult(hypothesis=hypothesis, confirmed=False, evidence="Claim not found")
+
+        refuting = [e for e in claim.evidence if not e.supports]
+        if refuting:
+            return AttackResult(
+                hypothesis=hypothesis,
+                confirmed=False,
+                evidence=f"Business logic verified: {refuting[0].detail}",
+            )
+
+        supporting = [e for e in claim.evidence if e.supports]
+        if supporting:
+            return AttackResult(
+                hypothesis=hypothesis,
+                confirmed=True,
+                evidence=f"Business logic abuse confirmed: {supporting[0].detail}",
+                severity=hypothesis.risk,
+                remediation="Add idempotency keys, rate limiting, or state guards",
+            )
+
+        return AttackResult(
+            hypothesis=hypothesis,
+            confirmed=False,
+            evidence="Insufficient evidence",
+        )