quoxcli 0.4.0 → 0.5.0

package/lib/commands/wazuh.js

@@ -0,0 +1,824 @@
+/**
+ * Wazuh commands (WAZ-3): first-class `quox wazuh`, the sibling of `quox kuma`.
+ *
+ * quox wazuh | status            manager healthy? stopped daemons (optional ones labelled), agent counts by state
+ * quox wazuh agents [--status --os --limit]     enrolled agents
+ * quox wazuh agents get <id|name>               one agent
+ * quox wazuh alerts [--level --since --agent --rule --mitre --limit]
+ * quox wazuh triage [--since --level --limit]   alerts grouped by rule (indexer aggregation; WAZ P7: CONTEXT flags per group)
+ * quox wazuh coverage                           fleet hosts vs Wazuh agents: gaps
+ * quox wazuh vulns [--severity --agent --limit]
+ * quox wazuh vulns --priority [--kev-only --agent --limit]   CVEs ranked by CISA KEV, EPSS, CVSS, hosts affected
+ * quox wazuh fim|sca|rootcheck [--agent]        syscheck, compliance policies (pass/fail), rootcheck
+ * quox wazuh deploy-history
+ * Writes (always the governed wazuh_* tool path, held for a human approval, the approval id is printed):
+ * quox wazuh deploy <host> | deploy-bulk <hosts...> | remove <agentId> | active-response <agentId> --command <c>
+ * quox wazuh indexer install-credential
+ * quox wazuh report generate|list|show|verify   signed, offline-verifiable posture report (wazuhReport.js)
+ * quox wazuh hooks create|list|rotate|delete|install   per-org signed hook Wazuh integratord posts alerts to (wazuhIntake.js);
+ *                                               install wires the manager to it in one governed step (wazuh_hooks_install)
+ * quox wazuh incidents [--open] [--since] | show | close   alerts that became witnessed incidents (wazuhIntake.js)
+ *
+ * Backend (existing collector routes): GET /api/v1/wazuh/{manager/status,agents,alerts,vulnerabilities,deploy-history};
+ * POST /api/v1/wazuh/proxy (read-only allowlist: /syscheck/:id, /sca/:id) for fim and sca.
+ * Tools it files through POST /api/v1/tools/execute: wazuh_rootcheck, wazuh_deploy_agent, wazuh_agent_remove,
+ * wazuh_active_response, wazuh_indexer_credential_install, wazuh_hooks_install.
+ *
+ * Honesty: a non-2xx, a success:false body, or a Wazuh error body inside a 200 is an ERROR (exit 1), reported with
+ * the verb, endpoint and status. It is never rendered as "0 agents". `status` exits 3 when the manager is unhealthy.
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+import { line as glyphLine } from '../core/quoxglyph.js';
+import { resolveOrgId } from './helpers.js';
+import { execResultFailed, execResultPending, pendingBodyOfError } from './agentAttach.js';
+import { relDuration } from './kuma.js';
+import { registerWazuhReport } from './wazuhReport.js';
+import { registerWazuhIntake, contextFlags } from './wazuhIntake.js';
+
+class WazFail extends Error {
+  constructor(message, exitCode = 1) { super(message); this.exitCode = exitCode; }
+}
+
+/**
+ * The daemons a manager cannot be called healthy without. Explicit on purpose: a stopped daemon is "unhealthy"
+ * only if it is in this set.
+ */
+export const REQUIRED_DAEMONS = new Set(['wazuh-analysisd', 'wazuh-remoted', 'wazuh-apid', 'wazuh-db', 'wazuh-modulesd', 'wazuh-execd', 'wazuh-authd', 'wazuh-monitord', 'wazuh-logcollector', 'wazuh-syscheckd']);
+/**
+ * Daemons Wazuh ships stopped unless the feature is switched on: a stopped one is not an unhealthy manager.
+ * wazuh-reportd is deprecated in 4.x (reports live in the dashboard), so it is stopped on a healthy manager.
+ */
+export const OPTIONAL_DAEMONS = new Set(['wazuh-clusterd', 'wazuh-maild', 'wazuh-agentlessd', 'wazuh-integratord', 'wazuh-dbd', 'wazuh-csyslogd', 'wazuh-reportd']);
+const AGENT_STATES = ['active', 'disconnected', 'never_connected', 'pending'];
+const PROXY_AGENT_CAP = 200; // fleet-wide reads batch 50 agents per tool call (WAZ-4), so 200 is at most 4 calls
+
+const plural = (n, one, many = `${one}s`) => `${n} ${Number(n) === 1 ? one : many}`;
+const stateText = (s) => String(s || 'unknown').replace(/_/g, ' ');
+
+function pad(rows) {
+  const w = [];
+  for (const r of rows) r.forEach((c, i) => { w[i] = Math.max(w[i] || 0, [...String(c)].length); });
+  return rows.map((r) => r.map((c, i) => String(c) + ' '.repeat(w[i] - [...String(c)].length)).join('  ').trimEnd());
+}
+
+const toMs = (v) => {
+  if (v === null || v === undefined || v === '') return null;
+  const t = typeof v === 'number' ? v : Date.parse(String(v));
+  return Number.isFinite(t) ? t : null;
+};
+/** "5m ago", or "-" when there is no usable time. */
+export function agoText(v, now = Date.now()) {
+  const t = toMs(v);
+  if (t === null) return '-';
+  return t > now ? 'in the future' : `${relDuration(now - t)} ago`;
+}
+/** Wazuh stamps the manager's own agent 000 with a keep-alive of 9999-12-31. */
+const isFarFuture = (v) => { const t = toMs(v); return t !== null && t > Date.now() + 365 * 864e5; };
+/** "YYYY-MM-DD HH:MM UTC". */
+export function utcText(v) {
+  const t = toMs(v);
+  return t === null ? '-' : `${new Date(t).toISOString().slice(0, 16).replace('T', ' ')} UTC`;
+}
+
+/** "24h", "7d", "30m", "2w" or an ISO date -> epoch ms. null when it is none of those. */
+export function parseSince(value, now = Date.now()) {
+  const m = /^(\d+)\s*([smhdw])$/i.exec(String(value).trim());
+  if (m) return now - Number(m[1]) * { s: 1e3, m: 6e4, h: 36e5, d: 864e5, w: 6048e5 }[m[2].toLowerCase()];
+  if (/^\d{4}-\d\d-\d\d/.test(String(value).trim())) { const t = Date.parse(value); return Number.isFinite(t) ? t : null; }
+  return null;
+}
+
+const HINTS = {
+  wazuh_indexer_credential_missing: 'Fix: quox wazuh indexer install-credential (files an approval; a person approves it, then retry).',
+  wazuh_sudo_refused: 'The Bastion exec user on the Wazuh host cannot run `sudo -n`, so it cannot read the indexer credential file. An owner grants that user a narrow NOPASSWD rule for the indexer read on that host.',
+  wazuh_not_configured: 'Wazuh is not configured for this org. An org admin connects it: quox wazuh connect --url <url> --user <user>; an instance superadmin who is also an org admin can import the collector\'s own Wazuh with: quox wazuh connect --from-instance-env',
+  wazuh_lease_blocked: 'The Wazuh credential lease is blocked, so the collector may not read it right now.',
+  wazuh_host_not_in_fleet: 'Check: quox fleet list (the Wazuh host must be a registered fleet host).',
+  wazuh_fleet_not_loaded: 'Check: quox fleet list; retry in a minute if the collector just restarted.',
+  wazuh_fleet_unavailable: 'Check: quox fleet list.',
+};
+
+/** Failure for a thrown API error: verb, endpoint, HTTP status, the server's own words, and a TRUE next step if known. */
+function failFrom(verb, method, path, err, via = '') {
+  const status = err && (err.status ?? err.statusCode);
+  const body = err && err.body && typeof err.body === 'object' ? err.body : null;
+  const code = (body && (body.code || (typeof body.error === 'string' && /^wazuh_/.test(body.error) ? body.error : null))) || (err && typeof err.code === 'string' ? err.code : null);
+  const said = (body && (body.message || (typeof body.error === 'string' ? body.error : null))) || (err && err.message) || String(err);
+  const hint = HINTS[code];
+  return new WazFail(`quox wazuh ${verb}: ${method} ${path}${via} failed${status ? ` with HTTP ${status}` : ''}: ${said}${hint ? `\n  ${hint}` : ''}`);
+}
+
+/**
+ * The Wazuh body behind a collector route: { success, data: <Wazuh API body>, status }. A Wazuh error (401/404)
+ * arrives as a 200 from the collector with the failure inside, so check it here before reading anything.
+ */
+function wazuhItems(verb, method, path, res) {
+  if (!res || typeof res !== 'object') throw new WazFail(`quox wazuh ${verb}: ${method} ${path} returned no body`);
+  const up = res.data;
+  const st = res.status;
+  const upDetail = up && typeof up === 'object' ? [up.title, up.detail].filter(Boolean).join(': ') : '';
+  if ((typeof st === 'number' && st >= 400) || (up && typeof up === 'object' && up.title && !up.data)) {
+    throw new WazFail(`quox wazuh ${verb}: ${method} ${path} failed: Wazuh answered ${st || 'an error'}${upDetail ? ` (${upDetail})` : ''}`);
+  }
+  if (res.success === false) throw new WazFail(`quox wazuh ${verb}: ${method} ${path} returned an error body: ${res.error || (typeof up === 'string' ? up.slice(0, 200) : 'success false')}`);
+  if (up && typeof up === 'object' && up.error && up.error !== 0) throw new WazFail(`quox wazuh ${verb}: ${method} ${path} failed: Wazuh error ${up.error}${upDetail ? ` (${upDetail})` : ''}`);
+  const inner = up && (up.data && typeof up.data === 'object' ? up.data : up);
+  if (!inner || !Array.isArray(inner.affected_items)) throw new WazFail(`quox wazuh ${verb}: ${method} ${path} returned an unexpected body (no affected_items); use --json to see it`);
+  return { items: inner.affected_items, total: inner.total_affected_items ?? inner.affected_items.length };
+}
+
+export function registerWazuhCommands(program, ctx) {
+  const wazuh = program
+    .command('wazuh')
+    .description('Wazuh security monitoring. Bare `quox wazuh` runs status. Verbs: status, agents, alerts, incidents, hooks, triage, coverage, vulns, fim, sca, rootcheck, report, deploy-history, deploy, deploy-bulk, remove, active-response, indexer')
+    .addHelpText('after', '\nExample:  quox wazuh\nExit codes: 0 ok, 1 error, 3 `quox wazuh status` found the manager unhealthy. Writes are held for human approval.');
+  attachWazuhVerbs(wazuh, program, ctx, { writes: true });
+  attachWazuhConnect(wazuh, program, ctx);
+}
+
+/**
+ * Attach the wazuh verbs to `wazuh`. `quox mon wazuh` shares the read verbs (one code path);
+ * its three legacy write verbs (deploy-agent, deploy-bulk, active-response) live in mon.js and run through the
+ * governed helpers this returns ({ guard, writeTool, deployOne, WazFail }), the same path `quox wazuh` writes take.
+ */
+export function attachWazuhVerbs(wazuh, program, ctx, { writes = true } = {}) {
+  const { client, auth } = ctx;
+  const jsonOut = () => program.opts().output === 'json';
+  const head = (verb, result, status = 'ok') => console.log(glyphLine('quox', `wazuh ${verb}`, { result, status }));
+
+  const example = (cmd, text) => cmd.addHelpText('after', `\nExample:  ${text}`);
+
+  const guard = (fn) => async (...args) => {
+    try { await fn(...args); } catch (err) {
+      if (!(err instanceof WazFail)) throw err;
+      console.error(err.message);
+      process.exitCode = err.exitCode || 1;
+    }
+  };
+
+  // A full-fleet CVE ranking runs two indexer passes plus the KEV/EPSS feeds and can pass 30 s (live 2026-11-05).
+  const SLOW_READS = { 'mon.wazuh.vulnerabilities.priority': 180000 };
+  async function getRoute(verb, key, query) {
+    const ep = resolveEndpoint(key);
+    let data;
+    try {
+      data = await client.get(ep.path, { service: ep.service, ...(query && Object.keys(query).length ? { query } : {}), ...(SLOW_READS[key] ? { timeout: SLOW_READS[key] } : {}) });
+    } catch (err) { throw failFrom(verb, ep.method, ep.path, err); }
+    return { ep, data };
+  }
+
+  async function proxyGet(verb, endpoint) {
+    const ep = resolveEndpoint('mon.wazuh.proxy');
+    let data;
+    try {
+      data = await client.post(ep.path, { service: ep.service, body: { endpoint, method: 'GET' } });
+    } catch (err) { throw failFrom(verb, ep.method, ep.path, err, ` (GET ${endpoint.split('?')[0]})`); }
+    return wazuhItems(verb, ep.method, `${ep.path} (GET ${endpoint.split('?')[0]})`, data);
+  }
+
+  async function allAgents(verb, query = { limit: '500' }) {
+    const { ep, data } = await getRoute(verb, 'mon.wazuh.agents.list', query);
+    return { ...wazuhItems(verb, ep.method, ep.path, data) };
+  }
+
+  const countStates = (agents) => {
+    const c = { active: 0, disconnected: 0, never_connected: 0, pending: 0, other: 0, total: agents.length };
+    for (const a of agents) { if (AGENT_STATES.includes(a.status)) c[a.status]++; else c.other++; }
+    return c;
+  };
+  const countText = (c) => {
+    const parts = [];
+    for (const s of AGENT_STATES) if (c[s]) parts.push(`${c[s]} ${stateText(s)}`);
+    if (c.other) parts.push(`${c.other} other`);
+    return parts.length ? parts.join(' · ') : 'none enrolled';
+  };
+
+  // ---- status ----
+  const statusAction = guard(async () => {
+    auth.requireAuth();
+    const m = await getRoute('status', 'mon.wazuh.manager-status.get');
+    const { items } = wazuhItems('status', m.ep.method, m.ep.path, m.data);
+    const daemons = items[0] && typeof items[0] === 'object' ? items[0] : {};
+    const names = Object.keys(daemons).sort();
+    if (!names.length) throw new WazFail(`quox wazuh status: ${m.ep.method} ${m.ep.path} returned no daemons`);
+    const running = names.filter((n) => daemons[n] === 'running');
+    const stopped = names.filter((n) => daemons[n] !== 'running');
+    const brokenCore = stopped.filter((n) => REQUIRED_DAEMONS.has(n) || !OPTIONAL_DAEMONS.has(n));
+    const healthy = brokenCore.length === 0;
+    const a = await allAgents('status');
+    const counts = countStates(a.items);
+    if (a.total > a.items.length) counts.total = a.total;
+    if (jsonOut()) {
+      console.log(JSON.stringify({ healthy, daemons, stopped_core: brokenCore, agents: counts }, null, 2));
+    } else {
+      head('status', `manager ${healthy ? 'healthy' : 'unhealthy'} · ${plural(counts.total, 'agent')}`, healthy ? 'ok' : 'fail');
+      console.log(`Manager ${healthy ? 'healthy' : 'unhealthy'}: ${running.length} running${stopped.length ? `, ${stopped.length} stopped` : ''}`);
+      if (stopped.length) {
+        console.log(pad(stopped.map((n) => [`  ${n}`, OPTIONAL_DAEMONS.has(n) ? `${daemons[n]} (optional)` : String(daemons[n])])).join('\n'));
+      }
+      console.log(`Agents: ${countText(counts)}${a.total > a.items.length ? ` (counted the first ${a.items.length} of ${a.total})` : ''}`);
+      if (!healthy) console.log(`Not running: ${brokenCore.join(', ')}. Check the manager host's service logs.`);
+    }
+    if (!healthy) process.exitCode = 3;
+  });
+  example(wazuh.command('status').description('Manager health (daemons) and agent counts by state').action(statusAction), 'quox wazuh status');
+  wazuh.action(statusAction);
+
+  // ---- agents ----
+  const agentOs = (a) => (a.os && (a.os.name || a.os.platform)) || '-';
+  const agents = wazuh.command('agents').description('Enrolled Wazuh agents')
+    .option('--status <status>', 'active|disconnected|never_connected|pending')
+    .option('--os <text>', 'only agents whose OS name or platform contains this')
+    .option('--limit <n>', 'max agents (default 100)');
+  example(agents, 'quox wazuh agents --status disconnected');
+  agents.action(guard(async (options) => {
+    auth.requireAuth();
+    const limit = options.limit ? String(options.limit) : '100'; // display cap; the route only gets a limit when you give one
+    if (options.limit && !/^\d+$/.test(limit)) throw new WazFail(`quox wazuh agents: --limit needs a whole number, got "${options.limit}"`);
+    const query = {};
+    if (options.os) query.limit = '500'; else if (options.limit) query.limit = limit;
+    if (options.status) query.status = options.status;
+    const { ep, data } = await getRoute('agents', 'mon.wazuh.agents.list', query);
+    let { items, total } = wazuhItems('agents', ep.method, ep.path, data);
+    if (options.os) {
+      const needle = String(options.os).toLowerCase();
+      items = items.filter((a) => `${(a.os && a.os.name) || ''} ${(a.os && a.os.platform) || ''}`.toLowerCase().includes(needle));
+      total = items.length;
+    }
+    const shown = items.slice(0, Number(limit));
+    if (jsonOut()) { console.log(JSON.stringify({ agents: shown, total }, null, 2)); return; }
+    head('agents', total > shown.length ? `showing ${shown.length} of ${total}` : plural(shown.length, 'agent'));
+    if (!shown.length) { console.log(options.status || options.os ? 'No agents match.' : 'No agents enrolled.'); return; }
+    const rows = [['ID', 'NAME', 'IP', 'STATUS', 'OS', 'VERSION', 'LAST SEEN']];
+    for (const a of shown) rows.push([a.id, a.name || '-', a.ip || '-', a.status || '-', agentOs(a), String(a.version || '-').replace(/^Wazuh /, ''), a.id === '000' && isFarFuture(a.lastKeepAlive) ? 'manager (local)' : agoText(a.lastKeepAlive)]);
+    console.log(pad(rows).join('\n'));
+  }));
+  example(agents.command('get').description('One agent by id or name (reads the wazuh_agent_get tool)')
+    .argument('<id|name>', 'agent id (1 or 001) or name')
+    .action(guard(async (key) => {
+      auth.requireAuth();
+      const input = /^\d+$/.test(key) ? { agent_id: String(Number(key)).padStart(3, '0') } : { name: key };
+      const { data } = await callTool('agents get', 'wazuh_agent_get', input);
+      const r = failIfToolFailed('agents get', 'wazuh_agent_get', data);
+      let hit = r.agent && typeof r.agent === 'object' ? r.agent : (r.id ? r : null);
+      // A caller whose hat lacks the tool gets it auto-delegated to its single holder, which answers in prose (no record).
+      // The org-scoped agents list route carries the same manager record, so read the agent from there and say so.
+      const hop = delegatedTo(data);
+      if (!hit && hop) {
+        const { items } = await allAgents('agents get');
+        const want = /^\d+$/.test(key) ? String(Number(key)).padStart(3, '0') : key;
+        hit = items.find((a) => (/^\d+$/.test(key) ? String(a.id) === want : a.name === want)) || null;
+        if (hit) console.error(`wazuh_agent_get was auto-delegated to agent ${hop} (a prose answer, no record); read from the agents list route instead.`);
+      }
+      if (!hit) throw new WazFail(`quox wazuh agents get: no agent "${key}". List them: quox wazuh agents`);
+      if (jsonOut()) { console.log(JSON.stringify(hit, null, 2)); return; }
+      head(`agents get ${hit.id}`, `${hit.name} ${hit.status}`, hit.status === 'active' ? 'ok' : 'warn');
+      const lastSeen = hit.lastKeepAlive || hit.last_keep_alive;
+      const rows = [['ID', hit.id], ['NAME', hit.name], ['IP', hit.ip], ['STATUS', hit.status], ['OS', typeof hit.os === 'string' ? hit.os : agentOs(hit)], ['VERSION', hit.version],
+        ['GROUPS', Array.isArray(hit.group) ? hit.group.join(', ') : hit.group], ['NODE', hit.node_name],
+        ['LAST SEEN', lastSeen ? (String(hit.id) === '000' && isFarFuture(lastSeen) ? 'manager (local)' : `${agoText(lastSeen)} (${utcText(lastSeen)})`) : null],
+        ['ENROLLED', hit.dateAdd ? `${agoText(hit.dateAdd)} (${utcText(hit.dateAdd)})` : null]];
+      console.log(pad(rows.map(([k, v]) => [k, v ?? '-'])).join('\n'));
+    })), 'quox wazuh agents get web01');
+
+  // ---- alerts ----
+  example(wazuh.command('alerts').description('Recent alerts, newest first')
+    .option('--q <text>', 'free text matched in rule description, agent name or rule groups')
+    .option('--level <n>', 'only rule level N and above (12+ is high severity)')
+    .option('--since <window>', 'only alerts newer than this: 30m, 24h, 7d or an ISO date')
+    .option('--agent <id|name>', 'only this agent')
+    .option('--rule <id|text>', 'rule id, or text in the rule description')
+    .option('--mitre <id>', 'MITRE technique id, e.g. T1110')
+    .option('--limit <n>', 'max alerts shown (default 50, capped at 500)')
+    .action(guard(async (options) => {
+      auth.requireAuth();
+      let sinceMs = null;
+      if (options.since) {
+        sinceMs = parseSince(options.since);
+        if (sinceMs === null) throw new WazFail(`quox wazuh alerts: --since needs a window like 30m, 24h, 7d or an ISO date, got "${options.since}"`);
+      }
+      if (options.level && !/^\d+$/.test(String(options.level))) throw new WazFail(`quox wazuh alerts: --level needs a whole number, got "${options.level}"`);
+      if (options.limit && !/^\d+$/.test(String(options.limit))) throw new WazFail(`quox wazuh alerts: --limit needs a whole number, got "${options.limit}"`);
+      const want = Math.min(Number(options.limit) || 50, 500);
+      const clientFilter = Boolean(options.since || options.agent || options.rule || options.mitre);
+      const query = {};
+      if (clientFilter) query.limit = '500'; else if (options.limit) query.limit = String(want);
+      if (options.q) query.q = options.q;
+      if (options.level) query.min_level = String(options.level);
+      const { ep, data } = await getRoute('alerts', 'mon.wazuh.alerts.list', query);
+      if (!data || data.success === false || !Array.isArray(data.data)) throw new WazFail(`quox wazuh alerts: ${ep.method} ${ep.path} returned an error body: ${(data && (data.message || data.error)) || 'no alerts array'}`);
+      const scanned = data.data.length;
+      const lc = (v) => String(v ?? '').toLowerCase();
+      const list = data.data.filter((al) => {
+        if (sinceMs !== null) { const t = toMs(al.timestamp); if (t === null || t < sinceMs) return false; }
+        if (options.agent && ![al.agent && al.agent.id, al.agent && al.agent.name].some((x) => lc(x) === lc(options.agent))) return false;
+        if (options.rule) {
+          const r = al.rule || {};
+          if (!(lc(r.id) === lc(options.rule) || lc(r.description).includes(lc(options.rule)))) return false;
+        }
+        if (options.mitre) {
+          const ids = [].concat((al.rule && al.rule.mitre && al.rule.mitre.id) || []).map(lc);
+          if (!ids.includes(lc(options.mitre))) return false;
+        }
+        return true;
+      }).slice(0, want);
+      if (jsonOut()) { console.log(JSON.stringify({ alerts: list, scanned, total: data.total ?? scanned }, null, 2)); return; }
+      const scope = [options.level ? `level ${options.level}+` : '', options.since ? `last ${options.since}` : ''].filter(Boolean).join(', ');
+      head('alerts', `${plural(list.length, 'alert')}${scope ? ` (${scope})` : ''}`, list.some((a) => (a.rule && a.rule.level) >= 12) ? 'warn' : 'ok');
+      if (!list.length) { console.log(clientFilter ? `No alerts match in the ${plural(scanned, 'newest alert')} scanned.` : 'No alerts found.'); return; }
+      const rows = [['WHEN', 'UTC', 'LVL', 'AGENT', 'RULE', 'DESCRIPTION']];
+      for (const al of list) rows.push([agoText(al.timestamp), utcText(al.timestamp), (al.rule && al.rule.level) ?? '-', (al.agent && al.agent.name) || '-', (al.rule && al.rule.id) || '-', (al.rule && al.rule.description) || '-']);
+      console.log(pad(rows).join('\n'));
+      if (!clientFilter && (data.total ?? 0) > list.length) console.log(`Showing ${list.length} of ${data.total}; raise --limit to see more.`);
+    })), 'quox wazuh alerts --level 10 --since 24h');
+
+  // ---- triage ----
+  example(wazuh.command('triage').description('Alerts grouped by rule: count, top hosts, MITRE, highest level first')
+    .option('--since <window>', 'window: 30m, 24h, 7d (default 24h)')
+    .option('--level <n>', 'only rule level N and above (default 7; 12+ is high severity)')
+    .option('--limit <n>', 'max rule groups (default 20, capped at 100)')
+    .action(guard(async (options) => {
+      auth.requireAuth();
+      if (options.since && !/^\d{1,4}[mhd]$/.test(String(options.since))) throw new WazFail(`quox wazuh triage: --since needs a window like 30m, 24h or 7d, got "${options.since}"`);
+      if (options.level && !/^\d+$/.test(String(options.level))) throw new WazFail(`quox wazuh triage: --level needs a whole number, got "${options.level}"`);
+      if (options.limit && !/^\d+$/.test(String(options.limit))) throw new WazFail(`quox wazuh triage: --limit needs a whole number, got "${options.limit}"`);
+      const query = {};
+      if (options.since) query.since = String(options.since);
+      if (options.level) query.level = String(options.level);
+      if (options.limit) query.limit = String(options.limit);
+      const { ep, data } = await getRoute('triage', 'mon.wazuh.alerts.triage', query);
+      if (!data || data.success === false || !Array.isArray(data.groups)) throw new WazFail(`quox wazuh triage: ${ep.method} ${ep.path} returned an error body: ${(data && (data.message || data.error)) || 'no groups array'}`);
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      const groups = data.groups;
+      head('triage', `${plural(groups.length, 'rule group')}, ${plural(data.total_alerts ?? 0, 'alert')} (level ${data.min_level}+, last ${data.window})`, groups.some((g) => g.level >= 12) ? 'warn' : 'ok');
+      if (!groups.length) { console.log('No alert groups in this window.'); return; }
+      // WAZ P7: CONTEXT per group (MAINT / KUMA-DOWN / DEPLOYED across its hosts; SRC? when a source could not answer).
+      const withCtx = groups.some((g) => g.context);
+      const rows = [['LVL', 'COUNT', 'RULE', 'MITRE', 'AGENTS', 'LAST SEEN', ...(withCtx ? ['CONTEXT'] : []), 'DESCRIPTION']];
+      for (const g of groups) {
+        rows.push([g.level ?? '-', g.count, g.rule_id, ((g.mitre && g.mitre.ids) || []).join(',') || '-',
+          (g.agents || []).slice(0, 3).map((a) => `${a.name}(${a.count})`).join(', ') || '-', agoText(g.last_seen), ...(withCtx ? [contextFlags(g.context)] : []), g.description || '-']);
+      }
+      console.log(pad(rows).join('\n'));
+    })), 'quox wazuh triage --since 24h --level 10');
+
+  // ---- coverage ----
+  example(wazuh.command('coverage').description('Which fleet hosts Wazuh does not cover: missing agents, disconnected agents, no vulnerability inventory')
+    .action(guard(async () => {
+      auth.requireAuth();
+      const { ep, data } = await getRoute('coverage', 'mon.wazuh.coverage');
+      if (!data || data.success === false || !data.summary) throw new WazFail(`quox wazuh coverage: ${ep.method} ${ep.path} returned an error body: ${(data && (data.message || data.error)) || 'no summary'}`);
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      const s = data.summary;
+      const n = (v, label) => (v === null || v === undefined ? `${label} unknown` : `${v} ${label}`);
+      const degraded = Boolean(data.fleet_error || data.vuln_error);
+      head('coverage', s.covered === null || s.covered === undefined ? 'fleet unknown' : `${s.covered} of ${s.fleet_hosts} covered`,
+        degraded || s.missing_agent > 0 || s.disconnected > 0 ? 'warn' : 'ok');
+      console.log([n(s.fleet_hosts, 'fleet hosts'), `${s.wazuh_agents} Wazuh agents`, n(s.covered, 'covered'), n(s.missing_agent, 'missing agent'), `${s.disconnected} disconnected`, n(s.no_vuln_inventory, 'without vulnerability inventory')].join(', '));
+      if (data.fleet_error) console.error(`Fleet list could not be read (${data.fleet_error}); fleet-side numbers are unknown, not zero.`);
+      if (data.vuln_error) console.error(`Vulnerability inventory could not be read (${data.vuln_error}); that section is unknown, not empty.`);
+      const section = (title, list, cols, row) => {
+        if (!Array.isArray(list) || !list.length) return;
+        console.log(`\n${title} (${list.length})`);
+        console.log(pad([cols, ...list.map(row)]).join('\n'));
+      };
+      section('Fleet hosts with no Wazuh agent', data.missing_agent, ['HOST', 'IP'], (h) => [h.host || '-', h.ip || '-']);
+      section('Disconnected Wazuh agents', data.disconnected, ['ID', 'NAME', 'LAST SEEN'], (a) => [a.id, a.name, a.last_seen ? agoText(a.last_seen) : 'never']);
+      section('Agents with no vulnerability inventory', data.no_vuln_inventory, ['ID', 'NAME'], (a) => [a.id, a.name]);
+      section('Wazuh agents unknown to fleet', data.unknown_to_fleet, ['ID', 'NAME', 'IP'], (a) => [a.id, a.name, a.ip || '-']);
+    })), 'quox wazuh coverage');
+
+  // ---- vulns ----
+  example(wazuh.command('vulns').description('Vulnerabilities on monitored hosts, highest score first')
+    .option('--severity <s>', 'Critical|High|Medium|Low')
+    .option('--agent <id|name>', 'only this agent')
+    .option('--limit <n>', 'max rows (default 50, capped at 1000; with --priority default 20, capped at 200)')
+    .option('--priority', 'rank by real exploit risk: CISA KEV, then EPSS, then CVSS, then hosts affected')
+    .option('--kev-only', 'with --priority: only CVEs in the CISA KEV catalogue')
+    .action(guard(async (options) => {
+      auth.requireAuth();
+      if (options.limit && !/^\d+$/.test(String(options.limit))) throw new WazFail(`quox wazuh vulns: --limit needs a whole number, got "${options.limit}"`);
+      if (options.kevOnly && !options.priority) throw new WazFail('quox wazuh vulns: --kev-only needs --priority');
+      if (options.priority) {
+        if (options.severity) throw new WazFail('quox wazuh vulns: --severity does not combine with --priority (the rank already weighs severity)');
+        const pq = {};
+        if (options.limit) pq.limit = String(options.limit);
+        if (options.kevOnly) pq.kev_only = 'true';
+        if (options.agent) { if (/^\d+$/.test(String(options.agent))) pq.agent_id = String(options.agent).padStart(3, '0'); else pq.agent_name = options.agent; }
+        const { ep, data } = await getRoute('vulns', 'mon.wazuh.vulnerabilities.priority', pq);
+        if (!data || data.success === false || !Array.isArray(data.items) || !data.summary) throw new WazFail(`quox wazuh vulns: ${ep.method} ${ep.path} returned an error body: ${(data && (data.message || data.error)) || 'no items array'}`);
+        if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+        const sm = data.summary;
+        const degraded = (sm.kev_status && sm.kev_status !== 'ok') || (sm.epss_status && sm.epss_status !== 'ok');
+        head('vulns', `${plural(sm.cves, 'CVE')}, ${sm.in_kev} in CISA KEV, ${sm.epss_over_0_1} with EPSS over 0.1`, sm.in_kev > 0 || degraded ? 'warn' : 'ok');
+        if (sm.kev_status && sm.kev_status !== 'ok') console.error(`⚠ CISA KEV ${sm.kev_status}; KEV membership is unknown, not "none".`);
+        if (sm.epss_status && sm.epss_status !== 'ok') console.error(`⚠ EPSS ${sm.epss_status}; exploit probability is unknown, ranked without it.`);
+        const cv = data.coverage || {};
+        if (cv.truncated) console.error(`⚠ ranked ${cv.cves_ranked} of ${cv.cves_total ?? 'more'} CVEs: the top by CVSS${cv.kev_sweep === 'ok' ? ' plus every CVE in CISA KEV' : `; the CISA KEV sweep is ${cv.kev_sweep}, so a KEV CVE outside the top may be missing`}. Narrow with --agent.`);
+        if (!data.items.length) { console.log(options.kevOnly ? 'No CVEs in CISA KEV.' : 'No vulnerabilities.'); return; }
+        const prows = [['RANK', 'CVE', 'SEV', 'CVSS', 'EPSS', 'KEV', 'HOSTS', 'PACKAGE']];
+        data.items.forEach((it, i) => prows.push([i + 1, it.cve, it.severity || '-', it.cvss ?? '-',
+          typeof it.epss === 'number' ? `${(it.epss * 100).toFixed(1)}%` : '-',
+          it.kev ? (it.kev.knownRansomwareCampaignUse ? 'yes (ransomware)' : 'yes') : 'no',
+          it.agents_affected, (it.packages || []).slice(0, 2).join(', ') || '-']));
+        console.log(pad(prows).join('\n'));
+        return;
+      }
+      const query = {};
+      if (options.limit) query.limit = String(options.limit);
+      if (options.severity) query.severity = options.severity;
+      if (options.agent) { if (/^\d+$/.test(String(options.agent))) query.agent_id = String(options.agent).padStart(3, '0'); else query.agent_name = options.agent; }
+      const { ep, data } = await getRoute('vulns', 'mon.wazuh.vulnerabilities.list', query);
+      if (!data || data.success === false || !Array.isArray(data.data)) throw new WazFail(`quox wazuh vulns: ${ep.method} ${ep.path} returned an error body: ${(data && (data.message || data.error)) || 'no vulnerabilities array'}`);
+      const list = data.data;
+      if (jsonOut()) { console.log(JSON.stringify({ vulnerabilities: list, total: data.total ?? list.length }, null, 2)); return; }
+      const bySev = {};
+      for (const v of list) { const s = (v.vulnerability && v.vulnerability.severity) || 'Unknown'; bySev[s] = (bySev[s] || 0) + 1; }
+      const sevText = ['Critical', 'High', 'Medium', 'Low', 'Unknown'].filter((s) => bySev[s]).map((s) => `${bySev[s]} ${s}`).join(' · ');
+      head('vulns', `${list.length === 0 ? 'none' : sevText}${(data.total ?? 0) > list.length ? ` (showing ${list.length} of ${data.total})` : ''}`, bySev.Critical ? 'warn' : 'ok');
+      if (!list.length) { console.log('No vulnerabilities.'); return; }
+      const rows = [['SEVERITY', 'SCORE', 'CVE', 'AGENT', 'PACKAGE']];
+      for (const v of list) rows.push([(v.vulnerability && v.vulnerability.severity) || '-', (v.vulnerability && v.vulnerability.score && v.vulnerability.score.base) ?? '-', (v.vulnerability && v.vulnerability.id) || '-', (v.agent && v.agent.name) || '-', v.package ? `${v.package.name || ''} ${v.package.version || ''}`.trim() : '-']);
+      console.log(pad(rows).join('\n'));
+    })), 'quox wazuh vulns --priority --kev-only');
+
+  // ---- fim / sca / rootcheck ----
+  /** The agent ids a per-agent read covers: --agent, else every active agent (capped). */
+  async function targetAgents(verb, agentOpt) {
+    if (agentOpt) {
+      if (/^\d+$/.test(String(agentOpt))) return { ids: [String(agentOpt).padStart(3, '0')], note: '' };
+      const a = await allAgents(verb);
+      const hit = a.items.find((x) => String(x.name).toLowerCase() === String(agentOpt).toLowerCase());
+      if (!hit) throw new WazFail(`quox wazuh ${verb}: no agent "${agentOpt}". List them: quox wazuh agents`);
+      return { ids: [hit.id], note: '' };
+    }
+    const a = await allAgents(verb);
+    const active = a.items.filter((x) => x.status === 'active');
+    const ids = active.slice(0, PROXY_AGENT_CAP).map((x) => x.id);
+    return { ids, names: new Map(a.items.map((x) => [x.id, x.name])), note: active.length > ids.length ? ` (first ${ids.length} of ${active.length} active agents; use --agent for the rest)` : '' };
+  }
+
+  // ---- governed tool path: fim/sca/rootcheck reads (read tools, no approval) and every write ----
+  async function callTool(verb, tool, input) {
+    const ep = resolveEndpoint('v1.tools.execute');
+    let data;
+    try {
+      data = await client.post(ep.path, { service: ep.service, body: { tool_name: tool, input, org_id: resolveOrgId(auth, program) } });
+    } catch (err) {
+      // The policy layer answers a held write with HTTP 403 + {pending:true, approvalId}: the approval is filed.
+      data = pendingBodyOfError(err);
+      if (!data) {
+        const f = failFrom(verb, ep.method, ep.path, err, ` (${tool})`);
+        const status = err && (err.status ?? err.statusCode);
+        if (status === 404 || /unknown tool|not found/i.test((err && err.message) || '')) f.message += `\n  The ${tool} tool is not available on this collector yet.`;
+        throw f;
+      }
+    }
+    return { data, pendingId: execResultPending(data) };
+  }
+  const resultOf = (data) => (data && data.result && typeof data.result === 'object' ? data.result : data) || {};
+  function failIfToolFailed(verb, tool, data) {
+    const r = resultOf(data);
+    if (execResultFailed(data) || !data || data.error || r.error) {
+      const code = (typeof r.error === 'string' && r.error) || (data && typeof data.error === 'string' && data.error) || '';
+      const hint = HINTS[code];
+      throw new WazFail(`quox wazuh ${verb}: ${tool} failed: ${r.message || (data && data.message) || code || 'tool reported failure'}${hint ? `\n  ${hint}` : ''}`);
+    }
+    return r;
+  }
+  const listOf = (r, keys) => { for (const k of keys) if (Array.isArray(r[k])) return r[k]; return null; };
+  /** The agent a read was auto-delegated to (the gateway's single-holder hop answers in prose), else null. */
+  const delegatedTo = (data) => {
+    const hop = (data && data.auto_delegated) || resultOf(data).auto_delegated;
+    return hop && typeof hop === 'object' ? String(hop.to || 'another agent') : null;
+  };
+
+  const BATCH_AGENTS = 50;
+
+  /**
+   * quox#1503: the per-agent reads go over GET /api/v1/wazuh/read/:tool, the same tool body with no auto-delegation hop
+   * (through tools/execute a profile whose hat lacks the tool was delegated to argus: prose or a 30 s timeout).
+   * A 404 is an older collector without the route, so it falls back to the governed tools path.
+   */
+  async function readTool(verb, tool, input) {
+    const ep = resolveEndpoint('mon.wazuh.read', { tool });
+    const query = {};
+    for (const [k, v] of Object.entries(input)) if (v != null) query[k] = Array.isArray(v) ? v.join(',') : String(v);
+    let data;
+    try {
+      data = await client.get(ep.path, { service: ep.service, query });
+    } catch (err) {
+      if ((err && (err.status ?? err.statusCode)) === 404) return callTool(verb, tool, input);
+      throw failFrom(verb, ep.method, ep.path, err);
+    }
+    return { data };
+  }
+
+  /** Run a per-agent read tool for --agent, or for every active agent (capped). Rows are tagged with the agent. */
+  async function perAgentTool(verb, tool, options, extra, keys) {
+    const t = await targetAgents(verb, options.agent);
+    const all = [];
+    let total = 0;
+    const take = (id, r) => {
+      const list = listOf(r, keys);
+      const hop = !list && delegatedTo(r);
+      if (hop) throw new WazFail(`quox wazuh ${verb}: ${tool} is not in this profile's hat, so it was auto-delegated to agent ${hop}, which answered in prose instead of returning data. Ask ${hop} in chat, or use a profile whose hat holds ${tool}`);
+      if (!list) throw new WazFail(`quox wazuh ${verb}: ${tool} returned an unexpected body (expected ${keys.join(' or ')}); use --json to see it`);
+      total += Number.isFinite(Number(r.total)) ? Number(r.total) : list.length;
+      for (const f of list) all.push({ agent: (t.names && t.names.get(id)) || id, agent_id: id, ...f });
+    };
+    if (t.ids.length <= 1) {
+      for (const id of t.ids) {
+        const { data } = await readTool(verb, tool, { agent_id: id, ...extra });
+        take(id, failIfToolFailed(verb, tool, data));
+      }
+      return { all, t, total };
+    }
+    // Several agents: ONE tool call per chunk of 50 (agent_ids), not one per agent (the tool-call limiter is 60/min).
+    for (let i = 0; i < t.ids.length; i += BATCH_AGENTS) {
+      const chunk = t.ids.slice(i, i + BATCH_AGENTS);
+      const { data } = await readTool(verb, tool, { agent_ids: chunk, ...extra });
+      const r = failIfToolFailed(verb, tool, data);
+      if (!Array.isArray(r.per_agent) && delegatedTo(r)) take(chunk[0], r);
+      if (!Array.isArray(r.per_agent)) throw new WazFail(`quox wazuh ${verb}: ${tool} returned an unexpected body (expected per_agent); use --json to see it`);
+      const byId = new Map(r.per_agent.map((row) => [String(row.agent_id), row]));
+      for (const id of chunk) {
+        const row = byId.get(id);
+        if (!row) throw new WazFail(`quox wazuh ${verb}: ${tool} returned no row for agent ${(t.names && t.names.get(id)) || id} (${id})`);
+        if (execResultFailed(row) || row.error || row.success === false) {
+          const code = typeof row.error === 'string' ? row.error : '';
+          throw new WazFail(`quox wazuh ${verb}: ${tool} failed for agent ${(t.names && t.names.get(id)) || id} (${id}): ${row.message || code || 'tool reported failure'}${HINTS[code] ? `\n  ${HINTS[code]}` : ''}`);
+        }
+        take(id, row);
+      }
+    }
+    return { all, t, total };
+  }
+
+  example(wazuh.command('fim').description('File integrity (syscheck): recently changed files (reads the wazuh_fim tool)')
+    .option('--agent <id|name>', 'one agent (default: every active agent)')
+    .option('--file <path>', 'only this file path')
+    .option('--search <text>', 'text to search for')
+    .option('--limit <n>', 'files per agent (default 20)')
+    .action(guard(async (options) => {
+      auth.requireAuth();
+      if (options.limit && !/^\d+$/.test(String(options.limit))) throw new WazFail(`quox wazuh fim: --limit needs a whole number, got "${options.limit}"`);
+      const extra = { limit: Number(options.limit) || 20 };
+      if (options.file) extra.file = options.file;
+      if (options.search) extra.search = options.search;
+      const { all, t, total } = await perAgentTool('fim', 'wazuh_fim', options, extra, ['events', 'files', 'items', 'affected_items']);
+      if (jsonOut()) { console.log(JSON.stringify({ files: all, total, agents: t.ids }, null, 2)); return; }
+      head('fim', `${all.length < total ? `showing ${all.length} of ${total}` : plural(all.length, 'file')} across ${plural(t.ids.length, 'agent')}${t.note}`);
+      if (!all.length) { console.log('No syscheck entries.'); return; }
+      const rows = [['WHEN', 'UTC', 'AGENT', 'TYPE', 'SIZE', 'OWNER', 'PERM', 'FILE']];
+      for (const f of all) {
+        const when = f.date || f.mtime;
+        const owner = f.uname || f.gname ? `${f.uname || '-'}:${f.gname || '-'}` : '-';
+        rows.push([agoText(when), utcText(when), f.agent, f.type || '-', f.size ?? '-', owner, f.perm || '-', f.file || '-']);
+      }
+      console.log(pad(rows).join('\n'));
+      if (all.length < total) console.log(`Showing ${all.length} of ${total}; raise --limit to see more.`);
+    })), 'quox wazuh fim --agent 001');
+
+  example(wazuh.command('sca').description('Security configuration assessment: policies with pass/fail; --policy lists its failed checks (reads the wazuh_sca tool)')
+    .option('--agent <id|name>', 'one agent (default: every active agent)')
+    .option('--policy <id>', "one policy's failed checks")
+    .option('--limit <n>', 'max rows per agent')
+    .action(guard(async (options) => {
+      auth.requireAuth();
+      if (options.policy && !options.agent) throw new WazFail('quox wazuh sca: --policy needs --agent (failed checks are per agent)');
+      if (options.limit && !/^\d+$/.test(String(options.limit))) throw new WazFail(`quox wazuh sca: --limit needs a whole number, got "${options.limit}"`);
+      const extra = {};
+      if (options.policy) extra.policy_id = options.policy;
+      if (options.limit) extra.limit = Number(options.limit);
+      const keys = options.policy ? ['checks', 'failed_checks', 'items', 'affected_items'] : ['policies', 'items', 'affected_items'];
+      const { all, t } = await perAgentTool('sca', 'wazuh_sca', options, extra, keys);
+      if (jsonOut()) { console.log(JSON.stringify(options.policy ? { checks: all, agents: t.ids } : { policies: all, agents: t.ids }, null, 2)); return; }
+      if (options.policy) {
+        head(`sca ${options.policy}`, plural(all.length, 'failed check'), all.length ? 'warn' : 'ok');
+        if (!all.length) { console.log('No failed checks.'); return; }
+        const rows = [['ID', 'RESULT', 'TITLE']];
+        for (const c of all) rows.push([c.id ?? '-', c.result || 'failed', c.title || c.description || '-']);
+        console.log(pad(rows).join('\n'));
+        return;
+      }
+      head('sca', `${plural(all.length, 'policy', 'policies')} across ${plural(t.ids.length, 'agent')}${t.note}`);
+      if (!all.length) { console.log('No SCA policies scanned.'); return; }
+      const rows = [['AGENT', 'POLICY', 'PASS', 'FAIL', 'N/A', 'SCORE', 'SCANNED']];
+      for (const p of all) rows.push([p.agent, p.name || p.policy_id || '-', p.pass ?? '-', p.fail ?? '-', p.invalid ?? '-', p.score === undefined ? '-' : `${p.score}%`, agoText(p.end_scan)]);
+      console.log(pad(rows).join('\n'));
+    })), 'quox wazuh sca --agent 001 --policy cis_ubuntu22');
+
+  example(wazuh.command('rootcheck').description('Rootcheck findings (reads the wazuh_rootcheck tool)')
+    .option('--agent <id|name>', 'one agent (default: every active agent)')
+    .option('--limit <n>', 'max findings per agent')
+    .action(guard(async (options) => {
+      auth.requireAuth();
+      if (options.limit && !/^\d+$/.test(String(options.limit))) throw new WazFail(`quox wazuh rootcheck: --limit needs a whole number, got "${options.limit}"`);
+      const extra = options.limit ? { limit: Number(options.limit) } : {};
+      const { all, t, total } = await perAgentTool('rootcheck', 'wazuh_rootcheck', options, extra, ['items', 'findings', 'affected_items', 'results']);
+      if (jsonOut()) { console.log(JSON.stringify({ findings: all, total, agents: t.ids }, null, 2)); return; }
+      head('rootcheck', `${plural(all.length, 'finding')}${total > all.length ? ` shown of ${total}` : ''}${t.note}`, all.length ? 'warn' : 'ok');
+      if (!all.length) { console.log('No rootcheck findings.'); return; }
+      const rows = [['WHEN', 'AGENT', 'STATUS', 'FINDING']];
+      for (const f of all) rows.push([agoText(f.date_last || f.date_first), f.agent, f.status || '-', f.log || f.description || '-']);
+      console.log(pad(rows).join('\n'));
+    })), 'quox wazuh rootcheck --agent 001');
+
+  example(wazuh.command('deploy-history').description('Wazuh agent deploy results')
+    .option('--mode <mode>', 'latest|all', 'latest')
+    .option('--limit <n>', 'max rows (mode=all)', '200')
+    .action(guard(async (options) => {
+      auth.requireAuth();
+      const { ep, data } = await getRoute('deploy-history', 'mon.wazuh.deploy-history.list', { mode: options.mode, limit: options.limit });
+      if (!data || data.success === false || !Array.isArray(data.deploys)) throw new WazFail(`quox wazuh deploy-history: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'no deploys array'}`);
+      if (jsonOut()) { console.log(JSON.stringify({ deploys: data.deploys }, null, 2)); return; }
+      const bad = data.deploys.filter((d) => !d.success).length;
+      head('deploy-history', `${plural(data.deploys.length, 'deploy')}${bad ? ` · ${bad} failed` : ''}`, bad ? 'warn' : 'ok');
+      if (!data.deploys.length) { console.log('No deploys recorded.'); return; }
+      const rows = [['HOST', 'IP', 'RESULT', 'WHEN']];
+      for (const d of data.deploys) rows.push([d.hostname || '-', d.ip || d.hostIp || '-', d.success ? 'ok' : (d.message ? `failed: ${String(d.message).slice(0, 40)}` : 'failed'), agoText(d.deployed_at || d.deployedAt)]);
+      console.log(pad(rows).join('\n'));
+    })), 'quox wazuh deploy-history');
+
+  // ---- writes: always the governed tool path; a person approves; the approval id is printed ----
+  async function writeTool(verb, tool, input, okText) {
+    auth.requireAuth();
+    const { data, pendingId } = await callTool(verb, tool, input);
+    if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); if (!pendingId && execResultFailed(data)) process.exitCode = 1; return; }
+    if (pendingId) { head(verb, 'awaiting approval', 'busy'); console.log(`◐ awaiting approval ${pendingId}: a person approves it in the inbox; check with quox approvals result ${pendingId}`); return; }
+    failIfToolFailed(verb, tool, data);
+    head(verb, okText, 'ok');
+  }
+
+  /** One governed wazuh_deploy_agent call for one host (hostname and host_ip are both required by the tool). */
+  const deployOne = (host, ip, options) => {
+    if (!ip) throw new WazFail(`quox wazuh deploy: ${host} needs an address (--ip <ip>, or name=ip for deploy-bulk); the tool requires hostname and host_ip`);
+    const input = { hostname: host, host_ip: ip };
+    if (options.sshUser) input.ssh_user = options.sshUser;
+    if (options.sshPort) input.ssh_port = Number(options.sshPort);
+    return writeTool(`deploy ${host}`, 'wazuh_deploy_agent', input, `deployed to ${host}`);
+  };
+  // WAZ-10: `quox mon wazuh` keeps its legacy write verbs, mapped onto these same governed helpers (no second path).
+  const governed = { guard, writeTool, deployOne, WazFail };
+  if (!writes) return governed;
+
+  example(wazuh.command('deploy').description('Install the Wazuh agent on a host (held for human approval)')
+    .argument('<host>', 'hostname')
+    .requiredOption('--ip <ip>', 'host address')
+    .option('--ssh-user <user>', 'SSH user')
+    .option('--ssh-port <n>', 'SSH port')
+    .action(guard(async (host, options) => { await deployOne(host, options.ip, options); })), 'quox wazuh deploy web09 --ip 192.0.2.9');
+
+  example(wazuh.command('deploy-bulk').description('Install the Wazuh agent on several hosts: one governed call and one approval per host')
+    .argument('<hosts...>', 'name=ip pairs')
+    .option('--ssh-user <user>', 'SSH user')
+    .option('--ssh-port <n>', 'SSH port')
+    .action(guard(async (hosts, options) => {
+      const pairs = hosts.map((h) => String(h).split('='));
+      const missing = pairs.filter(([, ip]) => !ip).map(([h]) => h);
+      if (missing.length) throw new WazFail(`quox wazuh deploy-bulk: every host needs an address as name=ip; missing for ${missing.join(', ')}`);
+      let failed = 0;
+      for (const [hostname, ip] of pairs) {
+        try { await deployOne(hostname, ip, options); } catch (err) {
+          if (!(err instanceof WazFail)) throw err;
+          console.error(err.message); failed++;
+        }
+      }
+      if (failed) process.exitCode = 1;
+    })), 'quox wazuh deploy-bulk web01=192.0.2.1 web02=192.0.2.2');
+
+  example(wazuh.command('remove').description('Remove an agent from the Wazuh manager (held for human approval)')
+    .argument('<agentId>', 'agent id, e.g. 007')
+    .action(guard(async (id) => {
+      await writeTool(`remove ${id}`, 'wazuh_agent_remove', { agent_id: /^\d+$/.test(id) ? id.padStart(3, '0') : id }, `removed agent ${id}`);
+    })), 'quox wazuh remove 007');
+
+  example(wazuh.command('active-response').description('Run an active response on one or more agents (held for human approval)')
+    .argument('<agentId...>', 'agent id(s), e.g. 001')
+    .requiredOption('--command <cmd>', 'firewall-block|host-isolate|restart-wazuh-agent')
+    .option('--reason <text>', 'why, at least 10 characters (shown to the approver)')
+    .option('--args <list>', 'comma-separated command arguments')
+    .action(guard(async (ids, options) => {
+      if (!options.reason || options.reason.trim().length < 10) throw new WazFail('quox wazuh active-response: --reason "<why>" is required, at least 10 characters (the approver sees it)');
+      const args = options.args ? String(options.args).split(',').map((s) => s.trim()).filter(Boolean) : [];
+      const input = { command: options.command, agent_ids: ids.map((i) => (/^\d+$/.test(i) ? i.padStart(3, '0') : i)), reason: options.reason.trim() };
+      if (args.length) input.args = args;
+      await writeTool(`active-response ${ids.join(',')}`, 'wazuh_active_response', input, `${options.command} ran on ${plural(ids.length, 'agent')}`);
+    })), 'quox wazuh active-response 001 --command firewall-block --args 203.0.113.9 --reason "ssh brute force"');
+
+  const indexer = wazuh.command('indexer').description('The Wazuh indexer credential behind alerts and vulns');
+  example(indexer.command('install-credential').description('Place the indexer read credential on the Wazuh host (held for human approval)')
+    .action(guard(async () => {
+      await writeTool('indexer install-credential', 'wazuh_indexer_credential_install', {}, 'indexer credential installed');
+    })), 'quox wazuh indexer install-credential');
+
+  // ---- report (WAZ P5): signed, offline-verifiable posture report. `quox wazuh` only, not the mon read set. ----
+  registerWazuhReport(wazuh, { client, auth, jsonOut, guard, WazFail, pad, head, failFrom, example });
+
+  // ---- alert intake (WAZ P6): integratord hook + the incidents it opens. `quox wazuh` only, like report. ----
+  registerWazuhIntake(wazuh, { client, auth, jsonOut, guard, WazFail, pad, head, failFrom, example, callTool, failIfToolFailed });
+  return governed;
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// `quox wazuh connect` (WAZ-2): separate block, no shared state with the read verbs above.
+// Creates/updates THIS org's `wazuh` vault credential. Passwords are hidden prompts only, never flags or argv.
+// ---------------------------------------------------------------------------------------------------------------
+
+async function hiddenPrompt(message) {
+  if (!process.stdin.isTTY) throw new WazFail(`quox wazuh connect: ${message} needs a terminal (the password is typed hidden, never passed as a flag or piped)`);
+  const { default: inquirer } = await import('inquirer');
+  const ans = await inquirer.prompt([{ type: 'password', name: 'v', message, mask: '*', validate: (v) => (v && v.length > 0) || 'required' }]);
+  return ans.v;
+}
+
+export function attachWazuhConnect(wazuh, program, ctx) {
+  const { client, auth } = ctx;
+  const promptSecret = ctx.promptSecret || hiddenPrompt;
+  async function importInstanceEnv() {
+    const ep = resolveEndpoint('mon.wazuh.credential.import-instance-env');
+    let res;
+    try { res = await client.post(ep.path, { service: ep.service, body: {} }); } catch (err) {
+      const f = failFrom('connect', ep.method, ep.path, err);
+      const code = err && err.body && typeof err.body === 'object' ? err.body.reason : null;
+      const NEXT = {
+        not_instance_superadmin: 'Only an instance superadmin can import the instance Wazuh environment. Ask one, or connect with your own details: quox wazuh connect --url <url> --user <user>.',
+        not_org_admin: 'You must be an owner or admin of the org you are logged into. Switch org (quox org switch) or ask an org admin.',
+        instance_env_empty: 'This collector has no WAZUH_* environment to import. Connect with your own details: quox wazuh connect --url <url> --user <user>.',
+        auth_unavailable: 'The auth service did not answer. Retry in a minute.',
+      };
+      throw new WazFail(`${f.message}${code ? `\n  reason: ${code}` : ''}${NEXT[code] ? `\n  ${NEXT[code]}` : ''}`);
+    }
+    if (!res || typeof res !== 'object') throw new WazFail(`quox wazuh connect: ${ep.method} ${ep.path} returned no body`);
+    if (res.imported) {
+      console.log(glyphLine('quox', 'wazuh connect', { result: `credential imported into org ${res.org_id}`, status: 'ok' }));
+      await wazuh.parseAsync(['status'], { from: 'user' });
+      return;
+    }
+    if (res.reason === 'already_present') {
+      console.log(glyphLine('quox', 'wazuh connect', { result: `already present in org ${res.org_id}; nothing imported (change it with quox wazuh connect --url <url> --user <user>)`, status: 'ok' }));
+      return;
+    }
+    throw new WazFail(`quox wazuh connect: instance env import did not happen: ${res.reason || 'no reason given'}`);
+  }
+
+  wazuh.command('connect')
+    .description('Connect this organisation to its Wazuh: stores the API (and optional indexer) credential in the vault, then runs status. Admin only. Passwords are prompted, never flags.')
+    .option('--from-instance-env', 'import the collector\'s own WAZUH_* environment into this org\'s vault (instance superadmin who is also an org admin; no prompts, no other flags)')
+    .option('--url <url>', 'Wazuh manager API URL, e.g. https://wazuh-host:55000')
+    .option('--user <user>', 'Wazuh API username, e.g. wazuh-wui')
+    .option('--indexer-url <url>', 'Wazuh indexer URL, e.g. https://wazuh-host:9200')
+    .option('--indexer-user <user>', 'Wazuh indexer username (a password is then prompted)')
+    .option('--transport <mode>', 'indexer transport: auto|direct|host', 'auto')
+    .addHelpText('after', '\nExample:  quox wazuh connect --url https://wazuh.example:55000 --user wazuh-wui --indexer-user admin --transport host')
+    .action(async (options) => {
+      try {
+        auth.requireAuth();
+        if (options.fromInstanceEnv) {
+          if (options.url || options.user || options.indexerUrl || options.indexerUser) throw new WazFail('quox wazuh connect: --from-instance-env cannot be combined with --url, --user, --indexer-url or --indexer-user');
+          await importInstanceEnv();
+          return;
+        }
+        if (!options.url) throw new WazFail('quox wazuh connect: --url <url> and --user <user> are required (or use --from-instance-env to import the collector\'s own Wazuh environment)');
+        if (!options.user) throw new WazFail('quox wazuh connect: --user <user> is required with --url');
+        if (!/^https:\/\/[^\s/]+/.test(options.url)) throw new WazFail('quox wazuh connect: --url must be an https:// URL (the credential is sent to it)');
+        if (options.indexerUrl && !/^https:\/\/[^\s/]+/.test(options.indexerUrl)) throw new WazFail('quox wazuh connect: --indexer-url must be an https:// URL');
+        if (!['auto', 'direct', 'host'].includes(options.transport)) throw new WazFail('quox wazuh connect: --transport must be auto, direct or host');
+        const orgId = resolveOrgId(auth, program);
+        const listEp = resolveEndpoint('vault.list', { orgId });
+        let existing;
+        try {
+          const data = await client.get(listEp.path, { service: listEp.service, query: { type: 'wazuh' } });
+          existing = (data.credentials || data || []).find((c) => c && c.integration_type === 'wazuh');
+        } catch (err) { throw failFrom('connect', listEp.method, listEp.path, err); }
+
+        const credentials = { base_url: options.url, username: options.user };
+        credentials.password = await promptSecret(`Wazuh API password for ${options.user}`);
+        if (options.indexerUser) {
+          credentials.indexer_username = options.indexerUser;
+          credentials.indexer_password = await promptSecret(`Wazuh indexer password for ${options.indexerUser}`);
+        }
+        if (options.indexerUrl) credentials.indexer_url = options.indexerUrl;
+        credentials.indexer_transport = options.transport;
+
+        const verb = existing ? 'update' : 'create';
+        const ep = resolveEndpoint(existing ? 'vault.update' : 'vault.create', { orgId, ...(existing ? { id: existing.id } : {}) });
+        try {
+          if (existing) await client.put(ep.path, { service: ep.service, body: { credentials } });
+          else await client.post(ep.path, { service: ep.service, body: { integration_type: 'wazuh', label: 'Wazuh', credentials, is_default: true } });
+        } catch (err) {
+          const f = failFrom('connect', ep.method, ep.path, err);
+          const st = err && (err.status ?? err.statusCode);
+          throw new WazFail(st === 403 ? `${f.message}\n  Saving a vault credential needs an org admin.` : f.message);
+        }
+        console.log(glyphLine('quox', 'wazuh connect', { result: `credential ${verb === 'update' ? 'updated' : 'saved'} for ${options.url}`, status: 'ok' }));
+        await wazuh.parseAsync(['status'], { from: 'user' });
+      } catch (err) {
+        if (!(err instanceof WazFail)) throw err;
+        console.error(err.message);
+        process.exitCode = err.exitCode || 1;
+      }
+    });
+}