@matthesketh/fleet 1.6.0 → 1.7.0

package/dist/cli.js

@@ -21,6 +21,7 @@ import { watchdogCommand } from './commands/watchdog.js';
 import { installMcpCommand } from './commands/install-mcp.js';
 import { patchSystemdCommand } from './commands/patch-systemd.js';
 import { freezeCommand, unfreezeCommand } from './commands/freeze.js';
+import { guardCommand } from './commands/guard.js';
 import { bootStartCommand } from './commands/boot-start.js';
 import { rollbackCommand } from './commands/rollback.js';
 import { routineRunCommand } from './commands/routine-run.js';
@@ -89,6 +90,7 @@ Commands:
   freeze <app>        Freeze a crash-looping service (stop + disable)
   rollback <app>      Roll back app to previous image
   unfreeze <app>      Unfreeze and restart a frozen service
+  guard <subcommand>  Cloudflare protection layer (install/status/approve/reject/...)
 
 Global flags:
   --json              Output as JSON
@@ -146,6 +148,7 @@ export async function run(argv) {
         case 'freeze': return freezeCommand(rest);
         case 'rollback': return rollbackCommand(rest);
         case 'unfreeze': return unfreezeCommand(rest);
+        case 'guard': return guardCommand(rest);
         case 'mcp': return startMcpServer();
         case 'tui':
         case 'dashboard': {

package/dist/commands/guard.d.ts

@@ -0,0 +1 @@
+export declare function guardCommand(args: string[]): void;

package/dist/commands/guard.js

@@ -0,0 +1,144 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, copyFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { error, info, success } from '../ui/output.js';
+const SCRIPTS = [
+    { name: 'notify', mode: 0o700 },
+    { name: 'fleet-guard', mode: 0o750, group: 'fleet-guard' },
+    { name: 'fleet-guard-execute', mode: 0o750, group: 'fleet-guard' },
+    { name: 'cf-audit-monitor', mode: 0o700 },
+    { name: 'cf-snapshot', mode: 0o700 },
+    { name: 'dns-drift-watch', mode: 0o750, group: 'fleet-guard' },
+    { name: 'cert-expiry-watch', mode: 0o750, group: 'fleet-guard' },
+];
+const TARGET_BIN = '/usr/local/sbin';
+const STATE_DIR = '/var/lib/fleet-guard';
+const LOG_DIR = '/var/log/fleet-guard';
+const SNAP_DIR = '/var/lib/cf-snapshots';
+const CRON_TARGET = '/etc/cron.d/cf-protect';
+function scriptsDir() {
+    // dist/commands/guard.js -> ../../scripts/guard relative to compiled file
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, '..', '..', 'scripts', 'guard');
+}
+function requireRoot() {
+    if (process.getuid && process.getuid() !== 0) {
+        throw new Error('this command needs root. try: sudo fleet guard install');
+    }
+}
+function run(cmd, args) {
+    const r = spawnSync(cmd, args, { stdio: 'inherit' });
+    if (r.status !== 0)
+        throw new Error(`${cmd} ${args.join(' ')} failed`);
+}
+function ensureUser() {
+    const r = spawnSync('id', ['fleet-guard'], { stdio: 'ignore' });
+    if (r.status === 0)
+        return;
+    run('useradd', ['--system', '--no-create-home', '--shell', '/usr/sbin/nologin', 'fleet-guard']);
+    info('created system user fleet-guard');
+}
+function ensureDir(path, mode, group) {
+    if (!existsSync(path))
+        mkdirSync(path, { recursive: true });
+    chmodSync(path, mode);
+    if (group)
+        run('chgrp', ['-R', group, path]);
+}
+function installScripts() {
+    const src = scriptsDir();
+    if (!existsSync(src)) {
+        throw new Error(`scripts not bundled at ${src} — broken install`);
+    }
+    for (const s of SCRIPTS) {
+        const from = join(src, s.name);
+        const to = join(TARGET_BIN, s.name);
+        if (!existsSync(from))
+            throw new Error(`missing bundled script: ${from}`);
+        copyFileSync(from, to);
+        chmodSync(to, s.mode);
+        if (s.group)
+            run('chown', [`root:${s.group}`, to]);
+        info(`installed ${to}`);
+    }
+}
+function installCron() {
+    const cron = `# fleet guard — auto-installed, edit with care
+SHELL=/bin/bash
+PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+
+*/15 * * * * root /usr/local/sbin/cf-audit-monitor >> /var/log/cf-audit-monitor.log 2>&1
+*/30 * * * * root /usr/local/sbin/cf-snapshot >> /var/log/cf-snapshot.log 2>&1
+*/30 * * * * root /usr/local/sbin/dns-drift-watch >> /var/log/dns-drift-watch.log 2>&1
+17 4 * * * root /usr/local/sbin/cert-expiry-watch >> /var/log/cert-expiry-watch.log 2>&1
+* * * * * fleet-guard /usr/local/sbin/fleet-guard execute >> /var/log/fleet-guard/execute.log 2>&1
+`;
+    writeFileSync(CRON_TARGET, cron, { mode: 0o644 });
+    info(`installed cron at ${CRON_TARGET}`);
+}
+function installCommand() {
+    requireRoot();
+    ensureUser();
+    ensureDir(STATE_DIR, 0o700, 'fleet-guard');
+    ensureDir(join(STATE_DIR, 'pending'), 0o700, 'fleet-guard');
+    ensureDir(join(STATE_DIR, 'approved'), 0o700, 'fleet-guard');
+    ensureDir(join(STATE_DIR, 'processed'), 0o700, 'fleet-guard');
+    ensureDir(LOG_DIR, 0o700, 'fleet-guard');
+    ensureDir(SNAP_DIR, 0o700);
+    installScripts();
+    installCron();
+    success('fleet guard installed.');
+    info('next steps:');
+    info('  1. seed creds at /etc/fleet/guard.cf.json (cloudflare api key + email + accountId)');
+    info('  2. ensure /etc/fleet/notify.json has telegram and/or bluebubbles adapters');
+    info('  3. add /approve, /reject, /guard commands to fleet-bot (PR #60 in fleet repo)');
+}
+function delegate(verb, args) {
+    // every other verb just shells out to the host /usr/local/sbin/fleet-guard cli
+    // so we have a single source of truth for the queue logic.
+    const r = spawnSync('/usr/local/sbin/fleet-guard', [verb, ...args], { stdio: 'inherit' });
+    return r.status ?? 1;
+}
+function helpText() {
+    return [
+        'fleet guard <subcommand>',
+        '',
+        'subcommands:',
+        '  install                            install scripts, user, cron, dirs (root)',
+        '  status                             show queue counts + pending tokens',
+        '  list [pending|approved|processed]  list records',
+        '  hold <kind> <summary> [--payload]  create a pending action',
+        '  approve <token>                    approve a pending action',
+        '  reject <token>                     reject a pending action',
+        '  show <token>                       dump one record',
+        '  execute                            run all approved actions',
+    ].join('\n');
+}
+export function guardCommand(args) {
+    const [sub, ...rest] = args;
+    if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
+        info(helpText());
+        return;
+    }
+    if (sub === 'install') {
+        try {
+            installCommand();
+        }
+        catch (e) {
+            error(e.message);
+            process.exit(1);
+        }
+        return;
+    }
+    const passthrough = new Set(['status', 'list', 'hold', 'approve', 'reject', 'show', 'execute']);
+    if (passthrough.has(sub)) {
+        const code = delegate(sub, rest);
+        if (code !== 0)
+            process.exit(code);
+        return;
+    }
+    error(`unknown subcommand: ${sub}`);
+    console.log(helpText());
+    process.exit(2);
+}

package/dist/core/routines/schema.d.ts

@@ -207,6 +207,11 @@ export declare const RoutineSchema: z.ZodObject<{
     enabled: boolean;
     name: string;
     id: string;
+    notify: {
+        config: Record<string, unknown>;
+        kind: "email" | "stdout" | "webhook" | "slack";
+        on: "always" | "failure" | "success";
+    }[];
     description: string;
     schedule: {
         kind: "manual";
@@ -239,11 +244,6 @@ export declare const RoutineSchema: z.ZodObject<{
         tool: string;
         args: Record<string, unknown>;
     };
-    notify: {
-        config: Record<string, unknown>;
-        kind: "email" | "stdout" | "webhook" | "slack";
-        on: "always" | "failure" | "success";
-    }[];
     tags: string[];
     updatedAt?: string | undefined;
     createdAt?: string | undefined;
@@ -281,14 +281,14 @@ export declare const RoutineSchema: z.ZodObject<{
     };
     enabled?: boolean | undefined;
     updatedAt?: string | undefined;
-    description?: string | undefined;
-    targets?: string[] | undefined;
-    perTarget?: boolean | undefined;
     notify?: {
         kind: "email" | "stdout" | "webhook" | "slack";
         config?: Record<string, unknown> | undefined;
         on?: "always" | "failure" | "success" | undefined;
     }[] | undefined;
+    description?: string | undefined;
+    targets?: string[] | undefined;
+    perTarget?: boolean | undefined;
     tags?: string[] | undefined;
     createdAt?: string | undefined;
 }>;

package/dist/core/routines/store.d.ts

@@ -112,6 +112,11 @@ declare const FileSchema: z.ZodObject<{
         enabled: boolean;
         name: string;
         id: string;
+        notify: {
+            config: Record<string, unknown>;
+            kind: "email" | "stdout" | "webhook" | "slack";
+            on: "always" | "failure" | "success";
+        }[];
         description: string;
         schedule: {
             kind: "manual";
@@ -144,11 +149,6 @@ declare const FileSchema: z.ZodObject<{
             tool: string;
             args: Record<string, unknown>;
         };
-        notify: {
-            config: Record<string, unknown>;
-            kind: "email" | "stdout" | "webhook" | "slack";
-            on: "always" | "failure" | "success";
-        }[];
         tags: string[];
         updatedAt?: string | undefined;
         createdAt?: string | undefined;
@@ -186,14 +186,14 @@ declare const FileSchema: z.ZodObject<{
         };
         enabled?: boolean | undefined;
         updatedAt?: string | undefined;
-        description?: string | undefined;
-        targets?: string[] | undefined;
-        perTarget?: boolean | undefined;
         notify?: {
             kind: "email" | "stdout" | "webhook" | "slack";
             config?: Record<string, unknown> | undefined;
             on?: "always" | "failure" | "success" | undefined;
         }[] | undefined;
+        description?: string | undefined;
+        targets?: string[] | undefined;
+        perTarget?: boolean | undefined;
         tags?: string[] | undefined;
         createdAt?: string | undefined;
     }>, "many">;
@@ -204,6 +204,11 @@ declare const FileSchema: z.ZodObject<{
         enabled: boolean;
         name: string;
         id: string;
+        notify: {
+            config: Record<string, unknown>;
+            kind: "email" | "stdout" | "webhook" | "slack";
+            on: "always" | "failure" | "success";
+        }[];
         description: string;
         schedule: {
             kind: "manual";
@@ -236,11 +241,6 @@ declare const FileSchema: z.ZodObject<{
             tool: string;
             args: Record<string, unknown>;
         };
-        notify: {
-            config: Record<string, unknown>;
-            kind: "email" | "stdout" | "webhook" | "slack";
-            on: "always" | "failure" | "success";
-        }[];
         tags: string[];
         updatedAt?: string | undefined;
         createdAt?: string | undefined;
@@ -282,14 +282,14 @@ declare const FileSchema: z.ZodObject<{
         };
         enabled?: boolean | undefined;
         updatedAt?: string | undefined;
-        description?: string | undefined;
-        targets?: string[] | undefined;
-        perTarget?: boolean | undefined;
         notify?: {
             kind: "email" | "stdout" | "webhook" | "slack";
             config?: Record<string, unknown> | undefined;
             on?: "always" | "failure" | "success" | undefined;
         }[] | undefined;
+        description?: string | undefined;
+        targets?: string[] | undefined;
+        perTarget?: boolean | undefined;
         tags?: string[] | undefined;
         createdAt?: string | undefined;
     }[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matthesketh/fleet",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Docker production management CLI + MCP server for Claude Code",
   "type": "module",
   "main": "dist/index.js",
@@ -10,6 +10,7 @@
   "files": [
     "dist/",
     "data/registry.example.json",
+    "scripts/guard/",
     "LICENSE",
     "README.md"
   ],

package/scripts/guard/cert-expiry-watch

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""
+cert-expiry-watch — sweeps /etc/letsencrypt/live and reports any cert
+that's expiring soon. tiered alerts:
+- < 14 days: notify (info)
+- < 3 days: hold (renewal probably broken — needs eyes)
+
+run from cron once a day.
+"""
+
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+LIVE = Path("/etc/letsencrypt/live")
+GUARD = "/usr/local/sbin/fleet-guard"
+NOTIFY = "/usr/local/sbin/notify"
+
+
+def active_cert_paths():
+    """parse nginx -T output to find ssl_certificate paths actually in use.
+    returns set of resolved file paths (Path objects)."""
+    try:
+        out = subprocess.run(
+            ["nginx", "-T"], capture_output=True, text=True, timeout=10,
+        )
+    except Exception:
+        return None  # cannot determine — caller should fall back
+    if out.returncode != 0:
+        return None
+    paths = set()
+    for m in re.finditer(r"ssl_certificate\s+([^\s;]+);", out.stdout):
+        paths.add(Path(m.group(1)).resolve())
+    return paths
+
+
+def cert_is_active(cert_dir, active):
+    """check if any cert under cert_dir is referenced by nginx."""
+    if active is None:
+        return True  # nginx not parseable — fall back to flagging everything
+    candidates = [
+        cert_dir / "fullchain.pem",
+        cert_dir / "cert.pem",
+        cert_dir / "chain.pem",
+    ]
+    return any(p.resolve() in active for p in candidates if p.exists())
+
+
+def cert_not_after(path):
+    out = subprocess.run(
+        ["openssl", "x509", "-noout", "-enddate", "-in", str(path)],
+        capture_output=True, text=True, timeout=5,
+    )
+    if out.returncode != 0:
+        return None
+    line = out.stdout.strip()  # notAfter=Apr 25 12:34:56 2026 GMT
+    _, _, when = line.partition("=")
+    try:
+        return datetime.strptime(when.strip(), "%b %d %H:%M:%S %Y %Z").replace(tzinfo=timezone.utc)
+    except ValueError:
+        return None
+
+
+def main():
+    if not LIVE.exists():
+        return 0
+    now = datetime.now(timezone.utc)
+    active = active_cert_paths()
+    soon = []
+    critical = []
+    skipped_inactive = 0
+    for cert_dir in sorted(LIVE.iterdir()):
+        if not cert_dir.is_dir():
+            continue
+        cert_path = cert_dir / "cert.pem"
+        if not cert_path.exists():
+            continue
+        if not cert_is_active(cert_dir, active):
+            skipped_inactive += 1
+            continue
+        not_after = cert_not_after(cert_path)
+        if not not_after:
+            continue
+        days_left = (not_after - now).total_seconds() / 86400
+        item = {"name": cert_dir.name, "expires": not_after.isoformat(), "days": int(days_left)}
+        if days_left < 3:
+            critical.append(item)
+        elif days_left < 14:
+            soon.append(item)
+
+    if soon:
+        body = "\n".join(f"{i['name']}: {i['days']}d left ({i['expires']})" for i in soon)
+        subprocess.run([NOTIFY, "certs expiring soon", body], check=False)
+
+    for item in critical:
+        summary = f"cert {item['name']} expires in {item['days']}d — renewal probably broken"
+        subprocess.run(
+            [GUARD, "hold", "cert_expiry_critical", summary, "--payload",
+             '{"cert":"' + item["name"] + '"}'],
+            check=False,
+        )
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/guard/cf-audit-monitor

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""
+poll cloudflare audit log api and notify via telegram on each new event.
+- state: /var/lib/cf-audit/last-seen.txt (rfc3339 utc)
+- creds: read from /root/.claude.json (cloudflare-mcp env block)
+- runs from cron every 15m. on first run seeds the state to "now-1h".
+- categorises events: noise events are silently logged; everything else
+  fires a telegram message.
+"""
+
+import json
+import os
+import sys
+import time
+import urllib.request
+import urllib.parse
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from subprocess import run
+
+CLAUDE_CFG = Path("/root/.claude.json")
+STATE_DIR = Path("/var/lib/cf-audit")
+STATE_FILE = STATE_DIR / "last-seen.txt"
+LOG_FILE = STATE_DIR / "events.jsonl"
+NOTIFIER = "/usr/local/sbin/notify"
+GUARD = "/usr/local/sbin/fleet-guard"
+
+# events that happen routinely and shouldn't page us
+NOISY_ACTIONS = {
+    "login",
+    "purge",
+    "challenge_solve",
+    "user_read",
+    "search",
+}
+
+# event action types that should always create a hold (require approval)
+# instead of merely notifying. these are the destructive / hijack-shaped ones.
+HOLD_ACTIONS = {
+    "zone_delete", "zone_create", "zone_settings_change",
+    "ns_change", "transfer_in", "transfer_out",
+    "member_add", "member_remove",
+    "api_token_create", "api_token_delete",
+    "ssl_change",
+}
+
+
+def read_creds():
+    with CLAUDE_CFG.open() as f:
+        cfg = json.load(f)
+    env = cfg.get("mcpServers", {}).get("cloudflare-mcp", {}).get("env", {}) or {}
+    api_key = env.get("CLOUDFLARE_API_KEY")
+    email = env.get("CLOUDFLARE_EMAIL")
+    if not api_key or not email:
+        sys.exit("cf creds missing in /root/.claude.json (mcpServers.cloudflare-mcp.env)")
+    # account id needed for v2 audit endpoint
+    inf_env = cfg.get("mcpServers", {}).get("infrastructure-mcp", {}).get("env", {}) or {}
+    account_id = inf_env.get("CLOUDFLARE_ACCOUNT_ID")
+    if not account_id:
+        sys.exit("CLOUDFLARE_ACCOUNT_ID missing in infrastructure-mcp env")
+    return api_key, email, account_id
+
+
+def load_since():
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+    if STATE_FILE.exists():
+        return STATE_FILE.read_text().strip()
+    # first run: pull last hour
+    return (datetime.now(timezone.utc) - timedelta(hours=1)).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def save_since(ts):
+    STATE_FILE.write_text(ts + "\n")
+
+
+def fetch_events(api_key, email, account_id, since):
+    # cf accounts audit log v1 endpoint (free plan compatible)
+    qs = urllib.parse.urlencode({
+        "since": since,
+        "before": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "per_page": 100,
+    })
+    url = f"https://api.cloudflare.com/client/v4/accounts/{account_id}/audit_logs?{qs}"
+    req = urllib.request.Request(url, headers={
+        "X-Auth-Email": email,
+        "X-Auth-Key": api_key,
+        "Content-Type": "application/json",
+    })
+    with urllib.request.urlopen(req, timeout=20) as resp:
+        return json.loads(resp.read())
+
+
+def classify(action_type):
+    a = (action_type or "").lower()
+    if a in NOISY_ACTIONS:
+        return "noise"
+    return "alert"
+
+
+def notify(title, body):
+    run([NOTIFIER, title, body], check=False)
+
+
+def fmt_event(ev):
+    when = ev.get("when", "?")
+    who = (ev.get("actor") or {}).get("email") or "?"
+    ip = (ev.get("actor") or {}).get("ip") or "?"
+    action = (ev.get("action") or {}).get("type") or "?"
+    resource = (ev.get("resource") or {}).get("type") or "?"
+    res_id = (ev.get("resource") or {}).get("id") or ""
+    metadata = ev.get("metadata") or {}
+    extras = ", ".join(f"{k}={v}" for k, v in metadata.items() if k in ("name", "domain", "zone"))
+    line = f"{when}\n{action} {resource} by {who} from {ip}"
+    if res_id:
+        line += f"\nresource: {res_id}"
+    if extras:
+        line += f"\n{extras}"
+    return line
+
+
+def main():
+    api_key, email, account_id = read_creds()
+    since = load_since()
+    try:
+        data = fetch_events(api_key, email, account_id, since)
+    except Exception as e:
+        notify("cf-audit-monitor failed", f"fetch error: {e}")
+        sys.exit(1)
+    if not data.get("success", False):
+        errs = data.get("errors") or []
+        notify("cf-audit-monitor api error", json.dumps(errs)[:300])
+        sys.exit(1)
+
+    events = data.get("result") or []
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+    if events:
+        with LOG_FILE.open("a") as f:
+            for ev in events:
+                f.write(json.dumps(ev) + "\n")
+
+    alerts = [ev for ev in events if classify((ev.get("action") or {}).get("type")) == "alert"]
+    for ev in alerts:
+        action = (ev.get("action") or {}).get("type") or ""
+        if action in HOLD_ACTIONS:
+            # destructive — create a fleet-guard hold instead of just notifying.
+            # the cli itself fires the notification with approval token.
+            payload = {
+                "cf_event": ev,
+                "suggested_action": "review and approve to acknowledge",
+            }
+            try:
+                run([GUARD, "hold", f"cf_{action}", fmt_event(ev), "--payload",
+                     json.dumps(payload)], check=False, timeout=30)
+            except Exception as e:
+                notify("cf-audit hold-failed", f"{e}\n{fmt_event(ev)}")
+        else:
+            notify("cloudflare audit event", fmt_event(ev))
+
+    # advance cursor: latest "when" + 1s, or now if no events
+    if events:
+        latest = max(ev.get("when", "") for ev in events)
+        if latest:
+            save_since(latest)
+    else:
+        save_since(datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"))
+
+
+if __name__ == "__main__":
+    main()