securenow 8.16.0 → 8.18.0

package/cli/security.js

@@ -33,6 +33,19 @@ function ruleStatusBadge(rule) {
   return st;
 }
 
+function throttleLabel(throttle) {
+  return throttle?.enabled ? `one alert per address every ${throttle.minutes || 15} min` : 'off';
+}
+
+// The API refuses edits (mode included) on system rules: they are read-only templates.
+function isSystemRuleRefusal(err) {
+  return err?.code === 'system_rule_readonly' || (err?.statusCode === 403 && /read-only templates/i.test(err?.message || ''));
+}
+
+function printWarnings(data) {
+  for (const warning of data?.warnings || []) ui.warn(warning);
+}
+
 /** Dispatch: list | show <id> | update <id> ... */
 async function alertRulesRoute(args, flags) {
   const sub = args[0];
@@ -42,6 +55,9 @@ async function alertRulesRoute(args, flags) {
   if (sub === 'from-text' || sub === 'draft') {
     return alertRuleFromText(args.slice(1), flags);
   }
+  if (sub === 'change') {
+    return alertRuleChange(args.slice(1), flags);
+  }
   if (sub === 'show') {
     return alertRuleShow(args.slice(1), flags);
   }
@@ -78,6 +94,18 @@ async function alertRulesRoute(args, flags) {
   if (sub === 'exclusions') {
     return alertRuleExclusions(args.slice(1), flags);
   }
+  if (sub === 'runs') {
+    return alertRuleRuns(args.slice(1), flags);
+  }
+  if (sub === 'request-promotion') {
+    return alertRuleRequestPromotion(args.slice(1), flags);
+  }
+  if (sub === 'run' || sub === 'run-now') {
+    return alertRuleRunNow(args.slice(1), flags);
+  }
+  if (sub === 'why' || sub === 'explain') {
+    return alertRuleWhy(args.slice(1), flags);
+  }
   if (sub === 'promote') {
     return alertRuleSetMode(args.slice(1), flags, 'prod');
   }
@@ -115,7 +143,9 @@ async function alertRuleSetMode(args, flags, mode) {
       s.stop(`${ui.truncate(id, 12)} → ${mode}`);
       okCount++;
     } catch (err) {
-      s.fail(`Failed on ${ui.truncate(id, 12)}: ${err.message}`);
+      s.fail(isSystemRuleRefusal(err)
+        ? `${ui.truncate(id, 12)} is a system rule (a read-only template): duplicate it first: securenow alerts rules duplicate ${id}`
+        : `Failed on ${ui.truncate(id, 12)}: ${err.message}`);
       failures.push(id);
     }
   }
@@ -284,6 +314,7 @@ async function alertRuleCreate(args, flags) {
   }
   if (flags['no-throttle']) body.throttle = { enabled: false, minutes: 0 };
   else if (flags['throttle-minutes']) body.throttle = { enabled: true, minutes: Number(flags['throttle-minutes']) };
+  if (flags['allow-no-ip']) body.allowNoIp = true;
 
   const channelStr = flags.channel || flags.channels;
   if (channelStr) {
@@ -326,10 +357,12 @@ async function alertRuleCreate(args, flags) {
       ['Severity', r.severity || '-'],
       ['Applications', r.applicationsAll ? 'all apps' : ((r.applications || []).join(', ') || '-')],
       ['Schedule', r.schedule?.enabled === false ? 'disabled' : (r.schedule?.description || r.schedule?.cronExpression || '-')],
-      ['Throttle', r.throttle?.enabled ? `${r.throttle.minutes} min` : 'off'],
+      ['Throttle', throttleLabel(r.throttle)],
       ['Query', r.queryMappingId?.name || r.queryMappingId || '-'],
       ['Validation', flags['no-validate'] ? 'skipped' : 'dry-run clean'],
+      ...(data.firstRunQueued ? [['First run', `queued now (see: securenow alerts rules runs ${createdId})`]] : []),
     ]);
+    printWarnings(data);
     console.log('');
     ui.success(`Created. View it with: securenow alerts rules show ${createdId}`);
   } catch (err) {
@@ -369,10 +402,12 @@ async function alertRuleShow(args, flags) {
       ['System rule', r.isSystem ? 'yes' : 'no'],
       ['Applications', appLine],
       ['Schedule', r.schedule?.enabled === false ? 'disabled' : (r.schedule?.description || r.schedule?.cronExpression || '—')],
-      ['Throttle', r.throttle?.enabled ? `${r.throttle.minutes} min` : 'off'],
+      ['Throttle', throttleLabel(r.throttle)],
       ['Query', r.queryMappingId?.name || '—'],
     ]);
     console.log('');
+    console.log(ui.c.dim(`  Runs: securenow alerts rules runs ${r._id || r.id || id}   Why no alert: securenow alerts rules why ${r._id || r.id || id} --ip <ip>`));
+    console.log('');
   } catch (err) {
     s.fail('Failed to fetch alert rule');
     throw err;
@@ -443,9 +478,14 @@ async function alertRuleUpdate(args, flags) {
 
   // Lifecycle mode promote/demote (also available as: alerts rules promote|demote <id>).
   if (flags.mode === 'test' || flags.mode === 'prod') body.mode = flags.mode;
+  if (flags.severity) {
+    const severity = String(flags.severity).toLowerCase();
+    if (!['critical', 'high', 'medium', 'low'].includes(severity)) { ui.error('--severity must be critical, high, medium or low'); process.exit(1); }
+    body.severity = severity;
+  }
 
   if (Object.keys(body).length === 0) {
-    ui.error('Nothing to update. Use --applications-all/--apps, --status (or --enable/--disable/--pause), or --mode test|prod (or: alerts rules promote/demote <id>).');
+    ui.error('Nothing to update. Use --applications-all/--apps, --status (or --enable/--disable/--pause), --severity, or --mode test|prod (or: alerts rules promote/demote <id>).');
     process.exit(1);
   }
 
@@ -453,10 +493,14 @@ async function alertRuleUpdate(args, flags) {
   try {
     await api.put(`/alert-rules/${id}`, body);
     s.stop('Updated');
-    const extras = [body.status && `status → ${body.status}`, body.mode && `mode → ${body.mode}`].filter(Boolean);
+    const extras = [body.status && `status → ${body.status}`, body.mode && `mode → ${body.mode}`, body.severity && `severity → ${body.severity}`].filter(Boolean);
     ui.success('Alert rule updated' + (extras.length ? ` (${extras.join(', ')})` : ''));
   } catch (err) {
     s.fail('Failed to update alert rule');
+    if (isSystemRuleRefusal(err)) {
+      ui.info(`System rules are read-only templates. Duplicate it first: securenow alerts rules duplicate ${id}`);
+      process.exit(1);
+    }
     throw err;
   }
 }
@@ -472,11 +516,13 @@ async function alertRuleSetSql(args, flags) {
   const body = { sqlQuery };
   if (flags.nlp || flags.text) body.nlpQuery = flags.nlp || flags.text;
   if (flags.category) body.category = flags.category;
+  if (flags['allow-no-ip']) body.allowNoIp = true;
 
   const s = ui.spinner('Updating rule SQL');
   try {
     const data = await api.put(`/alert-rules/${id}`, body);
     s.stop('Rule SQL updated');
+    printWarnings(data);
     const ok = flags['no-validate'] ? null : await validateRuleById(id, flags);
     if (ok && ok.status === 'failed') {
       ui.warn(`Saved, but the new SQL failed a dry-run: ${ok.error || 'unknown error'}`);
@@ -783,14 +829,30 @@ async function alertRuleFromText(args, flags) {
   }
   s.stop('Draft ready');
 
+  // A draft that matches the data right now alerts the moment it is saved: a real ongoing attack,
+  // or (more often) a bad baseline. Unattended (--yes) creation stops there unless --force.
+  const matches = Number(result.check?.matches || 0);
+  const refuse = Boolean(flags.yes) && !flags.force && !flags['draft-only'] && matches > 0;
+  const refusal = `Not created: the check found ${matches} match${matches === 1 ? '' : 'es'} in your data right now, so this rule would alert as soon as it is saved.`;
+
   if (flags.json && (flags['draft-only'] || !flags.yes)) { ui.json(result); return; }
+  if (flags.json && refuse) {
+    ui.json({ ...result, created: false, refused: 'check_matches', message: refusal });
+    process.exit(1);
+  }
   printDraft(result);
   console.log('');
   if (flags['draft-only']) {
     ui.info('Draft only: nothing was created. Drop --draft-only to create it.');
     return;
   }
+  if (refuse) {
+    ui.warn(refusal);
+    ui.info('If those rows are a real attack, create it anyway with --yes --force. If they are normal traffic, refine the description and draft again.');
+    process.exit(1);
+  }
   if (!flags.yes) {
+    if (matches > 0) ui.warn(`The check found ${matches} match${matches === 1 ? '' : 'es'} right now (above): this rule alerts as soon as it is saved.`);
     const ok = await ui.confirm('Create this rule? It starts in test mode: it alerts, but blocks nothing');
     if (!ok) { ui.info('Nothing created'); return; }
   }
@@ -814,9 +876,93 @@ async function alertRuleFromText(args, flags) {
     ['Kind', r.executionMode === 'instant' ? 'instant (every request, as it arrives)' : `periodic (${r.schedule?.description || r.schedule?.cronExpression || '-'})`],
     ['Mode', `${r.mode || 'test'} (alerts only, no blocking)`],
     ['Application', (r.applications || []).join(', ') || '-'],
+    ...(data.firstRunQueued ? [['First run', 'queued now']] : []),
   ]);
+  printWarnings(data);
   console.log('');
   ui.success(`Watching. Promote it when it has proved itself: securenow alerts rules promote ${id}`);
+  console.log(ui.c.dim(`  Runs: securenow alerts rules runs ${id}   Why no alert: securenow alerts rules why ${id} --ip <ip>`));
+}
+
+// Describe a change to an existing rule in English: the API rewrites the rule from its current
+// version and the app's data, checks the result, and the change is applied as a new rule version.
+async function alertRuleChange(args, flags) {
+  requireAuth();
+  const id = args[0];
+  const text = args.slice(1).join(' ').trim() || (typeof flags.text === 'string' ? flags.text.trim() : '');
+  if (!id || !text) {
+    ui.error('Usage: securenow alerts rules change <rule-id> "<what should change>" [--app <key>] [--yes] [--draft-only] [--json]');
+    console.log(ui.c.dim('  Example: securenow alerts rules change <id> "raise the threshold to 20 failed sign-ins"'));
+    process.exit(1);
+  }
+  const body = { text, ruleId: id };
+  if (flags.app) body.applicationKey = flags.app;
+
+  const s = ui.spinner('Rewriting the rule from your app\'s data');
+  let result;
+  try {
+    const started = await api.post('/alert-rules/draft', body);
+    result = await waitForDraft(started.draftId, s);
+  } catch (err) {
+    s.fail('Failed to draft the change');
+    throw err;
+  }
+  if (result.status !== 'complete') {
+    s.fail(result.error || 'Could not draft the change');
+    process.exit(1);
+  }
+  s.stop('Change drafted');
+
+  const matches = Number(result.check?.matches || 0);
+  const refuse = Boolean(flags.yes) && !flags.force && !flags['draft-only'] && matches > 0;
+  if (flags.json && (flags['draft-only'] || !flags.yes)) { ui.json(result); return; }
+  if (flags.json && refuse) {
+    ui.json({ ...result, applied: false, refused: 'check_matches' });
+    process.exit(1);
+  }
+  if (result.current?.kind === 'instant') {
+    console.log('');
+    console.log(ui.c.dim(`  Before: ${result.current.matchMode === 'all' ? 'all of' : 'any of'} ${(result.current.conditions || []).map((c) => `${c.field} ${c.operator} ${c.value}`).join('; ')}`));
+  } else if (result.current?.sql) {
+    console.log('');
+    console.log(ui.c.dim('  Before'));
+    for (const line of String(result.current.sql).split('\n')) console.log(ui.c.dim(`    ${line}`));
+  }
+  printDraft(result);
+  console.log('');
+  if (flags['draft-only']) { ui.info('Draft only: nothing was changed.'); return; }
+  if (refuse) {
+    ui.warn(`Not applied: the changed rule matches ${matches} row${matches === 1 ? '' : 's'} in your data right now, so it would alert at once. Apply anyway with --yes --force.`);
+    process.exit(1);
+  }
+  if (!flags.yes) {
+    if (matches > 0) ui.warn(`The changed rule matches ${matches} row${matches === 1 ? '' : 's'} right now (above): it alerts as soon as it is applied.`);
+    const ok = await ui.confirm('Apply this change? It is saved as a new rule version (roll back with alerts rules rollback)');
+    if (!ok) { ui.info('Nothing changed'); return; }
+  }
+
+  const d = result.draft || {};
+  const update = {
+    name: d.name,
+    description: d.summary || undefined,
+    severity: d.severity,
+    reviewNote: `Changed in English: ${text}`.slice(0, 1000),
+    // Instant: only what the draft decides, so the rule keeps its own instant-block settings.
+    ...(d.executionMode === 'instant'
+      ? { instant: { matchMode: d.instant?.matchMode, conditions: d.instant?.conditions || [], environments: d.instant?.environments || [] } }
+      : { sqlQuery: d.sqlQuery, schedule: d.schedule }),
+  };
+  const c = ui.spinner('Applying the change');
+  try {
+    const data = await api.put(`/alert-rules/${id}`, update);
+    c.stop(`Changed: version ${data.configVersion || '?'}`);
+    printWarnings(data);
+    if (flags.json) ui.json(data);
+    else console.log(ui.c.dim(`  History: securenow alerts rules versions ${id}   Runs: securenow alerts rules runs ${id}`));
+  } catch (err) {
+    c.fail('Failed to apply the change');
+    throw err;
+  }
 }
 
 async function alertRuleTest(args, flags) {
@@ -824,6 +970,7 @@ async function alertRuleTest(args, flags) {
   const id = args[0];
   if (!id) {
     ui.error('Usage: securenow alerts rules test <rule-id> [--app <key>] [--mode dry_run|live] [--wait]');
+    console.log(ui.c.dim('  dry_run (default) runs the query on your real data. live inserts 6 synthetic attack requests into your telemetry first.'));
     process.exit(1);
   }
 
@@ -1021,8 +1168,197 @@ async function alertRuleExclusions(args, flags) {
   }
 }
 
+// ── Rule runs: history, run now, why didn't this alert ──
+
+const RUN_OUTCOME_COLORS = {
+  notified: 'green',
+  storm: 'red',
+  error: 'red',
+  throttled: 'yellow',
+  suppressed_blocked: 'yellow',
+  suppressed_trusted: 'yellow',
+  no_ip: 'yellow',
+};
+
+function runOutcomeCell(outcome) {
+  const color = RUN_OUTCOME_COLORS[outcome];
+  return color && ui.c[color] ? ui.c[color](outcome) : ui.c.dim(outcome || '-');
+}
+
+function runAddressesCell(run) {
+  const parts = [];
+  if (run.notifiedIps?.length) parts.push(`notified ${run.notifiedIps.slice(0, 2).join(', ')}${run.notifiedIps.length > 2 ? '…' : ''}`);
+  const left = run.suppressedIps || [];
+  if (left.length) {
+    const reasons = [...new Set(left.map((x) => x.reason))].join('/');
+    parts.push(`${left.length} ${reasons}`);
+  }
+  if (!parts.length && run.ips?.length) parts.push(run.ips.slice(0, 2).join(', ') + (run.ips.length > 2 ? '…' : ''));
+  return parts.join('; ') || '—';
+}
+
+async function alertRuleRuns(args, flags) {
+  requireAuth();
+  const id = args[0];
+  if (!id) {
+    ui.error('Usage: securenow alerts rules runs <rule-id> [--limit 20] [--since 1h]');
+    process.exit(1);
+  }
+  const query = { limit: flags.limit || 20 };
+  if (flags.since) query.since = flags.since;
+  const s = ui.spinner('Fetching rule runs');
+  let data;
+  try {
+    data = await api.get(`/alert-rules/${id}/runs`, { query });
+    s.stop(`Found ${(data.runs || []).length} run${(data.runs || []).length === 1 ? '' : 's'}`);
+  } catch (err) {
+    s.fail('Failed to fetch rule runs');
+    throw err;
+  }
+  if (flags.json) { ui.json(data); return; }
+
+  const runs = data.runs || [];
+  console.log('');
+  ui.heading(data.ruleName || 'Rule runs');
+  if (data.nextRunAt) console.log(ui.c.dim(`  Next scheduled run: ${new Date(data.nextRunAt).toISOString().replace('T', ' ').slice(0, 19)} UTC`));
+  console.log('');
+  if (runs.length === 0) {
+    ui.info(data.executionMode === 'instant'
+      ? 'No matches recorded. An instant rule records a run when a request matches its conditions.'
+      : `No runs recorded. Run it now: securenow alerts rules run ${id}`);
+    return;
+  }
+  ui.table(['Started (UTC)', 'Trigger', 'Outcome', 'Rows', 'Addresses', 'Detail'], runs.map((run) => [
+    new Date(run.startedAt).toISOString().replace('T', ' ').slice(0, 19),
+    run.trigger,
+    runOutcomeCell(run.outcome),
+    String(run.rows ?? 0),
+    ui.truncate(runAddressesCell(run), 44),
+    ui.truncate(run.error || run.detail || (run.notificationId ? `notification ${run.notificationId}` : ''), 60),
+  ]));
+  console.log('');
+  console.log(ui.c.dim(`  Why no alert for an address: securenow alerts rules why ${id} --ip <ip> [--since 1h]`));
+  console.log('');
+}
+
+async function alertRuleRunNow(args, flags) {
+  requireAuth();
+  const id = args[0];
+  if (!id) {
+    ui.error('Usage: securenow alerts rules run <rule-id> [--no-wait] [--json]');
+    process.exit(1);
+  }
+  const requestedAt = Date.now();
+  const s = ui.spinner('Queueing a run');
+  let queued;
+  try {
+    queued = await api.post(`/alert-rules/${id}/run`, {});
+  } catch (err) {
+    s.fail('Failed to run the rule');
+    throw err;
+  }
+  if (flags['no-wait']) {
+    s.stop(queued.message || 'Queued');
+    if (flags.json) ui.json(queued);
+    return;
+  }
+
+  s.update('Waiting for the run to finish');
+  let run = null;
+  for (let i = 0; i < 30 && !run; i++) {
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+    const data = await api.get(`/alert-rules/${id}/runs`, { query: { limit: 5 } });
+    run = (data.runs || []).find((r) => r.trigger === 'manual' && new Date(r.startedAt).getTime() >= requestedAt - 15000) || null;
+  }
+  if (!run) {
+    s.stop('Queued; the run has not finished yet');
+    ui.info(`Check later: securenow alerts rules runs ${id}`);
+    if (flags.json) ui.json({ ...queued, run: null });
+    return;
+  }
+  s.stop(`Run finished: ${run.outcome}`);
+  if (flags.json) { ui.json({ ...queued, run }); return; }
+  console.log('');
+  ui.keyValue([
+    ['Outcome', runOutcomeCell(run.outcome)],
+    ['Rows', String(run.rows ?? 0)],
+    ['Addresses', String(run.uniqueIps ?? 0)],
+    ['Notified', (run.notifiedIps || []).join(', ') || '—'],
+    ['Left out', (run.suppressedIps || []).map((x) => `${x.ip} (${x.reason})`).join(', ') || '—'],
+    ['Notification', run.notificationId || '—'],
+    ['Duration', `${run.durationMs} ms`],
+    ...(run.detail ? [['Detail', run.detail]] : []),
+    ...(run.error ? [['Error', run.error]] : []),
+  ]);
+  console.log('');
+}
+
+async function alertRuleWhy(args, flags) {
+  requireAuth();
+  const id = args[0];
+  const ip = flags.ip || args[1];
+  if (!id || !ip || ip === true) {
+    ui.error('Usage: securenow alerts rules why <rule-id> --ip <ip> [--since 1h|30m|2d|<iso>] [--json]');
+    process.exit(1);
+  }
+  const query = { ip: String(ip), since: flags.since || '1h' };
+  const s = ui.spinner(`Checking what the rule did with ${ip}`);
+  let data;
+  try {
+    data = await api.get(`/alert-rules/${id}/explain`, { query });
+    s.stop('');
+  } catch (err) {
+    s.fail('Failed to explain the rule');
+    throw err;
+  }
+  if (flags.json) { ui.json(data); return; }
+  console.log('');
+  console.log(`  ${ui.c.bold(data.verdict || '')}`);
+  console.log('');
+  for (const finding of data.findings || []) {
+    console.log(`  • ${finding.title}`);
+    if (finding.detail) console.log(ui.c.dim(`    ${finding.detail}`));
+  }
+  console.log('');
+}
+
+// An agent hands the promotion of its test-mode rule to a person: the request waits on the rules
+// page and in `securenow human promotions` until someone approves or denies it.
+async function alertRuleRequestPromotion(args, flags) {
+  requireAuth();
+  const id = args[0];
+  const reason = typeof flags.reason === 'string' ? flags.reason.trim() : '';
+  if (!id || !reason) {
+    ui.error('Usage: securenow alerts rules request-promotion <rule-id> --reason "why it is ready for prod" [--evidence "<text>|@file"]');
+    process.exit(1);
+  }
+  const body = { reason };
+  if (typeof flags.evidence === 'string') {
+    body.evidence = flags.evidence.startsWith('@') ? fs.readFileSync(flags.evidence.slice(1), 'utf8') : flags.evidence;
+  }
+  const s = ui.spinner('Asking for promotion');
+  try {
+    const data = await api.post(`/alert-rules/${id}/promotion-requests`, body);
+    s.stop(data.existing ? 'A request for this rule is already waiting' : 'Promotion requested');
+    if (flags.json) { ui.json(data); return; }
+    ui.info(data.message || 'Waiting for a person to approve it.');
+    if (data.request?.id) console.log(ui.c.dim(`  Request ${data.request.id}. A person decides with: securenow human promotions`));
+  } catch (err) {
+    s.fail('Failed to request promotion');
+    throw err;
+  }
+}
+
 // ── Alert Channels ──
 
+function channelDestination(ch) {
+  if (ch.type === 'email') return ch.email || '—';
+  if (ch.type === 'securenow') return 'in-app (SecureNow inbox)';
+  if (ch.type === 'slack') return 'Slack webhook (URL hidden)';
+  if (ch.type === 'webhook') return `${ch.webhookMethod || 'POST'} webhook (URL hidden)`;
+  return '—';
+}
+
 async function alertChannelsList(args, flags) {
   requireAuth();
   const s = ui.spinner('Fetching alert channels');
@@ -1038,10 +1374,10 @@ async function alertChannelsList(args, flags) {
       ui.c.dim(ch.id || ch._id || ''),
       ch.name || '—',
       ch.type || '—',
-      ui.statusBadge(ch.enabled !== false ? 'enabled' : 'disabled'),
-      ch.target || ch.email || ch.webhookUrl || '—',
+      ui.statusBadge(ch.status === 'Disabled' ? 'disabled' : 'active'),
+      channelDestination(ch),
     ]);
-    ui.table(['ID', 'Name', 'Type', 'Status', 'Target'], rows);
+    ui.table(['ID', 'Name', 'Type', 'Status', 'Destination'], rows);
     console.log('');
   } catch (err) {
     s.fail('Failed to fetch alert channels');
@@ -1056,22 +1392,27 @@ async function alertHistoryList(args, flags) {
   const s = ui.spinner('Fetching alert history');
   try {
     const query = { limit: flags.limit || 20 };
+    if (flags.page) query.page = flags.page;
     const data = await api.get('/alert-history', { query });
-    const history = data.alerts || [];
-    s.stop(`Found ${history.length} alert${history.length !== 1 ? 's' : ''}${data.totalItems ? ` (${data.totalItems} total)` : ''}`);
+    const history = data.items || data.alerts || [];
+    const total = data.pagination?.total ?? data.totalItems;
+    s.stop(`Found ${history.length} alert${history.length !== 1 ? 's' : ''}${total ? ` (${total} total)` : ''}`);
 
     if (flags.json) { ui.json(data); return; }
 
     console.log('');
     const rows = history.map(h => [
       ui.c.dim(h.id || h._id || ''),
-      h.ruleName || h.type || '—',
-      h.severity ? ui.statusBadge(h.severity) : '—',
-      ui.truncate(h.message || h.description || '', 40),
-      h.serviceName || '—',
-      ui.timeAgo(h.triggeredAt || h.createdAt),
+      ui.truncate(h.subject || h.ruleName || '—', 40),
+      `${h.channelType || '—'}${h.channelName ? ` · ${ui.truncate(h.channelName, 20)}` : ''}`,
+      h.status ? ui.statusBadge(h.status) : '—',
+      h.applicationKey ? ui.truncate(h.applicationKey, 12) : '—',
+      ui.timeAgo(h.createdAt),
     ]);
-    ui.table(['ID', 'Rule', 'Severity', 'Message', 'App', 'Triggered'], rows);
+    ui.table(['ID', 'Subject', 'Channel', 'Status', 'App', 'Sent'], rows);
+    if (data.pagination?.totalPages > 1) {
+      console.log(ui.c.dim(`  Page ${data.pagination.page} of ${data.pagination.totalPages}: --page <n>`));
+    }
     console.log('');
   } catch (err) {
     s.fail('Failed to fetch alert history');

package/cli.js

@@ -195,6 +195,7 @@ const COMMANDS = {
     sub: {
       list: { desc: 'List recent logs', flags: { app: 'App key', env: 'Environment (production, staging, preview, local, or all)', environment: 'Alias for --env', limit: 'Max results (default 200)', since: 'Time window (e.g. 30m, 6h, 2d)', minutes: 'Time window in minutes (alias for --since Nm)', level: 'Filter by level (error, warn, info, debug)', start: 'Start time (ISO 8601)', end: 'End time (ISO 8601)' }, run: (a, f) => require('./cli/monitor').logsList(a, f) },
       trace: { desc: 'Show logs for a trace', usage: 'securenow logs trace <traceId>', flags: { app: 'App key', env: 'Environment', environment: 'Alias for --env' }, run: (a, f) => require('./cli/monitor').logsTrace(a, f) },
+      errors: { desc: 'Error lines grouped by message (ids and numbers normalized), most frequent first', usage: 'securenow logs errors [--app <key>] [--env <env>] [--since 1h] [--warn] [--limit 20]', flags: { app: 'App key', env: 'Environment', environment: 'Alias for --env', since: 'Window, e.g. 30m, 6h, 2d (default 1h)', warn: 'Include warnings', limit: 'Max groups (default 20)', json: 'Output as JSON' }, run: (a, f) => require('./cli/monitor').logsErrors(a, f) },
     },
     defaultSub: 'list',
   },
@@ -249,9 +250,10 @@ const COMMANDS = {
   },
   human: {
     desc: 'Work the human action queue prepared by SecureNow AI',
-    usage: 'securenow human <list|show|block|fp|report|action|prompt|work> [row|notificationId:ip] [options]',
+    usage: 'securenow human <list|show|block|fp|report|action|prompt|work|promotions|approve-promotion|deny-promotion> [row|notificationId:ip|request-id] [options]',
     flags: {
       json: 'Output as JSON',
+      note: 'With approve-promotion / deny-promotion: a note recorded with the decision',
       page: 'Queue page number',
       limit: 'Queue page size',
       search: 'Search IP, rule, path, or verdict',
@@ -286,6 +288,9 @@ const COMMANDS = {
       action: { desc: 'Approve/reject/execute a case-level proposed action', usage: 'securenow human action <row|notificationId> [actionKey] --status approved --yes --reason "..."', run: (a, f) => require('./cli/human').action(a, f) },
       prompt: { desc: 'Print a Codex/Claude MCP prompt for row or queue work', usage: 'securenow human prompt [row|notificationId:ip] [--limit 10]', run: (a, f) => require('./cli/human').prompt(a, f) },
       work: { desc: 'List the queue and print the MCP runbook to work it deeply', usage: 'securenow human work [--limit 10]', run: (a, f) => require('./cli/human').work(a, f) },
+      promotions: { desc: 'List requests to promote a test-mode rule to prod (agents ask, a person decides)', usage: 'securenow human promotions [--status pending|approved|denied|all]', run: (a, f) => require('./cli/human').promotions(a, f) },
+      'approve-promotion': { desc: 'Approve a promotion request: the rule goes to prod', usage: 'securenow human approve-promotion <request-id> --yes [--note "..."]', run: (a, f) => require('./cli/human').approvePromotion(a, f) },
+      'deny-promotion': { desc: 'Deny a promotion request: the rule stays in test mode', usage: 'securenow human deny-promotion <request-id> --reason "..."', run: (a, f) => require('./cli/human').denyPromotion(a, f) },
     },
     defaultSub: 'list',
   },
@@ -311,9 +316,14 @@ const COMMANDS = {
     usage: 'securenow alerts <subcommand> [options]',
     sub: {
       rules: {
-        desc: 'Create (from English or SQL), list, show, update, duplicate, promote/demote, set-sql, validate, delete, test, or tune alert rules',
-        usage: 'securenow alerts rules <list|from-text|create|show|update|duplicate|promote|demote|set-sql|validate|delete|test|dry-run-query|tune-query|exclusions|versions|version|rollback> [options]\n'
-          + '  securenow alerts rules from-text "<what to catch, in English>" --app <key> [--env <environment>] [--instant|--periodic] [--yes|--draft-only]',
+        desc: 'Create (from English or SQL), list, show, update, duplicate, promote/demote, set-sql, validate, delete, test, run, explain, or tune alert rules',
+        usage: 'securenow alerts rules <list|from-text|create|show|update|duplicate|promote|demote|set-sql|validate|delete|test|run|runs|why|dry-run-query|tune-query|exclusions|versions|version|rollback> [options]\n'
+          + '  securenow alerts rules from-text "<what to catch, in English>" --app <key> [--env <environment>] [--instant|--periodic] [--yes|--draft-only]\n'
+          + '  securenow alerts rules change <id> "<what should change>" [--yes|--draft-only]   rewrite a rule from English, checked, applied as a new version\n'
+          + '  securenow alerts rules runs <id> [--limit 20] [--since 1h]     what each run saw and why it did or didn\'t notify\n'
+          + '  securenow alerts rules run <id> [--no-wait]                     run a periodic rule now\n'
+          + '  securenow alerts rules why <id> --ip <ip> [--since 1h]          why the rule did or didn\'t alert on one address\n'
+          + '  securenow alerts rules request-promotion <id> --reason "..."    ask a person to promote a test-mode rule (for agents)',
         flags: {
           json: 'Output as JSON',
           env: 'With from-text or create --conditions: only watch this environment (default: every environment)',
@@ -327,10 +337,15 @@ const COMMANDS = {
           nlp: 'With create: plain-English intent stored on the query',
           text: 'Alias for --nlp',
           category: 'With create: query category (default: custom)',
-          severity: 'With create: critical | high | medium | low',
+          severity: 'With create/update: critical | high | medium | low',
           schedule: 'With create: cron expression (default */15 * * * *)',
-          'throttle-minutes': 'With create: notification throttle window in minutes',
+          'throttle-minutes': 'With create: one alert per address every N minutes (default 15)',
           'no-throttle': 'With create: disable throttling',
+          'allow-no-ip': 'With create/set-sql: save SQL that returns no ip column (it will never notify)',
+          ip: 'With why: the address to explain',
+          since: 'With runs/why: window, e.g. 30m, 1h, 2d or an ISO date (why defaults to 1h)',
+          limit: 'With runs: how many runs to show (default 20)',
+          'no-wait': 'With run: queue the run and return without waiting for it',
           'execution-mode': 'With create: scheduled | instant | hybrid',
           channel: 'With create: comma-separated alert channel ids (default: in-app)',
           'query-mapping-id': 'With create: reuse an existing saved query instead of --sql',
@@ -338,7 +353,7 @@ const COMMANDS = {
           'no-applications-all': 'With update: scope to explicit --apps list',
           apps: 'Comma-separated app keys (with create/update)',
           app: 'Application key for rule tests',
-          mode: 'With test: dry_run | live.  With list/update: lifecycle test | prod (test = detect-only, no mitigation)',
+          mode: 'With test: dry_run (default) | live (inserts 6 synthetic attack requests).  With list/update: lifecycle test | prod (test = detect-only, no mitigation)',
           status: 'With update: Active | Disabled | Paused.  With list: filter by status',
           enable: 'With update: shortcut for --status Active',
           disable: 'With update: shortcut for --status Disabled',
@@ -351,14 +366,15 @@ const COMMANDS = {
           query: 'Alias for --sql',
           file: 'Read SQL from a file',
           'no-validate': 'With create/set-sql: skip the post-write dry-run + rollback',
-          reason: 'Audit reason for a write',
+          reason: 'Audit reason for a write. With request-promotion: why the rule is ready for prod',
+          evidence: 'With request-promotion: evidence text or @file (runs, notifications, false-positive checks)',
           'apply-globally': 'Required for system query tuning',
           'reactivate-paused': 'Reactivate paused system copies after tuning',
           'expected-hash': 'Expected current SQL SHA-256 hash',
           notification: 'Review notification id tied to tuning',
           note: 'Review note tied to tuning',
           yes: 'Confirm write prompts',
-          force: 'Confirm write prompts',
+          force: 'Confirm write prompts. With from-text --yes: create even when the check matches data right now',
         },
         run: (a, f) => require('./cli/security').alertRulesRoute(a, f),
       },
@@ -767,8 +783,14 @@ const COMMANDS = {
   },
   mcp: {
     desc: 'Start the SecureNow MCP server over stdio',
-    usage: 'securenow mcp',
-    run: () => require('./mcp/server'),
+    usage: 'securenow mcp [--profile all|investigator|detection|responder]',
+    flags: {
+      profile: 'Serve a subset of the tools: investigator (read-only investigation), detection (alert rules), responder (alerts, blocks, limits). Default: all',
+    },
+    run: (a, f) => {
+      if (typeof f.profile === 'string') process.env.SECURENOW_MCP_PROFILE = f.profile;
+      require('./mcp/server');
+    },
   },
   version: {
     desc: 'Show CLI version',