patchi 0.7.5__py3-none-any.whl

patchi/core/assurance/__init__.py

@@ -0,0 +1,33 @@
+"""
+Assurance package — provable properties over the scanned codebase.
+
+The question this package exists to answer (UNIFIED_UPGRADE_PLAN.md):
+
+    "What should be impossible, and can I prove it isn't?"
+
+Structure:
+    graph.py       — AssuranceGraph: claims, evidence, verdicts, persistence
+    invariants.py  — invariant types + static verification engine
+"""
+
+from patchi.core.assurance.graph import (
+    AssuranceGraph,
+    Claim,
+    Evidence,
+    Verdict,
+)
+from patchi.core.assurance.invariants import (
+    Invariant,
+    InvariantType,
+    verify_invariants,
+)
+
+__all__ = [
+    "AssuranceGraph",
+    "Claim",
+    "Evidence",
+    "Verdict",
+    "Invariant",
+    "InvariantType",
+    "verify_invariants",
+]

patchi/core/assurance/builder.py

@@ -0,0 +1,211 @@
+"""Build an AssuranceGraph from brain scan data.
+
+Called after every ``p scan`` to populate the graph with claims derived from
+detected routes, import graph, auth patterns, and domain knowledge.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from .graph import AssuranceGraph, Evidence
+
+_log = logging.getLogger("patchi.core.assurance.builder")
+
+ASSURANCE_FILE = ".patchi/assurance_graph.json"
+
+
+def build_assurance_graph(
+    root: Path,
+    brain_data: dict[str, Any] | None = None,
+    route_map: list[dict] | None = None,
+    import_graph_data: dict | None = None,
+) -> AssuranceGraph:
+    """Build an AssuranceGraph from brain scan data.
+
+    Parameters
+    ----------
+    root : Path
+        Project root.
+    brain_data : dict
+        Brain report summary (from ``report.summary_dict()``).
+    route_map : list[dict]
+        Detected routes (from ``RouteMapper``).
+    import_graph_data : dict
+        Import graph as dict (from ``ImportGraph.to_dict()``).
+    """
+    graph = AssuranceGraph()
+    brain = brain_data or {}
+    routes = route_map or []
+    imp = import_graph_data or {}
+
+    # ── Components (frameworks detected) ──────────────────────────────────
+    frameworks = brain.get("detected_frameworks", [])
+    if not frameworks and brain.get("stack"):
+        frameworks = [brain["stack"].get("framework", "unknown")]
+    for fw in frameworks:
+        if fw and fw != "unknown":
+            _add_framework_claim(graph, fw)
+
+    # ── Actors (from auth patterns) ──────────────────────────────────────
+    auth_patterns = brain.get("auth_patterns", brain.get("project_context", {}).get("auth", {}))
+    actors = _extract_actors(auth_patterns)
+    for actor in actors:
+        _add_actor_claim(graph, actor)
+
+    # ── Assets (endpoints from route mapper) ─────────────────────────────
+    for route in routes:
+        path = route.get("path", route.get("route", ""))
+        methods = route.get("methods", route.get("http_methods", ["GET"]))
+        auth_required = route.get("auth_required", route.get("requires_auth", False))
+        if path:
+            _add_endpoint_claim(graph, path, methods, auth_required)
+
+    # ── Data flows (from import graph) ───────────────────────────────────
+    edges = imp.get("edges", [])
+    for edge in edges[:100]:  # cap for performance
+        src = edge.get("source", edge.get("from", ""))
+        dst = edge.get("target", edge.get("to", ""))
+        if src and dst:
+            _add_data_flow_claim(graph, src, dst)
+
+    # ── Dependency health ────────────────────────────────────────────────
+    vulns = brain.get("dependency_vulnerabilities", [])
+    for v in vulns[:20]:
+        pkg = v.get("package", v.get("name", ""))
+        cve = v.get("cve", v.get("id", ""))
+        if pkg:
+            _add_dependency_claim(graph, pkg, cve)
+
+    # ── State machine (from session/auth analysis) ───────────────────────
+    _add_state_claims(graph, auth_patterns)
+
+    return graph
+
+
+def _add_framework_claim(graph: AssuranceGraph, framework: str) -> None:
+    graph.upsert_claim(
+        f"framework-{framework}",
+        f"Project uses {framework}",
+        domain="architecture",
+        severity_if_disproved="info",
+    )
+    graph.attach_evidence(
+        f"framework-{framework}",
+        Evidence(source="brain_scan", detail=f"Detected framework: {framework}", supports=True),
+    )
+
+
+def _add_actor_claim(graph: AssuranceGraph, actor: str) -> None:
+    graph.upsert_claim(
+        f"actor-{actor}",
+        f"System has actor role: {actor}",
+        domain="auth",
+        severity_if_disproved="medium",
+    )
+    graph.attach_evidence(
+        f"actor-{actor}",
+        Evidence(source="brain_scan", detail=f"Actor detected: {actor}", supports=True),
+    )
+
+
+def _add_endpoint_claim(
+    graph: AssuranceGraph, path: str, methods: list, auth_required: bool
+) -> None:
+    claim_id = f"endpoint-{path.replace('/', '_').strip('_')}"
+    graph.upsert_claim(
+        claim_id,
+        f"Endpoint {path} requires authentication",
+        domain="auth-endpoint",
+        severity_if_disproved="high" if auth_required else "medium",
+    )
+    # If we know auth is required, that's evidence supporting the claim
+    # that it *should* require auth (we're asserting it as a property)
+    graph.attach_evidence(
+        claim_id,
+        Evidence(
+            source="route_mapper",
+            detail=f"Route {path} ({', '.join(methods)}) auth_required={auth_required}",
+            supports=True,
+            artifact={"path": path, "methods": methods, "auth_required": auth_required},
+        ),
+    )
+
+
+def _add_data_flow_claim(graph: AssuranceGraph, source: str, sink: str) -> None:
+    claim_id = f"flow-{source.replace('.', '_')}-{sink.replace('.', '_')}"
+    graph.upsert_claim(
+        claim_id,
+        f"Data flow from {source} to {sink} is properly secured",
+        domain="data-flow",
+        severity_if_disproved="medium",
+    )
+    graph.attach_evidence(
+        claim_id,
+        Evidence(
+            source="import_graph",
+            detail=f"Import edge: {source} → {sink}",
+            supports=True,
+            artifact={"source": source, "sink": sink},
+        ),
+    )
+
+
+def _add_dependency_claim(graph: AssuranceGraph, pkg: str, cve: str) -> None:
+    claim_id = f"dep-{pkg}"
+    graph.upsert_claim(
+        claim_id,
+        f"Dependency {pkg} has no known vulnerabilities",
+        domain="dependency",
+        severity_if_disproved="high",
+    )
+    if cve:
+        # CVE found = refutes the claim (it IS vulnerable)
+        graph.attach_evidence(
+            claim_id,
+            Evidence(
+                source="dependency_scan",
+                detail=f"Vulnerability {cve} found in {pkg}",
+                supports=False,
+                artifact={"package": pkg, "cve": cve},
+            ),
+        )
+
+
+def _extract_actors(auth_patterns: Any) -> list[str]:
+    """Extract actor roles from auth pattern data."""
+    actors = ["anonymous", "authenticated"]
+    if isinstance(auth_patterns, dict):
+        if auth_patterns.get("has_admin"):
+            actors.append("admin")
+        if auth_patterns.get("has_roles"):
+            actors.extend(["moderator", "service"])
+        if auth_patterns.get("has_api_key"):
+            actors.append("api_client")
+    return actors
+
+
+def _add_state_claims(graph: AssuranceGraph, auth_patterns: Any) -> None:
+    """Add state machine claims from auth analysis."""
+    states = ["anonymous", "authenticated"]
+    if isinstance(auth_patterns, dict) and auth_patterns.get("has_admin"):
+        states.append("admin")
+
+    for state in states:
+        claim_id = f"state-{state}"
+        graph.upsert_claim(
+            claim_id,
+            f"State '{state}' transitions are properly guarded",
+            domain="state-machine",
+            severity_if_disproved="high",
+        )
+
+    # Login transition
+    graph.upsert_claim(
+        "state-login-transition",
+        "Login transition regenerates session ID",
+        domain="state-machine",
+        severity_if_disproved="critical",
+    )

patchi/core/assurance/graph.py

@@ -0,0 +1,342 @@
+"""
+AssuranceGraph — a directed graph of claims backed by evidence.
+
+Every security/quality property Patchi asserts becomes a Claim:
+
+    property ("all state-changing routes require auth")
+      <- Evidence (route scan: 4 routes, 1 unguarded)
+      <- Verdict (proved / not-proved / disproved + timestamp)
+
+The graph persists to ``.patchi/assurance.json`` so campaigns accumulate
+across runs instead of evaporating with each scan. Honesty rule (2.1-1):
+a claim without evidence is NEVER reported as proved, and a disproved
+claim keeps its repair history — the system records what it tried, not
+just what it wanted to be true.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+_log = logging.getLogger("patchi.core.assurance.graph")
+
+ASSURANCE_FILE = ".patchi/assurance.json"
+COVERAGE_HISTORY_FILE = ".patchi/coverage_history.json"
+
+
+class Verdict(StrEnum):
+    """Outcome of verifying a claim. No evidence => UNPROVEN, never 'proved'."""
+
+    PROVED = "proved"
+    NOT_PROVED = "not_proved"  # couldn't establish (insufficient evidence)
+    DISPROVED = "disproved"  # positive counter-evidence found
+    UNPROVEN = "unproven"  # never checked
+
+
+@dataclass
+class Evidence:
+    """One piece of supporting/refuting observation for a claim."""
+
+    source: str  # what produced it: "intent_scan", "secret_scan", ...
+    detail: str  # human-readable observation
+    supports: bool  # True = supports claim; False = refutes
+    timestamp: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
+    artifact: dict = field(default_factory=dict)  # machine-checkable payload
+
+    def to_dict(self) -> dict:
+        return {
+            "source": self.source,
+            "detail": self.detail,
+            "supports": self.supports,
+            "timestamp": self.timestamp,
+            "artifact": self.artifact,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> Evidence:
+        return cls(
+            source=d.get("source", "?"),
+            detail=d.get("detail", ""),
+            supports=bool(d.get("supports", False)),
+            timestamp=d.get("timestamp", ""),
+            artifact=d.get("artifact", {}),
+        )
+
+
+@dataclass
+class Claim:
+    """A property asserted about the project, with its evidence trail."""
+
+    id: str  # stable slug, e.g. "auth-all-writes"
+    statement: str  # human-readable property
+    domain: str  # owning domain tag, e.g. "auth-session"
+    severity_if_disproved: str = "high"
+    verdict: Verdict = Verdict.UNPROVEN
+    evidence: list[Evidence] = field(default_factory=list)
+    repairs: list[dict] = field(default_factory=list)  # adversarial-repair chain
+    updated_at: str = ""
+
+    def add_evidence(self, ev: Evidence) -> None:
+        self.evidence.append(ev)
+        self.updated_at = ev.timestamp
+        # Verdict recomputation: ANY refuting evidence wins (honesty-first);
+        # otherwise proved only if >=1 supporting evidence exists.
+        refuting = [e for e in self.evidence if not e.supports]
+        supporting = [e for e in self.evidence if e.supports]
+        if refuting:
+            self.verdict = Verdict.DISPROVED
+        elif supporting:
+            self.verdict = Verdict.PROVED
+        else:
+            self.verdict = Verdict.NOT_PROVED
+
+    def record_repair(self, description: str, outcome: str) -> None:
+        """Record one loop of the adversarial repair chain."""
+        self.repairs.append(
+            {
+                "at": datetime.now(UTC).isoformat(),
+                "description": description,
+                "outcome": outcome,
+            }
+        )
+        # A repair attempt resets the verdict until re-verified.
+        self.verdict = Verdict.NOT_PROVED
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "statement": self.statement,
+            "domain": self.domain,
+            "severity_if_disproved": self.severity_if_disproved,
+            "verdict": self.verdict.value,
+            "evidence": [e.to_dict() for e in self.evidence],
+            "repairs": self.repairs,
+            "updated_at": self.updated_at,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> Claim:
+        c = cls(
+            id=d.get("id", "?"),
+            statement=d.get("statement", ""),
+            domain=d.get("domain", "general"),
+            severity_if_disproved=d.get("severity_if_disproved", "high"),
+            verdict=Verdict(d.get("verdict", "unproven")),
+            updated_at=d.get("updated_at", ""),
+        )
+        c.evidence = [Evidence.from_dict(e) for e in d.get("evidence", [])]
+        c.repairs = list(d.get("repairs", []))
+        return c
+
+
+@dataclass
+class AssuranceGraph:
+    """The persistent collection of claims for one project."""
+
+    claims: dict[str, Claim] = field(default_factory=dict)
+
+    def upsert_claim(
+        self,
+        claim_id: str,
+        statement: str,
+        domain: str = "general",
+        severity_if_disproved: str = "high",
+    ) -> Claim:
+        """Get-or-create a claim; preserves existing evidence across runs."""
+        if claim_id not in self.claims:
+            self.claims[claim_id] = Claim(
+                id=claim_id,
+                statement=statement,
+                domain=domain,
+                severity_if_disproved=severity_if_disproved,
+            )
+        return self.claims[claim_id]
+
+    def attach_evidence(self, claim_id: str, evidence: Evidence) -> Claim:
+        claim = self.claims[claim_id]  # KeyError = programming error upstream
+        claim.add_evidence(evidence)
+        return claim
+
+    # ── Reporting ───────────────────────────────────────────────────────────
+
+    def coverage(self) -> dict[str, Any]:
+        """Assurance status summary. Never says 'secure' — says what's proved."""
+        total = len(self.claims)
+        by_verdict: dict[str, int] = {}
+        by_domain: dict[str, dict[str, int]] = {}
+        for c in self.claims.values():
+            by_verdict[c.verdict.value] = by_verdict.get(c.verdict.value, 0) + 1
+            dom = by_domain.setdefault(c.domain, {"proved": 0, "total": 0})
+            dom["total"] += 1
+            if c.verdict == Verdict.PROVED:
+                dom["proved"] += 1
+
+        disproved = [c for c in self.claims.values() if c.verdict == Verdict.DISPROVED]
+        return {
+            "claims_total": total,
+            "by_verdict": by_verdict,
+            "by_domain": by_domain,
+            "disproved_claims": [c.to_dict() for c in disproved],
+            "statement": (
+                f"{by_verdict.get('proved', 0)}/{total} properties proved; "
+                f"{len(disproved)} violated"
+                if total
+                else "no properties established yet"
+            ),
+        }
+
+    # ── Diff ─────────────────────────────────────────────────────────────────
+
+    def diff(self, other: AssuranceGraph) -> dict[str, Any]:
+        """Compute difference between two assurance graphs.
+
+        Returns a dict with:
+          - added: claims in ``other`` but not in ``self``
+          - removed: claims in ``self`` but not in ``other``
+          - changed: claims present in both but with different verdicts or evidence
+          - unchanged: claim IDs present in both with same verdict and evidence count
+        """
+        self_ids = set(self.claims.keys())
+        other_ids = set(other.claims.keys())
+
+        added_ids = other_ids - self_ids
+        removed_ids = self_ids - other_ids
+        common_ids = self_ids & other_ids
+
+        added = {cid: other.claims[cid].to_dict() for cid in added_ids}
+        removed = {cid: self.claims[cid].to_dict() for cid in removed_ids}
+
+        changed = {}
+        unchanged = []
+        for cid in common_ids:
+            c1 = self.claims[cid]
+            c2 = other.claims[cid]
+            if c1.verdict != c2.verdict or len(c1.evidence) != len(c2.evidence):
+                changed[cid] = {
+                    "self": c1.to_dict(),
+                    "other": c2.to_dict(),
+                }
+            else:
+                unchanged.append(cid)
+
+        return {
+            "added": added,
+            "removed": removed,
+            "changed": changed,
+            "unchanged": unchanged,
+        }
+
+    # ── Persistence ─────────────────────────────────────────────────────────
+
+    def save(self, root: Path) -> Path:
+        path = root / ASSURANCE_FILE
+        path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "version": 1,
+            "claims": [c.to_dict() for c in self.claims.values()],
+        }
+        tmp = path.with_suffix(".json.tmp")
+        tmp.write_text(json_dumps(payload), encoding="utf-8")
+        tmp.replace(path)
+        # Record coverage snapshot for trend line
+        self._record_coverage_snapshot(root)
+        return path
+
+    @classmethod
+    def load(cls, root: Path) -> AssuranceGraph:
+        path = root / ASSURANCE_FILE
+        g = cls()
+        if not path.is_file():
+            return g
+        try:
+            import json
+
+            data = json.loads(path.read_text(encoding="utf-8"))
+            for cd in data.get("claims", []):
+                try:
+                    c = Claim.from_dict(cd)
+                    g.claims[c.id] = c
+                except Exception as e:  # noqa: BLE001 — skip corrupt entries
+                    _log.warning("skipping corrupt assurance claim: %s", e)
+        except Exception as e:  # noqa: BLE001 — corrupt file = fresh graph
+            _log.warning("failed to load assurance graph: %s", e)
+        return g
+
+
+    def _record_coverage_snapshot(self, root: Path) -> None:
+        """Append a coverage snapshot to the history file for trend analysis."""
+        try:
+            import json
+
+            history_path = root / COVERAGE_HISTORY_FILE
+            history_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # Load existing history
+            history: list[dict] = []
+            if history_path.is_file():
+                try:
+                    history = json.loads(history_path.read_text(encoding="utf-8"))
+                except Exception:
+                    history = []
+
+            # Compute current snapshot
+            cov = self.coverage()
+            snapshot = {
+                "timestamp": datetime.now(UTC).isoformat(),
+                "overall_pct": round(
+                    cov["by_verdict"].get("proved", 0) / cov["claims_total"] * 100
+                    if cov["claims_total"]
+                    else 0
+                ),
+                "claims_total": cov["claims_total"],
+                "proved": cov["by_verdict"].get("proved", 0),
+                "disproved": cov["by_verdict"].get("disproved", 0),
+                "unproven": cov["by_verdict"].get("unproven", 0),
+                "not_proved": cov["by_verdict"].get("not_proved", 0),
+                "by_domain": {},
+            }
+            # Per-domain breakdown
+            for dom, counts in cov.get("by_domain", {}).items():
+                dom_total = counts.get("total", 0)
+                dom_proved = counts.get("proved", 0)
+                snapshot["by_domain"][dom] = {
+                    "proved": dom_proved,
+                    "total": dom_total,
+                    "pct": round(dom_proved / dom_total * 100) if dom_total else 0,
+                }
+
+            history.append(snapshot)
+
+            # Keep last 500 snapshots to avoid unbounded growth
+            if len(history) > 500:
+                history = history[-500:]
+
+            tmp = history_path.with_suffix(".json.tmp")
+            tmp.write_text(json_dumps(history), encoding="utf-8")
+            tmp.replace(history_path)
+        except Exception as e:  # noqa: BLE001 — best-effort
+            _log.debug("coverage snapshot failed: %s", e)
+
+    @staticmethod
+    def load_coverage_history(root: Path) -> list[dict]:
+        """Load the coverage history for trend analysis."""
+        import json
+
+        history_path = root / COVERAGE_HISTORY_FILE
+        if not history_path.is_file():
+            return []
+        try:
+            return json.loads(history_path.read_text(encoding="utf-8"))
+        except Exception:
+            return []
+
+
+def json_dumps(payload: Any) -> str:
+    import json
+
+    return json.dumps(payload, indent=2, default=str)