@topy-ai/maggie 0.7.55 → 0.7.56

package/bundled-tools/clis/maggie_security_health.py

@@ -0,0 +1,415 @@
+#!/usr/bin/env python3
+"""Health and uptime with Gatus (docs/maggie-security/08-health-uptime-prd.md):
+``uptime-init``, ``uptime-deploy``, ``uptime-status``, ``uptime-push``.
+
+- ``uptime-init`` writes a Gatus configuration folder for the site's verified
+  domains (homepage status/latency/certificate/domain expiry/brand text,
+  DNS, HTTP→HTTPS, site-type extras) plus heartbeat endpoints for the
+  security jobs. Secrets are ``${ENV}`` references, never values.
+- ``uptime-deploy`` writes a plan (Docker on 127.0.0.1 behind nginx, image
+  pinned by digest, basic auth in Gatus); it never runs it.
+- ``uptime-status`` reads a running Gatus (and optionally an Uptime Kuma
+  status page) and turns failures, low uptime, slow responses, certificate
+  and domain expiry, DNS failures and missed heartbeats into findings.
+- ``uptime-push`` reports a job's result to its Gatus heartbeat endpoint.
+
+Gatus facts used here were checked in the TwiN/gatus source: the endpoint key
+format (``config/key/key.go``), the custom alert placeholders, the external
+endpoint route and its Bearer token, and the raw uptime route (a float).
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import re
+import urllib.parse
+from pathlib import Path
+
+import maggie_security_core as core
+import maggie_security_web as web
+
+GATUS_IMAGE = "ghcr.io/twin/gatus:v5.37.0@sha256:094eb186e55235db367e90e9d56140e5897b7044c41de23cde4cc18e6da1242e"
+HEARTBEATS = {"vuln-watch": "26h", "eol-watch": "26h", "report-daily": "26h", "report-weekly": "8d", "logs-sigma": "26h", "host-quick": "8d"}
+
+
+def gatus_key(group: str, name: str) -> str:
+    """Port of Gatus config/key ConvertGroupAndNameToKey."""
+    def sanitize(text: str) -> str:
+        text = text.strip().lower()
+        for char in "/_., #+&":
+            text = text.replace(char, "-")
+        return text
+    return f"{sanitize(group)}_{sanitize(name)}"
+
+
+def yaml_str(value: str) -> str:
+    return json.dumps(value)  # a JSON string is a valid YAML double-quoted scalar
+
+
+# --------------------------------------------------------------------------- uptime-init
+
+
+def site_list(ctx: core.Context) -> list[dict]:
+    args = ctx.args
+    if args.sites:
+        return core.read_json(Path(args.sites))
+    domains = (ctx.state.config().get("domains") or [])
+    stack_path = ctx.state.path("inventory", "stack.json")
+    site_type = "unknown"
+    if stack_path.is_file():
+        stack = core.read_json(stack_path)
+        domains = domains or stack["site"].get("domains") or []
+        site_type = stack["site"].get("type") or site_type
+    if not domains:
+        raise core.UsageError("no domains: set domains in .maggie/security/config.json or pass --sites FILE")
+    return [{"id": re.sub(r"[^a-z0-9-]+", "-", d.lower()), "url": f"https://{d}/", "type": site_type, "brand_text": args.brand_text} for d in domains]
+
+
+def endpoint_yaml(entry: dict) -> list[str]:
+    lines = [f"  - name: {yaml_str(entry['name'])}", f"    group: {yaml_str(entry['group'])}", f"    url: {yaml_str(entry['url'])}",
+             f"    interval: {entry.get('interval', '5m')}"]
+    if entry.get("dns"):
+        lines += ["    dns:", f"      query-name: {yaml_str(entry['dns']['query-name'])}", f"      query-type: {yaml_str(entry['dns']['query-type'])}"]
+    if entry.get("ignore_redirect"):
+        lines += ["    client:", "      ignore-redirect: true"]
+    lines.append("    conditions:")
+    lines += [f"      - {yaml_str(c)}" for c in entry["conditions"]]
+    if entry.get("alert", True):
+        lines += ["    alerts:", f"      - type: {entry.get('alert_type', 'custom')}", "        failure-threshold: 3", "        success-threshold: 2",
+                  "        send-on-resolved: true", f"        description: {yaml_str(entry['group'] + ' ' + entry['name'])}"]
+    return lines
+
+
+def site_endpoints(site: dict, interval: str, alert_type: str) -> list[dict]:
+    url = site["url"].rstrip("/") + "/"
+    host = web.host_of(url)
+    group = site["id"]
+    home = ["[STATUS] == 200", "[RESPONSE_TIME] < 1000", "[CERTIFICATE_EXPIRATION] > 720h"]
+    if site.get("brand_text"):
+        home.append(f"[BODY] == pat(*{site['brand_text']}*)")
+    endpoints = [{"name": "homepage", "group": group, "url": url, "interval": interval, "conditions": home},
+                 {"name": "domain-expiry", "group": group, "url": url, "interval": "1h", "conditions": ["[DOMAIN_EXPIRATION] > 720h"]},
+                 {"name": "dns-a", "group": group, "url": "1.1.1.1", "interval": "15m", "dns": {"query-name": host, "query-type": "A"},
+                  "conditions": ["[DNS_RCODE] == NOERROR"]},
+                 {"name": "https-redirect", "group": group, "url": f"http://{host}/", "interval": "30m", "ignore_redirect": True,
+                  "conditions": ["[STATUS] == 301"]}]
+    site_type = site.get("type")
+    if site_type == "wordpress":
+        endpoints += [{"name": "wp-login", "group": group, "url": url + "wp-login.php", "interval": "15m", "conditions": ["[STATUS] < 500"]},
+                      {"name": "wp-json", "group": group, "url": url + "wp-json/", "interval": "15m", "conditions": ["[STATUS] < 500"]},
+                      {"name": "xmlrpc-blocked", "group": group, "url": url + "xmlrpc.php", "interval": "1h",
+                       "conditions": [f"[STATUS] == {site.get('xmlrpc_status', 403)}"]}]
+    elif site_type in ("static", "workers", "astro"):
+        endpoints.append({"name": "sitemap", "group": group, "url": url + "sitemap.xml", "interval": "30m", "conditions": ["[STATUS] == 200"]})
+    if site.get("health_path"):
+        endpoints.append({"name": "health", "group": group, "url": url + site["health_path"].lstrip("/"), "interval": interval,
+                          "conditions": ["[STATUS] == 200"]})
+    for entry in endpoints:
+        entry["alert_type"] = alert_type
+        entry["alert"] = alert_type != "none"
+    return endpoints
+
+
+def uptime_init(ctx: core.Context) -> dict:
+    args = ctx.args
+    sites = site_list(ctx)
+    unverified = []
+    for site in sites:
+        try:
+            web.require_ownership(ctx, web.host_of(site["url"]), False)
+        except core.PolicyError:
+            unverified.append(web.registrable(web.host_of(site["url"])))
+    if unverified:
+        raise core.PolicyError(f"Gatus would poll these every few minutes, so they must be verified first: {', '.join(sorted(set(unverified)))}")
+    if args.alert == "ntfy" and args.ntfy_url and "ntfy.sh" in args.ntfy_url and not args.allow_public_ntfy:
+        raise core.PolicyError("public ntfy.sh topics can be read by anyone who guesses the name; use a self-hosted ntfy or pass --allow-public-ntfy")
+    for site in sites:
+        if site.get("brand_text"):
+            response = web.fetch(site["url"], timeout=15)
+            if site["brand_text"].lower() not in response["body"].decode("utf-8", errors="replace").lower():
+                raise core.UsageError(f"brand text {site['brand_text']!r} is not on {site['url']}; choose stable text from the page")
+    out = Path(args.out) if Path(args.out).is_absolute() else ctx.project / args.out
+    out.mkdir(parents=True, exist_ok=True)
+    alert_type = {"webhook": "custom", "ntfy": "ntfy", "email": "email", "none": "none"}[args.alert]
+    global_lines = ["# Maggie Gatus settings (generated by maggie security uptime-init; secrets are environment variables)",
+                    "storage:", "  type: sqlite", "  path: /data/gatus.db", "  maximum-number-of-results: 200", "  maximum-number-of-events: 50",
+                    "security:", "  basic:", '    username: "${GATUS_BASIC_USER}"', '    password-bcrypt-base64: "${GATUS_BASIC_PASSWORD_BCRYPT_B64}"']
+    if alert_type == "custom":
+        global_lines += ["alerting:", "  custom:", '    url: "${MAGGIE_ALERT_WEBHOOK_URL}"', '    method: "POST"', "    body: |",
+                         '      {"source":"gatus","endpoint":"[ENDPOINT_GROUP]/[ENDPOINT_NAME]","status":"[ALERT_TRIGGERED_OR_RESOLVED]","description":"[ALERT_DESCRIPTION]"}']
+    elif alert_type == "ntfy":
+        global_lines += ["alerting:", "  ntfy:", f"    url: {yaml_str(args.ntfy_url or 'https://ntfy.example.com')}", '    topic: "${MAGGIE_NTFY_TOPIC}"',
+                         '    token: "${MAGGIE_NTFY_TOKEN}"', "    priority: 4"]
+    elif alert_type == "email":
+        global_lines += ["alerting:", "  email:", '    from: "${MAGGIE_ALERT_FROM}"', '    host: "${MAGGIE_SMTP_HOST}"', "    port: 587",
+                         '    username: "${MAGGIE_SMTP_USER}"', '    password: "${MAGGIE_SMTP_PASSWORD}"', '    to: "${MAGGIE_ALERT_TO}"']
+    files = {"00-maggie-global.yaml": "\n".join(global_lines) + "\n"}
+    for site in sites:
+        lines = [f"# {site['url']} ({site.get('type') or 'site'})", "endpoints:"]
+        for entry in site_endpoints(site, args.interval, alert_type):
+            lines += endpoint_yaml(entry)
+        files[f"10-site-{site['id']}.yaml"] = "\n".join(lines) + "\n"
+    if args.with_heartbeats:
+        lines = ["# Heartbeats for Maggie security jobs: each job reports with `maggie security uptime-push`; silence raises an alert.",
+                 "external-endpoints:"]
+        for job, interval in HEARTBEATS.items():
+            lines += [f"  - name: {yaml_str(job)}", '    group: "maggie-security"', f'    token: "${{MAGGIE_HEARTBEAT_TOKEN}}"',
+                      "    heartbeat:", f"      interval: {interval}"]
+            if alert_type != "none":
+                lines += ["    alerts:", f"      - type: {alert_type}", f"        description: {yaml_str('security job ' + job + ' did not report')}"]
+        files["90-maggie-heartbeats.yaml"] = "\n".join(lines) + "\n"
+    files["README.md"] = ("# Gatus configuration (Maggie)\n\nGenerated by `maggie security uptime-init`. Each site file checks the homepage "
+                          "(status 200, under 1 s, certificate valid for 30+ days" + (", brand text present" if any(s.get("brand_text") for s in sites) else "")
+                          + "), domain expiry, DNS and the HTTP→HTTPS redirect.\nSet the environment variables named in `00-maggie-global.yaml` "
+                          "in the container's env file (mode 0600). Deploy with the plan from `maggie security uptime-deploy`.\n")
+    for name, text in files.items():
+        (out / name).write_text(text, encoding="utf-8")
+    return {"schema": "maggie-security-uptime-init.v1", "dir": str(out), "files": sorted(files), "sites": [s["url"] for s in sites],
+            "endpoints": sum(len(site_endpoints(s, args.interval, alert_type)) for s in sites), "heartbeats": sorted(HEARTBEATS) if args.with_heartbeats else []}
+
+
+# --------------------------------------------------------------------------- uptime-deploy (plan only)
+
+
+def uptime_deploy(ctx: core.Context) -> dict:
+    args = ctx.args
+    host_alias = args.host_alias or "ops1"
+    target = ((ctx.state.config().get("hosts") or {}).get(host_alias)) or f"deploy@{host_alias}"
+    plan_id = f"up_{core.iso()[:10]}_{host_alias}"
+    hostname = args.hostname or "status.example.com"
+    compose = "\n".join([
+        "services:", "  gatus:", f"    image: {GATUS_IMAGE}", "    restart: unless-stopped", "    ports:", '      - "127.0.0.1:8080:8080"',
+        "    environment:", "      GATUS_CONFIG_PATH: /config", "    env_file: /etc/gatus/gatus.env", "    volumes:",
+        "      - /srv/gatus/config:/config:ro", "      - /srv/gatus/data:/data", "    read_only: true", "    security_opt:", '      - "no-new-privileges:true"',
+        "    cap_drop:", '      - "ALL"'])
+    nginx = "\n".join([
+        "server {", "    listen 443 ssl http2;", f"    server_name {hostname};", f"    ssl_certificate /etc/letsencrypt/live/{hostname}/fullchain.pem;",
+        f"    ssl_certificate_key /etc/letsencrypt/live/{hostname}/privkey.pem;", '    add_header Strict-Transport-Security "max-age=31536000" always;',
+        "    location ~ ^/api/v1/endpoints/[^/]+/(uptimes|response-times|health)/ { deny all; }  # badges stay private unless you want them public",
+        "    location ~ ^/api/v1/endpoints/[^/]+/external$ { proxy_pass http://127.0.0.1:8080; }  # heartbeats (Bearer token)",
+        "    location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; }", "}"])
+    steps = [
+        {"n": 1, "title": "Take the host lock", "kind": "local", "run": f"maggie deployment host-lock acquire --host {target} --session {plan_id} --purpose 'deploy gatus'"},
+        {"n": 2, "title": "Create folders owned by an unprivileged user", "kind": "host",
+         "run": "sudo useradd --system --no-create-home gatus 2>/dev/null; sudo install -d -o gatus -g gatus -m 750 /srv/gatus/config /srv/gatus/data && sudo install -d -m 700 /etc/gatus",
+         "rollback": "sudo rm -rf /srv/gatus /etc/gatus"},
+        {"n": 3, "title": "Copy the generated configuration", "kind": "local", "run": f"scp {args.config}/*.yaml {target}:/srv/gatus/config/"},
+        {"n": 4, "title": "Create the env file yourself (mode 0600): GATUS_BASIC_USER, GATUS_BASIC_PASSWORD_BCRYPT_B64 (htpasswd -nbBC 9 user pass | cut -d: -f2 | base64 -w0), MAGGIE_ALERT_WEBHOOK_URL, MAGGIE_HEARTBEAT_TOKEN",
+         "kind": "host", "run": "sudoedit /etc/gatus/gatus.env && sudo chmod 600 /etc/gatus/gatus.env", "rollback": "sudo rm -f /etc/gatus/gatus.env"},
+        {"n": 5, "title": "Write docker-compose.yml (image pinned by digest, bound to 127.0.0.1 only: Docker ports bypass UFW)", "kind": "host",
+         "run": "sudo tee /srv/gatus/docker-compose.yml <<'EOF'\n" + compose + "\nEOF", "rollback": "sudo rm -f /srv/gatus/docker-compose.yml"},
+        {"n": 6, "title": "Start Gatus", "kind": "host", "run": "cd /srv/gatus && sudo docker compose up -d", "rollback": "cd /srv/gatus && sudo docker compose down"},
+        {"n": 7, "title": f"Add the nginx site for {hostname} (TLS via your usual certbot)", "kind": "host",
+         "run": f"sudo tee /etc/nginx/sites-available/gatus <<'EOF'\n{nginx}\nEOF\nsudo ln -sf /etc/nginx/sites-available/gatus /etc/nginx/sites-enabled/gatus && sudo nginx -t && sudo systemctl reload nginx",
+         "rollback": "sudo rm -f /etc/nginx/sites-enabled/gatus && sudo systemctl reload nginx"},
+        {"n": 8, "title": "Release the host lock", "kind": "local", "run": f"maggie deployment host-lock release --host {target} --session {plan_id}"},
+    ]
+    verify = [f"curl -fsS -u USER:PASS https://{hostname}/api/v1/endpoints/statuses | head -c 300",
+              "sudo ls -l /srv/gatus/data/gatus.db  # grows after a few minutes",
+              "cd /srv/gatus && sudo docker compose restart && curl … again: history is kept"]
+    markdown = "\n".join([f"# Uptime monitor plan {plan_id} — {host_alias}", "", "**Nothing has been changed.** Review, then run each step yourself under the host lock.",
+                          "", "> A monitor on the same server as the site goes silent when that server does. Prefer a second small server; at least keep the heartbeats.", ""]
+                         + [f"{s['n']}. **{s['title']}**\n   ```bash\n   {s['run']}\n   ```" + (f"\n   Undo: `{s['rollback']}`" if s.get("rollback") else "") for s in steps]
+                         + ["", "## Check afterwards", ""] + [f"- `{v}`" for v in verify])
+    out = ctx.state.path("plans", f"{plan_id}.md")
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(markdown + "\n", encoding="utf-8")
+    core.write_json(out.with_suffix(".json"), {"schema": "maggie-security-uptime-plan.v1", "id": plan_id, "image": GATUS_IMAGE, "steps": steps, "verify": verify})
+    return {"schema": "maggie-security-uptime-plan.v1", "id": plan_id, "path": str(out), "image": GATUS_IMAGE, "markdown": markdown}
+
+
+# --------------------------------------------------------------------------- uptime-status
+
+
+def gatus_get(ctx: core.Context, base: str, path: str, auth: bool) -> tuple[int, bytes]:
+    url = base.rstrip("/") + path
+    ctx.guard.extra_hosts.add(web.host_of(base))
+    ctx.guard.check("target-site", url)
+    headers = {}
+    user, password = os.environ.get("GATUS_BASIC_USER"), os.environ.get("GATUS_BASIC_PASSWORD")
+    if auth and user and password:
+        headers["Authorization"] = "Basic " + base64.b64encode(f"{user}:{password}".encode()).decode()
+    status, _h, body = core.http_request(url, headers=headers, timeout=20, retries=1)
+    return status, body
+
+
+def go_duration_hours(text: str) -> float | None:
+    match = re.search(r"\((?:(\d+)h)?(?:(\d+)m)?(?:[\d.]+s)?\)", text)
+    if not match or not (match.group(1) or match.group(2)):
+        return None
+    return int(match.group(1) or 0) + int(match.group(2) or 0) / 60
+
+
+def gatus_findings(ctx: core.Context, statuses: list[dict], uptimes: dict[str, float]) -> list[dict]:
+    findings = []
+
+    def add(rule: str, key: str, title: str, severity: str, kind: str = "availability", summary: str = "", url: str | None = None) -> None:
+        findings.append(core.make_finding(kind=kind, command="uptime-status", primary_id=f"{rule}:{key}", site=ctx.site, title=title, severity=severity,
+                                          severity_source="maggie", confidence="confirmed", target={"url": url or f"gatus:{key}", "host": "monitor"},
+                                          rule_id=rule, remediation={"summary": summary, "steps": [], "snippets": [], "references": [], "cheat_sheet": None}))
+
+    for status in statuses:
+        key, name, group = status.get("key"), status.get("name", ""), status.get("group", "")
+        results = status.get("results") or []
+        label = f"{group}/{name}"
+        if group == "maggie-security":
+            if results and not results[-1].get("success"):
+                add("job-missed", key, f"Security job {name} did not report or failed", "medium", summary="Check the routine or cron that runs it.")
+            continue
+        recent = results[-3:]
+        if recent and not any(r.get("success") for r in recent):
+            errors = "; ".join(e for r in recent for e in (r.get("errors") or []))[:150]
+            body_failed = all(any("[BODY]" in c.get("condition", "") and not c.get("success") for c in r.get("conditionResults") or []) for r in recent)
+            status_ok = all(r.get("status") == 200 for r in recent)
+            if body_failed and status_ok:
+                add("content-mismatch", key, f"{label}: the page loads but the expected text is missing (possible defacement or a wrong deploy)", "high",
+                    kind="exposure", summary="Open the page and compare it with the last deploy.")
+            elif name.startswith("dns"):
+                add("dns-failure", key, f"{label}: DNS lookups fail", "high", summary="Check the DNS records and the registrar.")
+            else:
+                add("uptime-down", key, f"{label} is down" + (f" ({errors})" if errors else ""), "high" if name == "homepage" else "medium",
+                    summary="Check the server and the last deploy.")
+        last = results[-1] if results else {}
+        for condition in last.get("conditionResults") or []:
+            text = condition.get("condition", "")
+            hours = go_duration_hours(text)
+            if hours is None:
+                continue
+            days = hours / 24
+            if "[CERTIFICATE_EXPIRATION]" in text and days <= 30:
+                add("cert-expiry", key, f"{label}: the certificate expires in {days:.0f} days", "high" if days <= 7 else "medium" if days <= 14 else "low",
+                    kind="tls", summary="Renew it and check automatic renewal.")
+            if "[DOMAIN_EXPIRATION]" in text and days <= 30:
+                add("domain-expiry", key, f"{label}: the domain expires in {days:.0f} days", "critical" if days <= 7 else "high" if days <= 14 else "medium",
+                    summary="Renew the domain at the registrar and turn on auto-renew.")
+        durations = [r.get("duration", 0) / 1e9 for r in results[-20:] if r.get("duration")]
+        if durations and name == "homepage" and sum(durations) / len(durations) > 1.0:
+            add("uptime-slow", key, f"{label} averages {sum(durations) / len(durations):.1f}s to respond", "low", summary="Check caching and the server load.")
+        ratio = uptimes.get(key)
+        if ratio is not None and ratio < 0.995:
+            add("uptime-below-target", key, f"{label} was up {ratio:.2%} of the window", "high" if ratio < 0.99 else "medium",
+                summary="Look at the outage times in Gatus.")
+    return findings
+
+
+def uptime_status(ctx: core.Context):
+    args = ctx.args
+    findings: list[dict] = []
+    if args.gatus:
+        if args.statuses_file:
+            statuses = core.read_json(Path(args.statuses_file))
+        else:
+            status, body = gatus_get(ctx, args.gatus, "/api/v1/endpoints/statuses", True)
+            if status == 401:
+                ctx.degrade("gatus", "401: set GATUS_BASIC_USER and GATUS_BASIC_PASSWORD")
+                return ctx.finish([])
+            if status != 200:
+                ctx.degrade("gatus", f"HTTP {status}")
+                return ctx.finish([])
+            statuses = json.loads(body.decode() or "[]")
+        if args.group:
+            statuses = [s for s in statuses if s.get("group") == args.group]
+        uptimes = {}
+        if not args.statuses_file:
+            for item in statuses:
+                code, body = gatus_get(ctx, args.gatus, f"/api/v1/endpoints/{urllib.parse.quote(item['key'])}/uptimes/{args.window}", False)
+                if code == 200:
+                    try:
+                        uptimes[item["key"]] = float(body.decode().strip())
+                    except ValueError:
+                        pass
+        findings += gatus_findings(ctx, statuses, uptimes)
+        ctx.run["inputs"].update({"gatus": web.host_of(args.gatus), "endpoints": len(statuses), "window": args.window})
+    if args.kuma and args.kuma_slug:
+        status, body = gatus_get(ctx, args.kuma, f"/api/status-page/heartbeat/{urllib.parse.quote(args.kuma_slug)}", False)
+        if status == 200:
+            data = json.loads(body.decode() or "{}")
+            for monitor_id, beats in (data.get("heartbeatList") or {}).items():
+                if beats and beats[-1].get("status") == 0:
+                    findings.append(core.make_finding(kind="availability", command="uptime-status", primary_id=f"uptime-down:kuma-{monitor_id}", site=ctx.site,
+                                                      title=f"Uptime Kuma monitor {monitor_id} is down", severity="medium", severity_source="tool",
+                                                      confidence="confirmed", target={"url": f"kuma:{monitor_id}", "host": "monitor"}))
+        else:
+            ctx.degrade("kuma", f"HTTP {status}")
+    if not args.gatus and not args.kuma:
+        raise core.UsageError("give --gatus URL (and/or --kuma URL --kuma-slug SLUG)")
+    return ctx.finish(findings, covered=["*"] if not ctx.run["degraded"] else [])
+
+
+# --------------------------------------------------------------------------- uptime-push
+
+
+def uptime_push(ctx: core.Context) -> dict:
+    args = ctx.args
+    config = ctx.state.config().get("uptime") or {}
+    token = os.environ.get("MAGGIE_HEARTBEAT_TOKEN")
+    if not token and config.get("heartbeat_token_file"):
+        token = Path(config["heartbeat_token_file"]).expanduser().read_text(encoding="utf-8").strip()
+    if not token:
+        raise core.UsageError("no heartbeat token: set MAGGIE_HEARTBEAT_TOKEN or uptime.heartbeat_token_file in config.json")
+    base = args.gatus or config.get("gatus_url")
+    if not base:
+        raise core.UsageError("give --gatus URL or set uptime.gatus_url in config.json")
+    key = gatus_key("maggie-security", args.job)
+    query = {"success": "true" if args.success == "true" else "false"}
+    if args.duration:
+        query["duration"] = args.duration
+    if args.error and args.success != "true":
+        query["error"] = re.sub(r"[^a-z0-9:_.-]", "", args.error.lower())[:60]  # a short code, never finding details
+    url = f"{base.rstrip('/')}/api/v1/endpoints/{key}/external?{urllib.parse.urlencode(query)}"
+    ctx.guard.extra_hosts.add(web.host_of(base))
+    ctx.guard.check("target-site", url)
+    try:
+        status, _h, _b = core.http_request(url, method="POST", data=b"", headers={"Authorization": f"Bearer {token}"}, timeout=15, retries=1)
+    except core.DegradedError as error:
+        return {"schema": "maggie-security-uptime-push.v1", "key": key, "pushed": False, "error": str(error), "exit_code": core.EXIT_DEGRADED}
+    return {"schema": "maggie-security-uptime-push.v1", "key": key, "pushed": status == 200, "status": status,
+            "exit_code": core.EXIT_OK if status == 200 else core.EXIT_DEGRADED}
+
+
+def _init(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--out", default="ops/gatus")
+    p.add_argument("--sites", help="JSON list of {id, url, type, brand_text, health_path, xmlrpc_status}")
+    p.add_argument("--interval", default="5m")
+    p.add_argument("--alert", choices=["webhook", "ntfy", "email", "none"], default="webhook")
+    p.add_argument("--ntfy-url")
+    p.add_argument("--allow-public-ntfy", action="store_true")
+    p.add_argument("--brand-text", help="stable text on the homepage (defacement check)")
+    p.add_argument("--no-heartbeats", dest="with_heartbeats", action="store_false")
+
+
+def _deploy(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--host-alias")
+    p.add_argument("--config", default="ops/gatus")
+    p.add_argument("--hostname", help="public name for the status page, e.g. status.example.com")
+
+
+def _status(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--gatus", help="Gatus base URL")
+    p.add_argument("--statuses-file", help="saved /api/v1/endpoints/statuses JSON (offline)")
+    p.add_argument("--window", choices=["1h", "24h", "7d", "30d"], default="7d")
+    p.add_argument("--group")
+    p.add_argument("--kuma")
+    p.add_argument("--kuma-slug")
+
+
+def _push(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--gatus")
+    p.add_argument("--job", required=True, choices=sorted(HEARTBEATS))
+    p.add_argument("--success", choices=["true", "false"], default="true")
+    p.add_argument("--duration", help="Go duration, e.g. 38s")
+    p.add_argument("--error", help="short code such as degraded:wpvulnerability")
+
+
+COMMANDS = [
+    core.Command("uptime-init", "generate a Gatus configuration for your verified sites and security-job heartbeats", ["target-site", "doh", "dns"],
+                 _init, uptime_init, findings=False),
+    core.Command("uptime-deploy", "a reviewed plan to run Gatus (Docker on 127.0.0.1 behind nginx); never applied", [], _deploy, uptime_deploy,
+                 findings=False, routine_safe=False),
+    core.Command("uptime-status", "read Gatus (or an Uptime Kuma status page) and report downtime, slowness, certificate and domain expiry",
+                 ["target-site"], _status, uptime_status),
+    core.Command("uptime-push", "report a security job's result to its Gatus heartbeat", ["target-site"], _push, uptime_push, findings=False),
+]