@topy-ai/maggie 0.7.55 → 0.7.56

package/bundled-tools/clis/maggie_security_web.py

@@ -0,0 +1,936 @@
+#!/usr/bin/env python3
+"""Web surface (docs/maggie-security/04-web-surface-prd.md):
+``domain-verify``, ``headers``, ``tls``, ``web-scan``, ``zap-baseline``.
+
+Nothing here sends a request to a site until its owner has proved control of
+the registrable domain (DNS TXT seen by the system resolver and by a public
+DoH resolver, or a token file on the site). ``headers`` and ``tls`` may run
+once against an unverified domain with ``--public-check`` — one ordinary GET
+or TLS handshake, the same as a browser — and say so. ``web-scan`` runs
+nuclei only with the safe profile (no fuzzing, brute force, OAST, DoS or
+intrusive templates) at ≤ 10 requests per second.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import datetime as dt
+import hashlib
+import html.parser
+import ipaddress
+import json
+import os
+import random
+import re
+import secrets
+import shutil
+import socket
+import ssl
+import struct
+import subprocess
+import tempfile
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+import maggie_security_core as core
+
+core.SOURCES.setdefault("doh", {"hosts": ["cloudflare-dns.com"], "ttl": "0s", "url": "https://cloudflare-dns.com/dns-query"})
+OWNERSHIP_DAYS = 90
+RECHECK_DAYS = 7
+TXT_NAME = "_maggie-security"
+WELL_KNOWN = "/.well-known/maggie-security-verification.txt"
+_PSL: set[str] | None = None
+
+
+# --------------------------------------------------------------------------- domains and ownership
+
+
+def public_suffixes() -> set[str]:
+    global _PSL
+    if _PSL is None:
+        text = (core.DATA_DIR / "public-suffix-icann.txt").read_text(encoding="utf-8")
+        _PSL = {line.strip().lower() for line in text.splitlines() if line.strip() and not line.startswith("#")}
+    return _PSL
+
+
+def is_ip(host: str) -> bool:
+    try:
+        ipaddress.ip_address(host.strip("[]"))
+        return True
+    except ValueError:
+        return False
+
+
+def registrable(host: str) -> str:
+    host = host.strip().lower().rstrip(".")
+    if is_ip(host) or "." not in host:
+        return host
+    labels = host.split(".")
+    suffixes = public_suffixes()
+    for i in range(len(labels)):
+        candidate = ".".join(labels[i:])
+        if candidate in suffixes:
+            return ".".join(labels[max(i - 1, 0):]) if i > 0 else host
+    return ".".join(labels[-2:])
+
+
+def host_of(url_or_host: str) -> str:
+    if "://" in url_or_host:
+        return (urllib.parse.urlsplit(url_or_host).hostname or "").lower()
+    return url_or_host.split("/")[0].split(":")[0].lower()
+
+
+def ownership_path(state: core.State, domain: str) -> Path:
+    return state.path("ownership", f"{registrable(domain)}.json")
+
+
+def system_resolvers() -> list[str]:
+    servers = []
+    try:
+        for line in Path("/etc/resolv.conf").read_text().splitlines():
+            parts = line.split()
+            if len(parts) >= 2 and parts[0] == "nameserver":
+                servers.append(parts[1])
+    except OSError:
+        pass
+    return servers or ["127.0.0.53"]
+
+
+def dns_txt_udp(name: str, server: str, timeout: float = 5.0, port: int = 53) -> list[str]:
+    """Minimal DNS TXT query over UDP (stdlib only)."""
+    qid = random.randint(0, 0xFFFF)
+    question = b"".join(bytes([len(label)]) + label.encode("idna") for label in name.rstrip(".").split(".")) + b"\x00"
+    packet = struct.pack(">HHHHHH", qid, 0x0100, 1, 0, 0, 0) + question + struct.pack(">HH", 16, 1)
+    family = socket.AF_INET6 if ":" in server else socket.AF_INET
+    with socket.socket(family, socket.SOCK_DGRAM) as sock:
+        sock.settimeout(timeout)
+        sock.sendto(packet, (server, port))
+        data, _ = sock.recvfrom(4096)
+    rid, flags, qd, an, _ns, _ar = struct.unpack(">HHHHHH", data[:12])
+    if rid != qid or flags & 0x000F not in (0, 3):
+        return []
+    offset = 12
+
+    def skip_name(pos: int) -> int:
+        while True:
+            length = data[pos]
+            if length == 0:
+                return pos + 1
+            if length & 0xC0 == 0xC0:
+                return pos + 2
+            pos += length + 1
+
+    for _ in range(qd):
+        offset = skip_name(offset) + 4
+    out = []
+    for _ in range(an):
+        offset = skip_name(offset)
+        rtype, _rclass, _ttl, rdlength = struct.unpack(">HHIH", data[offset:offset + 10])
+        offset += 10
+        rdata = data[offset:offset + rdlength]
+        offset += rdlength
+        if rtype == 16:
+            parts, pos = [], 0
+            while pos < len(rdata):
+                length = rdata[pos]
+                parts.append(rdata[pos + 1:pos + 1 + length].decode("utf-8", errors="replace"))
+                pos += 1 + length
+            out.append("".join(parts))
+    return out
+
+
+def dns_txt_doh(ctx: core.Context, name: str) -> list[str] | None:
+    url = f"https://cloudflare-dns.com/dns-query?name={urllib.parse.quote(name)}&type=TXT"
+    ctx.guard.check("doh", url)
+    try:
+        status, _h, body = core.http_request(url, headers={"Accept": "application/dns-json"}, timeout=10, retries=1)
+    except core.DegradedError:
+        return None
+    if status != 200:
+        return None
+    data = json.loads(body.decode() or "{}")
+    return [a.get("data", "").strip('"').replace('" "', "") for a in data.get("Answer") or [] if a.get("type") == 16]
+
+
+def token_hash(token: str) -> str:
+    return hashlib.sha256(token.strip().encode()).hexdigest()
+
+
+def check_record(ctx: core.Context, record: dict, host_hint: str | None = None) -> tuple[bool, dict]:
+    """Re-run the record's method; returns (ok, evidence)."""
+    domain = record["domain"]
+    if record["method"] == "dns":
+        name = f"{TXT_NAME}.{domain}"
+        seen: dict[str, list[str]] = {}
+        try:
+            seen["system"] = dns_txt_udp(name, system_resolvers()[0])
+        except OSError as error:
+            seen["system_error"] = [str(error)]
+        doh = dns_txt_doh(ctx, name)
+        if doh is not None:
+            seen["doh"] = doh
+        want = record["token_sha256"]
+        hit = lambda values: any(token_hash(v.split("=", 1)[1] if v.startswith("maggie-site-verification=") else v) == want for v in values)  # noqa: E731
+        ok_system = hit(seen.get("system", []))
+        ok_doh = hit(seen.get("doh", []))
+        return ok_system and ok_doh, {"txt_seen_by": [k for k, ok in (("system", ok_system), ("doh", ok_doh)) if ok],
+                                      "resolvers_answered": [k for k in ("system", "doh") if k in seen]}
+    host = record.get("host") or host_hint or domain
+    url = f"https://{host}{WELL_KNOWN}"
+    try:
+        response = fetch(url, follow=False, timeout=10)
+    except OSError as error:
+        return False, {"http_error": str(error)[:200]}
+    body = response["body"][:200].decode("utf-8", errors="replace").strip()
+    ok = response["status"] == 200 and token_hash(body) == record["token_sha256"]
+    return ok, {"http_status": response["status"]}
+
+
+def domain_verify(ctx: core.Context) -> dict:
+    args = ctx.args
+    action = args.action
+    if action == "status":
+        directory = ctx.state.path("ownership")
+        records = [core.read_json(p) for p in sorted(directory.glob("*.json"))] if directory.is_dir() else []
+        return {"schema": "maggie-security-ownership-status.v1", "records": [ownership_summary(r) for r in records]}
+    if not args.domain:
+        raise core.UsageError("--domain is required")
+    domain = registrable(host_of(args.domain)) if args.method != "file" else host_of(args.domain)
+    path = ownership_path(ctx.state, domain)
+    record = core.read_json(path) if path.is_file() else None
+    if action == "revoke":
+        if path.is_file():
+            path.unlink()
+        return {"revoked": domain}
+    if action == "start":
+        if record and record.get("verified_at") and not args.rotate:
+            return {"schema": "maggie-security-ownership-start.v1", "domain": domain, "already": ownership_summary(record),
+                    "note": "already verified; use --rotate for a new token"}
+        token = base64.b32encode(secrets.token_bytes(32)).decode().rstrip("=").lower()
+        record = {"schema": "maggie-security-ownership.v1", "domain": registrable(domain) if args.method == "dns" else domain,
+                  "host": None if args.method == "dns" else domain, "scope": "registrable-domain" if args.method == "dns" else "host",
+                  "method": args.method, "token_sha256": token_hash(token), "created_at": core.iso(), "verified_at": None,
+                  "expires_at": None, "last_checked_at": None, "evidence": {}}
+        core.write_json(path, record)
+        how = (f"Add a DNS TXT record: name `{TXT_NAME}.{record['domain']}`, value `maggie-site-verification={token}`"
+               if args.method == "dns" else
+               f"Serve `https://{domain}{WELL_KNOWN}` with exactly this text (Content-Type text/plain): {token}")
+        return {"schema": "maggie-security-ownership-start.v1", "domain": record["domain"], "method": args.method, "token": token,
+                "instructions": how, "next": f"maggie security domain-verify check --domain {record['domain']}",
+                "note": "The token is shown once; Maggie stores only its hash."}
+    if not record:
+        raise core.UsageError(f"no verification started for {domain}; run domain-verify start first")
+    ok, evidence = check_record(ctx, record)
+    record["last_checked_at"] = core.iso()
+    record["evidence"] = evidence
+    if ok:
+        record["verified_at"] = record.get("verified_at") if record.get("verified_at") and not record.get("stale") else core.iso()
+        record["expires_at"] = core.iso(core.parse_time(record["verified_at"]) + dt.timedelta(days=OWNERSHIP_DAYS))
+        record.pop("stale", None)
+    core.write_json(path, record)
+    result = {"schema": "maggie-security-ownership-check.v1", **ownership_summary(record), "evidence": evidence}
+    if not ok:
+        if record["method"] == "dns" and not evidence.get("resolvers_answered"):
+            result["exit_code"] = core.EXIT_DEGRADED
+        else:
+            result["exit_code"] = core.EXIT_POLICY
+            result["note"] = "not verified yet: DNS changes can take a while; both the system resolver and the public resolver must see the record"
+    return result
+
+
+def ownership_summary(record: dict) -> dict:
+    status = "pending"
+    if record.get("verified_at"):
+        expired = record.get("expires_at") and core.parse_time(record["expires_at"]) < core.utcnow()
+        status = "expired" if expired else ("stale" if record.get("stale") else "verified")
+    return {"domain": record["domain"], "method": record["method"], "scope": record.get("scope"), "status": status,
+            "verified_at": record.get("verified_at"), "expires_at": record.get("expires_at"), "last_checked_at": record.get("last_checked_at")}
+
+
+def require_ownership(ctx: core.Context, host: str, public_check: bool = False) -> str:
+    """'verified' or 'public-check'; raises PolicyError otherwise (PRD 00 section 13.2)."""
+    path = ownership_path(ctx.state, host)
+    record = core.read_json(path) if path.is_file() else None
+    if record is None and not path.is_file():
+        exact = ctx.state.path("ownership", f"{host}.json")
+        record = core.read_json(exact) if exact.is_file() else None
+    if record and record.get("scope") == "host" and record.get("host") not in (host, None):
+        record = None
+    if record and ownership_summary(record)["status"] == "verified":
+        last = core.parse_time(record.get("last_checked_at") or record["verified_at"])
+        if core.utcnow() - last > dt.timedelta(days=RECHECK_DAYS) and record["method"] in ("dns", "file"):
+            ok, evidence = check_record(ctx, record, host)
+            record["last_checked_at"], record["evidence"] = core.iso(), evidence
+            if not ok:
+                record["stale"] = True
+            core.write_json(ownership_path(ctx.state, host) if record.get("scope") != "host" else ctx.state.path("ownership", f"{host}.json"), record)
+            if not ok:
+                raise core.PolicyError(f"ownership of {record['domain']} could not be re-confirmed (the TXT record or file is gone)")
+        return "verified"
+    if public_check:
+        if getattr(ctx.args, "ci", False) or os.environ.get("MAGGIE_ROUTINE"):
+            raise core.PolicyError("--public-check is for a person checking their own site interactively, not for routines or CI")
+        return "public-check"
+    raise core.PolicyError(f"{registrable(host)} is not verified; run: maggie security domain-verify start --domain {registrable(host)}")
+
+
+# --------------------------------------------------------------------------- HTTP
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args, **kwargs):  # noqa: D401
+        return None
+
+
+def fetch(url: str, follow: bool = True, timeout: float = 15.0, max_hops: int = 5, method: str = "GET") -> dict:
+    """GET with manual redirects that stay within the registrable domain; returns status, headers (lists), body, chain."""
+    opener = urllib.request.build_opener(NoRedirect, urllib.request.HTTPSHandler(context=ssl.create_default_context()))
+    chain = []
+    current = url
+    start_domain = registrable(host_of(url))
+    for _ in range(max_hops + 1):
+        request = urllib.request.Request(current, method=method, headers={"User-Agent": core.USER_AGENT, "Accept": "text/html,*/*"})
+        try:
+            response = opener.open(request, timeout=timeout)
+            status, headers, body = response.status, response.headers, response.read(512 * 1024)
+        except urllib.error.HTTPError as error:
+            status, headers, body = error.code, error.headers, error.read(64 * 1024) if error.fp else b""
+        multi: dict[str, list[str]] = {}
+        for key, value in headers.items():
+            multi.setdefault(key.lower(), []).append(value)
+        chain.append({"url": current, "status": status})
+        location = (multi.get("location") or [None])[0]
+        if follow and status in (301, 302, 303, 307, 308) and location:
+            nxt = urllib.parse.urljoin(current, location)
+            if registrable(host_of(nxt)) != start_domain:
+                return {"status": status, "headers": multi, "body": body, "chain": chain, "url": current, "left_domain": nxt}
+            current = nxt
+            continue
+        return {"status": status, "headers": multi, "body": body, "chain": chain, "url": current}
+    return {"status": status, "headers": multi, "body": body, "chain": chain, "url": current, "too_many_redirects": True}
+
+
+# --------------------------------------------------------------------------- headers
+
+
+SNIPPETS = {
+    "nginx": {
+        "strict-transport-security": 'add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;',
+        "x-content-type-options": 'add_header X-Content-Type-Options "nosniff" always;',
+        "referrer-policy": 'add_header Referrer-Policy "strict-origin-when-cross-origin" always;',
+        "x-frame-options": 'add_header X-Frame-Options "SAMEORIGIN" always;',
+        "permissions-policy": 'add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;',
+        "content-security-policy": 'add_header Content-Security-Policy-Report-Only "{csp}" always;',
+        "server": "server_tokens off;  # and remove X-Powered-By in the app (PHP: expose_php = Off)",
+    },
+    "apache": {
+        "strict-transport-security": 'Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"',
+        "x-content-type-options": 'Header always set X-Content-Type-Options "nosniff"',
+        "referrer-policy": 'Header always set Referrer-Policy "strict-origin-when-cross-origin"',
+        "x-frame-options": 'Header always set X-Frame-Options "SAMEORIGIN"',
+        "permissions-policy": 'Header always set Permissions-Policy "camera=(), microphone=(), geolocation=()"',
+        "content-security-policy": 'Header always set Content-Security-Policy-Report-Only "{csp}"',
+        "server": "ServerTokens Prod\nServerSignature Off\nHeader unset X-Powered-By",
+    },
+    "headers-file": {  # Cloudflare Pages / Workers static assets / Netlify: public/_headers
+        "_template": "/*\n  {name}: {value}",
+    },
+    "astro": {"_template": 'res.headers.set("{name}", "{value}");  // in src/middleware.ts onRequest, after `const res = await next();`'},
+    "next": {"_template": "{{ key: '{name}', value: '{value}' }},  // next.config.js headers() → source: '/(.*)'"},
+    "php": {"_template": 'header("{name}: {value}");  // WordPress: in wp-content/mu-plugins/maggie-security-headers.php on send_headers'},
+    "cloudflare": {"_template": "Rules → Transform Rules → Modify Response Header → Set static: {name} = {value}"},
+}
+RECOMMENDED = {
+    "strict-transport-security": "max-age=31536000; includeSubDomains",
+    "x-content-type-options": "nosniff",
+    "referrer-policy": "strict-origin-when-cross-origin",
+    "x-frame-options": "SAMEORIGIN",
+    "permissions-policy": "camera=(), microphone=(), geolocation=()",
+}
+DISPLAY = {"strict-transport-security": "Strict-Transport-Security", "x-content-type-options": "X-Content-Type-Options",
+           "referrer-policy": "Referrer-Policy", "x-frame-options": "X-Frame-Options", "permissions-policy": "Permissions-Policy",
+           "content-security-policy": "Content-Security-Policy"}
+
+
+def detect_serving(project: Path, headers: dict[str, list[str]], requested: str) -> str:
+    if requested != "auto":
+        return requested
+    server = " ".join(headers.get("server", [])).lower()
+    powered = " ".join(headers.get("x-powered-by", [])).lower()
+    if "cf-ray" in headers and any((project / n).is_file() for n in ("wrangler.toml", "wrangler.json", "wrangler.jsonc")):
+        return "headers-file"
+    if "next.js" in powered or any(k.startswith("x-nextjs") for k in headers):
+        return "next"
+    if any(project.glob("astro.config.*")):
+        return "astro"
+    if (project / "wp-config.php").is_file() or "php" in powered:
+        return "php"
+    if "nginx" in server:
+        return "nginx"
+    if "apache" in server:
+        return "apache"
+    if "cf-ray" in headers or "cloudflare" in server:
+        return "cloudflare"
+    return "nginx"
+
+
+def snippet(layer: str, header: str, value: str) -> dict:
+    table = SNIPPETS.get(layer, SNIPPETS["nginx"])
+    # A new CSP always starts in report-only mode (PRD 04 section 7.4).
+    name = "Content-Security-Policy-Report-Only" if header == "content-security-policy" else DISPLAY.get(header, header)
+    text = table.get(header) or table.get("_template", SNIPPETS["nginx"].get(header, "")).format(name=name, value=value, csp=value)
+    if "{csp}" in text:
+        text = text.replace("{csp}", value)
+    return {"kind": layer, "text": text}
+
+
+class AssetOrigins(html.parser.HTMLParser):
+    """Collect script/style/img/connect origins from a page, to start a CSP in report-only mode."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.origins: dict[str, set[str]] = {"script-src": set(), "style-src": set(), "img-src": set(), "font-src": set(), "frame-src": set()}
+        self.inline_script = False
+
+    def handle_starttag(self, tag, attrs):
+        attrs = dict(attrs)
+        mapping = {"script": ("script-src", "src"), "img": ("img-src", "src"), "iframe": ("frame-src", "src")}
+        if tag == "link" and "stylesheet" in (attrs.get("rel") or ""):
+            self._add("style-src", attrs.get("href"))
+        elif tag in mapping:
+            directive, attr = mapping[tag]
+            if attrs.get(attr):
+                self._add(directive, attrs[attr])
+            elif tag == "script":
+                self.inline_script = True
+
+    def _add(self, directive: str, url: str | None) -> None:
+        if not url or url.startswith(("data:", "/", "./", "../")) or "://" not in url:
+            return
+        parts = urllib.parse.urlsplit(url)
+        self.origins[directive].add(f"{parts.scheme}://{parts.netloc}")
+
+
+def starter_csp(body: bytes) -> str:
+    parser = AssetOrigins()
+    try:
+        parser.feed(body.decode("utf-8", errors="replace")[:500_000])
+    except Exception:  # noqa: BLE001 - malformed HTML only means a weaker starting policy
+        pass
+    parts = ["default-src 'self'"]
+    for directive, origins in parser.origins.items():
+        if origins:
+            parts.append(f"{directive} 'self' {' '.join(sorted(origins))}")
+    parts += ["object-src 'none'", "base-uri 'self'", "frame-ancestors 'self'"]
+    return "; ".join(parts)
+
+
+def csp_problems(value: str) -> list[str]:
+    directives: dict[str, list[str]] = {}
+    for part in value.split(";"):
+        tokens = part.strip().split()
+        if tokens:
+            directives.setdefault(tokens[0].lower(), [t.lower() for t in tokens[1:]])
+    script = directives.get("script-src") or directives.get("default-src") or ["*"]
+    has_nonce = any(t.startswith(("'nonce-", "'sha256-", "'sha384-", "'sha512-")) for t in script)
+    problems = []
+    if "'unsafe-inline'" in script and not has_nonce and "'strict-dynamic'" not in script:
+        problems.append("allows inline scripts ('unsafe-inline' without a nonce or hash)")
+    if "'unsafe-eval'" in script:
+        problems.append("allows eval ('unsafe-eval')")
+    if any(t in ("*", "https:", "http:", "data:") for t in script):
+        problems.append("lets scripts load from anywhere (*, https: or data:)")
+    if not (directives.get("object-src") == ["'none'"] or directives.get("default-src") == ["'none'"]):
+        problems.append("does not set object-src 'none'")
+    if "base-uri" not in directives:
+        problems.append("does not set base-uri")
+    if "frame-ancestors" not in directives:
+        problems.append("does not set frame-ancestors (clickjacking)")
+    return problems
+
+
+def grade_response(ctx: core.Context, url: str, response: dict, layer: str, https: bool) -> list[dict]:
+    headers = response["headers"]
+    first = lambda name: (headers.get(name) or [None])[0]  # noqa: E731
+    findings = []
+    host = host_of(url)
+
+    def add(rule: str, title: str, severity: str, asvs: list[str], header: str | None = None, value: str | None = None,
+            summary: str = "", kind: str = "header", evidence: str | None = None) -> None:
+        snippets = [snippet(layer, header, value)] if header and value else []
+        findings.append(core.make_finding(
+            kind=kind, command="headers", primary_id=f"header-{rule}", site=ctx.site, title=title, severity=severity, severity_source="maggie",
+            confidence="confirmed", asvs_ids=asvs, target={"url": url, "host": host},
+            evidence=[{"path": url, "excerpt": evidence}] if evidence else [],
+            remediation={"summary": summary or title, "steps": [], "snippets": snippets,
+                         "references": ["https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Headers_Cheat_Sheet.html"], "cheat_sheet": "HTTP Headers"}))
+
+    hsts = first("strict-transport-security")
+    if https:
+        if not hsts:
+            add("hsts-missing", "No Strict-Transport-Security header: browsers may still load the site over plain HTTP", "high", ["V3.4.1"],
+                "strict-transport-security", RECOMMENDED["strict-transport-security"], "Add HSTS so browsers only use HTTPS.")
+        else:
+            match = re.search(r"max-age\s*=\s*\"?(\d+)", hsts, re.I)
+            age = int(match.group(1)) if match else 0
+            if age < 15_552_000:
+                add("hsts-short", f"HSTS max-age is {age} seconds (under six months)", "medium", ["V3.4.1"], "strict-transport-security",
+                    RECOMMENDED["strict-transport-security"], "Raise max-age to at least 15552000 (one year: 31536000).", evidence=hsts)
+    csp = first("content-security-policy")
+    csp_ro = first("content-security-policy-report-only")
+    if not csp:
+        starter = starter_csp(response["body"])
+        add("csp-missing", "No Content-Security-Policy header" + (" (a report-only policy is set)" if csp_ro else ""), "medium", ["V3.4.3"],
+            "content-security-policy", starter, "Start with this policy in report-only mode for a week, then switch to enforcing.")
+    else:
+        for problem in csp_problems(csp):
+            add(f"csp-{re.sub(r'[^a-z]+', '-', problem.split('(')[0].lower()).strip('-')[:40]}", f"Content-Security-Policy {problem}", "medium",
+                ["V3.4.3"], evidence=csp[:200], summary="Tighten the policy; use nonces or hashes for inline scripts.")
+    xcto = first("x-content-type-options")
+    if not xcto or xcto.strip().lower() != "nosniff":
+        add("xcto", "X-Content-Type-Options is not nosniff", "medium", ["V3.4.4"], "x-content-type-options", "nosniff", evidence=xcto)
+    xfo = first("x-frame-options")
+    if not xfo and not (csp and "frame-ancestors" in csp.lower()):
+        add("framing", "The site can be framed by other sites (no X-Frame-Options or frame-ancestors)", "medium", ["V3.4.6"],
+            "x-frame-options", RECOMMENDED["x-frame-options"])
+    elif xfo and "allow-from" in xfo.lower():
+        add("xfo-allow-from", "X-Frame-Options ALLOW-FROM is ignored by browsers", "medium", ["V3.4.6"], "x-frame-options", "SAMEORIGIN", evidence=xfo)
+    referrer = first("referrer-policy")
+    if not referrer:
+        add("referrer-missing", "No Referrer-Policy header", "medium", ["V3.4.5"], "referrer-policy", RECOMMENDED["referrer-policy"])
+    elif referrer.strip().lower() in ("unsafe-url", "no-referrer-when-downgrade"):
+        add("referrer-weak", f"Referrer-Policy {referrer} leaks full URLs to other sites", "medium", ["V3.4.5"], "referrer-policy",
+            RECOMMENDED["referrer-policy"], evidence=referrer)
+    if not first("permissions-policy"):
+        add("permissions-missing", "No Permissions-Policy header", "info", [], "permissions-policy", RECOMMENDED["permissions-policy"])
+    if not first("cross-origin-opener-policy"):
+        add("coop-missing", "No Cross-Origin-Opener-Policy header", "info", ["V3.4.8"])
+    for name in ("x-xss-protection", "expect-ct", "public-key-pins"):
+        if first(name):
+            add(f"deprecated-{name}", f"{name} is deprecated; remove it", "info", [], evidence=first(name))
+    for name in ("server", "x-powered-by", "x-aspnet-version"):
+        value = first(name)
+        if value and re.search(r"\d+\.\d+", value):
+            add(f"version-{name}", f"{name} header discloses a version ({value[:60]})", "low", ["V13.4.6"], "server", "off", evidence=value)
+    for cookie in headers.get("set-cookie") or []:
+        name = cookie.split("=", 1)[0].strip()
+        flags = cookie.lower()
+        sensitive = re.search(r"(?i)(sess|auth|token|login|sid|jwt|remember|wordpress_logged_in|wp-settings)", name)
+        missing = [flag for flag, present in (("Secure", "secure" in flags), ("HttpOnly", "httponly" in flags), ("SameSite", "samesite" in flags))
+                   if not present]
+        if missing and (sensitive or "Secure" in missing and https):
+            add(f"cookie-{name.lower()[:30]}", f"Cookie {name} is missing {', '.join(missing)}", "medium" if sensitive else "low",
+                ["V3.3.1"] if "Secure" in missing else ["V3.3.2"], kind="misconfiguration", evidence=f"{name}=…; {'; '.join(p.strip() for p in cookie.split(';')[1:])}"[:200],
+                summary="Set Secure, HttpOnly and SameSite=Lax (or Strict) on session cookies.")
+    origin = first("access-control-allow-origin")
+    if origin and origin.strip() == "*" and (first("access-control-allow-credentials") or "").lower() == "true":
+        add("cors-wildcard-credentials", "CORS allows any origin with credentials", "high", ["V3.4.2"], kind="misconfiguration",
+            evidence="Access-Control-Allow-Origin: *; Allow-Credentials: true")
+    return findings
+
+
+def headers_cmd(ctx: core.Context):
+    args = ctx.args
+    url = args.url if "://" in (args.url or "") else f"https://{args.url}"
+    host = host_of(url)
+    mode = require_ownership(ctx, host, args.public_check)
+    paths = args.paths or (ctx.state.config().get("headers") or {}).get("paths") or ["/"]
+    findings: list[dict] = []
+    https = url.startswith("https://")
+    layer = "nginx"
+    for path in paths[:5]:
+        target = urllib.parse.urljoin(url, path)
+        try:
+            response = fetch(target)
+        except (OSError, ssl.SSLError) as error:
+            ctx.degrade("target-site", f"{target}: {str(error)[:200]}")
+            continue
+        if response.get("left_domain"):
+            ctx.run["inputs"].setdefault("notes", []).append(f"{target} redirects to another domain ({response['left_domain']}); not followed")
+            continue
+        layer = detect_serving(ctx.project, response["headers"], args.serving)
+        findings += grade_response(ctx, response["url"], response, layer, response["url"].startswith("https://"))
+        if mode == "public-check":
+            break
+    if https and mode == "verified":
+        try:
+            plain = fetch(f"http://{host}/", follow=False)
+            location = (plain["headers"].get("location") or [""])[0]
+            if plain["status"] not in (301, 302, 307, 308) or not location.startswith("https://"):
+                findings.append(core.make_finding(kind="misconfiguration", command="headers", primary_id="http-no-redirect", site=ctx.site,
+                                                  title="Plain HTTP does not redirect to HTTPS", severity="medium", severity_source="maggie",
+                                                  confidence="confirmed", target={"url": f"http://{host}/", "host": host}, asvs_ids=["V12.2.1"],
+                                                  remediation={"summary": "Redirect every http:// request to https:// with a 301.", "steps": [],
+                                                               "snippets": [{"kind": "nginx", "text": "server { listen 80; server_name _; return 301 https://$host$request_uri; }"}],
+                                                               "references": [], "cheat_sheet": None}))
+        except OSError:
+            pass
+    ctx.run["inputs"].update({"url": url, "paths": paths[:5], "serving": layer, "ownership": mode})
+    if mode == "public-check":
+        ctx.run["inputs"]["label"] = "unverified domain (public check)"
+        ctx.args.no_ledger = True
+    return ctx.finish(findings, covered=[core.finding_locator(None, {"url": f["target"]["url"]}) for f in findings] or [f"url:{url}"])
+
+
+# --------------------------------------------------------------------------- TLS
+
+
+TESTSSL_SEVERITY = {"CRITICAL": "critical", "HIGH": "high", "MEDIUM": "medium", "LOW": "low", "WARN": "info"}
+
+
+def testssl_to_findings(ctx: core.Context, items: list[dict], host: str, port: int) -> list[dict]:
+    findings = []
+    for item in items:
+        severity = TESTSSL_SEVERITY.get(str(item.get("severity", "")).upper())
+        if not severity:
+            continue
+        if severity == "info" and str(item.get("severity", "")).upper() == "WARN":
+            ctx.run["inputs"].setdefault("testssl_warnings", []).append(item.get("id"))
+        cves = [c for c in str(item.get("cve") or "").split() if c.upper().startswith("CVE-")]
+        cwes = [c for c in str(item.get("cwe") or "").split() if re.match(r"^CWE-\d+$", c)]
+        rule = str(item.get("id") or "tls")
+        asvs = ["V12.2.2"] if rule.startswith("cert") else ["V12.1.2"] if rule.lower().startswith(("cipher", "rc4", "3des", "sweet32")) else ["V12.1.1"]
+        findings.append(core.make_finding(
+            kind="tls", command="tls", primary_id=f"tls-{rule}", site=ctx.site, title=f"TLS {rule}: {core.clean_excerpt(item.get('finding') or '', 150)}",
+            severity=severity, severity_source="tool", confidence="confirmed", aliases=cves, cwe_ids=cwes, asvs_ids=asvs,
+            target={"host": host, "url": f"https://{host}:{port}"}, tool="testssl.sh", rule_id=rule,
+            remediation={"summary": "Adjust the server's TLS settings (protocols, ciphers, certificate).", "steps": [], "snippets": [],
+                         "references": ["https://ssl-config.mozilla.org/"], "cheat_sheet": "Transport Layer Security"}))
+    return findings
+
+
+def native_tls(ctx: core.Context, host: str, port: int, ip: str | None) -> list[dict]:
+    findings = []
+    address = ip or host
+
+    def add(rule: str, title: str, severity: str, summary: str, evidence: str | None = None) -> None:
+        asvs = ["V12.2.2"] if rule.startswith("cert") else ["V12.1.1"]
+        findings.append(core.make_finding(kind="tls", command="tls", primary_id=f"tls-{rule}", site=ctx.site, title=title, severity=severity,
+                                          severity_source="maggie", confidence="confirmed", asvs_ids=asvs,
+                                          target={"host": host, "url": f"https://{host}:{port}"}, tool="maggie-tls-native",
+                                          evidence=[{"path": f"{host}:{port}", "excerpt": evidence}] if evidence else [],
+                                          remediation={"summary": summary, "steps": [], "snippets": [],
+                                                       "references": ["https://ssl-config.mozilla.org/"], "cheat_sheet": "Transport Layer Security"}))
+
+    context = ssl.create_default_context()
+    try:
+        with socket.create_connection((address, port), timeout=10) as raw, context.wrap_socket(raw, server_hostname=host) as conn:
+            cert = conn.getpeercert()
+            version = conn.version()
+            cipher = conn.cipher()
+    except ssl.SSLCertVerificationError as error:
+        add("cert-invalid", f"The certificate is not trusted for {host}: {error.verify_message}", "high",
+            "Install a valid certificate for this name (e.g. Let's Encrypt) including the intermediate chain.", str(error)[:200])
+        return findings
+    except (OSError, ssl.SSLError) as error:
+        ctx.degrade("target-site", f"{host}:{port}: {str(error)[:200]}")
+        return findings
+    not_after = dt.datetime.strptime(cert["notAfter"], "%b %d %H:%M:%S %Y %Z").replace(tzinfo=dt.timezone.utc)
+    days = (not_after - core.utcnow()).days
+    if days < 0:
+        add("cert-expired", f"The certificate expired on {not_after.date()}", "critical", "Renew the certificate now.")
+    elif days < 14:
+        add("cert-expiring", f"The certificate expires in {days} days ({not_after.date()})", "high", "Renew it now and check automatic renewal.")
+    elif days < 30:
+        add("cert-expiring-soon", f"The certificate expires in {days} days ({not_after.date()})", "medium", "Check that automatic renewal works.")
+    ctx.run["inputs"]["negotiated"] = {"version": version, "cipher": cipher[0] if cipher else None, "cert_expires": not_after.date().isoformat()}
+    for label, proto in (("TLSv1", getattr(ssl.TLSVersion, "TLSv1", None)), ("TLSv1.1", getattr(ssl.TLSVersion, "TLSv1_1", None))):
+        if proto is None:
+            continue
+        probe = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+        probe.check_hostname = False
+        probe.verify_mode = ssl.CERT_NONE
+        try:
+            probe.minimum_version = proto
+            probe.maximum_version = proto
+            probe.set_ciphers("ALL:@SECLEVEL=0")
+        except (ValueError, ssl.SSLError):
+            ctx.run["inputs"].setdefault("not_testable", []).append(label)
+            continue
+        try:
+            with socket.create_connection((address, port), timeout=10) as raw, probe.wrap_socket(raw, server_hostname=host) as conn:
+                accepted = conn.version() == label
+        except ssl.SSLError as error:
+            if "no protocols available" in str(error).lower() or "unsupported protocol" in str(error).lower() and "alert" not in str(error).lower():
+                ctx.run["inputs"].setdefault("not_testable", []).append(label)
+            accepted = False
+        except OSError:
+            accepted = False
+        if accepted:
+            add(f"protocol-{label}", f"The server still accepts {label}", "medium", f"Disable {label}; allow TLS 1.2 and 1.3 only.")
+    if version not in ("TLSv1.3",):
+        probe = ssl.create_default_context()
+        try:
+            probe.minimum_version = ssl.TLSVersion.TLSv1_3
+            with socket.create_connection((address, port), timeout=10) as raw, probe.wrap_socket(raw, server_hostname=host):
+                pass
+        except (OSError, ssl.SSLError, ValueError):
+            add("no-tls13", "TLS 1.3 is not offered", "low", "Enable TLS 1.3 (faster and safer).")
+    return findings
+
+
+def tls_cmd(ctx: core.Context):
+    args = ctx.args
+    host = host_of(args.host)
+    port = args.port
+    mode = require_ownership(ctx, host, args.public_check)
+    ip = None
+    if args.ip:
+        if mode != "verified":
+            raise core.PolicyError("--ip needs a verified domain")
+        ip = args.ip
+    findings: list[dict] = []
+    engine = args.engine
+    if engine == "auto":
+        engine = "testssl" if core.resolve_tool("testssl.sh", ctx.lock)[1] is not None else "native"
+    if engine == "testssl":
+        with tempfile.TemporaryDirectory() as tmp:
+            out = Path(tmp) / "tls.json"
+            argv = ["--warnings", "off", "--sneaky", "--color", "0", "--jsonfile-pretty", str(out), "--severity", "LOW"]
+            if args.mode == "quick":
+                argv.append("--fast")
+            if ip:
+                argv += ["--ip", ip]
+            argv.append(f"{host}:{port}")
+            core.run_tool("testssl.sh", argv, ctx.lock, timeout=1200)
+            data = json.loads(out.read_text() or "{}") if out.is_file() else {}
+            items = data.get("scanResult", [{}])[0] if isinstance(data.get("scanResult"), list) else {}
+            flat = []
+            for section, entries in (items.items() if isinstance(items, dict) else []):
+                if isinstance(entries, list):
+                    flat += [e for e in entries if isinstance(e, dict)]
+            findings = testssl_to_findings(ctx, flat, host, port)
+            ctx.run["tools"].append({"name": "testssl.sh", "version": ctx.lock["tools"]["testssl.sh"]["version"], "sha256": None})
+    else:
+        findings = native_tls(ctx, host, port, ip)
+        ctx.run["tools"].append({"name": "maggie-tls-native", "version": core.maggie_version(), "sha256": None})
+    try:
+        edge = fetch(f"https://{host}/", follow=False, timeout=10)
+        if "cf-ray" in edge["headers"]:
+            ctx.run["inputs"]["note"] = "measured at Cloudflare's edge; origin TLS is separate (use --ip with the origin address)"
+    except OSError:
+        pass
+    ctx.run["inputs"].update({"host": host, "port": port, "engine": engine, "ownership": mode})
+    if mode == "public-check":
+        ctx.args.no_ledger = True
+    return ctx.finish(findings, covered=[f"url:https://{host}:{port}"])
+
+
+# --------------------------------------------------------------------------- web-scan (httpx -> nuclei, safe profile)
+
+
+SAFE_EXCLUDE_TAGS = ["intrusive", "dos", "fuzz", "fuzzing", "bruteforce", "brute-force", "authenticated", "osint", "default-login", "headless",
+                     "oast", "file-upload", "sqli-time", "rce-blind"]
+NUCLEI_KIND = {"exposures": "exposure", "misconfiguration": "misconfiguration", "ssl": "tls", "vulnerabilities": "vulnerability",
+               "cves": "vulnerability", "default-logins": "exposure", "technologies": "misconfiguration"}
+
+
+def nuclei_to_findings(ctx: core.Context, lines: list[str]) -> list[dict]:
+    findings = []
+    for line in lines:
+        try:
+            item = json.loads(line)
+        except ValueError:
+            continue
+        info = item.get("info") or {}
+        classification = info.get("classification") or {}
+        cves = [c.upper() for c in classification.get("cve-id") or [] if c]
+        cvss = None
+        if classification.get("cvss-score"):
+            try:
+                cvss = {"version": "3.1", "score": float(classification["cvss-score"]), "vector": classification.get("cvss-metrics") or ""}
+            except (TypeError, ValueError):
+                cvss = None
+        epss = None
+        if classification.get("epss-score") is not None:
+            try:
+                epss = {"score": float(classification["epss-score"]), "percentile": float(classification.get("epss-percentile") or 0)}
+            except (TypeError, ValueError):
+                epss = None
+        tags = info.get("tags") or []
+        tags = tags.split(",") if isinstance(tags, str) else tags
+        path = str(item.get("template-path") or item.get("template") or "")
+        kind = "vulnerability" if cves else next((v for k, v in NUCLEI_KIND.items() if f"{k}/" in path or path.startswith(k)), "misconfiguration")
+        meta = info.get("metadata") or {}
+        affected = None
+        if meta.get("product") or meta.get("vendor"):
+            component = "wordpress-plugin" if "wp-plugin" in tags else "wordpress-theme" if "wp-theme" in tags else "service"
+            affected = {"purl": None, "ecosystem": None, "name": str(meta.get("product") or meta.get("vendor")), "version": None,
+                        "component_type": component, "direct": None, "scope": "runtime"}
+        extracted = item.get("extracted-results") or []
+        findings.append(core.make_finding(
+            kind=kind, command="web-scan", primary_id=cves[0] if cves else str(item.get("template-id")), site=ctx.site,
+            title=core.clean_excerpt(info.get("name") or item.get("template-id") or "nuclei finding", 200),
+            severity={"unknown": "info"}.get(info.get("severity"), info.get("severity") or "info"), severity_source="tool", cvss=cvss, epss=epss,
+            confidence="confirmed" if meta.get("verified") else "likely", aliases=cves + [str(item.get("template-id"))],
+            cwe_ids=[c.upper() for c in classification.get("cwe-id") or [] if re.match(r"(?i)^cwe-\d+$", c)],
+            kev={"listed": True} if {"kev", "vkev"} & set(tags) else None, affected=affected,
+            target={"url": item.get("matched-at") or item.get("host"), "host": host_of(str(item.get("host") or ""))},
+            evidence=[{"path": str(item.get("matched-at") or ""), "excerpt": core.clean_excerpt(", ".join(map(str, extracted))[:200])}] if extracted else [],
+            tool="nuclei", rule_id=str(item.get("template-id")),
+            remediation={"summary": core.clean_excerpt(info.get("remediation") or "See the references.", 300), "steps": [], "snippets": [],
+                         "references": (info.get("reference") or [])[:5] if isinstance(info.get("reference"), list) else [], "cheat_sheet": None},
+            untrusted={"description": core.clean_excerpt(info.get("description") or "", 400)} if info.get("description") else None))
+    return findings
+
+
+def web_scan(ctx: core.Context):
+    args = ctx.args
+    url = args.url if "://" in args.url else f"https://{args.url}"
+    host = host_of(url)
+    if require_ownership(ctx, host, False) != "verified":
+        raise core.PolicyError("web-scan needs a verified domain")
+    lock_dir = ctx.state.path("locks")
+    lock_dir.mkdir(parents=True, exist_ok=True)
+    lock = lock_dir / f"web-scan-{registrable(host)}.lock"
+    if lock.exists() and (core.utcnow().timestamp() - lock.stat().st_mtime) < 3600:
+        raise core.PolicyError(f"another web-scan of {registrable(host)} is running (lock {lock.name})")
+    lock.write_text(core.iso())
+    try:
+        tags = ["misconfig", "exposure", "ssl", "tech"]
+        with tempfile.TemporaryDirectory() as tmp:
+            fingerprint = {}
+            if core.resolve_tool("httpx", ctx.lock)[1] is not None:
+                out = Path(tmp) / "httpx.jsonl"
+                core.run_tool("httpx", ["-u", url, "-j", "-sc", "-title", "-server", "-td", "-cdn", "-tls-grab", "-fr", "-o", str(out)],
+                              ctx.lock, timeout=300)
+                if out.is_file() and out.read_text().strip():
+                    fingerprint = json.loads(out.read_text().splitlines()[0])
+            tech = " ".join(fingerprint.get("tech") or []).lower()
+            for needle, extra in (("wordpress", ["wordpress", "wp-plugin", "wp-theme"]), ("nginx", ["nginx"]), ("php", ["php"]),
+                                  ("next.js", ["nextjs"]), ("express", ["express", "nodejs"]), ("laravel", ["laravel"]), ("apache", ["apache"])):
+                if needle in tech:
+                    tags += extra
+            if args.profile == "full-safe":
+                tags.append("tech")
+            jsonl = Path(tmp) / "nuclei.jsonl"
+            argv = ["-u", url, "-tags", ",".join(dict.fromkeys(tags)), "-etags", ",".join(SAFE_EXCLUDE_TAGS),
+                    "-severity", "info,low,medium,high,critical" if args.profile == "full-safe" else "low,medium,high,critical",
+                    "-rl", str(min(args.rate, 10)), "-c", "5", "-bs", "5", "-timeout", "10", "-retries", "1", "-mhe", "10", "-nc",
+                    "-jle", str(jsonl)]
+            templates = ctx.state.path("db", "nuclei-templates")
+            if templates.is_dir():
+                argv += ["-t", str(templates)]
+            if args.templates_id:
+                argv += ["-id", args.templates_id]
+            proc = core.run_tool("nuclei", argv, ctx.lock, timeout=args.max_minutes * 60)
+            lines = jsonl.read_text(encoding="utf-8").splitlines() if jsonl.is_file() else []
+            if proc.returncode not in (0, 1) and not lines:
+                ctx.degrade("nuclei", core.clean_excerpt(proc.stderr.decode(errors="replace"), 200))
+            findings = nuclei_to_findings(ctx, lines)
+            ctx.run["tools"].append({"name": "nuclei", "version": ctx.lock["tools"]["nuclei"]["version"], "sha256": None})
+            ctx.run["inputs"].update({"url": url, "tags": tags, "fingerprint": {k: fingerprint.get(k) for k in ("tech", "webserver", "cdn_name", "status_code")}})
+    finally:
+        lock.unlink(missing_ok=True)
+    return ctx.finish(findings, covered=[f"url:{url}"] if not ctx.run["degraded"] else [])
+
+
+# --------------------------------------------------------------------------- ZAP baseline (passive)
+
+
+ZAP_IMAGE = "ghcr.io/zaproxy/zaproxy:stable"
+ZAP_IGNORE = {"10020", "10021", "10035", "10038", "10063"}  # headers already graded by `headers`
+
+
+def zap_to_findings(ctx: core.Context, report: dict) -> list[dict]:
+    findings = []
+    for site in report.get("site") or []:
+        for alert in site.get("alerts") or []:
+            plugin = str(alert.get("pluginid"))
+            if plugin in ZAP_IGNORE:
+                continue
+            risk = {"3": "high", "2": "medium", "1": "low", "0": "info"}.get(str(alert.get("riskcode")), "info")
+            confidence = {"3": "confirmed", "4": "confirmed", "2": "likely", "1": "possible"}.get(str(alert.get("confidence")), "possible")
+            instances = alert.get("instances") or []
+            first = instances[0] if instances else {}
+            cwe = str(alert.get("cweid") or "")
+            findings.append(core.make_finding(
+                kind="misconfiguration", command="zap-baseline", primary_id=f"zap-{plugin}", site=ctx.site,
+                title=core.clean_excerpt(re.sub(r"<[^>]+>", "", alert.get("alert") or alert.get("name") or plugin), 200),
+                severity=risk, severity_source="tool", confidence=confidence, cwe_ids=[f"CWE-{cwe}"] if cwe.isdigit() and cwe != "0" else [],
+                target={"url": first.get("uri") or site.get("@name"), "host": host_of(site.get("@name") or "")},
+                evidence=[{"path": i.get("uri", ""), "excerpt": core.clean_excerpt(i.get("evidence") or "", 200)} for i in instances[:5]],
+                tool="zap-baseline", rule_id=plugin,
+                remediation={"summary": core.clean_excerpt(re.sub(r"<[^>]+>", " ", alert.get("solution") or ""), 300), "steps": [], "snippets": [],
+                             "references": re.findall(r"https?://[^\s<]+", alert.get("reference") or "")[:4], "cheat_sheet": None}))
+    return findings
+
+
+def zap_baseline(ctx: core.Context):
+    args = ctx.args
+    url = args.url if "://" in args.url else f"https://{args.url}"
+    if require_ownership(ctx, host_of(url), False) != "verified":
+        raise core.PolicyError("zap-baseline needs a verified domain")
+    docker = shutil.which("docker")
+    if not docker:
+        raise core.ToolError("zap-baseline needs Docker (it runs the official ZAP image, passive rules only)")
+    with tempfile.TemporaryDirectory() as tmp:
+        conf = Path(tmp) / "maggie-zap-rules.conf"
+        conf.write_text("".join(f"{rule}\tIGNORE\t(maggie headers covers this)\n" for rule in sorted(ZAP_IGNORE)))
+        os.chmod(tmp, 0o777)
+        argv = [docker, "run", "--rm", "-v", f"{tmp}:/zap/wrk:rw", args.image or ZAP_IMAGE, "zap-baseline.py", "-t", url, "-m", str(args.minutes),
+                "-J", "zap.json", "-I", "-c", "maggie-zap-rules.conf", "-z", "-silent"]
+        proc = subprocess.run(argv, capture_output=True, timeout=(args.minutes + 10) * 60, check=False)
+        report_path = Path(tmp) / "zap.json"
+        if not report_path.is_file():
+            ctx.degrade("zap", core.clean_excerpt(proc.stderr.decode(errors="replace"), 200))
+            return ctx.finish([])
+        findings = zap_to_findings(ctx, json.loads(report_path.read_text()))
+    ctx.run["tools"].append({"name": "zap-baseline", "version": args.image or ZAP_IMAGE, "sha256": None})
+    return ctx.finish(findings, covered=[f"url:{url}"])
+
+
+# --------------------------------------------------------------------------- registration
+
+
+def _dv(p: argparse.ArgumentParser) -> None:
+    p.add_argument("action", choices=["start", "check", "status", "revoke"])
+    p.add_argument("--domain")
+    p.add_argument("--method", choices=["dns", "file"], default="dns")
+    p.add_argument("--rotate", action="store_true")
+
+
+def _headers(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--url", required=True)
+    p.add_argument("--paths", nargs="*", help="paths to check (default / plus config headers.paths; at most 5)")
+    p.add_argument("--serving", choices=["auto", "nginx", "apache", "cloudflare", "headers-file", "astro", "next", "php"], default="auto")
+    p.add_argument("--public-check", action="store_true", help="one GET on an unverified domain, labelled unverified (interactive only)")
+
+
+def _tls(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--host", required=True)
+    p.add_argument("--port", type=int, default=443)
+    p.add_argument("--ip", help="origin IP to test behind a CDN (verified domain only)")
+    p.add_argument("--mode", choices=["quick", "full"], default="quick")
+    p.add_argument("--engine", choices=["auto", "testssl", "native"], default="auto")
+    p.add_argument("--public-check", action="store_true")
+
+
+def _scan(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--url", required=True)
+    p.add_argument("--profile", choices=["safe", "full-safe"], default="safe")
+    p.add_argument("--templates-id", help="run one template id (e.g. after a new CVE template)")
+    p.add_argument("--rate", type=int, default=10, help="requests per second (max 10)")
+    p.add_argument("--max-minutes", type=int, default=15)
+
+
+def _zap(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--url", required=True)
+    p.add_argument("--minutes", type=int, default=5)
+    p.add_argument("--image", help="pinned ZAP image reference (default ghcr.io/zaproxy/zaproxy:stable)")
+
+
+COMMANDS = [
+    core.Command("domain-verify", "prove you control a domain (DNS TXT or a token file) before any active check", ["doh", "dns", "target-site"], _dv,
+                 domain_verify, findings=False),
+    core.Command("headers", "grade HTTP security headers and cookies per path, with fix snippets for your server", ["target-site", "doh", "dns"],
+                 _headers, headers_cmd),
+    core.Command("tls", "TLS protocols, certificate expiry and trust (testssl.sh when installed)", ["target-site", "doh", "dns"], _tls, tls_cmd),
+    core.Command("web-scan", "safe nuclei scan of your verified site (no fuzzing, brute force or OAST; 10 req/s)", ["target-site", "doh", "dns"],
+                 _scan, web_scan),
+    core.Command("zap-baseline", "weekly passive ZAP baseline scan of your verified site (Docker)", ["target-site", "doh", "dns"], _zap, zap_baseline,
+                 routine_safe=False),
+]