@topy-ai/maggie 0.7.55 → 0.7.56

package/bundled-tools/clis/maggie_security_protect.py

@@ -0,0 +1,519 @@
+#!/usr/bin/env python3
+"""``maggie security protect-plan`` (docs/maggie-security/05-protection-waf-prd.md section 6).
+
+Writes a plan — never applies it. A plan (``maggie-security-protect-plan.v1``)
+lists exact commands with a rollback for every step that touches the host,
+starts by taking the host lock and ends by releasing it, and states every
+host it downloads from. A person reviews it; an agent may run ``steps[].run``
+verbatim in an interactive session only after that approval.
+
+- CrowdSec (default): official packages, hub collections (no account),
+  acquisition for the site's logs, owner allowlist, nftables bouncer, and
+  **sharing off** (CrowdSec shares signals when the setting is absent; the
+  plan sets it to false unless the owner opts in with ``--capi``).
+- fail2ban (lightweight): distro package, built-in nginx/sshd jails and a
+  WordPress filter written for Maggie, checked here against a real log sample.
+- Cloudflare-only / static: advice, no host steps.
+
+``validate`` checks a plan against the rules; ``verify`` runs read-only checks
+on the host afterwards.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shlex
+import subprocess
+from pathlib import Path
+
+import maggie_security_core as core
+from maggie_host_runtime import parse_sections
+
+WORDPRESS_FILTER = r"""# Maggie WordPress login/xmlrpc brute-force filter (MIT, written for Maggie)
+[Definition]
+failregex = ^<HOST> -[^"]*"POST /(?:[^"/]*/)*wp-login\.php HTTP/[0-9.]+" (?:200|302|403)
+            ^<HOST> -[^"]*"POST /(?:[^"/]*/)*xmlrpc\.php HTTP/[0-9.]+" (?:200|403|405)
+ignoreregex =
+datepattern = {^LN-BEG}%%d/%%b/%%Y:%%H:%%M:%%S
+"""
+WORDPRESS_JAIL = """[maggie-wordpress]
+enabled = true
+port = http,https
+filter = maggie-wordpress
+logpath = {logs}
+maxretry = 6
+findtime = 10m
+bantime = 1h
+bantime.increment = true
+action = nftables-multiport[name=maggie-wordpress, port="80,443"]
+"""
+FORBIDDEN = [
+    (re.compile(r"cscli\s+console\s+enroll"), "enrols the host in the CrowdSec Console (an account)"),
+    (re.compile(r"curl[^|]*\|\s*(sudo\s+)?(ba)?sh"), "pipes a download straight into a shell"),
+    (re.compile(r"wget[^|]*\|\s*(sudo\s+)?(ba)?sh"), "pipes a download straight into a shell"),
+    (re.compile(r"\brm\s+-rf\s+/(\s|$)"), "deletes the root folder"),
+]
+CLOUDFLARE_V4 = ["173.245.48.0/20", "103.21.244.0/22", "103.22.200.0/22", "103.31.4.0/22", "141.101.64.0/18", "108.162.192.0/18", "190.93.240.0/20",
+                 "188.114.96.0/20", "197.234.240.0/22", "198.41.128.0/17", "162.158.0.0/15", "104.16.0.0/13", "104.24.0.0/14", "172.64.0.0/13",
+                 "131.0.72.0/22"]
+
+
+def host_facts(ctx: core.Context, host: str) -> dict:
+    """What we know about the host from earlier read-only runs (host-quick evidence, stack.json)."""
+    facts = {"crowdsec": False, "fail2ban": False, "firewall": None, "os": None, "logs": [], "site_type": None, "cloudflare": False, "ram_gb": None}
+    evidence = None
+    if ctx.args.evidence:
+        evidence = Path(ctx.args.evidence).read_text(encoding="utf-8", errors="replace")
+    else:
+        saved = ctx.state.path("inventory", f"host-{host}-host-quick.txt")
+        if saved.is_file():
+            evidence = saved.read_text(encoding="utf-8", errors="replace")
+    if evidence:
+        sections = parse_sections(evidence)
+        ips = sections.get("ips", "").lower()
+        facts["crowdsec"] = "crowdsec active" in ips or "crowdsec" in "".join(l for l in ips.splitlines() if " " not in l.strip())
+        facts["fail2ban"] = "fail2ban active" in ips
+        facts["firewall"] = "ufw" if "status: active" in sections.get("ufw", "").lower() else None
+        os_text = sections.get("os-release", "")
+        os_id = re.search(r"(?m)^ID=\"?(\w+)", os_text)
+        facts["os"] = os_id.group(1) if os_id else None
+    stack_path = ctx.state.path("inventory", "stack.json")
+    if stack_path.is_file():
+        stack = core.read_json(stack_path)
+        facts["site_type"] = stack["site"].get("type")
+        if not facts["os"]:
+            facts["os"] = next((r["name"] for r in stack.get("runtimes") or [] if r["name"] in ("ubuntu", "debian", "rhel", "rocky-linux", "almalinux")
+                                and r.get("host") == host), None)
+    config = ctx.state.config()
+    facts["logs"] = (config.get("logs") or {}).get("access_paths") or [(config.get("logs") or {}).get("access_path") or "/var/log/nginx/access.log"]
+    facts["cloudflare"] = bool(ctx.args.behind_cloudflare)
+    return facts
+
+
+def pkg(os_name: str | None) -> tuple[str, str]:
+    if os_name in ("rhel", "rocky", "rocky-linux", "almalinux", "centos", "fedora", "amzn"):
+        return "sudo dnf install -y", "sudo dnf remove -y"
+    return "sudo apt-get install -y", "sudo apt-get remove --purge -y"
+
+
+def base_steps(plan_id: str, host_target: str) -> tuple[dict, dict]:
+    lock = {"title": "Take the host lock", "kind": "local", "reversible": True,
+            "run": f"maggie deployment host-lock acquire --host {host_target} --session {plan_id} --purpose 'protect-plan {plan_id}' --ttl 3600"}
+    release = {"title": "Release the host lock", "kind": "local", "reversible": True,
+               "run": f"maggie deployment host-lock release --host {host_target} --session {plan_id}"}
+    return lock, release
+
+
+def crowdsec_plan(ctx: core.Context, plan_id: str, facts: dict, host_target: str) -> dict:
+    install, remove = pkg(facts["os"])
+    site_type = ctx.args.site_type or facts["site_type"] or "php-app"
+    collections = ["crowdsecurity/nginx", "crowdsecurity/base-http-scenarios", "crowdsecurity/http-cve", "crowdsecurity/linux", "crowdsecurity/sshd"]
+    if site_type == "wordpress":
+        collections.append("crowdsecurity/wordpress")
+    acquis = "\\n".join(["filenames:"] + [f"  - {path}" for path in facts["logs"]] + ["labels:", "  type: nginx"])
+    allow_ips = ctx.args.allow_ip or []
+    lock, release = base_steps(plan_id, host_target)
+    steps = [lock,
+             {"title": "Back up existing configuration", "kind": "host", "reversible": True,
+              "run": f"sudo tar czf /root/maggie-backup-{plan_id}.tgz /etc/nginx /etc/crowdsec 2>/dev/null; ls -l /root/maggie-backup-{plan_id}.tgz",
+              "rollback": f"sudo tar xzf /root/maggie-backup-{plan_id}.tgz -C /"}]
+    if not facts["crowdsec"]:
+        steps += [
+            {"title": "Download CrowdSec's repository script and review it (not piped to a shell)", "kind": "host", "reversible": True,
+             "run": "curl -fsSL -o /tmp/crowdsec-repo.sh https://install.crowdsec.net && sha256sum /tmp/crowdsec-repo.sh && less /tmp/crowdsec-repo.sh",
+             "rollback": "rm -f /tmp/crowdsec-repo.sh"},
+            {"title": "Add the repository and install CrowdSec", "kind": "host", "reversible": True,
+             "run": f"sudo sh /tmp/crowdsec-repo.sh && {install} crowdsec", "rollback": f"{remove} crowdsec"},
+        ]
+    sharing = "true" if ctx.args.capi else "false"
+    steps += [
+        {"title": f"Set signal sharing to {sharing}" + (" (owner opted in to the community blocklist)" if ctx.args.capi else " (CrowdSec shares by default when unset)"),
+         "kind": "host", "reversible": True,
+         "run": f"printf 'api:\\n  server:\\n    online_client:\\n      sharing: {sharing}\\n' | sudo tee /etc/crowdsec/config.yaml.local",
+         "rollback": "sudo rm -f /etc/crowdsec/config.yaml.local"},
+        {"title": "Install detection collections from the public hub (no account)", "kind": "host", "reversible": True,
+         "run": "sudo cscli collections install " + " ".join(collections), "rollback": "sudo cscli collections remove " + " ".join(collections)},
+        {"title": "Read the site's access logs", "kind": "host", "reversible": True,
+         "run": f"printf '{acquis}\\n' | sudo tee /etc/crowdsec/acquis.d/maggie-nginx.yaml", "rollback": "sudo rm -f /etc/crowdsec/acquis.d/maggie-nginx.yaml"},
+    ]
+    if allow_ips:
+        allow = "\\n".join(["name: maggie/allowlist", "description: owner addresses (from protect-plan)", "whitelist:", "  reason: owner", "  ip:"]
+                           + [f"    - {ip}" for ip in allow_ips])
+        steps.append({"title": "Never ban the owner's addresses", "kind": "host", "reversible": True,
+                      "run": f"printf '{allow}\\n' | sudo tee /etc/crowdsec/parsers/s02-enrich/maggie-allowlist.yaml",
+                      "rollback": "sudo rm -f /etc/crowdsec/parsers/s02-enrich/maggie-allowlist.yaml"})
+    if ctx.args.capi:
+        steps.append({"title": "Register with CrowdSec's central API (owner opted in: sends attacking IP, scenario, time; receives the community blocklist)",
+                      "kind": "host", "reversible": True, "run": "sudo cscli capi register", "rollback": "sudo rm -f /etc/crowdsec/online_api_credentials.yaml"})
+    steps += [
+        {"title": "Install the nftables firewall bouncer (applies bans)", "kind": "host", "reversible": True,
+         "run": f"{install} crowdsec-firewall-bouncer-nftables", "rollback": f"{remove} crowdsec-firewall-bouncer-nftables"},
+        {"title": "Reload CrowdSec", "kind": "host", "reversible": True, "run": "sudo systemctl reload crowdsec || sudo systemctl restart crowdsec",
+         "rollback": "sudo systemctl restart crowdsec"},
+        {"title": "Check it reads the logs", "kind": "host", "reversible": True, "run": "sudo cscli metrics show acquisition"},
+        release,
+    ]
+    notes = ["The first day mostly shows scanners; bans apply to the whole server (all ports)."]
+    if facts["cloudflare"]:
+        notes.append("This origin sits behind Cloudflare: bans at the origin firewall do not stop requests that come through Cloudflare. "
+                     "Turn on real client IPs in nginx first (see the real-ip step) and use Cloudflare-side rules or the CrowdSec Cloudflare bouncer for proxied traffic.")
+        steps.insert(2, real_ip_step())
+    if facts["firewall"] == "ufw":
+        notes.append("UFW is active; the nftables bouncer adds its own table and works alongside it.")
+    egress = [{"host": "install.crowdsec.net", "why": "repository script (reviewed before running)"},
+              {"host": "packagecloud.io", "why": "CrowdSec package repository"},
+              {"host": "hub-cdn.crowdsec.net", "why": "collections and parsers (no account)"}]
+    if ctx.args.capi:
+        egress.append({"host": "api.crowdsec.net", "why": "central API: sends signals, receives the community blocklist (owner opted in)"})
+    return {"engine": "crowdsec", "steps": steps, "risk_notes": notes, "egress": egress,
+            "data_sharing": {"crowdsec_capi": bool(ctx.args.capi), "console": False},
+            "verify": [{"check": "systemctl is-active crowdsec crowdsec-firewall-bouncer", "expect": "active (both)"},
+                       {"check": "sudo cscli metrics show acquisition", "expect": "lines read > 0 for each access log"},
+                       {"check": "sudo cscli bouncers list", "expect": "the firewall bouncer pulled within the last 2 minutes"},
+                       {"check": "sudo grep -A3 online_client /etc/crowdsec/config.yaml.local", "expect": f"sharing: {sharing}"}]}
+
+
+def real_ip_step() -> dict:
+    lines = "\\n".join([f"set_real_ip_from {net};" for net in CLOUDFLARE_V4] + ["real_ip_header CF-Connecting-IP;"])
+    return {"title": "Log the real visitor address behind Cloudflare (otherwise Cloudflare's addresses get banned)", "kind": "host", "reversible": True,
+            "run": f"printf '{lines}\\n' | sudo tee /etc/nginx/conf.d/maggie-cloudflare-realip.conf && sudo nginx -t && sudo systemctl reload nginx",
+            "rollback": "sudo rm -f /etc/nginx/conf.d/maggie-cloudflare-realip.conf && sudo systemctl reload nginx"}
+
+
+def fail2ban_plan(ctx: core.Context, plan_id: str, facts: dict, host_target: str) -> dict:
+    install, remove = pkg(facts["os"])
+    site_type = ctx.args.site_type or facts["site_type"] or "php-app"
+    logs = " ".join(facts["logs"])
+    ignore = " ".join(["127.0.0.1/8", "::1"] + (ctx.args.allow_ip or []))
+    jails = [f"[DEFAULT]\\nignoreip = {ignore}\\nbanaction = nftables-multiport\\n",
+             "[sshd]\\nenabled = true\\n", f"[nginx-botsearch]\\nenabled = true\\nlogpath = {logs}\\n",
+             f"[nginx-bad-request]\\nenabled = true\\nlogpath = {logs}\\n", "[recidive]\\nenabled = true\\n"]
+    lock, release = base_steps(plan_id, host_target)
+    steps = [lock,
+             {"title": "Back up existing configuration", "kind": "host", "reversible": True,
+              "run": f"sudo tar czf /root/maggie-backup-{plan_id}.tgz /etc/fail2ban /etc/nginx 2>/dev/null; ls -l /root/maggie-backup-{plan_id}.tgz",
+              "rollback": f"sudo tar xzf /root/maggie-backup-{plan_id}.tgz -C /"}]
+    if not facts["fail2ban"]:
+        steps.append({"title": "Install fail2ban (GPL; from the distribution)", "kind": "host", "reversible": True, "run": f"{install} fail2ban",
+                      "rollback": f"{remove} fail2ban"})
+    if site_type == "wordpress":
+        filter_text = WORDPRESS_FILTER.replace("\\", "\\\\").replace("'", "'\\''").replace("\n", "\\n").replace("%", "%%")
+        steps += [
+            {"title": "Add the WordPress login filter", "kind": "host", "reversible": True,
+             "run": f"printf '{filter_text}' | sudo tee /etc/fail2ban/filter.d/maggie-wordpress.conf",
+             "rollback": "sudo rm -f /etc/fail2ban/filter.d/maggie-wordpress.conf"},
+            {"title": "Check the filter on the real log before enabling it (look for attack lines, and none from your own address)", "kind": "host",
+             "reversible": True, "run": f"sudo fail2ban-regex {facts['logs'][0]} /etc/fail2ban/filter.d/maggie-wordpress.conf --print-all-matched | head -40"},
+        ]
+        jails.append(WORDPRESS_JAIL.format(logs=logs).replace("\n", "\\n"))
+    steps += [
+        {"title": "Enable the jails", "kind": "host", "reversible": True,
+         "run": f"printf '{''.join(j + chr(92) + 'n' for j in jails)}' | sudo tee /etc/fail2ban/jail.d/maggie.local",
+         "rollback": "sudo rm -f /etc/fail2ban/jail.d/maggie.local && sudo systemctl reload fail2ban"},
+        {"title": "Restart fail2ban", "kind": "host", "reversible": True, "run": "sudo systemctl enable --now fail2ban && sudo systemctl restart fail2ban",
+         "rollback": "sudo systemctl restart fail2ban"},
+        {"title": "Check the jails are running", "kind": "host", "reversible": True, "run": "sudo fail2ban-client status"},
+        release,
+    ]
+    notes = ["fail2ban bans at the firewall on ports 80/443 (and SSH for the sshd jail).",
+             "WordPress returns 200 for a failed login and 302 for a successful one; the filter counts both, so owners behind a shared office address may need a higher maxretry or an ignoreip entry."]
+    if facts["cloudflare"]:
+        steps.insert(2, real_ip_step())
+        notes.append("Behind Cloudflare, firewall bans do not stop proxied requests; use Cloudflare rate limiting for /wp-login.php as well.")
+    return {"engine": "fail2ban", "steps": steps, "risk_notes": notes, "egress": [{"host": "distribution package mirrors", "why": "fail2ban package"}],
+            "data_sharing": {"crowdsec_capi": False, "console": False},
+            "verify": [{"check": "sudo fail2ban-client status", "expect": "jails listed: sshd, nginx-botsearch, nginx-bad-request, recidive"
+                        + (", maggie-wordpress" if site_type == "wordpress" else "")},
+                       {"check": "systemctl is-active fail2ban", "expect": "active"}]}
+
+
+def cloudflare_plan(ctx: core.Context) -> dict:
+    return {"engine": "cloudflare", "steps": [], "egress": [], "data_sharing": {"crowdsec_capi": False, "console": False},
+            "risk_notes": ["There is no origin server to protect, so nothing is installed. Maggie cannot see Cloudflare's own logs without Logpush."],
+            "advice": ["Security → Settings: Security Level 'Medium', Bot Fight Mode on.",
+                       "SSL/TLS: minimum TLS 1.2, Always Use HTTPS on, HSTS on once HTTPS works everywhere.",
+                       "Rules → Rate limiting: limit login or form endpoints (e.g. /api/login) to ~10 requests per minute per IP.",
+                       "WAF → Managed rules: turn on what your plan includes."],
+            "verify": []}
+
+
+def wordpress_filter_matches(log_path: Path, limit: int = 200_000) -> dict:
+    """Python port of the WordPress failregex, run on a local log sample (PRD 05 section 6.4)."""
+    patterns = [re.compile(line.strip().replace("^<HOST>", r"^(?P<host>[0-9a-fA-F.:]+)"))
+                for line in WORDPRESS_FILTER.split("failregex =", 1)[1].split("ignoreregex", 1)[0].splitlines() if line.strip()]
+    hosts: dict[str, int] = {}
+    total = 0
+    opener = __import__("gzip").open if log_path.suffix == ".gz" else open
+    with opener(log_path, "rt", encoding="utf-8", errors="replace") as handle:
+        for index, line in enumerate(handle):
+            if index >= limit:
+                break
+            for pattern in patterns:
+                match = pattern.search(line)
+                if match:
+                    total += 1
+                    hosts[match.group("host")] = hosts.get(match.group("host"), 0) + 1
+                    break
+    would_ban = {h: n for h, n in hosts.items() if n >= 6}
+    return {"lines_matched": total, "addresses": len(hosts), "would_ban_at_6": len(would_ban),
+            "top": sorted(would_ban.items(), key=lambda kv: -kv[1])[:10]}
+
+
+def validate_plan(plan: dict) -> list[str]:
+    problems = core.validate_contract(plan, "protect-plan-v1")
+    steps = plan.get("steps") or []
+    if steps:
+        if "host-lock acquire" not in steps[0].get("run", ""):
+            problems.append("step 1 must take the host lock")
+        if "host-lock release" not in steps[-1].get("run", ""):
+            problems.append("the last step must release the host lock")
+    egress_hosts = {e["host"] for e in plan.get("egress") or []}
+    for step in steps:
+        run = step.get("run", "")
+        for pattern, why in FORBIDDEN:
+            if pattern.search(run):
+                problems.append(f"step {step.get('n')}: {why}")
+        if step.get("kind") == "host" and not step.get("rollback") and not re.match(r"^(sudo )?(cscli metrics|fail2ban-client status|sudo fail2ban-client status|systemctl is-active|ls |sudo fail2ban-regex|sudo cscli metrics)", run.strip()) \
+                and not re.search(r"(fail2ban-regex|cscli metrics|fail2ban-client status)", run):
+            problems.append(f"step {step.get('n')}: a host step needs a rollback")
+        if "cscli capi register" in run and not (plan.get("data_sharing") or {}).get("crowdsec_capi"):
+            problems.append(f"step {step.get('n')}: registers with the central API but data_sharing.crowdsec_capi is false")
+        for host in re.findall(r"https?://([A-Za-z0-9.-]+)", run):
+            if host not in egress_hosts:
+                problems.append(f"step {step.get('n')}: downloads from {host}, which is not listed in egress")
+    return problems
+
+
+def protect_plan(ctx: core.Context) -> dict:
+    args = ctx.args
+    if args.action == "validate":
+        if not args.plan:
+            raise core.UsageError("validate needs --plan FILE")
+        problems = validate_plan(core.read_json(Path(args.plan)))
+        return {"schema": "maggie-security-protect-plan-validation.v1", "valid": not problems, "problems": problems,
+                "exit_code": core.EXIT_OK if not problems else core.EXIT_FINDINGS}
+    if args.action == "verify":
+        return verify_plan(ctx)
+    host = args.host or "web1"
+    host_target = ((ctx.state.config().get("hosts") or {}).get(host)) or f"deploy@{host}"
+    if args.capi and not __import__("sys").stdin.isatty():
+        raise core.PolicyError("--capi (sharing with CrowdSec's central API) is an owner decision made interactively")
+    facts = host_facts(ctx, host)
+    engine = args.engine
+    if engine == "auto":
+        site_type = args.site_type or facts["site_type"]
+        if site_type in ("workers", "static") and not args.evidence:
+            engine = "cloudflare"
+        elif facts["crowdsec"]:
+            engine = "crowdsec"
+        elif facts["fail2ban"]:
+            engine = "fail2ban"
+        else:
+            engine = "crowdsec"
+    plan_id = f"pp_{core.iso()[:10]}_{host}_{core.sha256_bytes((host + core.iso()).encode())[:4]}"
+    body = {"crowdsec": crowdsec_plan, "fail2ban": fail2ban_plan}.get(engine)
+    content = body(ctx, plan_id, facts, host_target) if body else cloudflare_plan(ctx)
+    for index, step in enumerate(content["steps"], 1):
+        step["n"] = index
+    plan = {"schema": "maggie-security-protect-plan.v1", "id": plan_id, "host": host, "created_at": core.iso(), "engine": content["engine"],
+            "waf": waf_section(args, content["engine"]),
+            "inputs": {"facts": {k: v for k, v in facts.items() if k != "logs"}, "logs": facts["logs"]},
+            "egress": content["egress"], "data_sharing": content["data_sharing"],
+            "requires": {"consent": "host-change", "host_lock": bool(content["steps"]), "sudo": bool(content["steps"]),
+                         "approval": "a person reviews this plan; nothing runs from a routine"},
+            "risk_notes": content["risk_notes"], "steps": content["steps"], "verify": content["verify"],
+            "rollback": [s["rollback"] for s in reversed(content["steps"]) if s.get("rollback")],
+            "allowlist": {"ips": args.allow_ip or [], "note": "owner-provided only; never guessed"}}
+    if content.get("advice"):
+        plan["advice"] = content["advice"]
+    if args.log and content["engine"] == "fail2ban":
+        plan["inputs"]["filter_check"] = wordpress_filter_matches(Path(args.log))
+    problems = validate_plan(plan)
+    if problems:
+        raise core.SecurityError("generated plan failed its own validation: " + "; ".join(problems), core.EXIT_USAGE)
+    out = Path(args.out) if args.out else ctx.state.path("plans", f"{plan_id}.json")
+    core.write_json(out, plan)
+    markdown = render_plan(plan)
+    out.with_suffix(".md").write_text(markdown, encoding="utf-8")
+    return {**plan, "paths": {"json": str(out), "md": str(out.with_suffix(".md"))}, "markdown": markdown}
+
+
+def waf_section(args: argparse.Namespace, engine: str) -> dict:
+    if not getattr(args, "replay_report", None):
+        return {"engine": "none", "mode": "not-planned", "note": "run `maggie security waf-replay --log access.log` first to size a WAF"}
+    report = core.read_json(Path(args.replay_report))
+    rec = report.get("recommendation") or {}
+    return {"engine": "crowdsec-appsec" if engine == "crowdsec" else "modsecurity", "ruleset": "crs-4", "paranoia_level": rec.get("paranoia", 1),
+            "inbound_threshold": rec.get("threshold", 5), "mode": "detection-only",
+            "exclusions_needed": rec.get("exclusions_needed") or [], "replay_report": args.replay_report,
+            "note": "Blocking mode is a second plan after 7 days of detection-only logs show a false-positive rate under 0.1 %."}
+
+
+def render_plan(plan: dict) -> str:
+    lines = [f"# Protection plan {plan['id']} — {plan['host']} ({plan['engine']})", "",
+             "**Nothing has been changed.** Review every step; run them yourself (or let an agent run them verbatim after you approve) "
+             "while holding the host lock. Stop at the first error.", ""]
+    for note in plan["risk_notes"]:
+        lines.append(f"> {note}")
+    lines.append("")
+    if plan.get("advice"):
+        lines += ["## Settings to change", ""] + [f"- {a}" for a in plan["advice"]] + [""]
+    if plan["steps"]:
+        lines += ["## Steps", ""]
+        for step in plan["steps"]:
+            lines += [f"{step['n']}. **{step['title']}**", "   ```bash", f"   {step['run']}", "   ```"]
+            if step.get("rollback"):
+                lines.append(f"   Undo: `{step['rollback']}`")
+        lines += ["", "## Check afterwards", ""] + [f"- `{v['check']}` → {v['expect']}" for v in plan["verify"]]
+        lines += ["", "## Downloads from", ""] + [f"- {e['host']}: {e['why']}" for e in plan["egress"]]
+        lines += ["", f"Data sharing with CrowdSec's central API: **{'on (you opted in)' if plan['data_sharing']['crowdsec_capi'] else 'off'}**."]
+    return "\n".join(lines) + "\n"
+
+
+def verify_plan(ctx: core.Context) -> dict:
+    args = ctx.args
+    if not args.plan:
+        raise core.UsageError("verify needs --plan FILE")
+    plan = core.read_json(Path(args.plan))
+    checks = [v["check"] for v in plan.get("verify") or []]
+    if not checks:
+        return {"schema": "maggie-security-protect-verify.v1", "results": [], "note": "nothing to verify on a host for this plan"}
+    if args.evidence:
+        output = Path(args.evidence).read_text(encoding="utf-8", errors="replace")
+    else:
+        if not args.ssh:
+            raise core.UsageError("verify needs --ssh ALIAS=user@host (ssh-read consent) or --evidence FILE with the check outputs")
+        alias, _, target = args.ssh.partition("=")
+        core.require_consent(ctx.state, alias, "ssh-read")
+        script = "".join(f"printf '\\n### check-{i}\\n'; {c} 2>&1 | head -40\n" for i, c in enumerate(checks))
+        output = subprocess.run(["ssh", "-o", "BatchMode=yes", target, "sh -s"], input=script, capture_output=True, text=True, timeout=300, check=False).stdout
+    sections = parse_sections(output)
+    results = []
+    for i, item in enumerate(plan["verify"]):
+        text = sections.get(f"check-{i}", "")
+        ok = bool(text.strip()) and not re.search(r"(?i)\b(inactive|failed|not found|error)\b", text)
+        if "sharing" in item["expect"]:
+            ok = item["expect"].split(": ")[-1] in text
+        results.append({"check": item["check"], "expect": item["expect"], "passed": ok, "output": core.clean_excerpt(text, 200)})
+    return {"schema": "maggie-security-protect-verify.v1", "plan": plan["id"], "results": results,
+            "exit_code": core.EXIT_OK if all(r["passed"] for r in results) else core.EXIT_FINDINGS}
+
+
+# --------------------------------------------------------------------------- waf-replay (Coraza + OWASP CRS, offline)
+
+
+def waf_replay(ctx: core.Context) -> dict:
+    """Estimate how many real visitors a CRS WAF would block, by replaying an access log offline (PRD 05 section 7).
+
+    Access logs carry no request bodies and few headers, so only the request
+    line, query arguments, User-Agent and Referer are evaluated; the report says so.
+    """
+    import collections
+    import maggie_security_logs as logs
+
+    args = ctx.args
+    path = Path(args.log)
+    if not path.is_file():
+        raise core.UsageError(f"file not found: {path}")
+    lists = logs.IocLists(ctx, [])
+    requests, labels = [], []
+    per_ip_404 = collections.Counter()
+    opener = __import__("gzip").open if path.suffix == ".gz" else open
+    parsed = total = 0
+    with opener(path, "rt", encoding="utf-8", errors="replace") as handle:
+        rows = []
+        for line in handle:
+            total += 1
+            if total > args.sample:
+                break
+            rec = logs.parse_line(line)
+            if rec is None:
+                continue
+            parsed += 1
+            rows.append(rec)
+            if rec.status == 404:
+                per_ip_404[rec.ip] += 1
+    for rec in rows:
+        attack = bool(rec.ua and lists.ua.search(rec.ua)) or lists.mass_scanner(rec.ip) or per_ip_404[rec.ip] >= 20
+        if args.exclude_bots and attack:
+            continue
+        requests.append({"method": rec.method or "GET", "uri": rec.target or "/", "ua": rec.ua, "referer": rec.referer, "host": rec.vhost})
+        labels.append("attack" if attack else "legit")
+    stdin = "".join(json.dumps(r) + "\n" for r in requests).encode()
+    proc = core.run_tool("maggie-waf-replay", ["--paranoia", str(args.paranoia), "--threshold", str(args.threshold)], ctx.lock, stdin=stdin, timeout=3600)
+    if proc.returncode != 0:
+        raise core.DegradedError(f"maggie-waf-replay failed: {core.clean_excerpt(proc.stderr.decode(errors='replace'), 300)}")
+    levels: dict[str, dict] = {}
+    for line in proc.stdout.decode().splitlines():
+        item = json.loads(line)
+        label = labels[item["i"]] if item["i"] < len(labels) else "legit"
+        request = requests[item["i"]] if item["i"] < len(requests) else {}
+        for level, result in item["levels"].items():
+            entry = levels.setdefault(level, {"paranoia": int(level), "threshold": args.threshold, "would_block": 0, "would_block_legit_estimate": 0,
+                                              "legit_total": 0, "rules": collections.Counter(), "legit_rules": collections.Counter(), "samples": {}, "legit_samples": {}})
+            if label == "legit":
+                entry["legit_total"] += 1
+            if not result["block"]:
+                continue
+            entry["would_block"] += 1
+            for rule in result["rules"]:
+                entry["rules"][rule] += 1
+                entry["samples"].setdefault(rule, core.mask_query(request.get("uri", ""))[:150])
+            if label == "legit":
+                entry["would_block_legit_estimate"] += 1
+                for rule in result["rules"]:
+                    entry["legit_rules"][rule] += 1
+                    entry["legit_samples"].setdefault(rule, core.mask_query(request.get("uri", ""))[:150])
+    out_levels = []
+    for level in sorted(levels.values(), key=lambda l: l["paranoia"]):
+        rate = level["would_block_legit_estimate"] / level["legit_total"] if level["legit_total"] else 0.0
+        out_levels.append({"paranoia": level["paranoia"], "threshold": level["threshold"], "would_block": level["would_block"],
+                           "would_block_legit_estimate": level["would_block_legit_estimate"], "legit_rate": round(rate, 6),
+                           "top_rules": [{"id": r, "count": c, "sample_uri": level["samples"][r]} for r, c in level["rules"].most_common(10)],
+                           "top_legit_rules": [{"id": r, "count": c, "sample_uri": level["legit_samples"][r]} for r, c in level["legit_rules"].most_common(10)]})
+    acceptable = [l for l in out_levels if l["legit_rate"] < 0.001]
+    best = max(acceptable, key=lambda l: l["paranoia"]) if acceptable else (out_levels[0] if out_levels else None)
+    report = {"schema": "maggie-security-waf-replay.v1", "log": {"lines": total, "parsed": parsed, "replayed": len(requests)},
+              "coverage": "request-line-args-user-agent-referer-only",
+              "coverage_note": "Access logs have no request bodies: form and API body rules were not evaluated, so the real false-positive rate on forms may be higher.",
+              "levels": out_levels,
+              "recommendation": {"paranoia": best["paranoia"] if best else 1, "threshold": args.threshold, "mode": "detection-only first (7 days)",
+                                 "exclusions_needed": [f"{r['id']} on {r['sample_uri']}" for r in (best or {}).get("top_legit_rules", [])[:5]],
+                                 "blocking_ok": bool(best and best["legit_rate"] < 0.001)},
+              "engine": {"name": "maggie-waf-replay (Coraza + OWASP CRS v4)", "version": ctx.lock["tools"]["maggie-waf-replay"]["version"]}}
+    out = Path(args.out) if args.out else ctx.state.path("reports", f"waf-replay-{core.iso()[:10]}.json")
+    core.write_json(out, report)
+    return {**report, "path": str(out)}
+
+
+def _replay(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--log", required=True, help="access log (combined/vcombined/Caddy/Cloudflare JSON; .gz fine)")
+    p.add_argument("--paranoia", type=int, choices=[1, 2, 3, 4], default=2)
+    p.add_argument("--threshold", type=int, default=5)
+    p.add_argument("--sample", type=int, default=100_000)
+    p.add_argument("--exclude-bots", action="store_true", help="drop likely-attack traffic before replaying")
+    p.add_argument("--out")
+
+
+def configure(p: argparse.ArgumentParser) -> None:
+    p.add_argument("action", nargs="?", choices=["create", "validate", "verify"], default="create")
+    p.add_argument("--host", help="host alias (config.json hosts maps it to user@host)")
+    p.add_argument("--engine", choices=["auto", "crowdsec", "fail2ban", "cloudflare"], default="auto")
+    p.add_argument("--site-type", choices=["wordpress", "php-app", "node-app", "python-app", "static", "workers"])
+    p.add_argument("--allow-ip", action="append", help="an address that must never be banned (yours); repeatable")
+    p.add_argument("--behind-cloudflare", action="store_true", help="the origin is proxied by Cloudflare")
+    p.add_argument("--capi", action="store_true", help="opt in to CrowdSec's community blocklist (shares signals); interactive only")
+    p.add_argument("--evidence", help="host-quick collector output for this host")
+    p.add_argument("--log", help="a local access log sample to test the WordPress filter against")
+    p.add_argument("--plan", help="plan file for validate/verify")
+    p.add_argument("--ssh", help="ALIAS=user@host for verify (ssh-read)")
+    p.add_argument("--out", help="where to write the plan (default .maggie/security/plans/)")
+    p.add_argument("--replay-report", help="waf-replay report: adds a WAF section (detection-only first)")
+
+
+COMMANDS = [core.Command("waf-replay", "estimate how many real visitors an OWASP CRS WAF would block, by replaying an access log offline (Coraza)",
+                         [], _replay, waf_replay, findings=False),
+            core.Command("protect-plan", "a reviewed plan for CrowdSec or fail2ban (or Cloudflare settings); never applied by Maggie",
+                         ["dns"], configure, protect_plan, findings=False, routine_safe=False)]