wpguard 0.2.1__py3-none-any.whl

wpguard/__init__.py

@@ -0,0 +1,3 @@
+"""wpguard: scan, clean, harden, back up and monitor hacked WordPress sites with wp-cli."""
+
+__version__ = "0.2.1"

wpguard/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m wpguard`."""
+
+from wpguard.cli import main
+
+raise SystemExit(main())

wpguard/audit.py

@@ -0,0 +1,100 @@
+"""The `audit` command: full inventory + findings, exported as Markdown or JSON (secrets redacted)."""
+
+import os
+import re
+import subprocess
+from collections import Counter
+from datetime import datetime
+from pathlib import Path
+
+from wpguard import __version__, wpcli
+from wpguard.report import Rep
+from wpguard.scan import scan
+from wpguard.signatures import PHP_EXT
+
+SETTINGS = (
+    "siteurl", "home", "blogname", "admin_email", "default_role", "users_can_register",
+    "permalink_structure", "WPLANG", "template", "stylesheet",
+)  # fmt: skip
+DROPINS = ("advanced-cache.php", "object-cache.php", "db.php", "db-error.php", "maintenance.php", "sunrise.php")
+
+
+def audit(site: Path, a) -> Rep:
+    """Inventory + scan findings as a dict in rep.data (printed by the CLI, not logged)."""
+    rep = Rep(site, quiet=True)
+    sc = scan(site, a, Rep(site, quiet=True))
+    cfg = {}
+    if (cp := site / "wp-config.php").exists():
+        for k, v in re.findall(r"define\(\s*['\"](\w+)['\"]\s*,\s*([^;]*?)\)\s*;", cp.read_text(errors="replace")):
+            cfg[k] = "[redacted]" if re.search(r"PASSWORD|KEY|SALT|DB_USER", k) else v.strip()
+    nphp = sum(f.lower().endswith(tuple(PHP_EXT)) for _, _, fs in os.walk(site) for f in fs)
+    users = wpcli.jget(site, "user", "list", "--fields=ID,user_login,user_email,roles,user_registered", "--format=json")
+    wpc = site / "wp-content"
+    try:
+        php = subprocess.run(["php", "-r", "echo PHP_VERSION;"], capture_output=True, text=True, check=False).stdout
+    except OSError:
+        php = "unknown (php not found)"
+    rep.data = {
+        "site": str(site),
+        "generated": datetime.now().astimezone().isoformat(timespec="seconds"),
+        "tool": f"wpguard {__version__}",
+        "wordpress": wpcli.wp(site, "core", "version").stdout.strip(),
+        "php": php,
+        "settings": {k: wpcli.wp(site, "option", "get", k).stdout.strip() for k in SETTINGS},
+        "plugins": wpcli.jget(site, "plugin", "list", "--format=json", "--fields=name,version,status,update"),
+        "themes": wpcli.jget(site, "theme", "list", "--format=json", "--fields=name,version,status,update"),
+        "users": {"count": len(users), "by_role": dict(Counter(u["roles"] for u in users)), "list": users[:500]},
+        "cron_hooks": sorted(
+            {e["hook"] for e in wpcli.jget(site, "cron", "event", "list", "--fields=hook", "--format=json")}
+        ),
+        "mu_plugins": sorted(f.name for f in (wpc / "mu-plugins").glob("*.php")),
+        "dropins": [n for n in DROPINS if (wpc / n).exists()],
+        "wp_config": cfg,
+        "php_files": nphp,
+        "findings": sc.hits,
+    }
+    return rep
+
+
+def md_table(rows: list[dict], cols: list[str]) -> str:
+    if not rows:
+        return "_none_\n"
+
+    def cell(v: object) -> str:
+        return str(v).replace("|", "\\|").replace("\n", " ")
+
+    lines = ["| " + " | ".join(cols) + " |", "|" + "---|" * len(cols)]
+    lines += ["| " + " | ".join(cell(r.get(c, "")) for c in cols) + " |" for r in rows]
+    return "\n".join(lines) + "\n"
+
+
+def audit_md(d: dict) -> str:
+    def kv(m: dict) -> str:
+        return md_table([{"key": k, "value": v} for k, v in m.items()], ["key", "value"])
+
+    u = d["users"]
+    return "\n".join(
+        [
+            f"# WordPress audit: {d['site']}",
+            f"_generated {d['generated']} by {d['tool']}_\n",
+            (
+                f"## Overview\n\n- WordPress: {d['wordpress']}\n- PHP: {d['php']}\n- PHP files: {d['php_files']}\n"
+                f"- Findings: {len(d['findings'])}\n"
+            ),
+            "## Settings\n",
+            kv(d["settings"]),
+            f"## Findings ({len(d['findings'])})\n",
+            md_table(d["findings"], ["kind", "what", "why"]),
+            "## Plugins\n",
+            md_table(d["plugins"], ["name", "version", "status", "update"]),
+            "## Themes\n",
+            md_table(d["themes"], ["name", "version", "status", "update"]),
+            f"## Users ({u['count']}) by role: {u['by_role']}\n",
+            md_table(u["list"], ["ID", "user_login", "user_email", "roles", "user_registered"]),
+            f"## Must-use plugins\n\n{', '.join(d['mu_plugins']) or '_none_'}\n",
+            f"## Drop-ins\n\n{', '.join(d['dropins']) or '_none_'}\n",
+            f"## Cron hooks ({len(d['cron_hooks'])})\n\n{', '.join(d['cron_hooks']) or '_none_'}\n",
+            "## wp-config.php constants (secrets redacted)\n",
+            kv(d["wp_config"]),
+        ]
+    )

wpguard/backup.py

@@ -0,0 +1,193 @@
+"""backup / verify / restore: DB dump + site files in a zstd tar, optional age encryption, multi-destination upload."""
+
+import hashlib
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+from pathlib import Path
+
+from wpguard import wpcli
+from wpguard.destinations import DestError, Local, parse, upload_all
+from wpguard.report import Rep
+from wpguard.util import stamp
+
+SKIP_UPLOADS = "site/wp-content/uploads"
+CHUNK = 1024 * 1024
+
+
+def sha256(p: Path) -> str:
+    with p.open("rb") as fh:
+        return hashlib.file_digest(fh, "sha256").hexdigest()
+
+
+def age_encrypt(src: Path, recipient: str) -> Path:
+    if not shutil.which("age"):
+        msg = "--encrypt-to needs the `age` binary (https://age-encryption.org)"
+        raise DestError(msg)
+    out = src.with_name(src.name + ".age")
+    r = subprocess.run(["age", "-r", recipient, "-o", str(out), str(src)], capture_output=True, text=True, check=False)
+    if r.returncode:
+        msg = f"age failed: {r.stderr.strip()}"
+        raise DestError(msg)
+    src.unlink()
+    return out
+
+
+def age_decrypt(src: Path, identity: str, dst: Path) -> None:
+    r = subprocess.run(
+        ["age", "-d", "-i", identity, "-o", str(dst), str(src)], capture_output=True, text=True, check=False
+    )
+    if r.returncode:
+        msg = f"age decrypt failed: {r.stderr.strip()}"
+        raise DestError(msg)
+
+
+def write_archive(site: Path, out: Path, *, uploads: bool) -> None:
+    with tempfile.TemporaryDirectory() as tmp:
+        sql = Path(tmp) / "db.sql"
+        r = wpcli.wp(site, "db", "export", str(sql))
+        if r.returncode:
+            sys.exit(f"db export failed, aborting: {r.stderr.strip()}")
+        with tarfile.open(out, "x:zst") as t:  # "x": never overwrite an existing backup
+            t.add(sql, arcname="db.sql")
+            t.add(site, arcname="site", filter=lambda i: None if not uploads and i.name.startswith(SKIP_UPLOADS) else i)
+    out.chmod(0o600)  # holds wp-config.php and the DB
+
+
+def verify_archive(arc: Path, identity: str | None = None) -> list[str]:
+    """Problems found in a backup (empty list = good): checksum sidecar, readable tar, plausible db.sql, WP files."""
+    problems: list[str] = []
+    if (side := arc.with_name(arc.name + ".sha256")).exists():
+        if sha256(arc) != side.read_text().split()[0]:
+            return [f"checksum mismatch for {arc.name}"]
+    else:
+        problems.append("no .sha256 sidecar (cannot detect corruption of the file itself)")
+    if arc.suffix == ".age":
+        if not identity:
+            return [*problems, "encrypted: only the checksum was verified (pass --age-identity to verify contents)"]
+        with tempfile.TemporaryDirectory() as tmp:
+            plain = Path(tmp) / arc.name.removesuffix(".age")
+            age_decrypt(arc, identity, plain)
+            return [p for p in verify_archive(plain) if "sidecar" not in p]
+    seen = set()
+    try:
+        with tarfile.open(arc, "r:zst") as t:
+            for m in t:
+                seen.add(m.name)
+                if m.isfile():
+                    f = t.extractfile(m)
+                    head = f.read(CHUNK) if f else b""
+                    while f and f.read(CHUNK):
+                        pass
+                    if m.name == "db.sql" and not (m.size and (b"CREATE TABLE" in head or b"INSERT INTO" in head)):
+                        problems.append("db.sql is empty or does not look like a MySQL dump")
+    except (tarfile.TarError, OSError, EOFError, ValueError) as e:
+        return [*problems, f"archive unreadable: {e}"]
+    problems += [f"missing {need} in archive" for need in ("db.sql", "site/wp-load.php") if need not in seen]
+    return problems
+
+
+def make_backup(site: Path, a, rep: Rep, *, uploads: bool = True, local_only: bool = False) -> Path:
+    """Create the archive, optionally encrypt/verify, upload to every destination, apply retention."""
+    specs = [] if local_only else list(a.to or [])
+    dests = [parse(s) for s in specs]
+    out_dir = Path(a.out) if a.out else None
+    local = [d for d in dests if isinstance(d, Local)]
+    if not dests or (out_dir and not local):
+        dests.insert(0, Local(out_dir or site.parent))
+    staging_is_temp = False
+    if local_only or any(isinstance(d, Local) for d in dests):
+        staging = next(d.dir for d in dests if isinstance(d, Local)).resolve()
+    else:
+        staging, staging_is_temp = Path(tempfile.mkdtemp(prefix="wpguard-")), True
+    if staging == site or site in staging.parents:
+        sys.exit("backup destination must be outside the site directory")
+    staging.mkdir(parents=True, exist_ok=True)
+    arc = staging / f"wpguard-backup-{site.name}-{stamp()}.tar.zst"
+    write_archive(site, arc, uploads=uploads)
+    if a.encrypt_to:
+        arc = age_encrypt(arc, a.encrypt_to)
+        arc.chmod(0o600)
+    digest = sha256(arc)
+    side = arc.with_name(arc.name + ".sha256")
+    side.write_text(f"{digest}  {arc.name}\n")
+    rep.log(f"  backup -> {arc} ({arc.stat().st_size // 1024} KiB, sha256 {digest[:12]}...)")
+    if a.verify:
+        problems = [p for p in verify_archive(arc, a.age_identity) if "sidecar" not in p]
+        for p in problems:
+            rep.log(f"  VERIFY FAILED: {p}")
+        if problems:
+            rep.exit = 1
+            return arc
+        rep.log("  verified: archive readable, db.sql plausible, WordPress files present")
+    for label, result in upload_all(dests, [arc, side], site.name, a.keep or 0).items():
+        rep.log(f"  {label}: {result}")
+        if result.startswith("FAILED"):
+            rep.exit = 1
+    if staging_is_temp and not a.keep_local and not rep.exit:
+        shutil.rmtree(staging, ignore_errors=True)
+    elif staging_is_temp:
+        rep.log(f"  local copy kept in {staging}")
+    return arc
+
+
+def backup(site: Path, a) -> Rep:
+    rep = Rep(site)
+    make_backup(site, a, rep, uploads=not a.no_uploads)
+    return rep
+
+
+def latest(site: Path, a) -> Path | None:
+    if a.src:
+        return Path(a.src)
+    base = Path(a.out) if a.out else site.parent
+    found = sorted(p for p in base.glob(f"wpguard-backup-{site.name}-*.tar.zst*") if not p.name.endswith(".sha256"))
+    return found[-1] if found else None
+
+
+def verify(site: Path, a) -> Rep:
+    rep = Rep(site)
+    if not (arc := latest(site, a)) or not arc.is_file():
+        rep.log("no backup found (use --from FILE or --out DIR)")
+        rep.exit = 1
+        return rep
+    problems = verify_archive(arc, a.age_identity)
+    for p in problems:
+        rep.hit("verify", arc.name, p)
+    if not problems:
+        rep.log(f"OK {arc}")
+    return rep
+
+
+def restore(site: Path, a) -> Rep:
+    rep = Rep(site)
+    arc = latest(site, a)
+    if not arc or not arc.is_file():
+        rep.log("no backup found (use --from FILE.tar.zst)")
+        rep.exit = 1
+        return rep
+    if (side := arc.with_name(arc.name + ".sha256")).exists() and sha256(arc) != side.read_text().split()[0]:
+        rep.log(f"CHECKSUM MISMATCH for {arc}, aborting")
+        rep.exit = 1
+        return rep
+    with tempfile.TemporaryDirectory() as tmp:
+        src = arc
+        if arc.suffix == ".age":
+            if not a.age_identity:
+                rep.log("encrypted backup: pass --age-identity KEYFILE")
+                rep.exit = 1
+                return rep
+            src = Path(tmp) / arc.name.removesuffix(".age")
+            age_decrypt(arc, a.age_identity, src)
+        with tarfile.open(src, "r:zst") as t:
+            for m in t:
+                if m.name == "db.sql":
+                    t.extract(m, tmp, filter="data")
+                elif m.name.startswith("site/"):
+                    t.extract(m.replace(name=m.name.removeprefix("site/")), site, filter="data")
+        r = wpcli.wp(site, "db", "import", f"{tmp}/db.sql")
+    rep.log("db import:", (r.stdout + r.stderr).strip() or "ok")
+    rep.log(f"files restored from {arc}. Quarantined files stay in {site.parent}/wpguard-quarantine (use `undo`).")
+    return rep

wpguard/behavior.py

@@ -0,0 +1,70 @@
+"""Heuristic 'behavior' score for a PHP file: obfuscation, dangerous-call density, odd names/places, timestamps.
+
+Signatures catch known shells; this catches the unknown ones. A score >= threshold is reported for review and is
+never auto-quarantined unless `--aggressive` is given (heuristics have false positives).
+"""
+
+import math
+import re
+from collections import Counter
+
+CALLS = [
+    (re.compile(rb"\beval\s*\(", re.IGNORECASE), 3, "eval()"),
+    (re.compile(rb"\bassert\s*\(\s*\$", re.IGNORECASE), 3, "assert($var)"),
+    (re.compile(rb"\b(?:shell_exec|passthru|proc_open|popen|pcntl_exec)\s*\(", re.IGNORECASE), 3, "shell execution"),
+    (re.compile(rb"\b(?:system|exec)\s*\(\s*\$", re.IGNORECASE), 3, "system/exec($var)"),
+    (re.compile(rb"\b(?:gzinflate|gzuncompress|gzdecode|str_rot13)\s*\(", re.IGNORECASE), 2, "decompress/rot13"),
+    (re.compile(rb"\bbase64_decode\s*\(", re.IGNORECASE), 1, "base64_decode"),
+    (re.compile(rb"\bcreate_function\s*\(", re.IGNORECASE), 2, "create_function"),
+    (re.compile(rb"\bpreg_replace\s*\(\s*['\"][^'\"]*/[a-z]*e[a-z]*['\"]", re.IGNORECASE), 3, "preg_replace /e"),
+    (re.compile(rb"\$\$\w+|\$\{\s*['\"]"), 2, "variable variables"),
+    (re.compile(rb"\$\w+\s*\(\s*\$_(?:GET|POST|REQUEST|COOKIE)"), 3, "dynamic call on request input"),
+    (re.compile(rb"(?:\\x[0-9a-fA-F]{2}){8,}"), 3, "hex-escaped strings"),
+    (re.compile(rb"(?:chr\s*\(\s*\d+\s*\)\s*\.?\s*){6,}", re.IGNORECASE), 3, "chr() chains"),
+]
+DOUBLE_EXT = re.compile(r"\.php\d?\.(?:jpe?g|png|gif|ico|txt|css|js)$|\.(?:jpe?g|png|gif|ico)\.php\d?$", re.IGNORECASE)
+KNOWN_BAD_NAMES = {"wp-vcd.php", "wp-tmp.php", "wp-feed.php", "xmrlpc.php", "class.plugin-modules.php", "wp-cache.php"}
+ASSET_DIRS = ("wp-includes/js/", "wp-includes/css/", "wp-includes/images/", "wp-includes/fonts/", "wp-admin/images/",
+              "wp-admin/css/", "wp-admin/js/", "wp-content/languages/")  # fmt: skip
+WEEK = 7 * 86400
+
+
+def entropy(data: bytes) -> float:
+    if not data:
+        return 0.0
+    n = len(data)
+    return -sum(c / n * math.log2(c / n) for c in Counter(data).values())
+
+
+def score(
+    data: bytes, rel: str, mtime: float | None = None, sibling_median: float | None = None, now: float | None = None
+) -> tuple[int, list[str]]:
+    """(score, reasons) for a PHP file whose site-relative posix path is `rel`."""
+    total, why = 0, []
+
+    def add(points: int, reason: str) -> None:
+        nonlocal total
+        total += points
+        why.append(f"{reason} (+{points})")
+
+    for rx, pts, label in CALLS:
+        if rx.search(data):
+            add(pts, label)
+    sample = data[:200_000]
+    if len(sample) >= 1024 and entropy(sample) > 5.8:
+        add(3, "high entropy (packed/obfuscated)")
+    if len(sample) > 5000 and max(map(len, sample.split(b"\n"))) > 5000 and sample.count(b"\n") < len(sample) / 2000:
+        add(2, "very long lines")
+    name = rel.rsplit("/", 1)[-1]
+    if name.lower() in KNOWN_BAD_NAMES:
+        add(5, "filename used by known malware")
+    if DOUBLE_EXT.search(name):
+        add(4, "double extension")
+    if rel.startswith(ASSET_DIRS):
+        add(3, "php in an asset directory")
+    if mtime is not None:
+        if now is not None and mtime > now + 3600:
+            add(2, "modified in the future")
+        if sibling_median is not None and mtime - sibling_median > 30 * 86400:
+            add(2, "much newer than its siblings")
+    return total, why

wpguard/cli.py

@@ -0,0 +1,263 @@
+"""Command line: argument parsing, config/profile merging, local vs ssh dispatch, reports and exit codes."""
+
+import argparse
+import copy
+import sys
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+
+from wpguard import __version__, config, discover, feeds, remote, wpcli, wpscan
+from wpguard.audit import audit, audit_md
+from wpguard.backup import backup, restore, verify
+from wpguard.diffs import diff
+from wpguard.fix import fix, harden, undo
+from wpguard.lockfile import lock_cmd
+from wpguard.monitor import baseline, logs, watch
+from wpguard.recovery import recover_main
+from wpguard.report import Rep, notify, write_report
+from wpguard.scan import scan
+from wpguard.schedule import schedule
+from wpguard.updates import updates
+
+DOC = """wpguard: scan, clean, harden, back up and monitor hacked WordPress sites with wp-cli.
+
+site commands (SITE = path, profile name, hostname like blog.example.com, host:/path or host:domain over ssh):
+  scan  fix  harden  undo  baseline  watch  backup  verify  restore  audit  diff  lock  updates
+other commands:
+  setup                      download wp-cli (sha512 verified) and create ~/.config/wpguard/wpguard.toml
+  init [--config FILE]       create a starter ./wpguard.toml (--force to overwrite)
+  discover [HOST...] [--save]  find WordPress sites by hostname on this machine / ssh hosts (nginx, apache vhosts)
+  logs [SITE...]             find the entry point in web server access logs
+  sigs list|update [NAME..]  signature feeds (maldet hashes, YARA rules)
+  schedule add|remove|show JOB SITE   cron / systemd timers (JOB: watch backup scan sigs updates)
+  wp [--unsafe] SITE ARGS... run ANY wp-cli command (plugins/themes not loaded unless --unsafe)
+  wpscan [URL] ARGS...       run the real WPScan (local or docker); WPSCAN_TOKEN is used if set
+  recover ARGS...            rebuild a wiped site from a DB / dump (see `recover --help`)
+Docs: https://github.com/arian24b/wpguard
+"""
+SITE_CMDS: dict[str, Callable] = {
+    "scan": scan, "fix": fix, "harden": harden, "undo": undo, "baseline": baseline, "watch": watch,
+    "backup": backup, "verify": verify, "restore": restore, "audit": audit, "diff": diff, "lock": lock_cmd,
+    "updates": updates,
+}  # fmt: skip
+FAIL_ON_HITS = {"scan", "watch", "lock", "verify", "diff", "updates"}
+NOTIFY_ON = {*FAIL_ON_HITS, "fix"}
+LOCAL_WP_CMDS = {"scan", "fix", "harden", "restore", "audit", "backup", "diff", "lock", "updates", "undo"}
+LOCAL_ONLY = {"config", "report", "sites_file", "jobs", "pull", "all", "help", "version", "force", "save"}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="wpguard", description=DOC, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("cmd", choices=[*SITE_CMDS, "logs", "setup", "init", "discover", "sigs", "schedule"])
+    ap.add_argument("sites", nargs="*", help="paths, profile names, hostnames, host:/path or host:domain")
+    ap.add_argument("--version", action="version", version=f"wpguard {__version__}")
+    g = ap.add_argument_group("general")
+    g.add_argument("--config", help="wpguard.toml (default: ./wpguard.toml, ~/.config/wpguard/wpguard.toml)")
+    g.add_argument("--all", action="store_true", help="every site profile in the config")
+    g.add_argument("--force", action="store_true", help="(init, setup) overwrite / re-download")
+    g.add_argument("--save", action="store_true", help="(discover) add the found sites to the config")
+    g.add_argument("--sites-file")
+    g.add_argument("-j", "--jobs", type=int, default=1)
+    g.add_argument("--report", help="write report: out.json | out.html | out.txt")
+    g.add_argument("--notify", action="store_true", help="alert (telegram/email) when there are findings")
+    g.add_argument("--url", help="real site URL: pins WP_HOME/WP_SITEURL (harden/fix)")
+    g.add_argument("--ignore", action="append", help="glob of site-relative paths to ignore (repeatable)")
+    g.add_argument("--lock-file", help="path of wpguard.lock (default: next to the config, else ./)")
+    d = ap.add_argument_group("detection")
+    d.add_argument("--sigs", action="append", help="file of extra regexes, one per line")
+    d.add_argument("--hashdb", action="append", help="known-bad hash database (csv/txt/json/sqlite/.hdb)")
+    d.add_argument("--hashdb-good", action="append", help="known-clean hash database (suppresses findings)")
+    d.add_argument("--yara", action="append", help="YARA rule file (needs the yara or yr binary)")
+    d.add_argument("--no-feeds", action="store_true", help="ignore downloaded signature feeds")
+    d.add_argument("--no-behavior", action="store_true", help="disable heuristic behavior scoring")
+    d.add_argument("--behavior-threshold", type=int, default=5)
+    d.add_argument("--since", type=int, help="flag PHP modified / admins created in the last N days")
+    d.add_argument("--no-net", action="store_true", help="skip wordpress.org / WPScan lookups")
+    f = ap.add_argument_group("fix / harden")
+    f.add_argument("--dry-run", action="store_true", help="show the plan, change nothing")
+    f.add_argument("--yes", action="store_true", help="do not ask for confirmation")
+    f.add_argument("--aggressive", action="store_true", help="also quarantine behavior/yara findings")
+    f.add_argument("--clean-db", action="store_true")
+    f.add_argument("--prune", action="store_true")
+    f.add_argument("--delete-user", action="append")
+    f.add_argument("--lockdown", action="store_true", help="also DISALLOW_FILE_MODS + no auto-update (blocks updates)")
+    f.add_argument("--only", action="append", help="(undo) glob of files to restore")
+    b = ap.add_argument_group("backup")
+    b.add_argument("--out", help="backup: local directory | audit: output file")
+    b.add_argument(
+        "--to", action="append", help="destination: DIR | s3://bucket/prefix | rsync:HOST:/path (repeatable)"
+    )
+    b.add_argument("--keep", type=int, help="retention: keep the newest N backups per destination")
+    b.add_argument("--no-uploads", action="store_true")
+    b.add_argument("--encrypt-to", help="age recipient (age1...) to encrypt the archive")
+    b.add_argument("--age-identity", help="age identity file (verify/restore of encrypted backups)")
+    b.add_argument("--verify", action="store_true", help="backup: verify the archive before uploading")
+    b.add_argument(
+        "--keep-local", action="store_true", help="keep the local copy when only remote destinations are set"
+    )
+    b.add_argument("--from", dest="src", help="restore/verify/undo: backup file or quarantine dir")
+    b.add_argument("--pull", help="remote backup: rsync the archive back into this directory")
+    x = ap.add_argument_group("diff / lock / updates")
+    x.add_argument("--core", action="store_true", help="(diff) core files only")
+    x.add_argument("--plugin", action="append", help="(diff) only this plugin slug")
+    x.add_argument("--max-lines", type=int, default=60)
+    x.add_argument("--check", action="store_true", help="(lock) report drift instead of writing")
+    x.add_argument("--apply", action="store_true", help="(updates) apply the safe updates on the real site")
+    x.add_argument("--stage-db", help="(updates) existing empty database to use for staging")
+    x.add_argument("--check-url", action="append", help="(updates) extra URL path to health-check")
+    x.add_argument("--keep-stage", action="store_true")
+    s = ap.add_argument_group("schedule")
+    s.add_argument("--every", help="15m | 6h")
+    s.add_argument("--daily", help="HH:MM")
+    s.add_argument("--cron", help="raw cron expression")
+    s.add_argument("--systemd", action="store_true")
+    s.add_argument("--install", action="store_true")
+    o = ap.add_argument_group("output")
+    o.add_argument("--format", choices=["md", "json"], help="(audit)")
+    o.add_argument("--log", action="append", default=[], help="(logs) access log file")
+    o.add_argument("--top", type=int, default=10)
+    return ap
+
+
+def apply_opts(ap: argparse.ArgumentParser, ns: argparse.Namespace, opts: dict, origin: str) -> None:
+    """Fill options the user did not give on the command line from config values (CLI always wins)."""
+    dests = {act.dest for act in ap._actions}  # noqa: SLF001
+    for key, val in opts.items():
+        if key not in dests:
+            msg = f"{origin}: unknown option {key!r}"
+            raise config.ConfigError(msg)
+        if getattr(ns, key) == ap.get_default(key):
+            setattr(ns, key, list(val) if isinstance(val, list) else val)
+
+
+def serialize(ap: argparse.ArgumentParser, ns: argparse.Namespace) -> list[str]:
+    """Namespace -> CLI flags that differ from defaults (what a remote wpguard must be told)."""
+    out: list[str] = []
+    for act in ap._actions:  # noqa: SLF001
+        if not act.option_strings or act.dest in LOCAL_ONLY:
+            continue
+        val = getattr(ns, act.dest, None)
+        if val in (None, False, [], act.default):
+            continue
+        flag = max(act.option_strings, key=len)
+        if isinstance(act, argparse._StoreTrueAction):  # noqa: SLF001
+            out.append(flag)
+        elif isinstance(act, argparse._AppendAction):  # noqa: SLF001
+            for v in val:
+                out += [flag, str(v)]
+        else:
+            out += [flag, str(val)]
+    return out
+
+
+def run_target(ap: argparse.ArgumentParser, ns: argparse.Namespace, cfg: config.Config, t: config.Target) -> Rep:
+    ta = copy.copy(ns)
+    ta._det = None  # noqa: SLF001  detectors are built per target (options may differ)
+    ta.site_key, ta.config_path = t.key, cfg.path
+    apply_opts(ap, ta, t.opts, f"[sites.{t.name}]")  # first writer wins: CLI > profile > defaults
+    apply_opts(ap, ta, cfg.defaults, "[defaults]")
+    if t.ssh:
+        return remote.run(t.ssh, t.remote_cmd, [ns.cmd, t.path, *serialize(ap, ta)], live=Rep.live, pull=ns.pull)
+    return SITE_CMDS[ns.cmd](Path(t.path), ta)
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv[:1] == ["wp"]:
+        wpcli.wp_passthrough(argv[1:])
+    if argv[:1] == ["wpscan"]:
+        wpscan.wpscan_passthrough(argv[1:])
+    if argv[:1] == ["recover"]:
+        recover_main(argv[1:])
+        return 0
+    if not argv:
+        print(DOC)
+        return 2
+    ap = build_parser()
+    ns = ap.parse_args(argv)
+    if ns.cmd == "init":
+        path = Path(ns.config) if ns.config else Path("wpguard.toml")
+        if config.write_template(path, force=ns.force):
+            print(f"created {path.resolve()}  (edit it, then try: wpguard discover --save)")
+            return 0
+        print(f"{path} already exists (use --force to overwrite)")
+        return 1
+    if ns.cmd == "setup":
+        wpcli.setup()
+        if created := config.ensure_default():
+            print(f"created {created}  (edit it, or run: wpguard discover --save)")
+        return 0
+    try:
+        cfg = config.load(ns.config)
+    except config.ConfigError as e:
+        sys.exit(f"error: {e}")
+    if ns.cmd == "sigs":
+        return feeds.sigs_cmd(ns.sites, cfg.feeds)
+    ns.config_path = cfg.path
+    if ns.cmd == "discover":
+        try:
+            return discover.discover(ns.sites, cfg, cfg.path, save=ns.save)
+        except config.ConfigError as e:
+            sys.exit(f"error: {e}")
+    if ns.cmd == "schedule":
+        ns.site_key = ""
+        rep = schedule(ns.sites, ns)
+        return rep.exit
+    if ns.sites_file:
+        ns.sites += Path(ns.sites_file).read_text().split()
+    Rep.live = ns.jobs == 1
+    if ns.cmd == "logs":
+        reps = [logs([str(Path(s).resolve()) for s in ns.sites], ns)]
+    else:
+        if not ns.sites and not ns.all:
+            sys.exit("give at least one SITE (path, profile name, host:/path) or --all")
+        if ns.cmd == "fix" and ns.jobs > 1 and not (ns.yes or ns.dry_run):
+            sys.exit("fix with -j > 1 cannot ask for confirmation: add --yes (or use --dry-run)")
+        try:
+            targets = config.targets(cfg, ns.sites, every=ns.all)
+            for t in targets:
+                if not t.path:
+                    discover.fill(t)  # hostname-only target: find its path from the vhosts
+            if ns.cmd in LOCAL_WP_CMDS and any(not t.ssh for t in targets):
+                wpcli.need_wp()
+            bad = [t.path for t in targets if not t.ssh and not (Path(t.path) / "wp-load.php").exists()]
+            if bad:
+                sys.exit(f"not WordPress roots: {bad}")
+            with ThreadPoolExecutor(ns.jobs) as ex:
+                reps = list(ex.map(lambda t: run_target(ap, ns, cfg, t), targets))
+        except config.ConfigError as e:
+            sys.exit(f"error: {e}")
+    if not Rep.live:
+        for r in reps:
+            print("\n".join(r.lines))
+    if ns.cmd == "audit":
+        _export_audit(ns, reps)
+    if ns.report:
+        write_report(ns.report, reps)
+    found = [r for r in reps if r.hits]
+    if found and ns.notify and ns.cmd in NOTIFY_ON:
+        notify(
+            "\n".join(
+                f"{r.site}: {len(r.hits)} findings\n"
+                + "\n".join(f"- [{h['kind']}] {h['what']}: {h['why']}" for h in r.hits[:15])
+                for r in found
+            ),
+            cfg.notify,
+        )
+    return 1 if any(r.exit for r in reps) or (found and ns.cmd in FAIL_ON_HITS) else 0
+
+
+def _export_audit(ns: argparse.Namespace, reps: list[Rep]) -> None:
+    import json
+
+    fmt = ns.format or ("json" if (ns.out or "").endswith(".json") else "md")
+    docs = [r.data for r in reps]
+    txt = (
+        json.dumps(docs[0] if len(docs) == 1 else docs, indent=1) if fmt == "json" else "\n\n".join(map(audit_md, docs))
+    )
+    if ns.out:
+        Path(ns.out).write_text(txt)
+        print("audit ->", ns.out, file=sys.stderr)
+    else:
+        print(txt)