securenow 8.15.0 → 8.17.0

package/NPM_README.md

@@ -339,6 +339,11 @@ verification plus SQL validation. See `node_modules/securenow/TELEMETRY-SQL.md`
 timestamp handling, privacy rules, templates, and the full test-to-production lifecycle.
 
 ```bash
+# Describe a detection in English (new in 8.16): SecureNow picks an instant rule (every request,
+# as it arrives) or a periodic one (SQL on a schedule), writes it from your app's real data,
+# checks it against that data, and creates it in test mode when you confirm
+npx securenow alerts rules from-text "a sign-in from a new address, then a password change within 5 minutes" --app <app-key>
+
 # Create a custom detection rule from your own SQL (new in 8.1)
 npx securenow alerts rules create \
   --name "Auth: magic-link brute force" \
@@ -347,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>
@@ -358,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
 
@@ -612,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

@@ -275,6 +275,11 @@ its fields were observed and `alerts rules validate` succeeds. Otherwise label i
 ```bash
 securenow alerts                             # list alert rules (default)
 securenow alerts rules                       # list alert rules (columns: Status, Applications, Schedule)
+securenow alerts rules from-text \           # describe a detection in English; checked draft, then create (test mode)
+  "one IP failing 10 sign-ins in 5 minutes" \
+  --app <key> [--env production]             #   picks instant or periodic; --instant/--periodic, --draft-only, --yes
+securenow alerts rules create --name "Secrets probe" --apps <key> \
+  --conditions '[{"field":"path","operator":"contains","value":"/.env"}]'   # an instant rule, no SQL
 securenow alerts rules validate \            # dry-run a candidate query BEFORE creating any rule
   --sql @rule.sql --app <key>                #   no rule id needed — auto-hosts on an existing (system) rule
 securenow alerts rules create \              # create a custom detection rule from inline SQL
@@ -289,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
@@ -306,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/monitor.js

@@ -342,6 +342,8 @@ async function notificationsList(args, flags) {
   const s = ui.spinner('Fetching notifications');
   try {
     const query = { limit: flags.limit || 20, page: flags.page || 1 };
+    if (flags.search) query.search = String(flags.search);
+    if (flags.severity) query.severity = String(flags.severity).toLowerCase();
     const data = await api.get('/notifications', { query });
     const notifications = data.notifications || [];
     const pagination = data.pagination;
@@ -354,7 +356,7 @@ async function notificationsList(args, flags) {
       ui.c.dim(n.id || n._id || ''),
       ui.statusBadge(n.read ? 'read' : 'unread'),
       ui.truncate(n.title || n.message || n.type || '', 50),
-      n.ip || '—',
+      n.primaryIp || n.ip || '—',
       n.severity ? ui.statusBadge(n.severity) : '—',
       ui.timeAgo(n.createdAt),
     ]);

package/cli/security.js

@@ -33,12 +33,28 @@ 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];
   if (sub === 'create' || sub === 'add') {
     return alertRuleCreate(args.slice(1), flags);
   }
+  if (sub === 'from-text' || sub === 'draft') {
+    return alertRuleFromText(args.slice(1), flags);
+  }
   if (sub === 'show') {
     return alertRuleShow(args.slice(1), flags);
   }
@@ -75,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');
   }
@@ -112,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);
     }
   }
@@ -125,8 +152,8 @@ async function alertRuleSetMode(args, flags, mode) {
 
 // Duplicate any rule (including a read-only system template) into a new CUSTOM rule you
 // own. System rules are view-only examples — fork one with this to enable / edit it. The
-// copy defaults to Disabled (opt in with --enable / --status active); SQL, instant.block,
-// schedule, scope, and mode are copied from the source.
+// copy defaults to Disabled (opt in with --enable / --status active) and to test mode
+// (--mode prod to arm it); SQL, instant.block, schedule and scope are copied from the source.
 async function alertRuleDuplicate(args, flags) {
   requireAuth();
   const id = args[0];
@@ -221,8 +248,11 @@ async function alertRuleCreate(args, flags) {
 
   const queryMappingId = flags['query-mapping-id'] || flags.queryMappingId;
   const sqlQuery = readSqlArg(flags);
-  if (!queryMappingId && !sqlQuery) {
-    ui.error('Provide the detection query: --sql <sql|@file|-> (or reuse one with --query-mapping-id <id>).');
+  const instantConditions = flags.conditions ? readJsonArg(flags.conditions, '--conditions') : null;
+  if (!queryMappingId && !sqlQuery && !instantConditions) {
+    ui.error('Provide the detection query: --sql <sql|@file|-> (or reuse one with --query-mapping-id <id>),');
+    ui.error('or an instant rule: --conditions \'[{"field":"path","operator":"contains","value":"/.env"}]\' [--match any|all].');
+    ui.info('Or describe it in English: securenow alerts rules from-text "<what to catch>" --app <key>');
     console.log(ui.c.dim('  Scope app keys in SQL with the __USER_APP_KEYS__ placeholder. The column differs by table:'));
     console.log(ui.c.dim("  traces: WHERE `resource_string_service$$name` IN (__USER_APP_KEYS__) AND timestamp >= now64(9) - INTERVAL 15 MINUTE"));
     console.log(ui.c.dim("  logs:   WHERE resources_string['service.name'] IN (__USER_APP_KEYS__) AND timestamp >= toUnixTimestamp64Nano(now64() - INTERVAL 15 MINUTE)"));
@@ -239,12 +269,22 @@ async function alertRuleCreate(args, flags) {
 
   const body = { name };
   if (flags.description) body.description = flags.description;
-  if (queryMappingId) body.queryMappingId = queryMappingId;
+  if (instantConditions) {
+    // An instant rule: checked against every incoming request, no SQL and no schedule.
+    body.executionMode = 'instant';
+    body.instant = {
+      enabled: true,
+      matchMode: flags.match === 'all' ? 'all' : 'any',
+      conditions: Array.isArray(instantConditions) ? instantConditions : [instantConditions],
+    };
+    const env = resolveEnvironment(flags);
+    if (env) body.instant.environments = String(env).split(',').map((e) => e.trim()).filter(Boolean);
+  } else if (queryMappingId) body.queryMappingId = queryMappingId;
   else body.sqlQuery = sqlQuery;
   if (flags.nlp || flags.text) body.nlpQuery = flags.nlp || flags.text;
   if (flags.category) body.category = flags.category;
   if (flags.severity) body.severity = String(flags.severity).toLowerCase();
-  if (flags['execution-mode']) body.executionMode = flags['execution-mode'];
+  if (flags['execution-mode'] && !instantConditions) body.executionMode = flags['execution-mode'];
 
   if (hasAll) {
     body.applicationsAll = true;
@@ -268,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) {
@@ -310,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) {
@@ -353,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;
@@ -441,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;
   }
 }
@@ -456,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'}`);
@@ -646,11 +697,188 @@ function readSqlArg(flags) {
   return text;
 }
 
+// JSON from a flag value, '@file' or '-' (stdin).
+function readJsonArg(raw, label) {
+  const text = String(raw);
+  const source = text === '-' ? fs.readFileSync(0, 'utf8') : text.startsWith('@') ? fs.readFileSync(text.slice(1), 'utf8') : text;
+  try {
+    return JSON.parse(source);
+  } catch (err) {
+    ui.error(`${label} is not valid JSON: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// ── English → alert rule ──
+// The API drafts the rule from the app's real data (instant or periodic), checks it against that
+// data, and returns the draft. Nothing is created until you confirm; new rules start in test mode.
+
+async function waitForDraft(draftId, s) {
+  for (let i = 0; i < 90; i++) {
+    await new Promise(r => setTimeout(r, 1500));
+    const result = await api.get(`/alert-rules/draft/${draftId}`);
+    if (result.status !== 'running') return result;
+    if (s && i === 6) s.update('Checking the draft against your data');
+  }
+  return { status: 'failed', error: 'The draft is still running after 2 minutes; try again' };
+}
+
+function draftCell(value) {
+  if (value == null) return '';
+  const text = typeof value === 'object' ? JSON.stringify(value) : String(value);
+  return text.length > 40 ? `${text.slice(0, 37)}…` : text;
+}
+
+function printDraft(result) {
+  const d = result.draft || {};
+  const check = result.check || {};
+  const kindLabel = d.kind === 'instant' ? ui.c.cyan('Instant rule') : ui.c.cyan('Periodic rule');
+  console.log('');
+  console.log(`  ${kindLabel} ${ui.c.dim('·')} ${d.severity || 'medium'} ${ui.c.dim('·')} ${d.category || 'custom'}`);
+  console.log(`  ${ui.c.bold(d.name || '')}`);
+  if (d.summary) console.log(`  ${d.summary}`);
+  if (d.whyThisKind) console.log(ui.c.dim(`  Why ${d.kind}: ${d.whyThisKind}`));
+  console.log('');
+  if (d.kind === 'instant') {
+    const conditions = d.instant?.conditions || [];
+    const envs = d.instant?.environments || [];
+    console.log(`  Watches   every request, as it arrives${envs.length ? `, in ${envs.join(', ')}` : ', in every environment'}`);
+    console.log(`  When      ${d.instant?.matchMode === 'all' ? 'all of' : 'any of'}`);
+    for (const c of conditions) console.log(`            ${c.field} ${ui.c.dim(c.operator)} ${c.value}`);
+  } else {
+    const parts = [d.schedule?.description || d.schedule?.cronExpression];
+    if (d.windowMinutes) parts.push(`window ${d.windowMinutes} min`);
+    if (d.threshold) parts.push(d.threshold);
+    console.log(`  Schedule  ${parts.filter(Boolean).join(ui.c.dim(' · '))}`);
+    console.log('  SQL');
+    for (const line of String(d.sqlQuery || '').split('\n')) console.log(ui.c.dim(`    ${line}`));
+  }
+  console.log('');
+  console.log(`  Check     ${check.note || ''}`);
+  const rows = check.rows || [];
+  if (rows.length) {
+    const cols = Object.keys(rows[0]).slice(0, 6);
+    console.log('');
+    ui.table(cols, rows.slice(0, 8).map((row) => cols.map((c) => draftCell(row[c]))));
+  }
+  for (const w of check.warnings || []) ui.warn(w);
+}
+
+function draftToCreateBody(result, flags) {
+  const d = result.draft || {};
+  const body = {
+    name: flags.name ? String(flags.name) : d.name,
+    description: d.summary || '',
+    nlpQuery: d.nlpQuery,
+    category: d.category,
+    severity: flags.severity ? String(flags.severity).toLowerCase() : d.severity,
+    applicationsAll: false,
+    applications: [result.applicationKey],
+    executionMode: d.executionMode,
+  };
+  if (d.executionMode === 'instant') body.instant = d.instant;
+  else {
+    body.sqlQuery = d.sqlQuery;
+    body.schedule = d.schedule;
+  }
+  if (flags['no-throttle']) body.throttle = { enabled: false, minutes: 0 };
+  else if (flags['throttle-minutes']) body.throttle = { enabled: true, minutes: Number(flags['throttle-minutes']) };
+  return body;
+}
+
+async function alertRuleFromText(args, flags) {
+  requireAuth();
+  const text = (args.join(' ').trim() || (typeof flags.text === 'string' ? flags.text : '')).trim();
+  const appKey = resolveApp(flags);
+  if (!text || !appKey) {
+    ui.error('Usage: securenow alerts rules from-text "<what the rule should catch>" --app <key> [--env <environment>]');
+    console.log(ui.c.dim('  [--instant | --periodic] [--name "..."] [--severity high] [--yes] [--draft-only] [--json]'));
+    console.log(ui.c.dim('  Example: securenow alerts rules from-text "one IP failing 10 sign-ins in 5 minutes" --app <key>'));
+    process.exit(1);
+  }
+
+  const body = { text, applicationKey: appKey };
+  const environment = resolveEnvironment(flags);
+  if (environment) body.environment = environment;
+  if (flags.instant || flags.kind === 'instant') body.kind = 'instant';
+  else if (flags.periodic || flags.kind === 'periodic') body.kind = 'periodic';
+
+  const s = ui.spinner('Drafting 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 rule');
+    throw err;
+  }
+  if (result.status !== 'complete') {
+    s.fail(result.error || 'Could not draft the rule');
+    process.exit(1);
+  }
+  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; }
+  }
+
+  const c = ui.spinner('Creating the rule');
+  let data;
+  try {
+    data = await api.post('/alert-rules', draftToCreateBody(result, flags));
+  } catch (err) {
+    c.fail('Failed to create the rule');
+    throw err;
+  }
+  const r = data.alertRule || data;
+  const id = r._id || r.id || '';
+  c.stop('Rule created');
+  if (flags.json) { ui.json({ draft: result.draft, check: result.check, alertRule: r }); return; }
+  console.log('');
+  ui.keyValue([
+    ['ID', id || '-'],
+    ['Name', r.name || '-'],
+    ['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) {
   requireAuth();
   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);
   }
 
@@ -848,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');
@@ -865,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');
@@ -883,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

@@ -240,7 +240,7 @@ const COMMANDS = {
     desc: 'Manage notifications',
     usage: 'securenow notifications <subcommand> [options]',
     sub: {
-      list: { desc: 'List notifications', flags: { limit: 'Max results', page: 'Page number' }, run: (a, f) => require('./cli/monitor').notificationsList(a, f) },
+      list: { desc: 'List notifications', flags: { limit: 'Max results', page: 'Page number', search: 'Only notifications whose title, description or IP contains this text (e.g. a rule name)', severity: 'critical | high | medium | low' }, run: (a, f) => require('./cli/monitor').notificationsList(a, f) },
       read: { desc: 'Mark notification as read', usage: 'securenow notifications read <id>', run: (a, f) => require('./cli/monitor').notificationsRead(a, f) },
       'read-all': { desc: 'Mark all as read', run: () => require('./cli/monitor').notificationsReadAll() },
       unread: { desc: 'Show unread count', run: () => require('./cli/monitor').notificationsUnread() },
@@ -311,19 +311,34 @@ const COMMANDS = {
     usage: 'securenow alerts <subcommand> [options]',
     sub: {
       rules: {
-        desc: 'Create, list, show, update, duplicate, promote/demote, set-sql, validate, delete, test, or tune alert rules',
-        usage: 'securenow alerts rules <list|create|show|update|duplicate|promote|demote|set-sql|validate|delete|test|dry-run-query|tune-query|exclusions> [options]',
+        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',
-          name: 'With create: rule name',
+          env: 'With from-text or create --conditions: only watch this environment (default: every environment)',
+          instant: 'With from-text: ask for an instant rule (every request, as it arrives)',
+          periodic: 'With from-text: ask for a periodic rule (SQL on a schedule)',
+          'draft-only': 'With from-text: show the checked draft, create nothing',
+          conditions: 'With create: instant-rule conditions as JSON, @file or - ([{"field":"path","operator":"contains","value":"/.env"}])',
+          match: 'With create --conditions: any (default) | all',
+          name: 'With create/from-text: rule name',
           description: 'With create: rule description',
           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',
           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',
@@ -331,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',
@@ -351,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

@@ -1378,6 +1378,71 @@ const TOOLS = [
       ...confirmSchema,
     }, ['text', 'confirm', 'reason']),
   },
+  {
+    name: 'securenow_alert_rule_draft',
+    title: 'Draft an Alert Rule From English',
+    description: 'Turn a detection idea in plain English into an alert rule draft for one app, checked against that app\'s data. It reads the app\'s real event types, attribute keys and routes, then picks the kind: instant (conditions checked on every incoming request, alerts within seconds; one request is enough evidence) or periodic (SQL run on a schedule: counts, thresholds, distinct counts, ratios, sequences, baselines, security events, app log lines). Periodic SQL is run once against the data; instant conditions are replayed over the app\'s last 2000 requests, so check.matches shows what would alert today (false positives). Nothing is saved: create it with securenow_alert_rule_create, passing the draft fields. Waits up to 120 seconds.',
+    scope: 'alerts:write',
+    readOnly: false,
+    confirm: true,
+    method: 'POST',
+    endpoint: '/alert-rules/draft',
+    bodyFields: ['text', 'applicationKey', 'environment', 'kind'],
+    poll: {
+      tool: 'securenow_alert_rule_draft_status',
+      idField: 'draftId',
+      pending: ['running'],
+      timeoutMs: 120000,
+      intervalMs: 2000,
+    },
+    inputSchema: objectSchema({
+      text: string('What the rule should catch, in plain English, e.g. "one IP failing 10 sign-ins in 5 minutes" or "anyone requesting /.env or /.git".'),
+      applicationKey: string('App key the rule watches; the draft is checked against its data.'),
+      environment: string('Only watch this environment (e.g. production). Omit to watch every environment.'),
+      kind: string('Optional: instant or periodic. Omit to let the drafter choose.'),
+      ...confirmSchema,
+    }, ['text', 'applicationKey', 'confirm', 'reason']),
+  },
+  {
+    name: 'securenow_alert_rule_draft_status',
+    title: 'Alert Rule Draft Result',
+    description: 'Get an alert rule draft started by securenow_alert_rule_draft: status (running, complete or failed), then the draft (kind, name, summary, SQL and schedule, or instant conditions) and the check against the app\'s data.',
+    scope: 'alerts:read',
+    readOnly: true,
+    method: 'GET',
+    endpoint: '/alert-rules/draft/:draftId',
+    pathParams: ['draftId'],
+    inputSchema: objectSchema({
+      draftId: string('Draft id from securenow_alert_rule_draft.'),
+    }, ['draftId']),
+  },
+  {
+    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 (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', 'allowNoIp'],
+    inputSchema: objectSchema({
+      name: string('Rule name.'),
+      description: string('What it catches, in a sentence.'),
+      nlpQuery: string('The detection idea in plain English (kept with the rule).'),
+      category: string('One word, e.g. authentication, scanning, exfiltration.'),
+      severity: string('low, medium, high or critical.'),
+      applications: { type: 'array', items: { type: 'string' }, description: 'App keys the rule watches.' },
+      applicationsAll: boolean('true watches every app instead of applications.'),
+      executionMode: string('scheduled (periodic SQL, the default) or instant (conditions on every request).'),
+      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 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']),
+  },
   {
     name: 'securenow_alert_rules_list',
     title: 'List Alert Rules',
@@ -1472,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,
@@ -1768,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,
@@ -1779,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']),
   },
@@ -1816,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.15.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",