platformforge 0.1.0__py3-none-any.whl

platformforge/sandbox/env.py

@@ -0,0 +1,151 @@
+"""Sandboxed change verification — copy repository → apply patch →
+analyze before/after → compare findings and graph.
+
+Read-only contract: the original tree is opened read-only; all writes go
+to a temp copy under .platformforge/sandbox/ (or tmp)."""
+
+from __future__ import annotations
+
+import shutil
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class Sandbox:
+    root: Path
+    workdir: Path = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.root = Path(self.root).resolve()
+        self.workdir = Path(tempfile.mkdtemp(prefix="pf-sandbox-"))
+
+    def __enter__(self) -> Sandbox:  # noqa: PYI034 - typing.Self is 3.11+; no typing_extensions dep
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.destroy()
+
+    def copy(self) -> Path:
+        dst = self.workdir / "repo"
+        ignore = shutil.ignore_patterns(
+            ".git", ".venv", "__pycache__", ".platformforge",
+            "node_modules", "graphify-out")
+        shutil.copytree(self.root, dst, ignore=ignore)
+        return dst
+
+    def apply_patch(self, patch_text: str, dst: Path) -> dict[str, Any]:
+        """Apply a unified diff via `patch` if present, else fail closed."""
+        patch_file = self.workdir / "change.patch"
+        patch_file.write_text(patch_text)
+        import subprocess
+        r = subprocess.run(["patch", "-p1", "-d", str(dst), "-i",
+                            str(patch_file)],
+                           capture_output=True, text=True, check=False)
+        return {"applied": r.returncode == 0, "stdout": r.stdout[-2000:],
+                "stderr": r.stderr[-2000:]}
+
+    def write_file(self, rel: str, content: str, dst: Path) -> Path:
+        p = (dst / rel).resolve()
+        root = dst.resolve()
+        if p != root and root not in p.parents:
+            raise ValueError(
+                f"sandbox path escapes root: {rel!r} -> {p}")
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content)
+        return p
+
+    def destroy(self) -> None:
+        shutil.rmtree(self.workdir, ignore_errors=True)
+
+
+def _analyze_tree(tree: Path, analyzers: dict[str, Any]) -> dict[str, Any]:
+    facts: list[dict[str, Any]] = []
+    errors = []
+    for dom, fn in analyzers.items():
+        try:
+            facts += fn(str(tree))["facts"]
+        except Exception as e:  # noqa: BLE001 — analyzer failure is data
+            errors.append(f"{dom}: {e}")
+    return {"facts": facts, "errors": errors}
+
+
+def _default_analyzers() -> dict[str, Any]:
+    from platformforge.cicd import analyze_gha
+    from platformforge.iac import analyze_hcl
+    from platformforge.k8s import analyze_k8s
+    return {"iac": analyze_hcl, "k8s": analyze_k8s, "gha": analyze_gha}
+
+
+def sandbox_analyze(repo: str | Path,
+                    patch: str | None = None,
+                    files: dict[str, str] | None = None,
+                    analyzers: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Full §86 loop: copy → apply → analyze before/after → compare."""
+    analyzers = analyzers or _default_analyzers()
+    before = _analyze_tree(Path(repo), analyzers)
+    with Sandbox(repo) as sb:
+        dst = sb.copy()
+        applied = {}
+        if patch:
+            applied = sb.apply_patch(patch, dst)
+            if not applied["applied"]:
+                return {"refusal": "platform.sandbox.patch_failed",
+                        "detail": applied["stderr"], "before": before}
+        for rel, content in (files or {}).items():
+            try:
+                sb.write_file(rel, content, dst)
+            except ValueError as exc:
+                return {"refusal": "platform.sandbox.path_escape",
+                        "detail": str(exc), "before": before}
+        after = _analyze_tree(dst, analyzers)
+    return {"before": before, "after": after,
+            "delta": compare_runs(before, after), "applied": applied,
+            "semantic": semantic_delta(before, after)}
+
+
+def compare_runs(before: dict[str, Any],
+                 after: dict[str, Any]) -> dict[str, Any]:
+    """Fact-kind and rule-facing delta between two analyzer outputs."""
+    def kinds(run):
+        out: dict[str, int] = {}
+        for f in run["facts"]:
+            out[f["kind"]] = out.get(f["kind"], 0) + 1
+        return out
+    kb, ka = kinds(before), kinds(after)
+    added = {k: ka[k] for k in ka if k not in kb}
+    removed = {k: kb[k] for k in kb if k not in ka}
+    changed = {k: {"before": kb[k], "after": ka[k]}
+               for k in ka if k in kb and ka[k] != kb[k]}
+    ids_b = {f["fact_id"] for f in before["facts"]}
+    ids_a = {f["fact_id"] for f in after["facts"]}
+    return {"fact_kinds_added": added, "fact_kinds_removed": removed,
+            "fact_kinds_changed_count": changed,
+            "facts_added": len(ids_a - ids_b),
+            "facts_removed": len(ids_b - ids_a)}
+
+
+def semantic_delta(before: dict[str, Any], after: dict[str, Any]
+                   ) -> dict[str, Any]:
+    """§106 — graph-aware delta: build graphs from both runs, diff
+    semantically, score the risk change. Never returns just a count."""
+    from platformforge.graph.build import GraphBuilder
+    from platformforge.graph.diff import diff as graph_diff
+    try:
+        gb = GraphBuilder().from_facts(before["facts"]).graph
+        ga = GraphBuilder().from_facts(after["facts"]).graph
+        gdiff = graph_diff(gb, ga)
+    except Exception as exc:  # noqa: BLE001 — delta failure is data
+        return {"graph_diff": None, "error": str(exc)}
+    # risk delta: new security/exposure edges vs removed ones
+    exposure = (gdiff.get("semantic") or {}).get("exposure") or {}
+    sec = (gdiff.get("semantic") or {}).get("security") or {}
+    return {"graph_diff": gdiff,
+            "exposure_added": any(e.startswith("+")
+                                  for e in exposure.get("edge_changes", [])),
+            "security_edges_changed": sec.get("changed", False),
+            "nodes_added": len(gdiff.get("nodes_added") or []),
+            "nodes_removed": len(gdiff.get("nodes_removed") or []),
+            "note": "semantic delta over graph, not just fact counts"}

platformforge/sandbox/review.py

@@ -0,0 +1,92 @@
+"""§104 change review — composes the sandbox delta into the full review
+pipeline: diff → planned graph → blast → IAM/networking/availability/
+cost/security/SLO → risk → recommended validation. Read-only; review
+never applies.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.models import Fact
+from platformforge.risk.engine import assess_change
+from platformforge.rules import RuleEngine, load_catalog
+from platformforge.sandbox.env import sandbox_analyze
+
+
+def _findings(facts, catalog_dirs) -> list[dict[str, Any]]:
+    rules = load_catalog(*catalog_dirs)
+    objs = [Fact.from_dict(f) if isinstance(f, dict) else f for f in facts]
+    findings, _skipped = RuleEngine(rules).evaluate(objs)
+    return [f.to_dict() for f in findings]
+
+
+def review_change(repo: str | Any,
+                  patch: str | None = None,
+                  files: dict[str, str] | None = None,
+                  signals: dict[str, Any] | None = None,
+                  catalog_dirs=None) -> dict[str, Any]:
+    """Run sandbox_analyze, then judge findings on the after-state and
+    score the risk delta. Output is a review — never a decision."""
+    if catalog_dirs is None:
+        # resolve via data_path — a CWD-relative default yields an empty
+        # catalog (zero-rule review) outside the repo checkout
+        from platformforge.resources import data_path
+        catalog_dirs = (data_path("rules", "catalog"),)
+    run = sandbox_analyze(repo, patch=patch, files=files)
+    if "refusal" in run:
+        return run
+
+    findings_before = _findings(run["before"]["facts"], catalog_dirs)
+    findings_after = _findings(run["after"]["facts"], catalog_dirs)
+
+    sem = run.get("semantic") or {}
+    gdiff = sem.get("graph_diff") or {}
+    blast = gdiff.get("blast_radius_delta") or {}
+
+    # §104 dimensions — each is a named section, unknown when evidence is
+    # missing rather than silently "clean"
+    dims: dict[str, Any] = {
+        "diff": {"facts_added": run["delta"]["facts_added"],
+                 "facts_removed": run["delta"]["facts_removed"],
+                 "kinds_changed": run["delta"]["fact_kinds_changed_count"]},
+        "graph": {"nodes_added": sem.get("nodes_added"),
+                  "nodes_removed": sem.get("nodes_removed"),
+                  "exposure_added": sem.get("exposure_added"),
+                  "security_edges_changed":
+                      sem.get("security_edges_changed")},
+        "blast_radius": {"changed_nodes": len(blast),
+                         "worst": max((v["after"] for v in blast.values()),
+                                      default=0)},
+        "findings_delta": {
+            "before": len(findings_before),
+            "after": len(findings_after),
+            "new": [f.get("rule_id") for f in findings_after
+                    if f.get("rule_id") not in
+                    {fb.get("rule_id") for fb in findings_before}],
+            "resolved": [f.get("rule_id") for f in findings_before
+                         if f.get("rule_id") not in
+                         {fa.get("rule_id") for fa in findings_after}]},
+    }
+    signals_out = assess_change({
+        "blast_radius": dims["blast_radius"]["worst"],
+        "security_impact": bool(dims["findings_delta"]["new"]),
+        "network_exposure": sem.get("exposure_added", False),
+        **(signals or {})})
+    dims["risk"] = signals_out
+    dims["recommended_validation"] = _validation(dims)
+    return {"review": dims,
+            "note": "review only — apply/approve remain host-side"}
+
+
+def _validation(dims: dict[str, Any]) -> list[str]:
+    steps = ["re-run `platformforge judge` on the after-state"]
+    if dims["graph"].get("exposure_added"):
+        steps.append("manual network review — new exposure edge added")
+    if dims["findings_delta"]["new"]:
+        steps.append("fix new findings before approval")
+    if dims["risk"].get("level") in ("high", "critical"):
+        steps.append("require second approver + sandbox receipt")
+    if dims["risk"].get("underreported"):
+        steps.append("resolve unknown risk signals before sign-off")
+    return steps

platformforge/sdd/__init__.py

@@ -0,0 +1,8 @@
+"""Native SDD — spec-driven development lifecycle with hash cascade + gates.
+
+No runtime dependency on AgentSpec/cc-sdd/Cavekit — this is first-party.
+"""
+
+from platformforge.sdd.lifecycle import GATE_FAILURES, PHASES, SddArtifact, SDDProject
+
+__all__ = ["GATE_FAILURES", "PHASES", "SDDProject", "SddArtifact"]

platformforge/sdd/lifecycle.py

@@ -0,0 +1,239 @@
+"""SDD lifecycle: DISCOVER → DEFINE → DESIGN → CONTRACT → PLAN → BUILD →
+REVIEW → VERIFY → SHIP → LEARN. Every phase is a versioned artifact with an
+upstream content hash; a changed phase marks everything downstream stale.
+
+Ship gates refuse on: failed verification, missing evidence, stale upstream,
+unresolved critical findings, failed security gate, absent risk acceptance.
+Overrides always emit a receipt — never silent.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from platformforge.core.hashing import sha256_file
+
+PHASES = ["discover", "define", "design", "contract", "plan", "build",
+          "review", "verify", "ship", "learn"]
+ARTIFACT_EXT = {"build": ".json", "verify": ".json", "ship": ".md",
+                "learn": ".md"}
+DEFAULT_EXT = ".md"
+GATE_FAILURES = (
+    "required_test_failed", "evidence_missing", "upstream_hash_stale",
+    "critical_finding_unresolved", "security_gate_failed",
+    "risk_acceptance_absent",
+)
+SDD_ROOT = ".platformforge/sdd"
+
+FM_RE = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
+
+
+def artifact_name(phase: str) -> str:
+    return phase + ARTIFACT_EXT.get(phase, DEFAULT_EXT)
+
+
+@dataclass
+class SddArtifact:
+    feature: str
+    phase: str
+    path: Path
+    meta: dict[str, Any] = field(default_factory=dict)
+    body: str = ""
+    exists: bool = False
+
+    @property
+    def status(self) -> str:
+        return self.meta.get("status", "missing")
+
+    @property
+    def upstream(self) -> dict[str, Any]:
+        return self.meta.get("upstream", {})
+
+
+def _front(meta: dict[str, Any], body: str) -> str:
+    return "---\n" + yaml.safe_dump(meta, sort_keys=False) + "---\n" + body
+
+
+def _parse(text: str) -> tuple[dict[str, Any], str]:
+    m = FM_RE.match(text)
+    if not m:
+        return {}, text
+    return yaml.safe_load(m.group(1)) or {}, text[m.end():]
+
+
+class SDDProject:
+    def __init__(self, root: str | Path):
+        self.root = Path(root)
+        self.base = self.root / SDD_ROOT
+
+    # ── artifact io ───────────────────────────────────────────
+    def _feature_dir(self, feature: str) -> Path:
+        if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_\-]*", feature):
+            raise ValueError(f"invalid feature name: {feature!r}")
+        return self.base / feature
+
+    def artifact(self, feature: str, phase: str) -> SddArtifact:
+        p = self._feature_dir(feature) / artifact_name(phase)
+        if not p.exists():
+            return SddArtifact(feature, phase, p, exists=False)
+        if p.suffix == ".json":
+            meta = {"sdd": 1, "phase": phase}
+            doc = yaml.safe_load(p.read_text())
+            if isinstance(doc, dict):
+                meta = {**meta, **doc.pop("meta", doc)}
+                return SddArtifact(feature, phase, p, meta=meta,
+                                   body="", exists=True)
+            return SddArtifact(feature, phase, p, meta=meta, exists=True)
+        meta, body = _parse(p.read_text())
+        return SddArtifact(feature, phase, p, meta=meta, body=body, exists=True)
+
+    def write_artifact(self, feature: str, phase: str,
+                       body: str | dict[str, Any],
+                       meta_extra: dict[str, Any] | None = None) -> SddArtifact:
+        d = self._feature_dir(feature)
+        d.mkdir(parents=True, exist_ok=True)
+        idx = PHASES.index(phase)
+        upstream = {}
+        if idx > 0:
+            prev = self.artifact(feature, PHASES[idx - 1])
+            if prev.exists:
+                upstream = {"path": prev.path.name,
+                            "sha256": sha256_file(prev.path)}
+        now = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        meta = {"sdd": 1, "feature": feature, "phase": phase,
+                "status": "ready", "created_at": now, "updated_at": now,
+                "upstream": upstream, "evidence": [], "risks": [],
+                "owners": [], **(meta_extra or {})}
+        p = d / artifact_name(phase)
+        existing = self.artifact(feature, phase)
+        if existing.exists and existing.meta.get("created_at"):
+            meta["created_at"] = existing.meta["created_at"]
+        if p.suffix == ".json":
+            doc = {"meta": meta}
+            if isinstance(body, dict):
+                doc.update(body)
+            p.write_text(yaml.safe_dump(doc, sort_keys=False))
+        else:
+            text = body if isinstance(body, str) else yaml.safe_dump(body)
+            p.write_text(_front(meta, text))
+        return self.artifact(feature, phase)
+
+    # ── status & cascade ──────────────────────────────────────
+    def status(self, feature: str) -> dict[str, Any]:
+        stale = self._stale_phases(feature)
+        phases = []
+        for ph in PHASES:
+            a = self.artifact(feature, ph)
+            st = "missing"
+            if a.exists:
+                st = "stale" if ph in stale else a.status
+            phases.append({"phase": ph, "status": st,
+                           "file": artifact_name(ph)})
+        return {"feature": feature, "phases": phases, "stale": sorted(stale)}
+
+    def _stale_phases(self, feature: str) -> set[str]:
+        """Once a phase's upstream hash mismatches, everything downstream is
+        stale — the cascade never pretends nothing changed."""
+        stale: set[str] = set()
+        propagate = False
+        for i, ph in enumerate(PHASES):
+            a = self.artifact(feature, ph)
+            if not a.exists:
+                continue
+            if propagate:
+                stale.add(ph)
+                continue
+            if i == 0:
+                continue
+            up = a.upstream
+            prev = self.artifact(feature, PHASES[i - 1])
+            if (prev.exists and up.get("sha256")
+                    and up["sha256"] != sha256_file(prev.path)):
+                stale.add(ph)
+                propagate = True
+        return stale
+
+    # ── gates ─────────────────────────────────────────────────
+    def check(self, feature: str) -> dict[str, Any]:
+        st = self.status(feature)
+        return {**st, "ok": not st["stale"]}
+
+    def stamp(self, feature: str, phase: str | None = None) -> dict[str, Any]:
+        """Re-seal upstream hash(es) after intentional change."""
+        stamped = []
+        targets = [phase] if phase else PHASES[1:]
+        for ph in targets:
+            a = self.artifact(feature, ph)
+            if not a.exists or ph == PHASES[0]:
+                continue
+            prev = self.artifact(feature, PHASES[PHASES.index(ph) - 1])
+            if prev.exists:
+                a.meta["upstream"] = {"path": prev.path.name,
+                                      "sha256": sha256_file(prev.path)}
+                a.meta["status"] = "ready"
+                a.meta["updated_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ",
+                                                     time.gmtime())
+                if a.path.suffix == ".json":
+                    doc = yaml.safe_load(a.path.read_text()) or {}
+                    doc["meta"] = a.meta
+                    a.path.write_text(yaml.safe_dump(doc, sort_keys=False))
+                else:
+                    a.path.write_text(_front(a.meta, a.body))
+                stamped.append(ph)
+        return {"stamped": stamped, "status": self.status(feature)}
+
+    # ── ship gate ─────────────────────────────────────────────
+    def ship_gate(self, feature: str, verify: dict[str, Any] | None = None,
+                  findings: list[dict[str, Any]] | None = None,
+                  risk_accepted: bool = False) -> dict[str, Any]:
+        """Evaluate ship gates. Returns {allowed, failures[], receipt?}."""
+        failures: list[str] = []
+        status = self.status(feature)
+        if status["stale"]:
+            failures.append("upstream_hash_stale")
+        missing = [p["phase"] for p in status["phases"]
+                   if p["phase"] in ("discover", "define", "design", "contract",
+                                     "plan", "build", "review", "verify")
+                   and p["status"] == "missing"]
+        if missing:
+            failures.append(f"evidence_missing:{','.join(missing)}")
+        verify_doc = verify or {}
+        if verify_doc.get("required_failed") or verify_doc.get("tests") == "failed":
+            failures.append("required_test_failed")
+        if verify_doc.get("security") == "failed":
+            failures.append("security_gate_failed")
+        critical = [f for f in (findings or [])
+                    if f.get("severity") == "critical"
+                    and f.get("status") == "violated"]
+        if critical:
+            failures.append("critical_finding_unresolved")
+        high_risk = verify_doc.get("risk") in ("high", "critical")
+        if high_risk and not risk_accepted:
+            failures.append("risk_acceptance_absent")
+        return {"feature": feature, "allowed": not failures,
+                "failures": failures,
+                "rule": "overrides emit a receipt via ship(override=True)"}
+
+    def ship(self, feature: str, verify: dict[str, Any] | None = None,
+             findings: list[dict[str, Any]] | None = None,
+             risk_accepted: bool = False, override: bool = False,
+             override_reason: str = "") -> dict[str, Any]:
+        gate = self.ship_gate(feature, verify, findings, risk_accepted)
+        if not gate["allowed"] and not override:
+            return {**gate, "shipped": False}
+        meta_extra: dict[str, Any] = {}
+        if not gate["allowed"] and override:
+            meta_extra["override_receipt"] = {
+                "overridden_failures": gate["failures"],
+                "reason": override_reason,
+                "at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            }
+        self.write_artifact(feature, "ship", "Shipped.\n", meta_extra)
+        return {**gate, "shipped": True,
+                "override": bool(meta_extra)}

platformforge/security/__init__.py

@@ -0,0 +1,19 @@
+"""DevSecOps: IAM policy graphs, secret scanning, SBOM, supply chain."""
+
+from platformforge.security.cosign import analyze_cosign
+from platformforge.security.iam import analyze_iam_policy
+from platformforge.security.kyverno import analyze_kyverno
+from platformforge.security.sbom import analyze_sbom
+from platformforge.security.scan import scan_secrets
+from platformforge.security.slsa import slsa_assess
+from platformforge.security.supply import analyze_supply
+
+__all__ = [
+           "analyze_cosign",
+           "analyze_iam_policy",
+           "analyze_kyverno",
+           "analyze_sbom",
+           "analyze_supply",
+           "scan_secrets",
+           "slsa_assess",
+]

platformforge/security/cosign.py

@@ -0,0 +1,67 @@
+"""§99 Sigstore/Cosign — offline shape + attestation parsing.
+
+The core parses signature bundle/attestation JSON structure (bundle
+media types, DSSE envelopes, rekor/log entry presence) but never
+verifies: `signed=true` in a document is *claimed*, not *verified*.
+Actual verification is an optional host-side adapter boundary.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from platformforge.models.base import stable_id
+
+SIG_BUNDLE_HINTS = ("verificationMaterial", "dsseEnvelope",
+                    "rekorBundle", "signature", "signatures")
+
+
+def analyze_cosign(path: str | Path) -> dict[str, Any]:
+    root = Path(path)
+    files = sorted(root.rglob("*.json")) if root.is_dir() else [root]
+    facts: list[dict[str, Any]] = []
+    unresolved: list[dict[str, Any]] = []
+    for f in files:
+        try:
+            doc = json.loads(f.read_text())
+        except (OSError, json.JSONDecodeError):
+            continue
+        if not isinstance(doc, dict):
+            continue
+        has_bundle = any(k in doc for k in SIG_BUNDLE_HINTS)
+        is_attest = doc.get("_type") or doc.get("predicateType")
+        if not (has_bundle or is_attest):
+            continue
+        sigs = doc.get("signatures") or []
+        claimed = bool(sigs) or "signature" in doc
+        subj = doc.get("subject")
+        subj_name = subj[0].get("name", "?") \
+            if isinstance(subj, list) and subj else f.name
+        loc = f"{f}::{subj_name}"
+        facts.append({
+            "fact_id": stable_id("PF-COSIGN", "sig", loc),
+            "kind": "supply.signature", "source": str(f),
+            "location": loc, "tier": 3,
+            "attrs": {
+                "claimed_signed": claimed,
+                "verified": False,   # NEVER true offline
+                "signature_count": len(sigs),
+                "has_rekor_entry": "rekorBundle" in doc or
+                                   "verificationMaterial" in doc,
+                "dsse": "dsseEnvelope" in doc or "_type" in doc,
+                "attestation": bool(is_attest),
+                "note": "parsed shape only — signature is claimed, not "
+                        "verified; verification is a host adapter"}})
+        if claimed:
+            unresolved.append({
+                "capability": "cosign-verify",
+                "location": loc,
+                "reason": "signature present but verification requires "
+                          "key lookup + rekor transparency check — "
+                          "host-side boundary",
+                "unlock": "run the cosign verify adapter with the "
+                          "public key / fulcio bundle"})
+    return {"facts": facts, "unresolved": unresolved,
+            "counts": {"facts": len(facts)}}