@topy-ai/maggie 0.7.55 → 0.7.56

package/bundled-tools/clis/maggie_security_report.py

@@ -0,0 +1,506 @@
+#!/usr/bin/env python3
+"""``maggie security report`` (docs/maggie-security/09-risk-report-standards-prd.md section 6.1).
+
+Combines the latest run per command and the ledger into one per-site report:
+Markdown for the owner (plain language) or a technical audience, plus a
+``maggie-security-report.v1`` JSON. Both are written to
+``.maggie/security/reports/``. The report passes the same checks as
+``maggie assistant report-check`` before anything is saved; ``--save`` writes
+the exact ``report_save`` payload for the agent or bridge to send (this CLI
+never holds CMO.so credentials).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+
+import maggie_security_core as core
+import maggie_security_versions as versions
+from maggie_assistant_tools import report_check
+
+BODY_LIMIT = 50000
+KIND_INBOX = {"weekly": "weekly", "daily_ops": "daily_ops", "incident": "agent", "gate": "agent"}
+JARGON = {
+    "CVE": "a public ID for a known security flaw",
+    "KEV": "CISA's list of flaws attackers are using right now",
+    "EOL": "end of life: no more security fixes",
+    "HSTS": "a header that makes browsers always use HTTPS",
+    "CSP": "a header that limits which scripts a page may run",
+    "WAF": "a filter that blocks common attacks before they reach the site",
+    "SRI": "a check that a script from another site was not changed",
+}
+FEAR_WORDS = re.compile(r"(?i)\b(critical breach|hacked|compromised|catastrophic)\b")
+# Which command families a profile expects to have run (PRD 09 "What we checked").
+EXPECTED = {
+    "wordpress": ["vuln-watch", "wp-check", "eol-watch", "secrets", "headers", "tls", "host-quick", "logs-traffic"],
+    "node-app": ["vuln-watch", "deps", "eol-watch", "secrets", "headers", "tls"],
+    "php-app": ["vuln-watch", "deps", "eol-watch", "secrets", "headers", "tls", "host-quick"],
+    "astro": ["vuln-watch", "deps", "secrets", "headers", "tls"], "workers": ["vuln-watch", "deps", "secrets", "headers", "tls"],
+    "python-app": ["vuln-watch", "deps", "eol-watch", "secrets", "headers", "tls"], "java-app": ["vuln-watch", "deps", "eol-watch", "secrets", "headers", "tls"],
+    "go-app": ["vuln-watch", "deps", "eol-watch", "secrets", "headers", "tls"], "ruby-app": ["vuln-watch", "deps", "eol-watch", "secrets", "headers", "tls"],
+    "dotnet-app": ["vuln-watch", "deps", "eol-watch", "secrets", "headers", "tls"],
+    "static": ["vuln-watch", "secrets", "headers", "tls"], "unknown": ["vuln-watch", "deps", "secrets"],
+}
+AREA_LABEL = {"vuln-watch": "Vulnerabilities in your software", "wp-check": "WordPress core, plugins and themes", "eol-watch": "Software past end of life",
+              "deps": "Code dependencies", "secrets": "Passwords and keys in code", "headers": "Website security headers", "tls": "HTTPS setup",
+              "host-quick": "Server", "logs-traffic": "Traffic and attacks", "code-scan": "Code patterns", "web-scan": "Known website exposures",
+              "osv-query": "Package lookups", "node-check": "Node.js", "logs-sigma": "Attack patterns in logs", "host-audit": "Server hardening"}
+
+
+def latest_runs(state: core.State, since: str | None, run_ids: list[str] | None) -> list[dict]:
+    runs_dir = state.path("runs")
+    if not runs_dir.is_dir():
+        return []
+    docs = []
+    for path in sorted(runs_dir.glob("*.json")):
+        try:
+            docs.append(json.loads(path.read_text(encoding="utf-8")))
+        except (ValueError, OSError):
+            continue
+    if run_ids:
+        return [d for d in docs if d["run"]["id"] in run_ids]
+    floor = core.utcnow() - core.parse_duration(since) if since else None
+    latest: dict[str, dict] = {}
+    for doc in docs:
+        finished = core.parse_time(doc["run"]["finished_at"])
+        if floor and finished < floor:
+            continue
+        command = doc["run"]["command"]
+        if command in ("osv-query",):
+            continue
+        if command not in latest or core.parse_time(latest[command]["run"]["finished_at"]) <= finished:
+            latest[command] = doc
+    return list(latest.values())
+
+
+GATE_COMMANDS = ("deps", "secrets")
+
+
+def gate_decision(findings: list[dict], runs: list[dict]) -> dict:
+    """Pre-deploy gate (docs/maggie-security/12-workflows-prd.md section 7.3)."""
+    block, warn = [], []
+    ran = {d["run"]["command"]: d for d in runs}
+    for command in GATE_COMMANDS:
+        if command not in ran:
+            block.append({"reason": f"`maggie security {command}` did not run for this gate", "ids": []})
+        elif ran[command]["run"].get("degraded"):
+            block.append({"reason": f"`maggie security {command}` was incomplete ({', '.join(ran[command]['run']['degraded'])}); "
+                                    "a gate that silently skipped is worse than none", "ids": []})
+    active = [f for f in findings if f["status"] in ("new", "open")]
+    secrets = [f for f in active if f["kind"] == "secret" and f["severity"] in ("critical", "high")
+               and any(not e.get("commit") for e in f.get("evidence") or [{}])]
+    if secrets:
+        block.append({"reason": "secrets in tracked files or build output: rotate and remove them (no override)", "ids": [f["id"] for f in secrets]})
+    serious = [f for f in active if f["kind"] in ("vulnerability", "malicious-package") and f["severity"] in ("critical", "high")]
+    runtime_fixable = [f for f in serious if (f.get("affected") or {}).get("scope") != "dev" and ((f.get("fix") or {}).get("available") or f["kind"] == "malicious-package")]
+    if runtime_fixable:
+        block.append({"reason": "critical/high vulnerabilities with a fix available: upgrade, or record an accepted risk with "
+                                "`maggie security ledger accept --id … --reason …`", "ids": [f["id"] for f in runtime_fixable]})
+    no_fix = [f for f in serious if (f.get("affected") or {}).get("scope") != "dev" and not (f.get("fix") or {}).get("available") and f not in runtime_fixable]
+    if no_fix:
+        warn.append({"reason": "critical/high vulnerabilities without a fix: give a reason in the release notes", "ids": [f["id"] for f in no_fix]})
+    dev = [f for f in serious if (f.get("affected") or {}).get("scope") == "dev"]
+    if dev:
+        warn.append({"reason": "dev-only dependencies with known flaws", "ids": [f["id"] for f in dev]})
+    decision = "block" if block else "warn" if warn else "pass"
+    return {"decision": decision, "block": block, "warn": warn, "checked": sorted(ran)}
+
+
+def last_report_time(state: core.State) -> str | None:
+    index = state.path("reports", "index.jsonl")
+    if not index.is_file():
+        return None
+    lines = [json.loads(l) for l in index.read_text(encoding="utf-8").splitlines() if l.strip()]
+    return lines[-1]["at"] if lines else None
+
+
+def verdict(p0: int, p1: int, compromise: bool) -> dict:
+    if compromise:
+        return {"code": "possible-break-in", "text": "Something in your logs looks like a possible break-in. Check it now (first section)."}
+    if p0:
+        return {"code": "act-today", "text": f"{p0 + p1} thing{'s' if p0 + p1 != 1 else ''} to do, {p0} of them today. No sign that anyone got in."}
+    if p1:
+        return {"code": "act-this-week", "text": f"{p1} thing{'s' if p1 != 1 else ''} to do this week. No sign that anyone got in."}
+    return {"code": "nothing-urgent", "text": "Nothing needs doing this week."}
+
+
+def action_title(finding: dict) -> str:
+    affected = finding.get("affected") or {}
+    fix = finding.get("fix") or {}
+    name = affected.get("name") or ""
+    if finding["kind"] in ("vulnerability", "malicious-package") and fix.get("recommended"):
+        return f"Update {name} to {fix['recommended']}"
+    if finding["kind"] == "malicious-package":
+        return f"Remove {name} now"
+    if finding["kind"] == "eol":
+        return f"Plan the move off {name} {affected.get('version') or ''}".strip()
+    if finding["kind"] == "secret":
+        return "Revoke and replace the exposed key"
+    return finding["title"]
+
+
+def why(finding: dict) -> str:
+    kev = (finding.get("kev") or {}).get("listed")
+    kind = finding["kind"]
+    if kind == "malicious-package":
+        return "This package is known to be malicious."
+    if kind == "eol":
+        return "It no longer gets security fixes (EOL)."
+    if kind == "secret":
+        return "Anyone who sees the file can use this key."
+    if kev:
+        return "Attackers are already using this flaw (on the KEV list)."
+    severity = {"critical": "A serious", "high": "A serious", "medium": "A moderate", "low": "A minor", "info": "A minor"}[finding["severity"]]
+    return f"{severity} known flaw (CVE) affects the version you run."
+
+
+def how(finding: dict) -> str:
+    steps = (finding.get("remediation") or {}).get("steps") or []
+    step = next((s for s in steps if not s.startswith("Listed by CISA")), None)
+    return f"`{step}`" if step and len(step) < 120 else ((finding.get("remediation") or {}).get("summary") or "See details.")
+
+
+def group_actions(findings: list[dict]) -> list[dict]:
+    """One action per component: every vulnerability on the same package/runtime and host
+    becomes "Update X to <the version that fixes all of them>"."""
+    groups: dict[tuple, list[dict]] = {}
+    order: list[tuple] = []
+    for finding in findings:
+        affected = finding.get("affected") or {}
+        target = finding.get("target") or {}
+        if finding["kind"] in ("vulnerability",) and affected.get("name"):
+            key = ("vuln", affected.get("ecosystem"), affected["name"], target.get("host"), target.get("image"))
+        else:
+            key = ("single", finding["id"])
+        if key not in groups:
+            groups[key] = []
+            order.append(key)
+        groups[key].append(finding)
+    actions = []
+    for key in order:
+        items = core.sort_findings(groups[key])
+        lead = items[0]
+        if key[0] == "single" or len(items) == 1:
+            actions.append({"priority": lead["priority"], "title": action_title(lead), "why": why(lead), "how": how(lead),
+                            "ids": [lead["id"]], "count": 1, "lead": lead})
+            continue
+        affected = lead["affected"]
+        eco = affected.get("ecosystem")
+        fixes = [f["fix"]["recommended"] for f in items if (f.get("fix") or {}).get("recommended")]
+        unfixed = sum(1 for f in items if not (f.get("fix") or {}).get("recommended"))
+        target_version = max(fixes, key=versions.sort_key(eco)) if fixes else None
+        serious = sum(1 for f in items if f["severity"] in ("critical", "high"))
+        exploited = any((f.get("kev") or {}).get("listed") for f in items)
+        where = f" on {lead['target']['host']}" if (lead.get("target") or {}).get("host") else ""
+        if target_version and not unfixed:
+            title = f"Update {affected['name']}{where} to {target_version}"
+        elif target_version:
+            title = f"Update {affected['name']}{where} to {target_version} and plan a supported line ({unfixed} {'flaws have' if unfixed != 1 else 'flaw has'} no fix on this line)"
+        else:
+            title = f"Move {affected['name']} {affected.get('version') or ''}{where} to a supported line".replace("  ", " ")
+        reason = (f"{len(items)} known flaws (CVE) in the version you run, {serious} serious"
+                  + ("; attackers are using at least one (on the KEV list)." if exploited else "."))
+        step_from = next((f for f in items if (f.get("fix") or {}).get("recommended") == target_version), lead)
+        actions.append({"priority": lead["priority"], "title": title, "why": reason, "how": how(step_from),
+                        "ids": [f["id"] for f in items], "count": len(items), "lead": lead})
+    return sorted(actions, key=lambda a: (core.PRIORITIES.index(a["priority"]), -a["count"]))
+
+
+def explain_jargon(text: str, used: set[str]) -> str:
+    def sub(match: re.Match) -> str:
+        word = match.group(0)
+        if word in used:
+            return word
+        used.add(word)
+        return f"{word} ({JARGON[word]})"
+    return re.sub(r"\b(" + "|".join(JARGON) + r")\b", sub, text)
+
+
+def build(ctx: core.Context) -> dict:
+    args = ctx.args
+    since = args.since
+    if args.kind == "gate" and since in (None, "last-report"):
+        since = "6h"  # the gate reads this deploy's runs only
+    if since in (None, "last-report"):
+        last = last_report_time(ctx.state)
+        if last:
+            hours = max(1, int((core.utcnow() - core.parse_time(last)).total_seconds() // 3600) + 1)
+            since = f"{hours}h"
+        else:
+            since = "7d"
+    runs = latest_runs(ctx.state, since, args.runs)
+    if not runs:
+        raise core.UsageError(f"no security runs in the last {since}; run e.g. `maggie security vuln-watch` first")
+    ledger = core.Ledger(ctx.state.path("ledger.jsonl"))
+    history = ledger.history()
+    by_id: dict[str, dict] = {}
+    fixed_ids: set[str] = set()
+    for doc in sorted(runs, key=lambda d: d["run"]["finished_at"]):
+        for finding in doc.get("findings") or []:
+            by_id[finding["id"]] = finding
+        fixed_ids |= set(doc.get("fixed") or [])
+    merged = core.merge_findings(by_id.values())
+    floor = core.utcnow() - core.parse_duration(since)
+    findings = []
+    for finding in merged:
+        state = core.Ledger.derive(history.get(finding["id"], [])) if finding["id"] in history else None
+        status = (state or {}).get("status") or finding["status"]
+        if status == "fixed":
+            fixed_ids.add(finding["id"])
+            continue
+        first_seen = (state or {}).get("first_seen") or finding.get("first_seen")
+        finding = dict(finding, status="new" if first_seen and core.parse_time(first_seen) >= floor and status in ("new", "open") else status)
+        findings.append(finding)
+    findings = core.sort_findings(findings)
+    actionable = [f for f in findings if f["status"] in ("new", "open")]
+    grouped = group_actions([f for f in actionable if f["priority"] in ("p0", "p1")])
+    p0 = sum(1 for a in grouped if a["priority"] == "p0")
+    p1 = sum(1 for a in grouped if a["priority"] == "p1")
+    compromise = any((f.get("signal") or {}).get("type") == "compromise-indicator" for f in actionable)
+    verdict_info = verdict(p0, p1, compromise)
+    degraded = sorted({s for d in runs for s in d["run"].get("degraded") or []})
+    stack_path = ctx.state.path("inventory", "stack.json")
+    site_type = core.read_json(stack_path)["site"].get("type", "unknown") if stack_path.is_file() else core.detect_site_type(ctx.project)
+    checked = [{"command": d["run"]["command"], "last_run": d["run"]["finished_at"], "degraded": bool(d["run"].get("degraded"))}
+               for d in sorted(runs, key=lambda d: d["run"]["command"])]
+    ran = {c["command"] for c in checked}
+    import maggie_security
+
+    built = set(maggie_security.area_commands())
+    missing = [c for c in EXPECTED.get(site_type, EXPECTED["unknown"]) if c not in ran and c in built]
+    period = {"from": core.iso(floor), "to": core.iso()}
+    actions = [f for f in actionable if f["priority"] in ("p0", "p1")]
+    report_id = f"{core.iso()[:10]}-{args.kind}-{core.sha256_bytes(json.dumps(sorted(f['id'] for f in findings)).encode())[:6]}"
+    data = {
+        "schema": "maggie-security-report.v1", "id": report_id, "site": ctx.site, "kind": args.kind, "audience": args.audience, "period": period,
+        "verdict": verdict_info,
+        "counts": {"new": sum(1 for f in findings if f["status"] == "new"), "open": sum(1 for f in findings if f["status"] == "open"),
+                   "fixed": len(fixed_ids), "by_priority": {p: sum(1 for f in actionable if f["priority"] == p) for p in core.PRIORITIES}},
+        "actions": [{"finding_id": a["ids"][0], "finding_ids": a["ids"], "priority": a["priority"], "title": a["title"]}
+                    for a in group_actions(actions)[:5]],
+        "coverage": None,
+        "checked": checked, "not_checked": missing, "degraded_sources": degraded,
+        "runs": [d["run"]["id"] for d in runs], "findings": [f["id"] for f in findings], "fixed": sorted(fixed_ids),
+        "maggie_version": core.maggie_version(),
+    }
+    if args.kind == "gate":
+        data["gate"] = gate_decision(findings, runs)
+    if args.kind == "incident":
+        directory = ctx.state.path("incidents")
+        items = sorted(directory.glob("*.json"), key=lambda p: p.stat().st_mtime) if directory.is_dir() else []
+        chosen = next((p for p in items if p.stem == args.incident), None) if args.incident else (items[-1] if items else None)
+        if chosen:
+            data["incident"] = {k: v for k, v in core.read_json(chosen).items() if k in ("id", "title", "cve", "status", "timeline")}
+    markdown = render(data, findings, args.audience, ctx.site)
+    if len(markdown) > BODY_LIMIT:
+        markdown = render(data, findings, args.audience, ctx.site, clip=True)
+    title = f"Security: {verdict_info['text'].split('.')[0]} — {ctx.site} — {core.iso()[:10]}"[:120]
+    summary = (verdict_info["text"] + (f" First: {data['actions'][0]['title']}." if data["actions"] else ""))[:500]
+    payload = {"title": title, "summary": summary, "body_md": markdown, "kind": KIND_INBOX[args.kind],
+               "data": {k: v for k, v in data.items() if k != "findings"}}
+    check = report_check(payload)
+    texts = [markdown, json.dumps(data)]
+    leaked = core.assert_no_secret(texts, _secret_values(ctx))
+    if leaked:
+        check["passed"] = False
+        check["errors"].append("a secret value from the project appears in the report")
+    out_dir = ctx.state.path("reports")
+    out_dir.mkdir(parents=True, exist_ok=True)
+    base = out_dir / f"{core.iso()[:10]}-{args.kind}"
+    base.with_suffix(".md").write_text(markdown, encoding="utf-8")
+    core.write_json(base.with_suffix(".json"), data)
+    if args.output:
+        core.write_json(Path(args.output) if Path(args.output).is_absolute() else ctx.project / args.output, data)
+    result = {"schema": "maggie-security-report-result.v1", "report": data, "markdown": markdown, "check": check,
+              "paths": {"md": str(base.with_suffix(".md")), "json": str(base.with_suffix(".json"))}}
+    if not check["passed"]:
+        result["exit_code"] = core.EXIT_POLICY
+        return result
+    if args.save:
+        save_path = base.with_name(base.name + ".report_save.json")
+        core.write_json(save_path, payload)
+        with (out_dir / "index.jsonl").open("a", encoding="utf-8") as handle:
+            handle.write(core.canonical_json({"at": core.iso(), "id": report_id, "kind": args.kind, "payload": str(save_path)}) + "\n")
+        result["report_save"] = {"payload": str(save_path),
+                                 "next": "send this payload with the report_save MCP tool (routines: report_save is the only write allowed)"}
+    if args.kind == "gate":
+        result["exit_code"] = core.EXIT_FINDINGS if data["gate"]["decision"] == "block" else core.EXIT_OK
+        return result
+    threshold = core.fail_threshold(args)
+    if threshold and any(core.SEVERITIES.index(f["severity"]) <= core.SEVERITIES.index(threshold) for f in actionable):
+        result["exit_code"] = core.EXIT_FINDINGS
+    elif degraded:
+        result["exit_code"] = core.EXIT_DEGRADED
+    return result
+
+
+def _secret_values(ctx: core.Context) -> list[str]:
+    """Hashes are all we keep; a report-time check can only test known fixture/test values passed by env."""
+    import os
+
+    value = os.environ.get("MAGGIE_SECURITY_TEST_SECRET")
+    return [value] if value else []
+
+
+def render(data: dict, findings: list[dict], audience: str, site: str, clip: bool = False) -> str:
+    used: set[str] = set()
+    owner = audience == "owner"
+    lines = [f"# Security report — {site} — {data['period']['to'][:10]}", "", f"**Verdict:** {data['verdict']['text']}", ""]
+    incident = data.get("incident")
+    if incident:
+        lines += [f"## Incident: {incident['title']} ({incident['status']})", ""]
+        for item in incident["timeline"]:
+            lines.append(f"- {item['at']} — {item['event']}" + (f": {item['note']}" if item.get("note") else ""))
+        lines.append("")
+    gate = data.get("gate")
+    if gate:
+        lines += [f"## Deploy gate: {gate['decision'].upper()}", ""]
+        for item in gate["block"]:
+            lines.append(f"- Blocks: {item['reason']}" + (f" ({len(item['ids'])})" if item["ids"] else ""))
+        for item in gate["warn"]:
+            lines.append(f"- Warning: {item['reason']}" + (f" ({len(item['ids'])})" if item["ids"] else ""))
+        lines.append("")
+    compromise = [f for f in findings if (f.get("signal") or {}).get("type") == "compromise-indicator" and f["status"] in ("new", "open")]
+    if compromise:
+        lines += ["## Possible break-in — check now", ""]
+        for finding in compromise:
+            lines.append(f"- {finding['title']} ({(finding.get('target') or {}).get('host') or ''})")
+        lines.append("")
+    actionable = [f for f in findings if f["status"] in ("new", "open")]
+    urgent = [f for f in actionable if f["priority"] in ("p0", "p1")]
+    urgent_actions = group_actions(urgent)
+    lines.append(f"## Do this week ({len(urgent_actions)})")
+    lines.append("")
+    if not urgent_actions:
+        lines += ["Nothing urgent.", ""]
+    for index, action in enumerate(urgent_actions[:5], 1):
+        text = f"{index}. **{action['title']}** — {action['why']}"
+        lines.append(explain_jargon(text, used) if owner else text)
+        lines.append(f"   How: {action['how']}")
+        if not owner:
+            lead = action["lead"]
+            lines.append(f"   {action['count']} finding(s): " + ", ".join(f"`{i}`" for i in action["ids"][:6])
+                         + (" …" if len(action["ids"]) > 6 else "") + f" · {', '.join((lead.get('aliases') or [])[:3])}"
+                         + (f" · CVSS {lead['cvss']['score']}" if lead.get("cvss") else "")
+                         + (f" · EPSS {lead['epss']['score']:.2f}" if lead.get("epss") else ""))
+    if len(urgent_actions) > 5:
+        lines.append(f"\n…and {len(urgent_actions) - 5} more below.")
+    lines.append("")
+    attacks = [f for f in actionable if f["kind"] == "attack-signal" and (f.get("signal") or {}).get("type") == "attempt"]
+    for title, status in (("New since last report", "new"), ("Still open", "open")):
+        items = [f for f in findings if f["status"] == status and f["priority"] not in ("p0", "p1") and f["kind"] != "attack-signal"]
+        rows = group_actions(items) if owner else [{"priority": f["priority"], "title": f["title"], "ids": [f["id"]], "count": 1, "lead": f}
+                                                   for f in core.sort_findings(items)]
+        lines.append(f"## {title} ({len(rows)})")
+        lines.append("")
+        shown = rows[:20] if clip else rows
+        for row in shown:
+            lead = row["lead"]
+            since = f" (since {lead['first_seen'][:10]})" if status == "open" and lead.get("first_seen") else ""
+            extra = "" if owner else f" — `{lead['id']}`"
+            count = f" ({row['count']} issues)" if row["count"] > 1 else ""
+            lines.append(f"- [{row['priority']}] {row['title']}{count}{since}{extra}")
+        if len(shown) < len(rows):
+            lines.append(f"- {len(rows) - len(shown)} more in the full report (`maggie security report --format json`)")
+        lines.append("")
+    lines.append(f"## Fixed since last report ({len(data['fixed'])})")
+    lines.append("")
+    if data["fixed"]:
+        lines.append(f"{len(data['fixed'])} earlier finding(s) no longer appear in a complete check.")
+        lines.append("")
+    if attacks:
+        lines += ["## Attacks seen (not break-ins)", ""]
+        for finding in attacks:
+            signal = finding["signal"]
+            lines.append(f"- {signal.get('count')} attempts: {finding['title']} in {signal.get('window')}. Attempts are not break-ins.")
+        lines.append("")
+    lines += ["## What we checked", "", "| Area | Last checked | Result |", "|---|---|---|"]
+    for item in data["checked"]:
+        count = sum(1 for f in findings if f["source"]["command"] == item["command"] and f["status"] in ("new", "open"))
+        result = "incomplete" if item["degraded"] else (f"{count} open" if count else "no issues")
+        lines.append(f"| {AREA_LABEL.get(item['command'], item['command'])} | {item['last_run'][:10]} | {result} |")
+    for command in data["not_checked"]:
+        lines.append(f"| {AREA_LABEL.get(command, command)} | not checked yet | run `maggie security {command}` |")
+    lines.append("")
+    if data["degraded_sources"]:
+        lines += ["## Sources that did not answer", "",
+                  f"{', '.join(data['degraded_sources'])} did not answer; those checks may be incomplete, and nothing was marked fixed from them.", ""]
+    lines += ["---", "", core.PRIORITY_FOOTER, "",
+              "Data: OSV (CC-BY-4.0 / Apache-2.0 sources), CISA KEV (CC0), FIRST EPSS, endoflife.date (MIT), WPVulnerability, CVE List (CVE Terms of Use), "
+              f"Node.js security-wg (MIT). Generated by Maggie {data['maggie_version']} · report `{data['id']}`.", ""]
+    text = "\n".join(lines)
+    if owner and FEAR_WORDS.search(text) and not compromise:
+        text = FEAR_WORDS.sub("affected", text)
+    return text
+
+
+def configure(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--kind", choices=["weekly", "daily_ops", "incident", "gate"], default="weekly")
+    parser.add_argument("--runs", action="append", help="use these run ids instead of the latest per command")
+    parser.add_argument("--audience", choices=["owner", "technical"], default="owner")
+    parser.add_argument("--save", action="store_true", help="write the report_save payload and record it in reports/index.jsonl")
+    parser.add_argument("--level", type=int, choices=[1, 2], default=1)
+    parser.add_argument("--incident", help="incident id for --kind incident (default: the latest)")
+
+
+def run(ctx: core.Context) -> dict:
+    return build(ctx)
+
+
+# --------------------------------------------------------------------------- incidents (W2 timeline)
+
+INCIDENT_EVENTS = ["detected", "advisory-written", "inventory-checked", "plan-proposed", "plan-approved", "lock-acquired", "changed", "verified",
+                   "lock-released", "mitigated", "closed", "note"]
+
+
+def incident_cmd(ctx: core.Context) -> dict:
+    """A timeline for one CVE response (docs/maggie-security/12-workflows-prd.md section 6). Local records only."""
+    args = ctx.args
+    directory = ctx.state.path("incidents")
+    if args.action == "start":
+        if not args.title:
+            raise core.UsageError("incident start needs --title")
+        iid = f"inc-{core.iso()[:10]}-{core.sha256_bytes((args.title + core.iso()).encode())[:6]}"
+        data = {"schema": "maggie-security-incident.v1", "id": iid, "title": core.clean_excerpt(args.title, 200), "cve": args.cve,
+                "finding": args.finding, "status": "open", "opened_at": core.iso(), "closed_at": None,
+                "timeline": [{"at": core.iso(), "event": "detected", "note": core.clean_excerpt(args.note or "", 300)}]}
+        core.write_json(directory / f"{iid}.json", data)
+        return data
+    if args.action == "list":
+        items = [core.read_json(p) for p in sorted(directory.glob("*.json"))] if directory.is_dir() else []
+        return {"schema": "maggie-security-incidents.v1", "incidents": [{k: i[k] for k in ("id", "title", "cve", "status", "opened_at", "closed_at")} for i in items]}
+    path = directory / f"{args.id}.json"
+    if not args.id or not path.is_file():
+        raise core.UsageError("give --id of an incident (see `maggie security incident list`)")
+    data = core.read_json(path)
+    if args.action == "show":
+        return data
+    if data["status"] == "closed" and args.action != "show":
+        raise core.UsageError("incident is closed")
+    event = "closed" if args.action == "close" else args.event
+    if event not in INCIDENT_EVENTS:
+        raise core.UsageError(f"--event must be one of {', '.join(INCIDENT_EVENTS)}")
+    data["timeline"].append({"at": core.iso(), "event": event, "note": core.clean_excerpt(args.note or "", 300)})
+    if event == "closed":
+        data["status"], data["closed_at"] = "closed", core.iso()
+    core.write_json(path, data)
+    return data
+
+
+def _incident(p: argparse.ArgumentParser) -> None:
+    p.add_argument("action", choices=["start", "log", "close", "show", "list"])
+    p.add_argument("--id")
+    p.add_argument("--title")
+    p.add_argument("--cve")
+    p.add_argument("--finding")
+    p.add_argument("--event", help=", ".join(INCIDENT_EVENTS))
+    p.add_argument("--note")
+
+
+COMMANDS = [core.Command("report", "one per-site report from the latest runs and the ledger (Markdown + JSON, report_save payload)", [],
+                         configure, run, findings=False),
+            core.Command("incident", "timeline for a CVE response or other incident (local records; used by report --kind incident)", [], _incident,
+                         incident_cmd, findings=False)]