securenow 8.16.0 → 8.17.0

package/NPM_README.md

@@ -352,6 +352,11 @@ npx securenow alerts rules create \
   --severity high \
   --nlp "single IP flooding /api/auth/signin or /api/auth/callback"
 
+# What each run did, run one now, and why a rule didn't alert on an address (new in 8.17)
+npx securenow alerts rules runs <rule-id>
+npx securenow alerts rules run <rule-id>
+npx securenow alerts rules why <rule-id> --ip 203.0.113.50 --since 2h
+
 # View / manage alert rules, channels, and history
 npx securenow alerts rules
 npx securenow alerts rules show <rule-id>
@@ -363,7 +368,7 @@ npx securenow alerts channels
 npx securenow alerts history --limit 20
 ```
 
-Your detection SQL scopes app keys with the `__USER_APP_KEYS__` placeholder and selects an `ip` column for per-IP aggregation and remediation. SecureNow stores the query, runs it on the rule's schedule (default every 15 min), and routes matches to your in-app channel (override with `--channel <id>`). Requires an API key with `alerts:write`.
+Your detection SQL scopes app keys with the `__USER_APP_KEYS__` placeholder and selects an `ip` column for per-IP aggregation and remediation (SQL without one is refused: it would never notify). SecureNow stores the query, runs it once right away and then on the rule's schedule (default every 15 min), and routes matches to your in-app channel (override with `--channel <id>`). The throttle sends one alert per address every 15 minutes by default; other addresses still alert. Requires an API key with `alerts:write`.
 
 ### IP Intelligence & Blocklist
 
@@ -617,6 +622,8 @@ npx securenow logs --json --level error | jq '.logs'
 | | `alerts rules` | List rules (status, apps, schedule) |
 | | `alerts rules show <id>` | Rule detail |
 | | `alerts rules update <id> --applications-all` / `--apps k1,k2` | Application scope |
+| | `alerts rules runs <id>` / `run <id>` | Run history (outcome of each run) / run a periodic rule now |
+| | `alerts rules why <id> --ip <ip>` | Why the rule did or didn't alert on an address |
 | | `alerts channels` | Alert channels |
 | | `alerts history` | Alert history |
 | **Investigate** | `ip <addr>` | IP intelligence |

package/SKILL-CLI.md

@@ -294,7 +294,10 @@ securenow alerts rules set-sql <id> --sql @new.sql   # replace a CUSTOM rule's S
 securenow alerts rules delete <id> --yes    # delete a custom rule (system rules: disable instead)
 securenow alerts rules update <id> --applications-all   # all current & future apps
 securenow alerts rules update <id> --apps key1,key2     # explicit app keys only
-securenow alerts rules test <id> --mode dry_run --wait  # validate an existing rule's query
+securenow alerts rules test <id> --wait       # dry-run an existing rule's query (default; --mode live inserts 6 synthetic attack requests)
+securenow alerts rules runs <id> [--since 1h] # what each run saw and why it did or didn't notify (+ next scheduled run)
+securenow alerts rules run <id>               # run a periodic rule now and print the run (--no-wait to just queue it)
+securenow alerts rules why <id> --ip <ip> [--since 1h]   # why the rule did or didn't alert on one address: verdict + findings
 securenow alerts rules dry-run-query <id> --sql @candidate.sql --app <key> --wait   # candidate test against a specific host rule
 securenow alerts rules tune-query <id> --sql @candidate.sql --reason "Preserve exploit detector, remove benign broad match" --apply-globally --yes
 securenow alerts rules exclusions <id> list              # embedded rule exclusions
@@ -311,7 +314,13 @@ right tenant-scope column per table: logs (`signoz_logs.distributed_logs_v2`) us
 `resources_string['service.name'] IN (__USER_APP_KEYS__)`, traces
 (`signoz_traces.distributed_signoz_index_v3`) use `` `resource_string_service$$name` IN (__USER_APP_KEYS__) ``.
 
-`alerts rules create` flags: `--name` (required); one of `--sql <sql|@file|->` or `--query-mapping-id <id>`; one of `--apps k1,k2` or `--applications-all`; optional `--description`, `--nlp` (plain-English intent), `--category`, `--severity critical|high|medium|low`, `--schedule <cron>` (default `*/15 * * * *`), `--throttle-minutes N` / `--no-throttle`, `--execution-mode scheduled|instant|hybrid`, `--channel id1,id2` (defaults to your in-app SecureNow channel). Detection SQL must scope app keys via the `__USER_APP_KEYS__` placeholder and select an `ip` column for per-IP aggregation/remediation. Requires `alerts:write`.
+`alerts rules create` flags: `--name` (required); one of `--sql <sql|@file|->` or `--query-mapping-id <id>`; one of `--apps k1,k2` or `--applications-all`; optional `--description`, `--nlp` (plain-English intent), `--category`, `--severity critical|high|medium|low`, `--schedule <cron>` (default `*/15 * * * *`), `--throttle-minutes N` / `--no-throttle`, `--execution-mode scheduled|instant|hybrid`, `--channel id1,id2` (defaults to your in-app SecureNow channel). Detection SQL must scope app keys via the `__USER_APP_KEYS__` placeholder and select an `ip` column for per-IP aggregation/remediation: create and set-sql refuse SQL with no ip column (it would never notify) unless `--allow-no-ip`. A new periodic rule runs once right away. Requires `alerts:write`.
+
+**Throttle = one alert per rule AND address** (8.17): an address alerted on within the window (default 15 min) is left out of the next runs' notifications, and other addresses still alert. Alert storms keep one alert per rule per window.
+
+**When a rule stays quiet,** don't guess: `alerts rules runs <id>` shows every run's outcome — `notified`, `no_rows`, `throttled`, `suppressed_blocked` (already blocked, often by another rule's instant block), `suppressed_trusted`, `no_ip` (rows without an ip column), `storm`, `auto_resolved` (dismissed by an exclusion, trusted IP or verified bot), `skipped`, `error` — and which addresses were left out and why. `alerts rules why <id> --ip <ip>` ends in a verdict such as "Detected at 15:06:31 but not notified: 203.0.113.50 was already blocked by instant rule X". `--yes` on `from-text` refuses to create a rule whose check matches your data right now (it would alert at once, usually a bad baseline); review the rows, then `--yes --force` if they are a real attack.
+
+MCP parity for quiet rules: `securenow_alert_rule_runs` (run history), `securenow_alert_rule_run_now` (write, confirm) and `securenow_alert_rule_explain` (`ip`, `since`: verdict + findings).
 
 MCP parity for noisy alert-rule reviews:
 

package/cli/client.js

@@ -56,13 +56,16 @@ function request(method, endpoint, { body, query, token, raw } = {}) {
         }
         if (res.statusCode === 403) {
           const msg = parsed?.error || parsed?.message || 'Access denied';
-          reject(new CLIError(`${msg}. Admin auth is connected, but this user/plan may lack permission for this control-plane operation. Runtime app connection is unrelated.`, 403));
+          const err = new CLIError(`${msg}. Admin auth is connected, but this user/plan may lack permission for this control-plane operation. Runtime app connection is unrelated.`, 403);
+          if (parsed?.code) err.code = parsed.code;
+          reject(err);
           return;
         }
         if (res.statusCode >= 400) {
           const msg = parsed?.error || parsed?.message || `Request failed (HTTP ${res.statusCode})`;
           const details = parsed?.details || parsed?.unauthorizedKeys;
           const err = new CLIError(details ? `${msg} — ${details}` : msg, res.statusCode);
+          if (parsed?.code) err.code = parsed.code;
           reject(err);
           return;
         }

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];
@@ -78,6 +91,15 @@ 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 === '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 +137,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 +308,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 +351,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 +396,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;
@@ -457,6 +486,10 @@ async function alertRuleUpdate(args, flags) {
     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 +505,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 +818,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 +865,12 @@ 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>`));
 }
 
 async function alertRuleTest(args, flags) {
@@ -824,6 +878,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 +1076,170 @@ 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('');
+}
+
 // ── 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 +1255,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 +1273,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

@@ -311,9 +311,12 @@ 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 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',
         flags: {
           json: 'Output as JSON',
           env: 'With from-text or create --conditions: only watch this environment (default: every environment)',
@@ -329,8 +332,13 @@ const COMMANDS = {
           category: 'With create: query category (default: custom)',
           severity: 'With create: 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 +346,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',
@@ -358,7 +366,7 @@ const COMMANDS = {
           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),
       },

package/mcp/catalog.js

@@ -1419,13 +1419,13 @@ const TOOLS = [
   {
     name: 'securenow_alert_rule_create',
     title: 'Create Alert Rule (Test Mode)',
-    description: 'Create an alert rule. It always starts in test mode: it alerts, but nothing blocks, rate-limits or acts on its alerts until a person promotes it. Instant rule: executionMode "instant" plus instant {matchMode: any|all, conditions: [{field: path|method|user_agent|status_code|request_body|request_headers|client_ip|host, operator, value}]}. Periodic rule: sqlQuery plus schedule {cronExpression}; the SQL must scope every table with the __USER_APP_KEYS__ placeholder, bound time on every table read, and return a column named ip (rows without an ip never alert). Easiest path: securenow_alert_rule_draft, then pass its draft fields here. Write action; requires confirmation.',
+    description: 'Create an alert rule. It always starts in test mode: it alerts, but nothing blocks, rate-limits or acts on its alerts until a person promotes it. Instant rule: executionMode "instant" plus instant {matchMode: any|all, conditions: [{field: path|method|user_agent|status_code|request_body|request_headers|client_ip|host, operator, value}]}. Periodic rule: sqlQuery plus schedule {cronExpression}; the SQL must scope every table with the __USER_APP_KEYS__ placeholder, bound time on every table read, and return a column named ip (the API refuses SQL with no ip column, since it would never alert, unless allowNoIp). A periodic rule runs once right away (firstRunQueued); see securenow_alert_rule_runs. Easiest path: securenow_alert_rule_draft, then pass its draft fields here. Write action; requires confirmation.',
     scope: 'alerts:write',
     readOnly: false,
     confirm: true,
     method: 'POST',
     endpoint: '/alert-rules',
-    bodyFields: ['name', 'description', 'nlpQuery', 'category', 'severity', 'applications', 'applicationsAll', 'executionMode', 'sqlQuery', 'schedule', 'instant', 'throttle'],
+    bodyFields: ['name', 'description', 'nlpQuery', 'category', 'severity', 'applications', 'applicationsAll', 'executionMode', 'sqlQuery', 'schedule', 'instant', 'throttle', 'allowNoIp'],
     inputSchema: objectSchema({
       name: string('Rule name.'),
       description: string('What it catches, in a sentence.'),
@@ -1438,7 +1438,8 @@ const TOOLS = [
       sqlQuery: string('Periodic rules: the detection SELECT.'),
       schedule: { type: 'object', additionalProperties: true, description: 'Periodic rules: {cronExpression: "* * * * *", description: "Every minute"}. Default every 15 minutes.' },
       instant: { type: 'object', additionalProperties: true, description: 'Instant rules: {matchMode: "any" | "all", conditions: [{field, operator, value}], environments: ["staging"] (optional; omit to watch every environment)}.' },
-      throttle: { type: 'object', additionalProperties: true, description: 'Optional {enabled: true, minutes: 15}: one alert per rule per window.' },
+      throttle: { type: 'object', additionalProperties: true, description: 'Optional {enabled: true, minutes: 15}: one alert per address every N minutes (other addresses still alert).' },
+      allowNoIp: boolean('Periodic rules: save SQL that returns no ip column anyway (it will never notify). Default false.'),
       ...confirmSchema,
     }, ['name', 'confirm', 'reason']),
   },
@@ -1536,9 +1537,9 @@ const TOOLS = [
       applicationsAll: boolean('Scope rule to all applications.'),
       applications: arrayOfStrings('Application keys when applicationsAll is false.'),
       schedule: { type: 'object', additionalProperties: true, description: 'Schedule patch.' },
-      throttle: { type: 'object', additionalProperties: true, description: 'Throttle patch.' },
+      throttle: { type: 'object', additionalProperties: true, description: 'Throttle patch {enabled, minutes}: one alert per address every N minutes.' },
       alertChannelIds: arrayOfStrings('Alert channel ids.'),
-      reviewAction: string('Rule review action, e.g. keep_active or saved_new_version.'),
+      reviewAction: string('Rule review action: keep_active (keep it running and stop auto-pausing it) or tuned_version (the rule was tuned; resume it).'),
       reviewNote: string('Review note.'),
       reviewNotificationId: string('Notification id tied to this review.'),
       ...confirmSchema,
@@ -1832,7 +1833,7 @@ const TOOLS = [
   {
     name: 'securenow_alert_rule_test',
     title: 'Test Alert Rule',
-    description: 'Start an alert rule test. Pass mode "dry_run" for a read-only query run; "live" (the server default when mode is omitted) inserts synthetic spans into the app\'s telemetry.',
+    description: 'Start an alert rule test. By default (mode "dry_run") it runs the rule\'s query once on the app\'s real data and inserts nothing. Mode "live" first inserts 6 synthetic attack requests into the app\'s telemetry; only ask for it explicitly.',
     scope: 'alerts:write',
     readOnly: false,
     confirm: true,
@@ -1843,7 +1844,7 @@ const TOOLS = [
     inputSchema: objectSchema({
       id: string('Alert rule id.'),
       applicationKey: string('Application key to test.'),
-      mode: string('dry_run (read-only, recommended) or live (inserts synthetic spans).'),
+      mode: string('dry_run (default, read-only) or live (inserts 6 synthetic attack requests).'),
       ...confirmSchema,
     }, ['id', 'confirm', 'reason']),
   },
@@ -1880,6 +1881,53 @@ const TOOLS = [
       testId: string('Alert rule test id.'),
     }, ['id', 'testId']),
   },
+  {
+    name: 'securenow_alert_rule_runs',
+    title: 'List Alert Rule Runs',
+    description: 'A rule\'s recent runs, newest first: when it ran (schedule, manual, create or instant trigger), what it returned (rows, addresses), and the outcome: notified, no_rows, throttled (address alerted on within the throttle window), suppressed_blocked (already blocked), suppressed_trusted, no_ip (rows without an address), storm, auto_resolved (dismissed by an exclusion, trusted IP or verified bot), skipped or error. suppressedIps says which addresses were left out and why. Also nextRunAt for periodic rules. Quiet runs are kept 2 days, the rest 14.',
+    scope: 'alerts:read',
+    readOnly: true,
+    method: 'GET',
+    endpoint: '/alert-rules/:id/runs',
+    pathParams: ['id'],
+    queryFields: ['limit', 'since'],
+    inputSchema: objectSchema({
+      id: string('Alert rule id.'),
+      limit: number('How many runs (default 50, max 200).', { minimum: 1, maximum: 200 }),
+      since: string('Only runs since then: 30m, 1h, 2d or an ISO date.'),
+    }, ['id']),
+  },
+  {
+    name: 'securenow_alert_rule_run_now',
+    title: 'Run Alert Rule Now',
+    description: 'Run a periodic (scheduled) rule once now, outside its schedule. It can notify like a scheduled run (test-mode rules alert only). The run appears in securenow_alert_rule_runs within seconds with trigger "manual". Instant rules have nothing to run (they check every request); use securenow_alert_rule_explain instead. Write action; requires confirmation.',
+    scope: 'alerts:write',
+    readOnly: false,
+    confirm: true,
+    method: 'POST',
+    endpoint: '/alert-rules/:id/run',
+    pathParams: ['id'],
+    inputSchema: objectSchema({
+      id: string('Alert rule id (an active periodic rule).'),
+      ...confirmSchema,
+    }, ['id', 'confirm', 'reason']),
+  },
+  {
+    name: 'securenow_alert_rule_explain',
+    title: 'Explain Why a Rule Did or Didn\'t Alert',
+    description: 'Why did (or didn\'t) this rule alert on this address? Checks, in a time window: the rule\'s status, mode, apps and environments; its runs and what each did with the address (notified, throttled, already blocked, trusted, dismissed); the per-address throttle; blocks on the address and the rule that made them; trusted and allowlist entries; notifications; and the address\'s requests, replayed through an instant rule\'s conditions. Returns ordered findings and a one-line verdict, e.g. "Detected at 15:06:31 but not notified: 203.0.113.50 was already blocked by instant rule X".',
+    scope: 'alerts:read',
+    readOnly: true,
+    method: 'GET',
+    endpoint: '/alert-rules/:id/explain',
+    pathParams: ['id'],
+    queryFields: ['ip', 'since'],
+    inputSchema: objectSchema({
+      id: string('Alert rule id.'),
+      ip: string('The address to explain (IPv4 or IPv6).'),
+      since: string('Window start: 30m, 1h (default), 2d or an ISO date; at most 7 days.'),
+    }, ['id', 'ip']),
+  },
   {
     name: 'securenow_alert_rule_exclusions_list',
     title: 'List Alert Rule Exclusions',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securenow",
-  "version": "8.16.0",
+  "version": "8.17.0",
   "mcpName": "ai.securenow/securenow",
   "description": "OpenTelemetry instrumentation for Node.js, Next.js, and Nuxt - Send traces and logs to any OTLP-compatible backend",
   "type": "commonjs",