@topy-ai/maggie 0.7.55 → 0.7.57

package/bundled-tools/clis/maggie_security_core.py

@@ -0,0 +1,1512 @@
+#!/usr/bin/env python3
+"""Shared helpers for every ``maggie security`` command.
+
+One place for the pieces that must behave the same everywhere
+(docs/maggie-security/00-foundation-prd.md):
+
+- findings: builder, fingerprint id, severity from CVSS, priority rule,
+  within-run merge, findings-set envelope, clipping;
+- the ledger (``.maggie/security/ledger.jsonl``) that turns a run into
+  ``new`` / ``open`` / ``fixed`` and never marks a finding fixed from a
+  degraded run;
+- the feed cache with conditional GET, TTLs, cursors and the
+  ``MAGGIE_SECURITY_MIRROR`` override;
+- the egress guard: every network call names a declared source, and
+  ``--offline`` refuses all of them (a socket guard backs this up);
+- the external tool lock and runner: sha256 before exec, required flags
+  injected, forbidden flags refused;
+- redaction, so a secret value never reaches stdout, files, the ledger or a
+  report;
+- a small JSON Schema validator (the subset our contracts use), because the
+  CLIs stay standard-library only.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import hashlib
+import io
+import json
+import os
+import platform
+import re
+import shutil
+import socket
+import stat
+import subprocess
+import sys
+import tarfile
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import zipfile
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Callable, Iterable
+
+HERE = Path(__file__).resolve().parent
+ROOT = HERE.parents[1]
+DATA_DIR = HERE / "security_data"
+
+SEVERITIES = ["critical", "high", "medium", "low", "info"]
+PRIORITIES = ["p0", "p1", "p2", "p3", "p4"]
+CONFIDENCE = ["confirmed", "likely", "possible"]
+STATUSES = ["new", "open", "fixed", "accepted-risk", "false-positive", "suppressed"]
+KINDS = ["vulnerability", "eol", "malicious-package", "misconfiguration", "exposure", "secret", "code", "tls", "header",
+         "attack-signal", "host-hardening", "availability", "agent-skill", "checklist"]
+
+EXIT_OK, EXIT_FINDINGS, EXIT_USAGE, EXIT_DEGRADED, EXIT_POLICY, EXIT_TOOL = 0, 1, 2, 3, 4, 5
+
+
+class SecurityError(Exception):
+    """An error with a security-CLI exit code (PRD 00 section 6.3)."""
+
+    code = EXIT_USAGE
+
+    def __init__(self, message: str, code: int | None = None) -> None:
+        super().__init__(message)
+        if code is not None:
+            self.code = code
+
+
+class UsageError(SecurityError):
+    code = EXIT_USAGE
+
+
+class DegradedError(SecurityError):
+    code = EXIT_DEGRADED
+
+
+class PolicyError(SecurityError):
+    code = EXIT_POLICY
+
+
+class ToolError(SecurityError):
+    code = EXIT_TOOL
+
+
+# --------------------------------------------------------------------------- basics
+
+
+def maggie_version() -> str:
+    for candidate in (ROOT / "VERSION",):
+        if candidate.is_file():
+            return candidate.read_text(encoding="utf-8").strip()
+    package = ROOT / "package.json"
+    if package.is_file():
+        with contextlib.suppress(ValueError, OSError):
+            return str(json.loads(package.read_text(encoding="utf-8")).get("version") or "0.0.0")
+    return "0.0.0"
+
+
+def utcnow() -> datetime:
+    override = os.environ.get("MAGGIE_SECURITY_NOW")
+    if override:
+        return parse_time(override)
+    return datetime.now(timezone.utc).replace(microsecond=0)
+
+
+def iso(moment: datetime | None = None) -> str:
+    return (moment or utcnow()).astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def parse_time(value: str) -> datetime:
+    text = value.strip()
+    if re.fullmatch(r"\d{4}-\d{2}-\d{2}", text):
+        return datetime.fromisoformat(text).replace(tzinfo=timezone.utc)
+    if text.endswith("Z"):
+        text = text[:-1] + "+00:00"
+    moment = datetime.fromisoformat(text)
+    if moment.tzinfo is None:
+        moment = moment.replace(tzinfo=timezone.utc)
+    return moment.astimezone(timezone.utc)
+
+
+def parse_duration(value: str) -> timedelta:
+    match = re.fullmatch(r"\s*(\d+)\s*([smhdw])\s*", value or "")
+    if not match:
+        raise UsageError(f"bad duration {value!r}; use e.g. 30m, 24h, 7d")
+    amount, unit = int(match.group(1)), match.group(2)
+    units = {"s": "seconds", "m": "minutes", "h": "hours", "d": "days", "w": "weeks"}
+    return timedelta(**{units[unit]: amount})
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1 << 20), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def canonical_json(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def read_json(path: Path) -> Any:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as error:
+        raise UsageError(f"file not found: {path}") from error
+    except json.JSONDecodeError as error:
+        raise UsageError(f"{path}: invalid JSON ({error.msg} at line {error.lineno})") from error
+
+
+def write_json(path: Path, value: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + f".{os.getpid()}.{threading.get_ident()}.tmp")
+    tmp.write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    tmp.replace(path)
+
+
+# --------------------------------------------------------------------------- schema validation
+
+
+def contracts_dir() -> Path:
+    for candidate in (ROOT / "contracts" / "maggie-security", ROOT / "bundled-contracts" / "maggie-security"):
+        if candidate.is_dir():
+            return candidate
+    raise UsageError("maggie-security contracts not found (expected contracts/maggie-security)")
+
+
+def load_contract(name: str) -> dict:
+    return read_json(contracts_dir() / f"{name}.schema.json")
+
+
+_TYPES: dict[str, Callable[[Any], bool]] = {
+    "object": lambda v: isinstance(v, dict),
+    "array": lambda v: isinstance(v, list),
+    "string": lambda v: isinstance(v, str),
+    "integer": lambda v: isinstance(v, int) and not isinstance(v, bool),
+    "number": lambda v: isinstance(v, (int, float)) and not isinstance(v, bool),
+    "boolean": lambda v: isinstance(v, bool),
+    "null": lambda v: v is None,
+}
+
+
+def schema_errors(instance: Any, schema: dict, root: dict | None = None, path: str = "$") -> list[str]:
+    """Validate the JSON Schema subset our contracts use; returns error strings."""
+    root = root if root is not None else schema
+    errors: list[str] = []
+    if "$ref" in schema:
+        ref = schema["$ref"]
+        if not ref.startswith("#/"):
+            return [f"{path}: unsupported $ref {ref}"]
+        target: Any = root
+        for part in ref[2:].split("/"):
+            target = target[part]
+        return schema_errors(instance, target, root, path)
+    if "const" in schema and instance != schema["const"]:
+        errors.append(f"{path}: expected {schema['const']!r}")
+    if "enum" in schema and instance not in schema["enum"]:
+        errors.append(f"{path}: {instance!r} not in {schema['enum']}")
+    if "type" in schema:
+        types = schema["type"] if isinstance(schema["type"], list) else [schema["type"]]
+        if not any(_TYPES[t](instance) for t in types):
+            return errors + [f"{path}: expected {'/'.join(types)}"]
+    if isinstance(instance, str):
+        if "pattern" in schema and not re.search(schema["pattern"], instance):
+            errors.append(f"{path}: does not match {schema['pattern']}")
+        if "minLength" in schema and len(instance) < schema["minLength"]:
+            errors.append(f"{path}: shorter than {schema['minLength']}")
+        if "maxLength" in schema and len(instance) > schema["maxLength"]:
+            errors.append(f"{path}: longer than {schema['maxLength']}")
+    if _TYPES["number"](instance):
+        if "minimum" in schema and instance < schema["minimum"]:
+            errors.append(f"{path}: below {schema['minimum']}")
+        if "maximum" in schema and instance > schema["maximum"]:
+            errors.append(f"{path}: above {schema['maximum']}")
+    if isinstance(instance, dict):
+        for key in schema.get("required", []):
+            if key not in instance:
+                errors.append(f"{path}: missing {key}")
+        props = schema.get("properties", {})
+        for key, value in instance.items():
+            if key in props:
+                errors.extend(schema_errors(value, props[key], root, f"{path}.{key}"))
+            elif schema.get("additionalProperties") is False:
+                errors.append(f"{path}: unexpected {key}")
+            elif isinstance(schema.get("additionalProperties"), dict):
+                errors.extend(schema_errors(value, schema["additionalProperties"], root, f"{path}.{key}"))
+    if isinstance(instance, list) and isinstance(schema.get("items"), dict):
+        for index, item in enumerate(instance):
+            errors.extend(schema_errors(item, schema["items"], root, f"{path}[{index}]"))
+    return errors
+
+
+def validate_contract(instance: Any, name: str) -> list[str]:
+    schema = load_contract(name)
+    errors = schema_errors(instance, schema)
+    if name == "findings-set-v1" and isinstance(instance, dict):
+        finding_schema = load_contract("finding-v1")
+        for index, item in enumerate(instance.get("findings") or []):
+            errors.extend(schema_errors(item, finding_schema, path=f"$.findings[{index}]"))
+    return errors
+
+
+# --------------------------------------------------------------------------- findings
+
+
+def severity_from_cvss(score: float | None) -> str | None:
+    if score is None:
+        return None
+    if score >= 9.0:
+        return "critical"
+    if score >= 7.0:
+        return "high"
+    if score >= 4.0:
+        return "medium"
+    if score > 0:
+        return "low"
+    return "info"
+
+
+_CVSS3 = {
+    "AV": {"N": 0.85, "A": 0.62, "L": 0.55, "P": 0.2}, "AC": {"L": 0.77, "H": 0.44},
+    "UI": {"N": 0.85, "R": 0.62}, "C": {"H": 0.56, "L": 0.22, "N": 0.0}, "I": {"H": 0.56, "L": 0.22, "N": 0.0},
+    "A": {"H": 0.56, "L": 0.22, "N": 0.0},
+}
+
+
+def _roundup(value: float) -> float:
+    integer = round(value * 100000)
+    return integer / 100000.0 if integer % 10000 == 0 else (int(integer / 10000) + 1) / 10.0
+
+
+def cvss3_base_score(vector: str) -> float | None:
+    """CVSS v3.0/3.1 base score from a vector string (FIRST specification formula)."""
+    if not vector or not vector.startswith("CVSS:3"):
+        return None
+    try:
+        metrics = dict(part.split(":", 1) for part in vector.split("/")[1:])
+        scope_changed = metrics["S"] == "C"
+        pr = {"N": 0.85, "L": 0.68 if scope_changed else 0.62, "H": 0.5 if scope_changed else 0.27}[metrics["PR"]]
+        iss = 1 - (1 - _CVSS3["C"][metrics["C"]]) * (1 - _CVSS3["I"][metrics["I"]]) * (1 - _CVSS3["A"][metrics["A"]])
+        impact = 7.52 * (iss - 0.029) - 3.25 * (iss - 0.02) ** 15 if scope_changed else 6.42 * iss
+        exploitability = 8.22 * _CVSS3["AV"][metrics["AV"]] * _CVSS3["AC"][metrics["AC"]] * pr * _CVSS3["UI"][metrics["UI"]]
+    except (KeyError, ValueError):
+        return None
+    if impact <= 0:
+        return 0.0
+    total = 1.08 * (impact + exploitability) if scope_changed else impact + exploitability
+    return _roundup(min(total, 10))
+
+
+def purl_without_version(purl: str | None) -> str | None:
+    if not purl:
+        return None
+    base = purl.split("?", 1)[0].split("#", 1)[0]
+    head, sep, _version = base.rpartition("@")
+    # "pkg:npm/@scope/name" has an @ that is part of the name, not a version.
+    if sep and "/" not in _version and not head.endswith("/"):
+        return head
+    return base
+
+
+def make_purl(ecosystem: str, name: str, version: str | None = None) -> str | None:
+    eco = (ecosystem or "").lower()
+    # Ecosystem -> purl type, after osv.dev purl_helpers.ECOSYSTEM_PURL_DATA (Apache-2.0).
+    kind = {"npm": "npm", "packagist": "composer", "composer": "composer", "pypi": "pypi", "go": "golang",
+            "crates.io": "cargo", "maven": "maven", "nuget": "nuget", "rubygems": "gem", "hex": "hex", "pub": "pub",
+            "wordpress": "wordpress", "debian": "deb", "deb": "deb", "alpine": "apk", "apk": "apk",
+            "github-actions": "github"}.get(eco)
+    if not kind or not name:
+        return None
+    if kind == "npm" and name.startswith("@"):
+        scope, _, rest = name[1:].partition("/")
+        encoded = f"%40{scope}/{rest}"
+    else:
+        encoded = name
+    return f"pkg:{kind}/{encoded}" + (f"@{version}" if version else "")
+
+
+def fingerprint(kind: str, primary: str, locator: str, site: str | None) -> str:
+    material = "\x1f".join([kind, primary.upper() if primary else "", locator or "", site or ""])
+    return "msf_" + sha256_bytes(material.encode("utf-8"))[:24]
+
+
+def finding_locator(affected: dict | None, target: dict) -> str:
+    """What a finding is about, without the version; host-scoped for runtimes on a host."""
+    host = f"#{target['host']}" if target.get("host") else ""
+    if affected:
+        purl = purl_without_version(affected.get("purl"))
+        if purl:
+            return purl + host
+        if affected.get("name"):
+            return f"{affected.get('component_type') or 'component'}:{affected['name']}{host}"
+    for key in ("url", "host", "path", "image"):
+        if target.get(key):
+            return f"{key}:{target[key]}"
+    return ""
+
+
+def make_finding(*, kind: str, title: str, command: str, primary_id: str, site: str | None = None,
+                 severity: str | None = None, severity_source: str | None = None, cvss: dict | None = None,
+                 confidence: str = "likely", aliases: Iterable[str] = (), epss: dict | None = None,
+                 kev: dict | None = None, cwe_ids: Iterable[str] = (), asvs_ids: Iterable[str] = (),
+                 affected: dict | None = None, fix: dict | None = None, target: dict | None = None,
+                 evidence: Iterable[dict] = (), tool: str | None = None, tool_version: str | None = None,
+                 rule_id: str | None = None, feed: str | None = None, fetched_at: str | None = None,
+                 remediation: dict | None = None, signal: dict | None = None, internet_facing: bool = True,
+                 untrusted: dict | None = None) -> dict:
+    """Build one finding-v1 with id, severity and priority filled in."""
+    if kind not in KINDS:
+        raise ValueError(f"unknown finding kind {kind}")
+    target = {"site": site, "host": None, "url": None, "path": None, "image": None, **(target or {})}
+    if site and not target.get("site"):
+        target["site"] = site
+    cvss_sev = severity_from_cvss((cvss or {}).get("score")) if cvss else None
+    if cvss_sev:
+        severity, severity_source = cvss_sev, "cvss"
+    severity = severity if severity in SEVERITIES else "info"
+    severity_source = severity_source or ("tool" if tool else "maggie")
+    alias_list = sorted({a for a in aliases if a} | ({primary_id} if primary_id else set()),
+                        key=lambda a: (not a.upper().startswith("CVE-"), a))
+    finding = {
+        "schema": "maggie-security-finding.v1",
+        "id": fingerprint(kind, primary_id, finding_locator(affected, target), target.get("site")),
+        "kind": kind,
+        "title": title[:300],
+        "severity": severity,
+        "severity_source": severity_source,
+        "priority": "p4",
+        "confidence": confidence,
+        "aliases": alias_list,
+        "cvss": cvss,
+        "epss": epss,
+        "kev": kev,
+        "cwe_ids": sorted(set(cwe_ids)),
+        "asvs_ids": sorted(set(asvs_ids)),
+        "affected": affected,
+        "fix": fix,
+        "target": target,
+        "evidence": [clean_evidence(item) for item in evidence],
+        "source": {"command": command, "tool": tool, "tool_version": tool_version, "rule_id": rule_id or primary_id,
+                   "feed": feed, "fetched_at": fetched_at},
+        "remediation": remediation,
+        "signal": signal,
+        "status": "new",
+        "first_seen": None,
+        "last_seen": None,
+    }
+    if untrusted:
+        finding["untrusted"] = untrusted
+    finding["priority"] = compute_priority(finding, internet_facing=internet_facing)
+    return finding
+
+
+def _step(priority: str, delta: int) -> str:
+    index = min(max(PRIORITIES.index(priority) + delta, 0), len(PRIORITIES) - 1)
+    return PRIORITIES[index]
+
+
+def compute_priority(finding: dict, internet_facing: bool = True, today: date | None = None) -> str:
+    """PRD 00 section 7.4; first match wins, dev scope lowers one step except secrets."""
+    kind = finding.get("kind")
+    severity = finding.get("severity")
+    confidence = finding.get("confidence")
+    kev_listed = bool((finding.get("kev") or {}).get("listed"))
+    epss = float((finding.get("epss") or {}).get("score") or 0)
+    affected = finding.get("affected") or {}
+    fix = finding.get("fix") or {}
+    signal = finding.get("signal") or {}
+    target = finding.get("target") or {}
+    scope = affected.get("scope")
+    eol_days = finding.get("_eol_days")
+    public_artifact = any(str(target.get("path") or "").startswith(p) for p in ("dist/", "public/", "build/", ".output/")) or bool(target.get("url"))
+
+    if (kev_listed and confidence in ("confirmed", "likely") and internet_facing) \
+            or (kind == "secret" and confidence == "confirmed" and public_artifact) \
+            or signal.get("type") == "compromise-indicator":
+        priority = "p0"
+    elif severity == "critical" or (severity == "high" and epss >= 0.1) \
+            or (kind == "eol" and eol_days is not None and eol_days < 0 and internet_facing):
+        priority = "p1"
+    elif severity == "high" or (severity == "medium" and fix.get("available") and affected.get("direct")) \
+            or (kind == "eol" and eol_days is not None and eol_days <= 30):
+        priority = "p2"
+    elif severity in ("medium", "low") or (kind == "eol" and eol_days is not None and eol_days <= 90) \
+            or (kind in ("host-hardening", "header", "misconfiguration") and severity != "info"):
+        priority = "p3"
+    else:
+        priority = "p4"
+    if confidence == "possible" and priority != "p0" and kind != "attack-signal" and not kev_listed:
+        priority = "p4"  # no corroboration: "worth a look", never a notification
+    if kev_listed and fix and fix.get("available") is False and not fix.get("fixed_versions"):
+        priority = _step(priority, -1)
+    if scope == "dev" and kind != "secret":
+        priority = _step(priority, 1)
+    return priority
+
+
+def _better_confidence(a: str, b: str) -> str:
+    return a if CONFIDENCE.index(a) <= CONFIDENCE.index(b) else b
+
+
+def merge_findings(findings: Iterable[dict]) -> list[dict]:
+    """Merge same-fingerprint findings within one run (PRD 00 section 7.5)."""
+    merged: dict[str, dict] = {}
+    order: list[str] = []
+    for finding in findings:
+        fid = finding["id"]
+        if fid not in merged:
+            merged[fid] = json.loads(json.dumps(finding))
+            order.append(fid)
+            continue
+        base = merged[fid]
+        base["aliases"] = sorted(set(base.get("aliases") or []) | set(finding.get("aliases") or []),
+                                 key=lambda a: (not a.upper().startswith("CVE-"), a))
+        if CONFIDENCE.index(finding["confidence"]) < CONFIDENCE.index(base["confidence"]):
+            base["affected"] = finding.get("affected") or base.get("affected")
+        base["confidence"] = _better_confidence(base["confidence"], finding["confidence"])
+        if SEVERITIES.index(finding["severity"]) < SEVERITIES.index(base["severity"]):
+            base["severity"], base["severity_source"] = finding["severity"], finding["severity_source"]
+        for key in ("cvss", "epss", "kev", "fix", "remediation"):
+            if not base.get(key) and finding.get(key):
+                base[key] = finding[key]
+        base["cwe_ids"] = sorted(set(base.get("cwe_ids") or []) | set(finding.get("cwe_ids") or []))
+        base["asvs_ids"] = sorted(set(base.get("asvs_ids") or []) | set(finding.get("asvs_ids") or []))
+        base["evidence"] = (base.get("evidence") or []) + [e for e in finding.get("evidence") or [] if e not in (base.get("evidence") or [])]
+        also = base["source"].setdefault("also", [])
+        src = {k: v for k, v in finding["source"].items() if k != "also"}
+        if src not in also and src != {k: v for k, v in base["source"].items() if k != "also"}:
+            also.append(src)
+        base["priority"] = compute_priority(base)
+    return [merged[fid] for fid in order]
+
+
+def sort_findings(findings: list[dict]) -> list[dict]:
+    return sorted(findings, key=lambda f: (PRIORITIES.index(f.get("priority", "p4")), SEVERITIES.index(f.get("severity", "info")),
+                                           STATUSES.index(f.get("status", "new")), f.get("title", "")))
+
+
+def new_run(command: str, site: str | None, inputs: dict | None = None) -> dict:
+    started = utcnow()
+    suffix = sha256_bytes(f"{command}{time.time_ns()}{os.getpid()}".encode())[:4]
+    return {"id": f"{iso(started)}-{command}-{suffix}", "command": command, "maggie_version": maggie_version(),
+            "started_at": iso(started), "finished_at": iso(started), "site": site, "inputs": inputs or {},
+            "sources": [], "tools": [], "degraded": [], "refused": [], "covered": []}
+
+
+def findings_set(run: dict, findings: list[dict], max_items: int = 200, fixed_ids: list[str] | None = None) -> dict:
+    run = dict(run)
+    run["finished_at"] = iso()
+    ordered = sort_findings(findings)
+    by_severity = {s: 0 for s in SEVERITIES}
+    by_priority = {p: 0 for p in PRIORITIES}
+    for finding in ordered:
+        by_severity[finding["severity"]] += 1
+        by_priority[finding["priority"]] += 1
+    summary = {"new": sum(1 for f in ordered if f["status"] == "new"),
+               "open": sum(1 for f in ordered if f["status"] == "open"),
+               "fixed": len(fixed_ids or []), "by_severity": by_severity, "by_priority": by_priority}
+    clipped = len(ordered) > max_items
+    return {"schema": "maggie-security-findings.v1", "run": run, "summary": summary,
+            "clipped": {"findings": clipped, "total": len(ordered)},
+            "findings": ordered[:max_items], "fixed": list(fixed_ids or [])}
+
+
+# --------------------------------------------------------------------------- redaction
+
+SECRET_QUERY = re.compile(r"(?i)([?&;](?:[a-z0-9_.-]*?(?:token|key|password|passwd|pwd|secret|session|auth|signature|sig)[a-z0-9_.-]*)=)([^&;#\s\"']+)")
+
+
+def redact_secret(value: str) -> dict:
+    """Never store the value: a short preview and a hash for de-duplication."""
+    preview = f"{value[:4]}…{value[-4:]}" if len(value) >= 12 else "…"
+    return {"redacted": preview, "value_sha256": sha256_bytes(value.encode("utf-8"))}
+
+
+def mask_query(text: str) -> str:
+    return SECRET_QUERY.sub(lambda m: m.group(1) + "***", text)
+
+
+def clean_excerpt(text: str, limit: int = 200) -> str:
+    text = mask_query(str(text)).replace("\r", " ").replace("\n", " ")
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+def clean_evidence(item: dict) -> dict:
+    out = dict(item)
+    if "excerpt" in out and out["excerpt"] is not None:
+        out["excerpt"] = clean_excerpt(out["excerpt"])
+    return out
+
+
+def assert_no_secret(texts: Iterable[str], secrets: Iterable[str]) -> list[str]:
+    """Return the secrets that leaked into any of the texts (tests and report-check)."""
+    leaked = []
+    blob = "\n".join(texts)
+    for secret in secrets:
+        if secret and secret in blob:
+            leaked.append(secret[:4] + "…")
+    return leaked
+
+
+# --------------------------------------------------------------------------- state and config
+
+
+@dataclass
+class State:
+    project: Path
+
+    @property
+    def root(self) -> Path:
+        return self.project / ".maggie" / "security"
+
+    def path(self, *parts: str) -> Path:
+        return self.root.joinpath(*parts)
+
+    def config(self) -> dict:
+        path = self.path("config.json")
+        return read_json(path) if path.is_file() else {}
+
+    def ensure(self) -> None:
+        self.root.mkdir(parents=True, exist_ok=True)
+
+
+def site_id(project: Path, explicit: str | None = None) -> str:
+    if explicit:
+        return explicit
+    state = State(project)
+    cfg = state.config()
+    if cfg.get("site"):
+        return str(cfg["site"])
+    meta = project / ".maggie" / "project.json"
+    if meta.is_file():
+        with contextlib.suppress(UsageError):
+            data = read_json(meta)
+            for key in ("site", "id", "slug", "name"):
+                if isinstance(data.get(key), str) and data[key]:
+                    return re.sub(r"[^a-z0-9-]+", "-", data[key].lower()).strip("-") or "site"
+    return re.sub(r"[^a-z0-9-]+", "-", project.resolve().name.lower()).strip("-") or "site"
+
+
+# --------------------------------------------------------------------------- ledger
+
+
+class Ledger:
+    """Append-only status history (PRD 00 section 9.1)."""
+
+    USER_EVENTS = ("accepted-risk", "false-positive", "suppressed", "reopened")
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+
+    def events(self) -> list[dict]:
+        if not self.path.is_file():
+            return []
+        out = []
+        for line in self.path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if line:
+                with contextlib.suppress(json.JSONDecodeError):
+                    out.append(json.loads(line))
+        return out
+
+    def append(self, events: Iterable[dict]) -> None:
+        events = list(events)
+        if not events:
+            return
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a", encoding="utf-8") as handle:
+            for event in events:
+                handle.write(canonical_json(event) + "\n")
+
+    def history(self) -> dict[str, list[dict]]:
+        out: dict[str, list[dict]] = {}
+        for event in self.events():
+            out.setdefault(event.get("id", ""), []).append(event)
+        return out
+
+    @staticmethod
+    def derive(events: list[dict], now: datetime | None = None) -> dict:
+        """Current state of one id from its history."""
+        now = now or utcnow()
+        status = None
+        first_seen = last_seen = None
+        severity = kev = target = command = None
+        for event in events:
+            kind = event.get("event")
+            if kind == "seen":
+                first_seen = first_seen or event.get("at")
+                last_seen = event.get("at")
+                severity = event.get("severity", severity)
+                kev = event.get("kev", kev)
+                target = event.get("target", target)
+                command = event.get("command", command)
+                if status in (None, "fixed"):
+                    status = "open"
+            elif kind == "fixed":
+                status = "fixed"
+            elif kind == "accepted-risk":
+                until = event.get("until")
+                status = "accepted-risk" if not until or parse_time(until) > now else "open"
+            elif kind in ("false-positive", "suppressed"):
+                status = kind
+            elif kind == "reopened":
+                status = "open"
+        return {"status": status, "first_seen": first_seen, "last_seen": last_seen, "severity": severity, "kev": kev,
+                "target": target, "command": command}
+
+    def apply_run(self, findings: list[dict], run: dict, record: bool = True) -> tuple[list[dict], list[str]]:
+        """Set status on each finding, append seen/fixed events, return (findings, fixed ids).
+
+        A previously open finding is marked fixed only when this run covered its
+        target (``run.covered``), it is absent, and no source was degraded.
+        """
+        now = utcnow()
+        history = self.history()
+        present = {f["id"] for f in findings}
+        new_events: list[dict] = []
+        out = []
+        for finding in findings:
+            prior = self.derive(history.get(finding["id"], []), now) if finding["id"] in history else None
+            finding = dict(finding)
+            stamp = iso(now)
+            if prior is None or prior["status"] is None:
+                finding["status"] = "new"
+                finding["first_seen"] = stamp
+            else:
+                finding["first_seen"] = prior["first_seen"] or stamp
+                if prior["status"] in ("accepted-risk", "false-positive", "suppressed"):
+                    finding["status"] = prior["status"]
+                elif prior["status"] == "fixed":
+                    finding["status"] = "new"
+                else:
+                    finding["status"] = "open"
+                escalated = (prior.get("severity") in SEVERITIES and SEVERITIES.index(finding["severity"]) < SEVERITIES.index(prior["severity"])) \
+                    or (bool((finding.get("kev") or {}).get("listed")) and not prior.get("kev"))
+                if escalated and finding["status"] in ("open", "accepted-risk"):
+                    finding["status"] = "new"
+                    finding["change"] = "escalated"
+            finding["last_seen"] = stamp
+            if finding.get("change") is None:
+                finding.pop("change", None)
+            out.append(finding)
+            new_events.append({"id": finding["id"], "at": stamp, "event": "seen", "run": run["id"], "command": run["command"],
+                               "severity": finding["severity"], "kev": bool((finding.get("kev") or {}).get("listed")),
+                               "version": (finding.get("affected") or {}).get("version"),
+                               "target": finding_locator(finding.get("affected"), finding.get("target") or {}) or None})
+        fixed: list[str] = []
+        degraded = bool(run.get("degraded"))
+        covered = set(run.get("covered") or [])
+        if not degraded and covered:
+            for fid, events in history.items():
+                if fid in present or not fid:
+                    continue
+                state = self.derive(events, now)
+                if state["status"] != "open":
+                    continue
+                if state.get("command") not in (None, run["command"]):
+                    continue
+                if (state.get("target") or "") in covered or "*" in covered:
+                    fixed.append(fid)
+                    new_events.append({"id": fid, "at": iso(now), "event": "fixed", "run": run["id"]})
+        if record:
+            self.append(new_events)
+        return out, fixed
+
+    def mark(self, fid: str, event: str, reason: str | None, until: str | None = None, by: str = "user") -> dict:
+        if event not in self.USER_EVENTS:
+            raise UsageError(f"unknown ledger event {event}")
+        if event in ("accepted-risk", "false-positive") and not (reason or "").strip():
+            raise UsageError("--reason is required")
+        if fid not in self.history():
+            raise UsageError(f"unknown finding id {fid}")
+        entry = {"id": fid, "at": iso(), "event": event, "by": by}
+        if reason:
+            entry["reason"] = clean_excerpt(reason, 300)
+        if until:
+            entry["until"] = until
+        self.append([entry])
+        return entry
+
+    def compact(self, keep_days: int = 365) -> dict:
+        """Keep the last event per id plus everything newer than keep_days."""
+        events = self.events()
+        cutoff = utcnow() - timedelta(days=keep_days)
+        last: dict[str, dict] = {}
+        for event in events:
+            last[event.get("id", "")] = event
+        kept = [e for e in events if e is last.get(e.get("id", "")) or parse_time(e.get("at", iso())) >= cutoff]
+        if len(kept) != len(events):
+            self.path.write_text("".join(canonical_json(e) + "\n" for e in kept), encoding="utf-8")
+        return {"before": len(events), "after": len(kept)}
+
+
+# --------------------------------------------------------------------------- egress and feeds
+
+USER_AGENT = f"maggie-security/{maggie_version()} (+https://cmo.so)"
+
+# Every network source a command may use. Commands declare a list of these
+# ids; --explain-egress prints the hosts and --offline refuses them all.
+SOURCES: dict[str, dict] = {
+    "cvelistv5-delta": {"hosts": ["raw.githubusercontent.com"], "ttl": "1h",
+                        "url": "https://raw.githubusercontent.com/CVEProject/cvelistV5/main/cves/deltaLog.json"},
+    "cve-record": {"hosts": ["cveawg.mitre.org"], "ttl": "7d", "url": "https://cveawg.mitre.org/api/cve/{id}"},
+    "osv-modified": {"hosts": ["storage.googleapis.com"], "ttl": "1h",
+                     "url": "https://storage.googleapis.com/osv-vulnerabilities/{ecosystem}/modified_id.csv"},
+    "osv-zip": {"hosts": ["storage.googleapis.com"], "ttl": "24h", "url": "https://storage.googleapis.com/osv-vulnerabilities/{ecosystem}/all.zip"},
+    "osv-api": {"hosts": ["api.osv.dev"], "ttl": "24h", "url": "https://api.osv.dev/v1/querybatch"},
+    "kev": {"hosts": ["raw.githubusercontent.com"], "ttl": "6h",
+            "url": "https://raw.githubusercontent.com/cisagov/kev-data/main/known_exploited_vulnerabilities.json"},
+    "eol": {"hosts": ["endoflife.date"], "ttl": "24h", "url": "https://endoflife.date/api/v1/products/{product}/"},
+    "node-core": {"hosts": ["raw.githubusercontent.com"], "ttl": "6h",
+                  "url": "https://raw.githubusercontent.com/nodejs/security-wg/main/vuln/core/index.json"},
+    "wpvulnerability": {"hosts": ["www.wpvulnerability.net"], "ttl": "12h", "url": "https://www.wpvulnerability.net/{kind}/{slug}/"},
+    "nuclei-cves": {"hosts": ["raw.githubusercontent.com"], "ttl": "24h",
+                    "url": "https://raw.githubusercontent.com/projectdiscovery/nuclei-templates/main/cves.json"},
+    "ossf-malicious": {"hosts": ["api.osv.dev"], "ttl": "24h", "url": "https://api.osv.dev/v1/querybatch"},
+    "retire-jsrepo": {"hosts": ["raw.githubusercontent.com"], "ttl": "24h",
+                      "url": "https://raw.githubusercontent.com/RetireJS/retire.js/master/repository/jsrepository-v4.json"},
+    "github-releases": {"hosts": ["github.com", "objects.githubusercontent.com", "release-assets.githubusercontent.com"], "ttl": "0s",
+                        "url": "https://github.com/"},
+    "target-site": {"hosts": ["<verified domain>"], "ttl": "0s", "url": ""},
+    "dns": {"hosts": ["<system resolver>"], "ttl": "0s", "url": ""},
+}
+
+
+class EgressGuard:
+    """Checks every request against the command's declared sources."""
+
+    def __init__(self, declared: Iterable[str], offline: bool = False, extra_hosts: Iterable[str] = ()) -> None:
+        self.declared = list(declared)
+        self.offline = offline
+        self.extra_hosts = set(extra_hosts)
+
+    def hosts(self) -> list[str]:
+        out: list[str] = []
+        for source in self.declared:
+            for host in SOURCES.get(source, {}).get("hosts", []):
+                if host not in out:
+                    out.append(host)
+        return out + sorted(self.extra_hosts - set(out))
+
+    def check(self, source: str, url: str) -> str:
+        if url.startswith("file://") and mirror_base() and url.startswith(mirror_base()):
+            return url  # a local mirror directory is not network egress
+        if self.offline:
+            raise DegradedError(f"--offline: not contacting {source}")
+        if source not in self.declared:
+            raise PolicyError(f"egress to undeclared source {source}")
+        mirror = mirror_base()
+        host = urllib.parse.urlsplit(url).hostname or ""
+        if mirror and url.startswith(mirror):
+            return url
+        allowed = set(SOURCES.get(source, {}).get("hosts", [])) | self.extra_hosts
+        if host not in allowed and not any(h.startswith("<") for h in allowed):
+            raise PolicyError(f"egress to undeclared host {host} for {source}")
+        return url
+
+    def explain(self) -> dict:
+        return {"sources": [{"id": s, "hosts": SOURCES.get(s, {}).get("hosts", [])} for s in self.declared],
+                "hosts": self.hosts(), "offline_ok": False}
+
+
+def mirror_base() -> str | None:
+    value = os.environ.get("MAGGIE_SECURITY_MIRROR", "").strip().rstrip("/")
+    return value or None
+
+
+def mirrored(url: str) -> str:
+    base = mirror_base()
+    if not base:
+        return url
+    parts = urllib.parse.urlsplit(url)
+    return f"{base}/{parts.hostname}{parts.path}" + (f"?{parts.query}" if parts.query else "")
+
+
+@contextlib.contextmanager
+def socket_guard():
+    """Make any socket connection raise; used by --offline and the tests."""
+    original_connect = socket.socket.connect
+    original_create = socket.create_connection
+
+    def refuse(*_args, **_kwargs):
+        raise OSError("network disabled by maggie security --offline")
+
+    socket.socket.connect = refuse  # type: ignore[assignment]
+    socket.create_connection = refuse  # type: ignore[assignment]
+    try:
+        yield
+    finally:
+        socket.socket.connect = original_connect  # type: ignore[assignment]
+        socket.create_connection = original_create  # type: ignore[assignment]
+
+
+def http_request(url: str, *, method: str = "GET", data: bytes | None = None, headers: dict | None = None,
+                 timeout: float = 60.0, retries: int = 2) -> tuple[int, dict, bytes]:
+    """Plain HTTP with retries and backoff; returns (status, headers, body). 304 is not an error."""
+    if url.startswith("file://"):
+        local = Path(urllib.parse.unquote(urllib.parse.urlsplit(url).path))
+        if method != "GET":
+            return 404, {}, b""
+        return (200, {}, local.read_bytes()) if local.is_file() else (404, {}, b"")
+    hdrs = {"User-Agent": USER_AGENT, "Accept": "application/json, text/plain, */*"}
+    hdrs.update(headers or {})
+    last: Exception | None = None
+    for attempt in range(retries + 1):
+        request = urllib.request.Request(url, data=data, headers=hdrs, method=method)
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                return response.status, {k.lower(): v for k, v in response.headers.items()}, response.read()
+        except urllib.error.HTTPError as error:
+            if error.code == 304:
+                return 304, {k.lower(): v for k, v in error.headers.items()}, b""
+            if error.code in (404, 410):
+                return error.code, {k.lower(): v for k, v in (error.headers or {}).items()}, b""
+            last = error
+            if error.code < 500 and error.code != 429:
+                break
+        except (urllib.error.URLError, TimeoutError, OSError) as error:
+            last = error
+        if attempt < retries:
+            time.sleep(min(2 ** attempt, 8) * float(os.environ.get("MAGGIE_SECURITY_BACKOFF", "1")))
+    raise DegradedError(f"{urllib.parse.urlsplit(url).hostname}: {last}")
+
+
+class FeedCache:
+    """Cached feed payloads under .maggie/security/feeds/<source>/ (PRD 00 section 10)."""
+
+    def __init__(self, state: State, guard: EgressGuard) -> None:
+        self.state = state
+        self.guard = guard
+        self.report: list[dict] = []
+        self._lock = threading.RLock()  # commands fetch in parallel; state.json is read-modify-write
+
+    def _dir(self, source: str) -> Path:
+        return self.state.path("feeds", source)
+
+    def _key(self, url: str) -> str:
+        return sha256_bytes(url.encode())[:16]
+
+    def meta(self, source: str) -> dict:
+        path = self._dir(source) / "state.json"
+        return read_json(path) if path.is_file() else {"entries": {}}
+
+    def save_meta(self, source: str, meta: dict) -> None:
+        with self._lock:
+            write_json(self._dir(source) / "state.json", meta)
+
+    def _update_entry(self, source: str, key: str, entry: dict) -> None:
+        with self._lock:
+            meta = self.meta(source)
+            meta["entries"][key] = entry
+            self.save_meta(source, meta)
+
+    def cursor(self, source: str) -> str | None:
+        return self.meta(source).get("cursor")
+
+    def set_cursor(self, source: str, cursor: str | None) -> None:
+        with self._lock:
+            meta = self.meta(source)
+            meta["cursor"] = cursor
+            self.save_meta(source, meta)
+
+    def _note(self, source: str, status: str, fetched_at: str | None = None, error: str | None = None, version: str | None = None) -> None:
+        with self._lock:
+            self._note_locked(source, status, fetched_at, error, version)
+
+    def _note_locked(self, source: str, status: str, fetched_at: str | None, error: str | None, version: str | None) -> None:
+        for item in self.report:
+            if item["id"] == source:
+                if status == "degraded" or item["status"] != "degraded":
+                    item.update(status=status, fetched_at=fetched_at or item.get("fetched_at"), error=error or item.get("error"))
+                return
+        self.report.append({"id": source, "status": status, "fetched_at": fetched_at, "error": error, "version": version,
+                            "cursor": self.cursor(source)})
+
+    def get(self, source: str, url: str, *, ttl: str | None = None, method: str = "GET", body: bytes | None = None,
+            headers: dict | None = None, key: str | None = None, allow_stale: bool = True) -> bytes | None:
+        """Return the payload (fresh, revalidated or cached); None when unavailable."""
+        ttl_delta = parse_duration(ttl or SOURCES.get(source, {}).get("ttl", "1h"))
+        meta = self.meta(source)
+        entry_key = key or self._key(url + (sha256_bytes(body) if body else ""))
+        entry = meta["entries"].get(entry_key)
+        payload_path = self._dir(source) / f"{entry_key}.bin"
+        now = utcnow()
+        if entry and payload_path.is_file() and ttl_delta.total_seconds() > 0 \
+                and now - parse_time(entry["fetched_at"]) < ttl_delta:
+            self._note(source, "cached", entry["fetched_at"])
+            return payload_path.read_bytes()
+        try:
+            real_url = mirrored(url)
+            self.guard.check(source, real_url)
+            hdrs = dict(headers or {})
+            if entry and payload_path.is_file() and method == "GET":
+                if entry.get("etag"):
+                    hdrs["If-None-Match"] = entry["etag"]
+                if entry.get("last_modified"):
+                    hdrs["If-Modified-Since"] = entry["last_modified"]
+            status, resp_headers, data = http_request(real_url, method=method, data=body, headers=hdrs)
+            if status == 304 and payload_path.is_file():
+                entry["fetched_at"] = iso(now)
+                self._update_entry(source, entry_key, entry)
+                self._note(source, "ok", iso(now))
+                return payload_path.read_bytes()
+            if status in (404, 410):
+                self._note(source, "ok", iso(now))
+                return None
+            payload_path.parent.mkdir(parents=True, exist_ok=True)
+            tmp_payload = payload_path.with_suffix(f".{threading.get_ident()}.tmp")
+            tmp_payload.write_bytes(data)
+            tmp_payload.replace(payload_path)
+            self._update_entry(source, entry_key, {"url": url, "fetched_at": iso(now), "etag": resp_headers.get("etag"),
+                                                   "last_modified": resp_headers.get("last-modified"), "bytes": len(data)})
+            self._note(source, "ok", iso(now))
+            return data
+        except DegradedError as error:
+            if allow_stale and payload_path.is_file() and entry:
+                self._note(source, "degraded", entry.get("fetched_at"), f"{error} (using cache from {entry.get('fetched_at')})")
+                return payload_path.read_bytes()
+            self._note(source, "degraded", None, str(error))
+            return None
+
+    def get_json(self, source: str, url: str, **kwargs: Any) -> Any:
+        data = self.get(source, url, **kwargs)
+        if data is None:
+            return None
+        try:
+            return json.loads(data.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            self._note(source, "degraded", None, f"unparseable payload: {error}")
+            return None
+
+    def status(self) -> list[dict]:
+        out = []
+        root = self.state.path("feeds")
+        for source, spec in SOURCES.items():
+            if spec.get("hosts", [""])[0].startswith("<"):
+                continue
+            meta = self.meta(source) if (root / source).is_dir() else {"entries": {}}
+            entries = meta.get("entries", {})
+            newest = max((e["fetched_at"] for e in entries.values()), default=None)
+            ttl = parse_duration(spec["ttl"])
+            stale = None
+            if newest and ttl.total_seconds() > 0:
+                stale = (utcnow() - parse_time(newest)) > ttl * 3
+            out.append({"id": source, "entries": len(entries), "fetched_at": newest, "cursor": meta.get("cursor"),
+                        "ttl": spec["ttl"], "stale": stale})
+        return out
+
+    def verify(self) -> list[dict]:
+        problems = []
+        root = self.state.path("feeds")
+        if not root.is_dir():
+            return problems
+        for source_dir in sorted(p for p in root.iterdir() if p.is_dir()):
+            meta = self.meta(source_dir.name)
+            for key, entry in meta.get("entries", {}).items():
+                payload = source_dir / f"{key}.bin"
+                if not payload.is_file():
+                    problems.append({"source": source_dir.name, "key": key, "problem": "payload missing"})
+                    continue
+                if payload.stat().st_size and payload.read_bytes()[:1] in (b"{", b"["):
+                    try:
+                        json.loads(payload.read_text(encoding="utf-8"))
+                    except (ValueError, UnicodeDecodeError):
+                        problems.append({"source": source_dir.name, "key": key, "problem": "invalid JSON"})
+        for item in self.status():
+            if item["stale"]:
+                problems.append({"source": item["id"], "problem": f"older than 3x TTL ({item['ttl']})"})
+        return problems
+
+
+# --------------------------------------------------------------------------- tool lock and runner
+
+
+def packaged_lock_path() -> Path:
+    return DATA_DIR / "tools.lock.json"
+
+
+def load_lock(state: State | None = None) -> dict:
+    """The project copy if present (written by tools install), else the packaged lock."""
+    if state is not None:
+        local = state.path("tools.lock.json")
+        if local.is_file():
+            return read_json(local)
+    return read_json(packaged_lock_path())
+
+
+def platform_key() -> str:
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    arch = {"x86_64": "amd64", "amd64": "amd64", "aarch64": "arm64", "arm64": "arm64"}.get(machine, machine)
+    return f"{system}-{arch}"
+
+
+def tools_cache_dir() -> Path:
+    base = os.environ.get("MAGGIE_SECURITY_TOOLS_DIR")
+    if base:
+        return Path(base)
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    return (Path(xdg) if xdg else Path.home() / ".cache") / "maggie" / "security-tools"
+
+
+def tool_install_path(name: str, spec: dict) -> Path:
+    return tools_cache_dir() / name / spec["version"] / (spec.get("binary") or name)
+
+
+def resolve_tool(name: str, lock: dict) -> tuple[dict, Path | None, str]:
+    """Return (spec, path, how) where how is 'pinned', 'system' or 'missing'."""
+    spec = (lock.get("tools") or {}).get(name)
+    if not spec:
+        raise UsageError(f"tool {name} is not in the tools lock")
+    pinned = tool_install_path(name, spec)
+    if pinned.is_file():
+        return spec, pinned, "pinned"
+    if spec.get("class") == "external-only" or not spec.get("assets"):
+        found = shutil.which(spec.get("binary") or name)
+        if found:
+            return spec, Path(found), "system"
+    return spec, None, "missing"
+
+
+def check_flags(spec: dict, args: list[str]) -> list[str]:
+    """Refuse forbidden flags (exit 4) and inject required ones."""
+    forbidden = set(spec.get("forbidden_flags") or [])
+    for arg in args:
+        flag = arg.split("=", 1)[0]
+        bare = flag.lstrip("-")
+        if flag in forbidden or bare in forbidden or f"-{bare}" in forbidden or f"--{bare}" in forbidden:
+            raise PolicyError(f"flag {flag} is forbidden for {spec.get('binary') or 'this tool'} by the tools lock")
+    required = [f for f in spec.get("required_flags") or [] if f not in args]
+    if spec.get("flags_after_subcommand") and args and not args[0].startswith("-"):
+        return [args[0]] + required + list(args[1:])  # e.g. `semgrep scan --metrics=off …`
+    return required + list(args)
+
+
+def verify_tool(name: str, lock: dict) -> dict:
+    spec, path, how = resolve_tool(name, lock)
+    result = {"tool": name, "version": spec["version"], "class": spec["class"], "how": how, "path": str(path) if path else None,
+              "ok": False, "problem": None}
+    if path is None:
+        result["problem"] = "not installed (run: maggie security tools install --tool %s)" % name
+        return result
+    if how == "pinned":
+        asset = (spec.get("assets") or {}).get(platform_key()) or {}
+        expected = asset.get("binary_sha256") or asset.get("sha256")
+        marker = path.parent / ".sha256"
+        recorded = marker.read_text(encoding="utf-8").strip() if marker.is_file() else None
+        actual = sha256_file(path)
+        if recorded and recorded != actual:
+            result["problem"] = f"sha256 mismatch: binary changed since install ({actual[:12]}…)"
+            return result
+        if not recorded and expected and expected != "UNPINNED" and expected != actual:
+            result["problem"] = f"sha256 mismatch: expected {expected[:12]}…, got {actual[:12]}…"
+            return result
+    result["ok"] = True
+    return result
+
+
+def run_tool(name: str, args: list[str], lock: dict, *, timeout: int = 900, cwd: Path | None = None,
+             stdin: bytes | None = None, env: dict | None = None) -> subprocess.CompletedProcess:
+    """Run a pinned external tool after checksum and flag checks. Never via a shell."""
+    spec, path, how = resolve_tool(name, lock)
+    if path is None:
+        if spec.get("class") == "external-only" or not spec.get("assets"):
+            raise ToolError(f"{name} is not installed. {spec.get('notes') or 'Install it with your package manager'} "
+                            f"(version {spec['version']}; Maggie runs it as a separate program)")
+        raise ToolError(f"{name} is not installed; run: maggie security tools install --tool {name}")
+    verdict = verify_tool(name, lock)
+    if not verdict["ok"]:
+        raise ToolError(f"{name}: {verdict['problem']}")
+    argv = [str(path)] + check_flags(spec, args)
+    full_env = {**os.environ, **(spec.get("env") or {}), **(env or {})}
+    try:
+        return subprocess.run(argv, cwd=str(cwd) if cwd else None, input=stdin, capture_output=True, timeout=timeout, env=full_env, check=False)
+    except subprocess.TimeoutExpired as error:
+        raise DegradedError(f"{name} timed out after {timeout}s") from error
+
+
+def install_tool(name: str, lock: dict, guard: EgressGuard) -> dict:
+    spec = (lock.get("tools") or {}).get(name)
+    if not spec:
+        raise UsageError(f"tool {name} is not in the tools lock")
+    if spec.get("class") == "reference-only":
+        raise PolicyError(f"{name} is reference-only: Maggie does not run it")
+    asset = (spec.get("assets") or {}).get(platform_key())
+    if not asset:
+        if spec.get("class") == "external-only" or not spec.get("assets"):
+            found = shutil.which(spec.get("binary") or name)
+            return {"tool": name, "installed": bool(found), "how": "system" if found else "missing",
+                    "note": spec.get("notes") or "install it with your OS package manager; Maggie calls it as a separate process"}
+        raise ToolError(f"{name} has no pinned asset for {platform_key()}")
+    if asset["sha256"] == "UNPINNED":
+        raise ToolError(f"{name} {spec['version']} has no pinned sha256 for {platform_key()} yet; refusing to install an unverified binary")
+    url = mirrored(asset["url"])
+    guard.check("github-releases", url)
+    status, _headers, data = http_request(url, timeout=300)
+    if status != 200:
+        raise DegradedError(f"download failed: HTTP {status}")
+    actual = sha256_bytes(data)
+    if actual != asset["sha256"]:
+        raise ToolError(f"{name}: download sha256 {actual[:12]}… does not match the lock {asset['sha256'][:12]}…")
+    target = tool_install_path(name, spec)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    archive = asset.get("archive", "none")
+    member = asset.get("member") or spec.get("binary") or name
+    if archive == "none":
+        target.write_bytes(data)
+    elif archive == "tar.gz":
+        with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as tar:
+            match = next((m for m in tar.getmembers() if m.isfile() and (m.name == member or m.name.endswith("/" + member))), None)
+            if match is None:
+                raise ToolError(f"{member} not found in archive")
+            extracted = tar.extractfile(match)
+            target.write_bytes(extracted.read() if extracted else b"")
+    elif archive == "zip":
+        with zipfile.ZipFile(io.BytesIO(data)) as zf:
+            match = next((n for n in zf.namelist() if n == member or n.endswith("/" + member)), None)
+            if match is None:
+                raise ToolError(f"{member} not found in archive")
+            target.write_bytes(zf.read(match))
+    target.chmod(target.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    (target.parent / ".sha256").write_text(sha256_file(target) + "\n", encoding="utf-8")
+    return {"tool": name, "installed": True, "how": "pinned", "path": str(target), "version": spec["version"]}
+
+
+# --------------------------------------------------------------------------- output
+
+
+def exit_code_for(findings_doc: dict, fail_on: str | None) -> int:
+    if fail_on in (None, "never", "none"):
+        threshold = None
+    elif fail_on in SEVERITIES:
+        threshold = SEVERITIES.index(fail_on)
+    else:
+        raise UsageError(f"--fail-on must be one of {', '.join(SEVERITIES)} or never")
+    if threshold is not None:
+        for finding in findings_doc.get("findings", []):
+            if finding.get("status") in ("new", "open") and SEVERITIES.index(finding["severity"]) <= threshold:
+                return EXIT_FINDINGS
+    if findings_doc.get("run", {}).get("refused"):
+        return EXIT_POLICY
+    if findings_doc.get("run", {}).get("degraded"):
+        return EXIT_DEGRADED
+    return EXIT_OK
+
+
+SARIF_LEVEL = {"critical": "error", "high": "error", "medium": "warning", "low": "note", "info": "note"}
+
+
+def to_sarif(doc: dict) -> dict:
+    rules: dict[str, dict] = {}
+    results = []
+    for finding in doc.get("findings", []):
+        rule_id = finding["source"].get("rule_id") or finding["id"]
+        rules.setdefault(rule_id, {"id": rule_id, "shortDescription": {"text": finding["title"][:200]},
+                                   "properties": {"security-severity": str((finding.get("cvss") or {}).get("score") or
+                                                                           {"critical": 9.5, "high": 8.0, "medium": 5.5, "low": 3.0, "info": 0.0}[finding["severity"]])}})
+        location = {}
+        evidence = (finding.get("evidence") or [{}])[0]
+        path = evidence.get("path") or finding["target"].get("path")
+        if path:
+            location = {"physicalLocation": {"artifactLocation": {"uri": path}}}
+            if evidence.get("line"):
+                location["physicalLocation"]["region"] = {"startLine": int(evidence["line"])}
+        result = {"ruleId": rule_id, "level": SARIF_LEVEL[finding["severity"]],
+                  "message": {"text": f"{finding['title']} [{finding['priority']}, {finding['status']}]"},
+                  "partialFingerprints": {"maggieFinding": finding["id"]}}
+        if location:
+            result["locations"] = [location]
+        results.append(result)
+    return {"version": "2.1.0", "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+            "runs": [{"tool": {"driver": {"name": "maggie-security", "version": doc["run"].get("maggie_version", ""),
+                                          "informationUri": "https://cmo.so", "rules": list(rules.values())}},
+                      "results": results}]}
+
+
+PRIORITY_FOOTER = ("Priority: p0 = exploited in the wild (KEV) on an internet-facing component, a confirmed secret in a public file, "
+                   "or a compromise indicator; p1 = critical, or high with EPSS >= 0.1, or an internet-facing runtime past end of life; "
+                   "p2 = high, or medium with a fix on a direct dependency, or EOL within 30 days; p3 = medium/low, EOL within 90 days, "
+                   "hardening; p4 = info, unconfirmed or dev-only.")
+
+
+def to_markdown(doc: dict, title: str | None = None) -> str:
+    run = doc["run"]
+    lines = [f"# {title or 'Maggie security: ' + run['command']}", "",
+             f"Site: `{run.get('site') or '-'}` · run `{run['id']}` · {run['finished_at']}", ""]
+    summary = doc["summary"]
+    lines.append(f"**{summary['new']} new**, {summary['open']} open, {summary['fixed']} fixed. "
+                 + ", ".join(f"{k}: {v}" for k, v in summary["by_severity"].items() if v))
+    if run.get("degraded"):
+        lines += ["", f"> Incomplete: {', '.join(run['degraded'])} could not be checked. Nothing was marked fixed."]
+    if run.get("refused"):
+        lines += ["", f"> Refused by policy: {'; '.join(run['refused'])}"]
+    lines.append("")
+    if not doc["findings"]:
+        lines += ["No findings.", ""]
+    for finding in doc["findings"]:
+        marker = " (new)" if finding["status"] == "new" else ""
+        lines.append(f"## [{finding['priority']}] {finding['title']}{marker}")
+        lines.append("")
+        facts = [f"severity {finding['severity']}", f"confidence {finding['confidence']}"]
+        if (finding.get("kev") or {}).get("listed"):
+            facts.append("**actively exploited (CISA KEV)**")
+        if finding.get("epss"):
+            facts.append(f"EPSS {finding['epss'].get('score')}")
+        if finding.get("aliases"):
+            facts.append(", ".join(finding["aliases"][:4]))
+        lines.append("- " + " · ".join(facts))
+        affected = finding.get("affected") or {}
+        if affected:
+            lines.append(f"- Affects `{affected.get('name')}` {affected.get('version') or ''}".rstrip())
+        target = {k: v for k, v in (finding.get("target") or {}).items() if v and k != "site"}
+        if target:
+            lines.append("- Where: " + ", ".join(f"{k} `{v}`" for k, v in target.items()))
+        signal = finding.get("signal")
+        if signal:
+            label = "attack attempts (not a compromise)" if signal.get("type") == "attempt" else "possible compromise indicator"
+            lines.append(f"- Signal: {signal.get('count')} {label} in {signal.get('window')}")
+        remediation = finding.get("remediation") or {}
+        if remediation.get("summary"):
+            lines.append(f"- Fix: {remediation['summary']}")
+        for step in remediation.get("steps") or []:
+            lines.append(f"  - {step}")
+        if finding.get("asvs_ids"):
+            lines.append(f"- ASVS: {', '.join(finding['asvs_ids'])}")
+        lines.append("")
+    if doc["clipped"]["findings"]:
+        lines += [f"_Showing {len(doc['findings'])} of {doc['clipped']['total']} findings._", ""]
+    lines += ["---", "", PRIORITY_FOOTER, ""]
+    return "\n".join(lines)
+
+
+def to_text(doc: dict) -> str:
+    run = doc["run"]
+    summary = doc["summary"]
+    out = [f"maggie security {run['command']}: {summary['new']} new, {summary['open']} open, {summary['fixed']} fixed"
+           + (f" (degraded: {', '.join(run['degraded'])})" if run.get("degraded") else "")]
+    for finding in doc["findings"]:
+        out.append(f"  {finding['priority']} {finding['severity']:<8} {finding['status']:<14} {finding['title']}")
+    if doc["clipped"]["findings"]:
+        out.append(f"  … {doc['clipped']['total'] - len(doc['findings'])} more (raise --max-items)")
+    return "\n".join(out)
+
+
+def render(doc: dict, fmt: str) -> str:
+    if fmt == "json":
+        return json.dumps(doc, indent=2, ensure_ascii=False)
+    if fmt == "sarif":
+        return json.dumps(to_sarif(doc), indent=2, ensure_ascii=False)
+    if fmt == "md":
+        return to_markdown(doc)
+    return to_text(doc)
+
+
+def common_parent() -> argparse.ArgumentParser:
+    parent = argparse.ArgumentParser(add_help=False)
+    parent.add_argument("--project", type=Path, default=Path("."), help="site project root (state in PATH/.maggie/security)")
+    parent.add_argument("--site", help="site id recorded on findings")
+    parent.add_argument("--format", choices=["json", "sarif", "md", "text"], help="output format (default: text on a TTY, else json)")
+    parent.add_argument("--output", type=Path, help="also write the findings set to this file")
+    parent.add_argument("--fail-on", help="exit 1 when a new/open finding is at or above this severity (default: high with --ci, else never)")
+    parent.add_argument("--ci", action="store_true", help="non-interactive: SARIF output and --fail-on high unless set")
+    parent.add_argument("--offline", action="store_true", help="no network; cache and mirror only")
+    parent.add_argument("--since", help="lookback for feed/log commands, e.g. 24h, 7d")
+    parent.add_argument("--max-items", type=int, default=200, help="clip the findings list")
+    parent.add_argument("--no-ledger", action="store_true", help="do not read or write the ledger")
+    parent.add_argument("--explain-egress", action="store_true", help="print every host this command would contact and exit")
+    return parent
+
+
+def output_format(args: argparse.Namespace) -> str:
+    if args.format:
+        return args.format
+    if getattr(args, "ci", False):
+        return "sarif"
+    return "text" if sys.stdout.isatty() else "json"
+
+
+def fail_threshold(args: argparse.Namespace) -> str | None:
+    if args.fail_on:
+        return args.fail_on
+    return "high" if getattr(args, "ci", False) else None
+
+
+@dataclass
+class Context:
+    """What a command needs: parsed args, state, guard, cache, lock."""
+
+    args: argparse.Namespace
+    command: str
+    sources: list[str]
+
+    def __post_init__(self) -> None:
+        self.project = Path(self.args.project).resolve()
+        self.state = State(self.project)
+        self.site = site_id(self.project, getattr(self.args, "site", None))
+        self.guard = EgressGuard(self.sources, offline=getattr(self.args, "offline", False))
+        self.cache = FeedCache(self.state, self.guard)
+        self.run = new_run(self.command, self.site, {})
+        self._lock: dict | None = None
+
+    @property
+    def lock(self) -> dict:
+        if self._lock is None:
+            self._lock = load_lock(self.state)
+        return self._lock
+
+    def degrade(self, source: str, error: str) -> None:
+        if source not in self.run["degraded"]:
+            self.run["degraded"].append(source)
+        if not any(s["id"] == source for s in self.run["sources"]):
+            self.run["sources"].append({"id": source, "status": "degraded", "error": error})
+
+    def refuse(self, reason: str) -> None:
+        self.run["refused"].append(reason)
+
+    def finish(self, findings: list[dict], covered: Iterable[str] = ()) -> dict:
+        """Merge, apply the ledger, write runs/<id>.json and return the findings set."""
+        for item in self.cache.report:
+            existing = next((s for s in self.run["sources"] if s["id"] == item["id"]), None)
+            if existing:
+                existing.update({k: v for k, v in item.items() if v is not None})
+            else:
+                self.run["sources"].append({k: v for k, v in item.items()})
+            if item["status"] == "degraded" and item["id"] not in self.run["degraded"]:
+                self.run["degraded"].append(item["id"])
+        self.run["covered"] = sorted(set(covered))
+        merged = merge_findings(findings)
+        fixed: list[str] = []
+        if not getattr(self.args, "no_ledger", False):
+            merged, fixed = Ledger(self.state.path("ledger.jsonl")).apply_run(merged, self.run)
+        doc = findings_set(self.run, merged, max_items=getattr(self.args, "max_items", 200), fixed_ids=fixed)
+        if not getattr(self.args, "no_ledger", False):
+            write_json(self.state.path("runs", f"{self.run['id'].replace(':', '')}.json"), doc)
+        return doc
+
+
+def emit(ctx: Context, doc: dict) -> int:
+    fmt = output_format(ctx.args)
+    text = render(doc, fmt)
+    print(text)
+    if getattr(ctx.args, "output", None):
+        out: Path = ctx.args.output
+        out.parent.mkdir(parents=True, exist_ok=True)
+        if out.suffix == ".md":
+            out.write_text(to_markdown(doc), encoding="utf-8")
+        elif out.suffix == ".sarif":
+            out.write_text(json.dumps(to_sarif(doc), indent=2) + "\n", encoding="utf-8")
+        else:
+            out.write_text(json.dumps(doc, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    return exit_code_for(doc, fail_threshold(ctx.args))
+
+
+def explain_egress(sources: list[str], command: str) -> int:
+    guard = EgressGuard(sources)
+    print(json.dumps({"command": command, **guard.explain(),
+                      "never_sent": ["lockfile contents beyond package name+version to OSV", "source code", "logs", "host evidence",
+                                     "secrets", "findings"]}, indent=2))
+    return EXIT_OK
+
+
+# --------------------------------------------------------------------------- commands and site detection
+
+
+@dataclass
+class Command:
+    """One ``maggie security <name>`` command contributed by an area module."""
+
+    name: str
+    help: str
+    sources: list[str]
+    configure: Callable[[argparse.ArgumentParser], None]
+    run: Callable[["Context"], Any]
+    findings: bool = True  # False: the command prints its own JSON (doctor, tools, feeds…)
+    routine_safe: bool = True
+
+
+def detect_site_type(project: Path) -> str:
+    """Best guess from files on disk: wordpress, astro, workers, node-app, php-app, static, unknown."""
+    if (project / "wp-config.php").is_file() or (project / "wp-content").is_dir() or (project / "wp-includes").is_dir():
+        return "wordpress"
+    package = project / "package.json"
+    deps: dict = {}
+    if package.is_file():
+        with contextlib.suppress(UsageError, AttributeError):
+            data = read_json(package)
+            deps = {**(data.get("dependencies") or {}), **(data.get("devDependencies") or {})}
+    if any((project / name).is_file() for name in ("wrangler.toml", "wrangler.json", "wrangler.jsonc")) and not (project / "Dockerfile").is_file():
+        return "workers"
+    if "astro" in deps:
+        return "astro"
+    if package.is_file():
+        return "node-app"
+    if (project / "composer.json").is_file() or any(project.glob("*.php")):
+        return "php-app"
+    if any((project / n).is_file() for n in ("pyproject.toml", "requirements.txt", "Pipfile", "poetry.lock", "uv.lock", "setup.py", "manage.py")):
+        return "python-app"
+    if any((project / n).is_file() for n in ("pom.xml", "build.gradle", "build.gradle.kts", "gradle.lockfile")):
+        return "java-app"
+    if (project / "go.mod").is_file():
+        return "go-app"
+    if (project / "Gemfile").is_file() or (project / "Gemfile.lock").is_file():
+        return "ruby-app"
+    if any(project.glob("*.csproj")) or any(project.glob("*.sln")):
+        return "dotnet-app"
+    if (project / "index.html").is_file() or (project / "dist").is_dir() or (project / "public").is_dir():
+        return "static"
+    return "unknown"
+
+
+# Which command families make sense per site type (doctor prints this; PRD 12 site-type matrix).
+APPLICABLE = {
+    "wordpress": ["inventory", "vuln-watch", "wp-check", "eol-watch", "osv-query", "secrets", "headers", "tls", "web-scan",
+                  "logs-traffic", "logs-sigma", "host-quick", "host-audit", "host-nginx-config", "protect-plan", "report"],
+    "node-app": ["inventory", "vuln-watch", "osv-query", "deps", "node-check", "eol-watch", "secrets", "code-scan", "headers",
+                 "tls", "web-scan", "logs-traffic", "host-quick", "protect-plan", "report"],
+    "php-app": ["inventory", "vuln-watch", "osv-query", "deps", "eol-watch", "secrets", "code-scan", "headers", "tls", "web-scan",
+                "logs-traffic", "logs-sigma", "host-quick", "host-nginx-config", "protect-plan", "report"],
+    "astro": ["inventory", "vuln-watch", "osv-query", "deps", "node-check", "eol-watch", "secrets", "code-scan", "headers", "tls", "report"],
+    "workers": ["inventory", "vuln-watch", "osv-query", "deps", "secrets", "code-scan", "headers", "tls", "report"],
+    "python-app": ["inventory", "vuln-watch", "osv-query", "deps", "eol-watch", "secrets", "code-scan", "headers", "tls", "web-scan",
+                   "logs-traffic", "host-quick", "protect-plan", "report"],
+    "java-app": ["inventory", "vuln-watch", "osv-query", "deps", "eol-watch", "secrets", "headers", "tls", "web-scan", "logs-traffic",
+                 "host-quick", "protect-plan", "report"],
+    "go-app": ["inventory", "vuln-watch", "osv-query", "deps", "eol-watch", "secrets", "headers", "tls", "web-scan", "host-quick", "report"],
+    "ruby-app": ["inventory", "vuln-watch", "osv-query", "deps", "eol-watch", "secrets", "headers", "tls", "web-scan", "host-quick", "report"],
+    "dotnet-app": ["inventory", "vuln-watch", "osv-query", "deps", "eol-watch", "secrets", "headers", "tls", "web-scan", "host-quick", "report"],
+    "static": ["inventory", "deps", "secrets", "headers", "tls", "report"],
+    "unknown": ["inventory", "deps", "secrets", "report"],
+}
+
+
+# --------------------------------------------------------------------------- consent (PRD 00 section 13.3)
+
+CONSENT_LEVELS = ["read-local", "read-public", "scan-owned", "ssh-read", "ssh-temp-write", "host-change", "third-party-verify"]
+IMPLICIT_CONSENT = {"read-local", "read-public"}
+
+
+def consents(state: State) -> list[dict]:
+    path = state.path("consent.json")
+    return (read_json(path).get("grants") or []) if path.is_file() else []
+
+
+def has_consent(state: State, host: str, level: str) -> bool:
+    if level in IMPLICIT_CONSENT:
+        return True
+    now = utcnow()
+    for grant in consents(state):
+        if grant.get("host") == host and grant.get("level") == level and not grant.get("revoked_at"):
+            if not grant.get("until") or parse_time(grant["until"]) > now:
+                return True
+    return False
+
+
+def require_consent(state: State, host: str, level: str) -> None:
+    if level == "host-change":
+        raise PolicyError("no security command changes a host; use protect-plan and run the plan yourself under host-lock")
+    if not has_consent(state, host, level):
+        raise PolicyError(f"no {level} consent for host {host}; grant it interactively with: "
+                          f"maggie security consent grant --host {host} --level {level}")