quoxcli 0.4.0 → 0.6.0

package/lib/commands/wazuhIntake.js

@@ -0,0 +1,358 @@
+/**
+ * quox wazuh hooks ... / quox wazuh incidents ... : Wazuh alerts become witnessed Quox incidents (WAZ P6).
+ * The sibling of `quox kuma hooks` / `quox kuma incidents` (kuma.js).
+ *
+ * quox wazuh hooks list                          this org's alert hooks (never shows a secret)
+ * quox wazuh hooks create [--label <text>]       new hook; prints the URL path, the secret ONCE and the ossec.conf block
+ * quox wazuh hooks rotate <hookId>               new secret for a hook, shown ONCE; the old one stops working
+ * quox wazuh hooks delete <hookId>               Wazuh posts to it are refused from then on
+ * quox wazuh hooks install --collector-url <url> [--level 7] [--label <l>]
+ *                                                one governed step (held for approval): hook + custom-quox + ossec.conf + restart;
+ *                                                the secret goes to the manager on Bastion stdin and is never shown
+ * quox wazuh incidents [--open] [--since <24h|ISO>] [--limit <n>]
+ * quox wazuh incidents show <id>                context (Kuma maintenance, open Kuma incidents, deploys), diagnosis, escalation
+ * quox wazuh incidents close <id> --reason <text>
+ * quox wazuh incidents diagnose <id>            read-only host reads; off-list reads are held for approval (WAZ P7)
+ * quox wazuh incidents escalate <id> [--engagement <id|name>]   file it as a QuoxSecurity finding (WAZ P7)
+ *
+ * Hook management needs an org admin or owner (a signed-in person). Incidents: any org member.
+ * Backend: /api/v1/wazuh/hooks, /api/v1/wazuh/incidents (services/collector/lib/wazuhAlerts.js).
+ * Install on the Wazuh manager: docs/wazuh/custom-quox-integration.md.
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+import { relDuration } from './kuma.js';
+
+const RUNBOOK = 'docs/wazuh/custom-quox-integration.md';
+
+// WAZ-11: ARGUS's routing proposal from the verdict: what it proposes and the command a person runs to accept it.
+function proposalCell(p) {
+  if (!p || typeof p !== 'object' || !p.proposed_action) return 'none';
+  return `${p.proposed_action}${p.verdict ? ` (ARGUS verdict ${p.verdict})` : ''}${p.command ? `: ${p.command}` : ''}`;
+}
+
+// WAZ P7: compact context flags. A source that could not answer shows as SRC?, never as "nothing".
+// WAZ-11: a source the org never set up (context.not_configured, e.g. no Uptime Kuma) is left out, not SRC? on every row.
+const UNKNOWN_FLAG = { maintenance: 'MAINT?', kuma: 'KUMA?', deploys: 'DEPLOY?' };
+export function contextFlags(ctx) {
+  if (!ctx || typeof ctx !== 'object') return '-';
+  const skip = new Set(Array.isArray(ctx.not_configured) ? ctx.not_configured : []);
+  const parts = [...(ctx.flags || []), ...(ctx.unavailable || []).filter((s) => !skip.has(s)).map((s) => UNKNOWN_FLAG[s] || `${String(s).toUpperCase()}?`)];
+  return parts.length ? parts.join(' ') : '-';
+}
+
+const yesNo = (v) => (v === true ? 'yes' : v === false ? 'no' : 'unknown');
+function contextRows(c) {
+  if (!c || typeof c !== 'object') return [];
+  const m = c.maintenance || {};
+  const k = c.kuma || {};
+  const d = c.deploys || {};
+  const unav = (x) => `unavailable: ${x.reason || 'no answer'}`;
+  const maint = m.status !== 'ok' ? unav(m)
+    : (m.now ? `in a Kuma maintenance window now (${(m.monitors || []).join(', ') || 'monitor'}); at the last alert: ${yesNo(m.at_last_seen)}`
+      : `not in a Kuma maintenance window now; at the last alert: ${yesNo(m.at_last_seen)}`);
+  const open = k.open || [];
+  const kuma = k.status !== 'ok' ? unav(k)
+    : (open.length ? `${open.length} open Kuma incident${open.length === 1 ? '' : 's'}: ${open.slice(0, 3).map((x) => `${x.monitor_name} (${x.id})`).join(', ')}` : 'no open Kuma incident for this host');
+  const recent = d.recent || [];
+  const dep = d.status !== 'ok' ? unav(d)
+    : (recent.length ? `${recent.length} Wazuh deploy${recent.length === 1 ? '' : 's'} to this host in the 24h before the last alert (latest ${recent[0].at}${recent[0].success === false ? ', failed' : ''})` : 'no Wazuh deploy to this host in the 24h before the last alert');
+  return [['Maintenance', maint], ['Kuma', kuma], ['Deploys', dep]];
+}
+
+function printChecks(d, pad) {
+  const rows = [['CHECK', 'STATUS', 'OK', 'DETAIL']];
+  for (const c of d.checks || []) rows.push([c.name, c.status, c.ok === true ? 'yes' : c.ok === false ? 'NO' : '-', `${c.detail || '-'}${c.approval_id ? ` (approval ${c.approval_id})` : ''}`]);
+  if (rows.length > 1) { console.log(''); console.log(pad(rows).join('\n')); }
+  for (const c of d.checks || []) for (const l of c.lines || []) console.log(`  ${c.name}: ${l}`);
+}
+
+function ossecBlock(path, secret, level = 7) {
+  return [
+    '<integration>',
+    '  <name>custom-quox</name>',
+    `  <hook_url>COLLECTOR_BASE_URL${path}</hook_url>`,
+    `  <api_key>${secret}</api_key>`,
+    `  <level>${level}</level>`,
+    '  <alert_format>json</alert_format>',
+    '</integration>',
+  ].join('\n');
+}
+
+export function registerWazuhIntake(wazuh, { client, auth, jsonOut, guard, WazFail, pad, head, failFrom, example, callTool, failIfToolFailed }) {
+  const call = async (verb, key, params, fn, id, extra = {}) => {
+    const ep = resolveEndpoint(key, params);
+    try { return { ep, data: await fn(ep) }; } catch (err) {
+      const status = err && (err.status ?? err.statusCode);
+      const code = err && err.body && err.body.error_code;
+      const base = `quox wazuh ${verb}: ${ep.method} ${ep.path} failed${status ? ` with HTTP ${status}` : ''}`;
+      if (status === 403 && (code === 'admin_required' || /admin role required/i.test((err && err.message) || ''))) throw new WazFail(`${base}: managing Wazuh alert hooks needs an org admin or owner.`);
+      if (status === 403 && code === 'human_required') throw new WazFail(`${base}: this needs a signed-in person, not a service key.`);
+      if (status === 404 && code === 'engagement_not_found') throw new WazFail(`${base}: no engagement ${extra.engagement || ''} in this org. List them with \`quox engagement list\`, or leave out --engagement to create one.`);
+      if (status === 409 && code === 'already_escalated') {
+        const e = (err.body && err.body.escalation) || {};
+        throw new WazFail(`${base}: incident${id ? ` ${id}` : ''} is already escalated${e.finding_id ? ` as finding ${e.finding_id}` : ''}${e.engagement_id ? ` in engagement ${e.engagement_id}` : ''}.`);
+      }
+      if (status === 503 && code === 'store_unavailable') throw new WazFail(`${base}: the QuoxSecurity engagement store is not available on this collector.`);
+      if (status === 404 && /^hooks/.test(verb)) throw new WazFail(`${base}: no such hook${id ? ` (${id})` : ''} in this org. List them with \`quox wazuh hooks list\`.`);
+      if (status === 404) throw new WazFail(`${base}: no such incident${id ? ` (${id})` : ''} in this org. List them with \`quox wazuh incidents\`.`);
+      if (status === 409 && code === 'already_closed') throw new WazFail(`${base}: incident${id ? ` ${id}` : ''} is already closed.`);
+      throw failFrom(verb, ep.method, ep.path, err);
+    }
+  };
+  const errBody = (verb, ep, data, what) => new WazFail(`quox wazuh ${verb}: ${ep.method} ${ep.path} returned an error body: ${(data && (data.error || data.message)) || what}`);
+  const bad = (data) => !data || data.success === false || data.error;
+
+  // ---- hooks ----
+  const hooks = wazuh.command('hooks')
+    .description('The per-org signed hook Wazuh integratord posts alerts to (list, create, rotate, delete; org admin)');
+
+  example(hooks.command('list')
+    .description('This org\'s Wazuh alert hooks (never shows secrets)')
+    .action(guard(async () => {
+      auth.requireAuth();
+      const { ep, data } = await call('hooks list', 'mon.wazuh.hooks.list', {}, (e) => client.get(e.path, { service: e.service }));
+      if (bad(data) || !Array.isArray(data.hooks)) throw errBody('hooks list', ep, data, 'response had no hooks array');
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      head('hooks list', `${data.hooks.length} ${data.hooks.length === 1 ? 'hook' : 'hooks'}`);
+      if (!data.hooks.length) { console.log('No hooks yet. Create one: quox wazuh hooks create'); return; }
+      const rows = [['HOOK', 'LABEL', 'CREATED', 'ROTATED', 'LAST USED', 'PATH']];
+      for (const h of data.hooks) rows.push([h.hookId, h.label || '-', h.created_at || '-', h.rotated_at || '-', h.last_used_at || 'never', h.path || '-']);
+      console.log(pad(rows).join('\n'));
+    })), 'quox wazuh hooks list');
+
+  const printSecret = (data, verb) => {
+    console.log([
+      `URL path : ${data.path}   (append to your Quox collector base URL)`,
+      `Secret   : ${data.secret}`,
+      '',
+      'The secret is shown ONCE and is stored only as a hash. Copy it now.',
+      '',
+      `Set it up on the Wazuh manager (full steps and the integration script: ${RUNBOOK}):`,
+      '  1. Install /var/ossec/integrations/custom-quox (root:wazuh, 750) from the runbook.',
+      '  2. Add this block inside <ossec_config> in /var/ossec/etc/ossec.conf:',
+      '',
+      ossecBlock(data.path, data.secret).split('\n').map((l) => `     ${l}`).join('\n'),
+      '',
+      '  3. Restart the manager (systemctl restart wazuh-manager). Alerts at the chosen level and above',
+      `     open incidents: quox wazuh incidents --open. Level 12+ also alert in the inbox; ${verb === 'rotate' ? 'the old secret stops working now, update <api_key>.' : 'the rest go in the daily digest.'}`,
+    ].join('\n'));
+  };
+
+  example(hooks.command('create')
+    .description('Create a Wazuh alert hook; the secret is shown ONCE (org admin)')
+    .option('--label <text>', 'a name for this hook (for example the manager name)')
+    .action(guard(async (options) => {
+      auth.requireAuth();
+      const { ep, data } = await call('hooks create', 'mon.wazuh.hooks.create', {}, (e) => client.post(e.path, { service: e.service, body: options.label ? { label: options.label } : {} }));
+      if (bad(data) || !data.hookId || !data.secret) throw errBody('hooks create', ep, data, 'response had no hook');
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      head('hooks create', data.hookId);
+      printSecret(data, 'create');
+    })), 'quox wazuh hooks create --label wz-mgr-01');
+
+  example(hooks.command('rotate')
+    .description('Issue a new secret for a hook, shown ONCE; the old secret stops working at once (org admin)')
+    .argument('<hookId>', 'hook id from `quox wazuh hooks list`')
+    .action(guard(async (hookId) => {
+      auth.requireAuth();
+      const { ep, data } = await call('hooks rotate', 'mon.wazuh.hooks.rotate', { id: hookId }, (e) => client.post(e.path, { service: e.service, body: {} }), hookId);
+      if (bad(data) || !data.secret) throw errBody('hooks rotate', ep, data, 'response had no secret');
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      head('hooks rotate', `${data.hookId || hookId} · old secret stops working now`, 'warn');
+      printSecret({ ...data, path: data.path || ep.path.replace(/\/rotate$/, '') }, 'rotate');
+    })), 'quox wazuh hooks rotate wh_0123456789abcdef');
+
+  example(hooks.command('delete')
+    .description('Delete a Wazuh alert hook; posts to it are refused from then on (org admin)')
+    .argument('<hookId>', 'hook id from `quox wazuh hooks list`')
+    .action(guard(async (hookId) => {
+      auth.requireAuth();
+      const { ep, data } = await call('hooks delete', 'mon.wazuh.hooks.delete', { id: hookId }, (e) => client.delete(e.path, { service: e.service }), hookId);
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      if (bad(data)) throw errBody('hooks delete', ep, data, 'no body');
+      head('hooks delete', `deleted ${hookId}`);
+    })), 'quox wazuh hooks delete wh_0123456789abcdef');
+
+  if (callTool) {
+    // WAZ-6: the governed one-step install. Validated here so a typo never files an approval; the collector re-validates.
+    example(hooks.command('install')
+      .description('Wire the Wazuh manager to Quox alert intake: hook, custom-quox integration, ossec.conf (backed up), restart (held for human approval; the secret is never shown)')
+      .requiredOption('--collector-url <url>', 'base URL the Wazuh manager reaches Quox on, http(s)://host[:port], no path')
+      .option('--level <n>', 'lowest Wazuh rule level sent (3-15)', '7')
+      .option('--allow-http', 'allow plain http to a private LAN IP (the hook secret then crosses the LAN unencrypted; shown on the approval card)')
+      .option('--label <label>', 'hook label; an existing hook with this label is rotated, not duplicated (default wazuh-<host>)')
+      .action(guard(async (options) => {
+        const verb = 'hooks install';
+        const raw = String(options.collectorUrl || '').trim();
+        let u = null;
+        try { u = new URL(raw); } catch { u = null; }
+        if (!u || !/^https?:$/.test(u.protocol) || u.username || u.password || raw.includes('@') || /[?#\s]/.test(raw) || (u.pathname !== '/' && u.pathname !== '')) {
+          throw new WazFail(`quox wazuh ${verb}: --collector-url must be an http(s) base URL with no credentials, path or query, for example https://quox.example:9848`);
+        }
+        const lv = String(options.level).trim();
+        if (!/^\d{1,2}$/.test(lv) || Number(lv) < 3 || Number(lv) > 15) throw new WazFail(`quox wazuh ${verb}: --level must be a whole number from 3 to 15`);
+        const input = { collector_url: raw.replace(/\/$/, ''), level: Number(lv) };
+        if (options.allowHttp) input.allow_http = true;
+        if (options.label) input.label = String(options.label);
+        auth.requireAuth();
+        const { data, pendingId } = await callTool(verb, 'wazuh_hooks_install', input);
+        if (jsonOut()) {
+          console.log(JSON.stringify(data, null, 2));
+          if (!pendingId) { try { failIfToolFailed(verb, 'wazuh_hooks_install', data); } catch { 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; }
+        const r = failIfToolFailed(verb, 'wazuh_hooks_install', data);
+        head(verb, `${r.hook_id} on ${r.host}`, 'ok');
+        console.log(pad([
+          ['Hook', `${r.hook_id}${r.rotated ? ' (rotated: new secret)' : ' (new)'}`],
+          ['Host', r.host],
+          ['Level', `${r.level} and above`],
+          ['Sends to', r.hook_url || '-'],
+          ['Backup', r.backup || '-'],
+          ['Manager', 'wazuh-manager restart requested'],
+        ]).join('\n'));
+        console.log('Check it: quox wazuh hooks list (LAST USED fills in at the first alert), quox wazuh incidents --open');
+      })), 'quox wazuh hooks install --collector-url https://quox.example:9848 --level 7 --label wz-mgr-01');
+  }
+
+  // ---- incidents ----
+  // WAZ P11: the governance incident a level >= notify-level Wazuh incident opened (shared lifecycle: status, assignee, tickets).
+  const governanceCell = (i) => (i.governance_incident_id
+    ? `${i.governance_incident_id} (${i.governance_incident && i.governance_incident.status ? i.governance_incident.status : 'status unavailable'})`
+    : '-');
+  const ago = (iso) => { const t = Date.parse(iso); return Number.isFinite(t) ? relDuration(Date.now() - t).replace(/ /g, '') : (iso || '-'); };
+
+  const incidents = example(wazuh.command('incidents')
+    .description('Wazuh alerts that became Quox incidents (one per rule and agent; repeats counted, not re-alerted)')
+    .option('--open', 'only incidents not yet closed')
+    .option('--since <when>', 'last seen since a duration (30m, 24h, 7d) or an ISO time')
+    .option('--limit <n>', 'max rows (default 50, max 200)')
+    .action(guard(async (options) => {
+      auth.requireAuth();
+      const { ep, data } = await call('incidents', 'mon.wazuh.incidents.list', { open: !!options.open, since: options.since, limit: options.limit }, (e) => client.get(e.path, { service: e.service }));
+      if (bad(data) || !Array.isArray(data.incidents)) throw errBody('incidents', ep, data, 'response had no incidents array');
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      const openN = data.incidents.filter((i) => i.open).length;
+      // WAZ-11: governance incidents still open/investigating after their Wazuh side went quiet (additive; the same
+      // section ARGUS's wazuh_incidents returns, so the CLI and chat count the same).
+      const q = data.quiet_still_open && typeof data.quiet_still_open === 'object' ? data.quiet_still_open : null;
+      const qRows = q && Array.isArray(q.incidents) ? q.incidents : [];
+      const qUnknown = !!(q && q.count === null);
+      const qN = qRows.length;
+      const qHead = qUnknown ? ' · gov-open: unknown' : (qN ? ` · ${qN} gov-open (quiet)` : '');
+      head('incidents', `${data.incidents.length} shown · ${openN} open${qHead}`, openN || qN || qUnknown ? 'warn' : 'ok');
+      const printQuiet = () => {
+        if (qUnknown) { console.log(`\nstill open in governance: unknown (${q.error || 'the collector could not read it'})`); return; }
+        if (!qN) return;
+        const qr = [['GOVERNANCE', 'STATUS', 'SEVERITY', 'ASSIGNED', 'WAZUH', 'CLOSED AS', 'CLOSED', 'AGENT', 'RULE']];
+        for (const g of qRows) {
+          qr.push([g.id, g.status, g.severity, g.assigned_to || '-', g.wazuh_incident_id || '-', g.wazuh_close_reason || '-', ago(g.wazuh_closed_at),
+            g.agent_name || g.agent_id || '-', g.rule_id || '-']);
+        }
+        console.log(`\n${q.label || 'Wazuh went quiet; still open in governance'} (${qN}):`);
+        console.log(pad(qr).join('\n'));
+        console.log('Resolve or claim: quox monitoring incidents claim <id> | quox monitoring incidents status <id> resolved --resolution "<what was done>"');
+      };
+      if (!data.incidents.length) { printQuiet(); return; }
+      // WAZ P7: CONTEXT (MAINT / KUMA-DOWN / DEPLOYED, SRC? when a source could not answer) when the collector sent it.
+      const withCtx = data.incidents.some((i) => i.context);
+      // WAZ P11: GOVERNANCE (the linked governance incident id + its status) when any incident is linked.
+      const withGov = data.incidents.some((i) => i.governance_incident_id);
+      // WAZ P11 1c: VERDICT (ARGUS's rule-based first pass: noise / fix_needed / security_event) when any incident has one.
+      const withVerdict = data.incidents.some((i) => i.triage && i.triage.verdict);
+      const rows = [['ID', 'STATE', 'LEVEL', 'AGENT', 'RULE', 'DESCRIPTION', 'COUNT', 'LAST SEEN', 'MITRE', ...(withCtx ? ['CONTEXT'] : []), ...(withGov ? ['GOVERNANCE'] : []), ...(withVerdict ? ['VERDICT'] : [])]];
+      for (const i of data.incidents) {
+        rows.push([i.id, i.open ? 'open' : `closed${i.close_reason === 'quiet' ? ' (quiet)' : ''}`, i.level, i.agent_name || i.agent_id, i.rule_id,
+          String(i.rule_description || '-').slice(0, 60), i.count ?? '-', ago(i.last_seen), (i.mitre_ids || []).join(',') || '-', ...(withCtx ? [contextFlags(i.context)] : []),
+          ...(withGov ? [governanceCell(i)] : []), ...(withVerdict ? [(i.triage && i.triage.verdict) || '-'] : [])]);
+      }
+      console.log(pad(rows).join('\n'));
+      printQuiet();
+    })), 'quox wazuh incidents --open --since 24h');
+
+  example(incidents.command('show')
+    .description('One Wazuh incident, including its stored (truncated) log line')
+    .argument('<id>', 'incident id from `quox wazuh incidents`')
+    .action(guard(async (id) => {
+      auth.requireAuth();
+      const { ep, data } = await call('incidents show', 'mon.wazuh.incidents.get', { id }, (e) => client.get(e.path, { service: e.service }), id);
+      if (bad(data) || !data.incident) throw errBody('incidents show', ep, data, 'response had no incident');
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      const i = data.incident;
+      head('incidents show', `${i.id} · ${i.open ? 'open' : 'closed'}`, i.open ? 'warn' : 'ok');
+      const rows = [
+        ['Rule', `${i.rule_id} (level ${i.level}) ${i.rule_description || ''}`],
+        ['Agent', `${i.agent_name || '-'} (agent ${i.agent_id}${i.agent_ip ? `, ${i.agent_ip}` : ''})`],
+        ['Groups', (i.rule_groups || []).join(', ') || '-'],
+        ['MITRE', [...(i.mitre_ids || []), ...(i.mitre_techniques || []), ...(i.mitre_tactics || [])].join(', ') || '-'],
+        ['Location', i.location || '-'],
+        ['Seen', `${i.count} time(s), first ${i.first_seen}, last ${i.last_seen}`],
+        ['Alerted', i.notified ? 'yes (inbox)' : (i.suppressed && i.suppressed.reason === 'maintenance'
+          ? `no: suppressed, host was in a Kuma maintenance window (${(i.suppressed.monitors || []).join(', ') || 'monitor'})`
+          : 'no (digest only)')],
+        ['Log', i.log_snippet || '-'],
+        ['Governance', governanceCell(i)],
+        ['Verdict', i.triage && i.triage.verdict ? `${i.triage.verdict} (ARGUS rule-based first pass, no model)` : 'not triaged (set when a governance incident is opened)'],
+        ...(i.triage && Array.isArray(i.triage.reasons) && i.triage.reasons.length ? [['Why', i.triage.reasons.join('; ')]] : []),
+        ['Proposal', proposalCell(i.proposal)],
+        ...contextRows(i.context),
+      ];
+      const dg = i.diagnosis;
+      rows.push(['Diagnosis', dg ? `${dg.status} (${dg.trigger || dg.mode || 'manual'}) ${dg.summary || ''}`.trim() : `not run (quox wazuh incidents diagnose ${i.id})`]);
+      const es = i.escalation;
+      rows.push(['Escalated', es && es.finding_id ? `finding ${es.finding_id} in engagement ${es.engagement_id}${es.engagement_name ? ` (${es.engagement_name})` : ''}` : `no (quox wazuh incidents escalate ${i.id})`]);
+      if (!i.open) rows.push(['Closed', `${i.closed_at}${i.closed_by ? ` by ${i.closed_by}` : ''}${i.close_reason ? `: ${i.close_reason}` : ''}`]);
+      console.log(pad(rows).join('\n'));
+      if (dg) printChecks(dg, pad);
+    })), 'quox wazuh incidents show WINC_abc');
+
+  example(incidents.command('close')
+    .description('Close a Wazuh incident with what you found (witnessed)')
+    .argument('<id>', 'incident id from `quox wazuh incidents`')
+    .requiredOption('--reason <text>', 'what you found, for the record')
+    .action(guard(async (id, options) => {
+      auth.requireAuth();
+      const { ep, data } = await call('incidents close', 'mon.wazuh.incidents.close', { id }, (e) => client.post(e.path, { service: e.service, body: { reason: String(options.reason) } }), id);
+      if (bad(data) || !data.incident) throw errBody('incidents close', ep, data, 'response had no incident');
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      head('incidents close', `closed ${data.incident.id || id}`);
+    })), 'quox wazuh incidents close WINC_abc --reason "known scanner, blocked at edge-02"');
+
+  // ---- WAZ P7: diagnose + escalate ----
+  example(incidents.command('diagnose')
+    .description('Read-only host diagnosis for an incident (auth failures, sessions, ports, processes, logins, the unit): allowlisted reads run, the rest are held for a human approval')
+    .argument('<id>', 'incident id from `quox wazuh incidents`')
+    .action(guard(async (id) => {
+      auth.requireAuth();
+      const { ep, data } = await call('incidents diagnose', 'mon.wazuh.incidents.diagnose', { id }, (e) => client.post(e.path, { service: e.service, body: {} }), id);
+      if (bad(data) || !data.incident || !data.incident.diagnosis) throw errBody('incidents diagnose', ep, data, 'response had no diagnosis');
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      const d = data.incident.diagnosis;
+      head('incidents diagnose', `${id} · ${d.status}${d.host ? ` on ${d.host}` : ''}`, d.status === 'ran' ? 'ok' : (d.status === 'refused' || d.status === 'unavailable' ? 'fail' : 'warn'));
+      console.log(d.summary || '-');
+      printChecks(d, pad);
+      const held = (d.checks || []).filter((c) => c.approval_id);
+      if (held.length) {
+        console.log('');
+        for (const c of held) console.log(`◐ ${c.name} is held for approval ${c.approval_id}: a person approves it in the inbox; read the output with quox approvals result ${c.approval_id}`);
+      }
+    })), 'quox wazuh incidents diagnose WINC_abc');
+
+  example(incidents.command('escalate')
+    .description('File the incident as a finding in a QuoxSecurity engagement (a new wazuh-incident-<id> engagement unless --engagement is given); the finding id is linked on the incident')
+    .argument('<id>', 'incident id from `quox wazuh incidents`')
+    .option('--engagement <idOrName>', 'an existing engagement of this org (id or exact name)')
+    .action(guard(async (id, options) => {
+      auth.requireAuth();
+      const body = options.engagement ? { engagement: String(options.engagement) } : {};
+      const { ep, data } = await call('incidents escalate', 'mon.wazuh.incidents.escalate', { id }, (e) => client.post(e.path, { service: e.service, body }), id, { engagement: options.engagement });
+      if (bad(data) || !data.finding || !data.engagement) throw errBody('incidents escalate', ep, data, 'response had no finding');
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      const f = data.finding;
+      head('incidents escalate', `finding ${f.id} filed`);
+      console.log(`Filed finding ${f.id} (${f.severity}, ${f.status}) in ${data.created_engagement ? 'new ' : ''}engagement ${data.engagement.id}.`);
+      console.log(`Engagement: ${data.engagement.name || data.engagement.id}. Next: quox engagement findings ${data.engagement.id}; verify it: quox engagement verify-finding ${f.id} confirmed|refuted --reason "..."`);
+    })), 'quox wazuh incidents escalate WINC_abc --engagement soc-week-45');
+}

package/lib/commands/wazuhReport.js

@@ -0,0 +1,192 @@
+/**
+ * quox wazuh report ... : signed, offline-verifiable Wazuh security posture reports (WAZ P5).
+ * The sibling of `quox kuma sla` (kumaSla.js): same canonical form, same signer, same bundle shape.
+ *
+ * quox wazuh report generate [--agent <id|name>] [--out <file>]   build + sign + store a posture report
+ * quox wazuh report list                                         this org's stored reports
+ * quox wazuh report show <id> [--out <file>]                     one stored report (and its signed bundle)
+ * quox wazuh report verify <id|file> [--public-key <pem|base64|file>]
+ *
+ * `verify <id>` asks the collector, which checks against its pinned WARD key (trust anchored).
+ * `verify <file>` is fully OFFLINE: it recomputes sha256 over the canonical report and checks the Ed25519
+ * signature with node:crypto. Against the key embedded in the file this proves integrity only (anyone can
+ * mint a keypair); pass --public-key (a PEM, a PEM file, or the raw 32 byte base64 WARD key) to pin the signer.
+ *
+ * Exit codes: 0 ok / verified, 1 error, 2 verification FAILED.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { createHash, createPublicKey, verify as cryptoVerify } from 'node:crypto';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { canonicalize } from './kumaSla.js';
+
+const KIND = 'quox.wazuh.posture.report';
+const SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
+/** A public key from a PEM string, a path to a PEM file, or a raw 32 byte base64 Ed25519 key. null if none of those. */
+export function parsePublicKey(value) {
+  if (!value) return null;
+  let text = String(value);
+  try { if (!/BEGIN PUBLIC KEY/.test(text) && existsSync(text)) text = readFileSync(text, 'utf-8'); } catch { /* not a file */ }
+  try {
+    if (/BEGIN PUBLIC KEY/.test(text)) {
+      const k = createPublicKey(text);
+      return k.asymmetricKeyType === 'ed25519' ? k : null;
+    }
+    const raw = Buffer.from(text.trim(), 'base64');
+    if (raw.length !== 32) return null;
+    return createPublicKey({ key: Buffer.concat([SPKI_PREFIX, raw]), format: 'der', type: 'spki' });
+  } catch { return null; }
+}
+
+/** Offline verification of an export bundle. Mirrors services/collector/lib/wazuhPostureReports.js verifyBundle. */
+export function verifyBundleOffline(bundle, { publicKey } = {}) {
+  const out = { valid: false, hash_ok: false, binding_ok: false, signature_ok: false, key_source: 'none', trust_anchored: false };
+  if (!bundle || typeof bundle !== 'object' || !bundle.report || typeof bundle.report !== 'object') return { ...out, reason: 'malformed_bundle' };
+  const sig = bundle.signature;
+  if (!sig || !sig.signature || !sig.message) return { ...out, reason: 'missing_signature' };
+  const recomputed = createHash('sha256').update(canonicalize(bundle.report), 'utf-8').digest('hex');
+  out.recomputed_sha256 = recomputed;
+  out.hash_ok = recomputed === bundle.report_sha256;
+  if (!out.hash_ok) return { ...out, reason: 'report_hash_mismatch' };
+  const r = bundle.report;
+  const expected = { kind: KIND, report_id: bundle.report_id, org_id: r.org_id, scope: r.scope, generated_at: r.generated_at, report_sha256: recomputed };
+  out.binding_ok = canonicalize(expected) === canonicalize(sig.message);
+  if (!out.binding_ok) return { ...out, reason: 'signature_not_bound_to_report' };
+  if (sig.sig_type !== 'ed25519') return { ...out, reason: `unverifiable_sig_type:${sig.sig_type}` };
+  let key = null; let source = 'none';
+  if (publicKey) { key = parsePublicKey(publicKey); source = 'pinned'; if (!key) return { ...out, reason: 'bad_public_key' }; }
+  else { key = parsePublicKey(sig.public_key); source = 'embedded'; }
+  if (!key) return { ...out, reason: 'no_verification_key' };
+  out.key_source = source;
+  try {
+    out.signature_ok = cryptoVerify(null, Buffer.from(canonicalize(sig.message), 'utf-8'), key, Buffer.from(String(sig.signature), 'base64'));
+  } catch (err) { return { ...out, reason: `verify_error:${err.message}` }; }
+  if (!out.signature_ok) return { ...out, reason: 'signature_mismatch' };
+  out.valid = true;
+  out.trust_anchored = source === 'pinned' && !sig.warning;
+  if (sig.warning) out.warning = sig.warning;
+  return out;
+}
+
+const bundleOf = (d) => ({ report_id: d.report_id, report: d.report, report_sha256: d.report_sha256, signature: d.signature });
+
+/** Human summary of a report: one line per section with its source status. Unavailable is said, never shown as zero. */
+function printReport(d, pad) {
+  const r = d.report || {};
+  const s = r.sections || {};
+  console.log(`Report ${d.report_id}   sha256 ${d.report_sha256}`);
+  console.log(`Org ${r.org_id}   scope ${r.scope}   manager ${r.wazuh_manager || 'unknown'}   generated ${r.generated_at}`);
+  const st = (x) => (x ? x.status : 'missing');
+  const rows = [['SECTION', 'SOURCE', 'SUMMARY']];
+  const m = s.manager;
+  if (m) rows.push(['manager', st(m), m.status === 'unavailable' ? m.error : `${m.running} daemons running${m.stopped && m.stopped.length ? `, stopped: ${m.stopped.join(', ')}` : ''}; agents ${m.agent_counts ? `${m.agent_counts.active ?? '?'} active of ${m.agent_counts.total ?? '?'}` : 'unknown'}`]);
+  const c = s.coverage;
+  if (c) rows.push(['coverage', st(c), c.status === 'unavailable' ? c.error : `${c.summary.covered ?? 'unknown'} of ${c.summary.fleet_hosts ?? 'unknown'} fleet hosts covered, ${c.summary.missing_agent ?? 'unknown'} missing an agent, ${c.summary.disconnected} disconnected`]);
+  const v = s.vulnerabilities;
+  if (v) rows.push(['vulnerabilities', st(v), v.status === 'unavailable' ? v.error : `${v.summary.cves} CVEs, ${v.summary.in_kev} in CISA KEV, top ${v.items.length} listed`]);
+  const t = s.alert_triage;
+  if (t) rows.push(['alert triage', st(t), t.status === 'unavailable' ? t.error : `${t.total_alerts} alerts level ${t.min_level}+ in ${t.window}, ${t.groups.length} rule groups`]);
+  const sca = s.sca;
+  if (sca) rows.push(['sca', st(sca), sca.status === 'unavailable' ? sca.error : `${sca.policies.length} policies on agent ${sca.agent_id}`]);
+  console.log(`\n${pad(rows).join('\n')}`);
+  if (v && v.status !== 'unavailable' && v.items.length) {
+    const vr = [['CVE', 'KEV', 'EPSS', 'CVSS', 'HOSTS']];
+    for (const it of v.items) vr.push([it.cve, it.kev ? (it.kev_ransomware ? 'yes (ransomware)' : 'yes') : 'no', typeof it.epss === 'number' ? `${(it.epss * 100).toFixed(1)}%` : '-', it.cvss ?? '-', it.agents_affected ?? '-']);
+    console.log(`\nTop CVEs\n${pad(vr).join('\n')}`);
+  }
+  if (Array.isArray(r.not_included) && r.not_included.length) console.log(`\nNot included: ${r.not_included.map((n) => `${n.section} (${n.reason})`).join('; ')}`);
+  if (Array.isArray(r.cannot_establish) && r.cannot_establish.length) console.log(`Cannot establish:\n${r.cannot_establish.map((x) => `  - ${x}`).join('\n')}`);
+}
+
+export function registerWazuhReport(wazuh, { client, auth, jsonOut, guard, WazFail, pad, head, failFrom, example }) {
+  const call = async (verb, key, params, fn) => {
+    const ep = resolveEndpoint(key, params);
+    try { return { ep, data: await fn(ep) }; } catch (err) { throw failFrom(verb, ep.method, ep.path, err); }
+  };
+  const writeOut = (file, d) => writeFileSync(file, `${JSON.stringify(bundleOf(d), null, 2)}\n`);
+
+  const report = wazuh.command('report')
+    .description('Signed, offline-verifiable Wazuh security posture report: generate, list, show, verify')
+    .addHelpText('after', '\nExit codes: 0 ok, 1 error, 2 `report verify` found the report does NOT verify.');
+
+  example(report.command('generate')
+    .description('Build, sign and store a posture report (manager, coverage, CVE priority, 24h alert triage; SCA with --agent)')
+    .option('--agent <id|name>', 'scope the vulnerabilities (and add SCA) to one agent')
+    .option('--out <file>', 'also write the signed bundle here for offline verification')
+    .action(guard(async (options) => {
+      auth.requireAuth();
+      const body = {};
+      if (options.agent) body.agent = String(options.agent);
+      const { ep, data } = await call('report generate', 'mon.wazuh.reports.create', {}, (e) => client.post(e.path, { service: e.service, body, timeout: 180000, retries: 0 }));
+      if (!data || data.success === false || data.error || !data.report || !data.signature) {
+        throw new WazFail(`quox wazuh report generate: ${ep.method} ${ep.path} returned an error body: ${(data && (data.error || data.message)) || 'response had no report'}`);
+      }
+      if (options.out) writeOut(options.out, data);
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      const un = data.report.sections_unavailable || [];
+      head('report generate', `${data.report.scope}${un.length ? ` · ${un.length} section${un.length === 1 ? '' : 's'} unavailable` : ''}`, un.length || !data.trust_anchored ? 'warn' : 'ok');
+      printReport(data, pad);
+      console.log(data.trust_anchored ? '\nSigned with the WARD key and witnessed.' : '\nWARNING: signed with an ephemeral key (no persistent WARD key on this collector): integrity only, not trust anchored.');
+      console.log(`Verify:  quox wazuh report verify ${options.out || data.report_id}`);
+    })), 'quox wazuh report generate --out posture.json');
+
+  example(report.command('list')
+    .description('This org\'s stored posture reports')
+    .action(guard(async () => {
+      auth.requireAuth();
+      const { ep, data } = await call('report list', 'mon.wazuh.reports.list', {}, (e) => client.get(e.path, { service: e.service }));
+      if (!data || data.success === false || data.error || !Array.isArray(data.reports)) {
+        throw new WazFail(`quox wazuh report list: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'response had no reports array'}`);
+      }
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      head('report list', `${data.reports.length} ${data.reports.length === 1 ? 'report' : 'reports'}`);
+      if (!data.reports.length) { console.log('No reports yet. Generate one: quox wazuh report generate'); return; }
+      const rows = [['REPORT', 'SCOPE', 'CREATED', 'SHA256']];
+      for (const r of data.reports) rows.push([r.report_id, r.scope, r.created_at, String(r.report_sha256).slice(0, 16)]);
+      console.log(pad(rows).join('\n'));
+    })), 'quox wazuh report list');
+
+  example(report.command('show')
+    .description('One stored posture report')
+    .argument('<id>', 'a report id from `quox wazuh report list`')
+    .option('--out <file>', 'write the signed bundle here for offline verification')
+    .action(guard(async (id, options) => {
+      auth.requireAuth();
+      const { ep, data } = await call('report show', 'mon.wazuh.reports.get', { id }, (e) => client.get(e.path, { service: e.service }));
+      if (!data || data.success === false || data.error || !data.report || !data.signature) {
+        throw new WazFail(`quox wazuh report show: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'response had no report'}`);
+      }
+      if (options.out) writeOut(options.out, data);
+      if (jsonOut()) { console.log(JSON.stringify(data, null, 2)); return; }
+      head('report show', data.report.scope);
+      printReport(data, pad);
+    })), 'quox wazuh report show WPR_ABC --out posture.json');
+
+  example(report.command('verify')
+    .description('Recompute the report hash and check the signature (id: via the collector, pinned WARD key; file: fully offline)')
+    .argument('<id|file>', 'a report id, or a bundle file written by `report generate --out` / `report show --out`')
+    .option('--public-key <pem|base64|file>', 'offline: pin this Ed25519 WARD public key (PEM, PEM file, or raw 32 byte base64) instead of trusting the key in the file')
+    .action(guard(async (target, options) => {
+      let result;
+      if (existsSync(target)) {
+        let bundle;
+        try { bundle = JSON.parse(readFileSync(target, 'utf-8')); } catch (err) { throw new WazFail(`quox wazuh report verify: ${target} is not valid JSON: ${err.message}`); }
+        result = { report_id: bundle && bundle.report_id, mode: 'offline', ...verifyBundleOffline(bundle, { publicKey: options.publicKey }) };
+      } else {
+        auth.requireAuth();
+        const { ep, data } = await call('report verify', 'mon.wazuh.reports.verify', { id: target }, (e) => client.get(e.path, { service: e.service }));
+        if (!data || data.success === false || data.error || typeof data.valid !== 'boolean') {
+          throw new WazFail(`quox wazuh report verify: ${ep.method} ${ep.path} returned an error body: ${(data && data.error) || 'response had no verdict'}`);
+        }
+        result = { mode: 'collector', ...data };
+      }
+      if (jsonOut()) { console.log(JSON.stringify(result, null, 2)); } else {
+        head('report verify', result.valid ? `verified (${result.mode})` : `NOT verified: ${result.reason}`, result.valid ? 'ok' : 'fail');
+        console.log(`hash ${result.hash_ok ? 'matches' : 'DOES NOT match'}   binding ${result.binding_ok ? 'ok' : 'FAILED'}   signature ${result.signature_ok ? 'valid' : 'INVALID'}   key ${result.key_source}${result.trust_anchored ? ' (trust anchored)' : ' (not trust anchored)'}`);
+        if (result.valid && !result.trust_anchored) console.log('Integrity holds, but the signer was not checked against the WARD key. Pin it with --public-key, or verify by id through the collector.');
+        if (result.warning) console.log(`Warning: ${result.warning}`);
+      }
+      if (!result.valid) process.exitCode = 2;
+    })), 'quox wazuh report verify posture.json --public-key ward-pub.pem');
+}