quoxcli 0.3.1 → 0.5.0

package/lib/commands/wazuhIntake.js

@@ -0,0 +1,317 @@
+/**
+ * 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 P7: compact context flags. A source that could not answer shows as SRC?, never as "nothing".
+const UNKNOWN_FLAG = { maintenance: 'MAINT?', kuma: 'KUMA?', deploys: 'DEPLOY?' };
+export function contextFlags(ctx) {
+  if (!ctx || typeof ctx !== 'object') return '-';
+  const parts = [...(ctx.flags || []), ...(ctx.unavailable || []).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 ----
+  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;
+      head('incidents', `${data.incidents.length} shown · ${openN} open`, openN ? 'warn' : 'ok');
+      if (!data.incidents.length) 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);
+      const rows = [['ID', 'STATE', 'LEVEL', 'AGENT', 'RULE', 'DESCRIPTION', 'COUNT', 'LAST SEEN', 'MITRE', ...(withCtx ? ['CONTEXT'] : [])]];
+      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)] : [])]);
+      }
+      console.log(pad(rows).join('\n'));
+    })), '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 || '-'],
+        ...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');
+}

package/lib/commands/workflow.js

@@ -11,6 +11,23 @@ import { resolveOrgId, parseJSON } from './helpers.js';
 import { resolveEndpoint } from '../api/endpoints.js';
 import { confirmDestructive } from '../core/confirm.js';
 
+// QUOXON (owner decision 2026-11-05, "opt-in yes"): a created workflow is not armed unless --activate was given.
+// Say which, from the engine's own answer (active / trigger_state), never a guess. Silent in --json mode.
+function printArmState(created, fallbackId) {
+  if (getOutputFormat() === 'json' || !created || typeof created !== 'object') return;
+  const id = created.id || fallbackId;
+  const ts = created.trigger_state && typeof created.trigger_state === 'object' ? created.trigger_state : null;
+  const active = ts && typeof ts.active === 'boolean' ? ts.active : created.active;
+  if (typeof active !== 'boolean') return;
+  const nodes = created.definition?.nodes || created.nodes || [];
+  const hasTrigger = Array.isArray(nodes) && nodes.some((n) => n && typeof n.type === 'string' && n.type.startsWith('trigger:'));
+  if (active) {
+    printInfo(ts?.next_run_at ? `Active: its trigger is armed, next run ${ts.next_run_at}.` : 'Active: its trigger is armed.');
+  } else if (hasTrigger) {
+    printInfo(`NOT active: its trigger is not armed, so it will not run on its own. Arm it with: quox trigger workflow-activate ${id}`);
+  }
+}
+
 // Top-level Workflow fields compared for `workflow apply`'s diff-preview
 // (mirrors core/workflow.ts's WorkflowSchema field set, minus `id`).
 const APPLY_DIFF_FIELDS = ['name', 'description', 'notes', 'version', 'nodes', 'edges', 'variables', 'credentials', 'settings', 'metadata'];
@@ -242,10 +259,11 @@ export function registerWorkflowCommands(program, ctx) {
 
   workflow
     .command('create')
-    .description('Create a new workflow in the workflow engine (quoxflow). --steps takes a JSON array of nodes (chained in order) or an object with nodes and optional edges')
+    .description('Create a new workflow in the workflow engine (quoxflow). --steps takes a JSON array of nodes (chained in order) or an object with nodes and optional edges. The workflow is created NOT active (its schedule or trigger is not armed) unless you pass --activate; arm it later with `quox trigger workflow-activate <id>`')
     .requiredOption('--name <name>', 'workflow name')
     .option('--description <desc>', 'description')
     .option('--steps <json>', 'nodes as a JSON array (chained sequentially), or {"nodes":[...],"edges":[...]}')
+    .option('--activate', 'arm the workflow now: register its schedule/webhook/event trigger (default: created inactive)')
     .action(async (options) => {
       auth.requireAuth();
       // #1190: the engine is the one workflow store. Same id shape as `workflow apply`.
@@ -264,12 +282,13 @@ export function registerWorkflowCommands(program, ctx) {
           throw new Error('--steps must be a JSON array of nodes, or an object with a "nodes" array (and optional "edges").');
         }
       }
-      const body = { id, name: options.name, nodes, edges };
+      const body = { id, name: options.name, nodes, edges, activate: options.activate === true };
       if (options.description) body.description = options.description;
       const ep = resolveEndpoint('workflows.applyCreate');
       const res = await client.post(ep.path, { service: ep.service, body });
       const created = res?.data || res;
       printEvent(events.created('quox', 'workflow', `${options.name} (quoxflow) id:${created.id || id}`));
+      printArmState(created, id);
       // #1000: --json gets the saved workflow (the event line is suppressed in json mode, which left nothing)
       if (getOutputFormat() === 'json') formatDetail(created, { format: 'json' });
     });
@@ -288,7 +307,22 @@ export function registerWorkflowCommands(program, ctx) {
       if (options.name) body.name = options.name;
       if (options.description) body.description = options.description;
       if (options.status) body.status = options.status;
-      const data = await client.patch(resolveEndpoint('workflows.update', { orgId, workflowId }).path, { service: resolveEndpoint('workflows.update', { orgId, workflowId }).service, body });
+      // Same order as `workflow get`/`delete`: `list` shows engine (quoxflow) workflows, so try the engine first and
+      // only fall back to the auth store on a 404. Any other engine error (403 etc.) is surfaced, never masked.
+      let data;
+      if (options.status === undefined) {
+        try {
+          const ep = resolveEndpoint('workflows.applyUpdate', { workflowId });
+          const res = await client.put(ep.path, { service: ep.service, body });
+          data = res?.data || res;
+        } catch (err) {
+          if (err.status !== 404) throw err;
+        }
+      }
+      if (data === undefined) {
+        const ep = resolveEndpoint('workflows.update', { orgId, workflowId });
+        data = await client.patch(ep.path, { service: ep.service, body });
+      }
       printEvent(events.updated('quox', 'workflow', workflowId));
       if (getOutputFormat() === 'json') formatDetail(data?.workflow || data, { format: 'json' });
     });
@@ -485,6 +519,7 @@ export function registerWorkflowCommands(program, ctx) {
     .description('Create or update a workflow declaratively from a YAML/JSON file (quoxflow-direct: POST if the file has no id, PUT with a diff-preview if it does)')
     .requiredOption('-f, --file <path>', 'path to a workflow definition file (.yaml/.yml/.json)')
     .option('--force', 'skip the diff-preview confirmation on update')
+    .option('--activate', 'when this creates the workflow, arm its trigger now (default: created inactive). An update never changes whether it is armed: use `quox trigger workflow-activate|workflow-deactivate`')
     .action(async (options) => {
       auth.requireAuth();
       const wf = readDeclarativeFile(options.file);
@@ -538,10 +573,13 @@ export function registerWorkflowCommands(program, ctx) {
       const createEp = resolveEndpoint('workflows.applyCreate');
       // #1000: quoxflow's WorkflowSchema requires an id, so "no id = create" 400'd. Mint one in the
       // engine's own wf-<ms>-<6> shape; the created id is printed, so the file can be given it to update later.
-      const body = wf.id ? wf : { ...wf, id: `wf-${Date.now()}-${Math.random().toString(36).slice(2, 8).padEnd(6, '0')}` };
+      const minted = wf.id ? wf : { ...wf, id: `wf-${Date.now()}-${Math.random().toString(36).slice(2, 8).padEnd(6, '0')}` };
+      // Owner decision 2026-11-05: arming is opt-in; a file's own `activate` key is not an opt-in, only --activate is.
+      const body = { ...minted, activate: options.activate === true };
       const data = await client.post(createEp.path, { service: createEp.service, body });
       const created = data.data || data;
       printEvent(events.created('quox', 'workflow', `${created.name || wf.name || created.id} (quoxflow) id:${created.id}`));
+      printArmState(created, body.id);
       formatDetail(created, { format: program.opts().output });
     });
 
@@ -600,6 +638,7 @@ export function registerWorkflowCommands(program, ctx) {
     .requiredOption('-f, --file <path>', 'path to an n8n workflow export (.yaml/.yml/.json)')
     .option('--generate-ids', 'generate new node/workflow ids instead of reusing the n8n ones')
     .option('--include-positions', 'preserve n8n canvas node positions')
+    .option('--activate', 'arm the imported workflow\'s trigger now (default: imported inactive)')
     .action(async (options) => {
       auth.requireAuth();
       const parsed = readDeclarativeFile(options.file);
@@ -608,6 +647,9 @@ export function registerWorkflowCommands(program, ctx) {
       const importOptions = { ...(parsed?.options || {}) };
       if (options.generateIds) importOptions.generateIds = true;
       if (options.includePositions) importOptions.includePositions = true;
+      // Owner decision 2026-11-05: only --activate arms an import (a wrapped file's own options.activate does not).
+      delete importOptions.activate;
+      if (options.activate) importOptions.activate = true;
 
       const ep = resolveEndpoint('workflows.importN8n');
       const data = await client.post(ep.path, {
@@ -616,6 +658,7 @@ export function registerWorkflowCommands(program, ctx) {
       });
       const result = data.data || data;
       printEvent(glyphLine('quox', 'n8n workflow imported', { result: result.workflow?.id || result.id, status: 'ok' }));
+      printArmState(result.workflow, result.workflow?.id || result.id);
       if (result.warnings?.length) {
         for (const w of result.warnings) printWarning(w);
       }