securenow 8.16.0 → 8.18.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

@@ -28,6 +28,22 @@ npx -p securenow securenow-mcp
 
 The MCP server reads admin/control-plane auth from `.securenow/admin.json` and SDK runtime app credentials from `.securenow/runtime.json`, with legacy `.securenow/credentials.json` still supported. Admin/global tools use admin auth; runtime-scoped read tools can use the runtime API key where its scopes allow it. Write tools require `confirm:true` plus a reason.
 
+**For agents, prefer the hosted MCP** (`https://api.securenow.ai/mcp`, OAuth sign-in, no install and always the current tools). With the local stdio server, warm the package once so the first connection doesn't time out on the download (`npx -y securenow@latest --version`), and give the client a longer connect timeout (Claude Code: `MCP_TIMEOUT=120000`).
+
+**Tool profiles** (stdio server): `securenow mcp --profile <name>` (or `SECURENOW_MCP_PROFILE=<name>`) serves only the tools one job needs, so the agent carries less context. Every profile keeps `securenow_auth_status`, `securenow_apps_list` and `securenow_apps_info`; calling a tool outside the profile returns an error naming the profile.
+
+| Profile | Tools | What's in it |
+|---|---|---|
+| `all` (default) | 112 | everything |
+| `investigator` | 58 | every read-only tool, plus forensics question/chat/confirm |
+| `detection` | 47 | `securenow_alert_rule*` (draft, create, test, run, runs, explain, versions, exclusions, request promotion…), traces, logs, forensics, IP intelligence, notifications list/get |
+| `responder` | 77 | notifications, human queue, alert reviews, blocklist, allowlist, trusted IPs, rate limits, challenges, automations, firewall, IP intelligence, plus rule get/runs/explain and traces/logs for context |
+
+```bash
+claude mcp add securenow-investigator -- npx -y securenow@latest mcp --profile investigator
+codex mcp add securenow-detection -- npx securenow mcp --profile detection
+```
+
 ### Authenticate
 
 ```bash
@@ -213,8 +229,11 @@ securenow traces analyze <traceId> --env production   # AI-powered trace analysi
 securenow logs [--app <key>] [--env production] [--limit N] [--minutes M] [--level error|warn|info]
 securenow logs list --app my-app --env production --minutes 30 --level error
 securenow logs trace <traceId> --env production       # logs correlated to a specific trace
+securenow logs errors --app my-app --since 6h [--warn]  # what is failing: error lines grouped by message (ids/numbers normalized), counts, first/last seen, sample traces
 ```
 
+For "what's broken right now?", start with `logs errors` (MCP `securenow_logs_errors`): one call returns the distinct failures, not hundreds of raw lines.
+
 ### Notifications
 
 ```bash
@@ -294,7 +313,11 @@ 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 change <id> "raise the threshold to 20"   # rewrite a rule from English: checked, shown before/after, applied as a new version
+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 +334,15 @@ 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).
+
+**Agents don't promote rules; they ask.** When a test-mode rule has proved itself, an agent runs `securenow alerts rules request-promotion <id> --reason "..." --evidence "..."` (MCP `securenow_alert_rule_request_promotion`). A person sees it on the rules page or with `securenow human promotions` and runs `securenow human approve-promotion <request-id> --yes` (the rule goes to prod, recorded as a rule version naming the approver) or `deny-promotion <request-id> --reason "..."`. API keys and MCP tokens can ask but not decide.
 
 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/human.js

@@ -569,6 +569,66 @@ async function work(args, flags) {
   console.log('');
 }
 
+// ── Rule promotion requests ──
+// Agents create rules in test mode and ask a person to promote them. A person approves (the rule
+// goes to prod, recorded as a rule version) or denies here or on the dashboard's rules page.
+
+async function promotions(args, flags) {
+  requireAuth();
+  const status = typeof flags.status === 'string' ? flags.status : 'pending';
+  const s = ui.spinner('Fetching promotion requests');
+  let data;
+  try {
+    data = await api.get('/alert-rules/promotion-requests', { query: { status, limit: flags.limit || 50 } });
+    s.stop(`Found ${(data.requests || []).length} ${status === 'all' ? '' : `${status} `}request${(data.requests || []).length === 1 ? '' : 's'}`);
+  } catch (err) {
+    s.fail('Failed to fetch promotion requests');
+    throw err;
+  }
+  if (flags.json) { ui.json(data); return; }
+  const requests = data.requests || [];
+  if (requests.length === 0) { ui.info('No promotion requests waiting.'); return; }
+  console.log('');
+  for (const r of requests) {
+    console.log(`  ${ui.c.bold(r.ruleName || r.ruleId)}  ${ui.c.dim(r.id)}  ${r.status}`);
+    console.log(`    asked by ${r.requestedBy?.name || r.requestedBy?.kind || 'unknown'} ${ui.timeAgo(r.createdAt)}: ${r.reason}`);
+    if (r.evidence) console.log(ui.c.dim(`    evidence: ${ui.truncate(String(r.evidence).replace(/\s+/g, ' '), 160)}`));
+    if (r.status !== 'pending') console.log(ui.c.dim(`    ${r.status} by ${r.decidedByName || 'someone'}${r.decisionNote ? `: ${r.decisionNote}` : ''}`));
+  }
+  console.log('');
+  if (requests.some((r) => r.status === 'pending')) {
+    console.log(ui.c.dim('  Approve: securenow human approve-promotion <id> --yes [--note "..."]   Deny: securenow human deny-promotion <id> --reason "..."'));
+    console.log(ui.c.dim('  Before approving, check what it would arm: securenow alerts rules show <ruleId> and securenow alerts rules runs <ruleId>'));
+    console.log('');
+  }
+}
+
+async function decidePromotion(args, flags, decision) {
+  requireAuth();
+  const id = args[0];
+  const verb = decision === 'approve' ? 'approve-promotion' : 'deny-promotion';
+  if (!id) {
+    ui.error(`Usage: securenow human ${verb} <request-id> ${decision === 'approve' ? '--yes [--note "..."]' : '--reason "..."'}`);
+    process.exit(1);
+  }
+  if (decision === 'approve' && !flags.yes && !flags.force) {
+    ui.warn('Approving moves the rule to prod: its instant block, matching automations and the AI pipeline can act on its alerts.');
+    const ok = await ui.confirm('Approve this promotion?');
+    if (!ok) { ui.info('Cancelled'); return; }
+  }
+  const note = flags.note || flags.reason || '';
+  const s = ui.spinner(decision === 'approve' ? 'Approving' : 'Denying');
+  try {
+    const data = await api.post(`/alert-rules/promotion-requests/${id}/${decision}`, { note });
+    s.stop(decision === 'approve' ? `Approved: "${data.alertRule?.name || data.request?.ruleName}" is in prod` : 'Denied: the rule stays in test mode');
+    for (const warning of data.warnings || []) ui.warn(warning);
+    if (flags.json) ui.json(data);
+  } catch (err) {
+    s.fail(`Failed to ${decision} the promotion`);
+    throw err;
+  }
+}
+
 module.exports = {
   list,
   show,
@@ -578,4 +638,7 @@ module.exports = {
   report,
   prompt,
   work,
+  promotions,
+  approvePromotion: (args, flags) => decidePromotion(args, flags, 'approve'),
+  denyPromotion: (args, flags) => decidePromotion(args, flags, 'deny'),
 };

package/cli/monitor.js

@@ -294,6 +294,48 @@ async function logsList(args, flags) {
   }
 }
 
+// Error lines grouped by message (ids and numbers normalized): what is failing, how often, since when.
+async function logsErrors(args, flags) {
+  requireAuth();
+  const appKey = resolveApp(flags);
+  if (!appKey) {
+    ui.error('No app specified. Use --app <key> or set a default.');
+    process.exit(1);
+  }
+  const query = { appKeys: appKey, since: flags.since || '1h', limit: flags.limit || 20 };
+  if (flags.warn) query.includeWarn = 'true';
+  addEnvironment(query, flags);
+  const s = ui.spinner('Grouping error logs');
+  let data;
+  try {
+    data = await api.get('/logs/errors', { query });
+    const kind = data.includeWarn ? 'error/warning' : 'error';
+    s.stop(`${data.total} ${kind} line${data.total === 1 ? '' : 's'} in ${data.distinct} group${data.distinct === 1 ? '' : 's'}`);
+  } catch (err) {
+    s.fail('Failed to summarize error logs');
+    throw err;
+  }
+  if (flags.json) { ui.json(data); return; }
+  const groups = data.groups || [];
+  console.log('');
+  if (groups.length === 0) { ui.info(`No ${data.includeWarn ? 'warnings or errors' : 'errors'} since ${data.window?.from}.`); return; }
+  for (const g of groups) {
+    const last = g.lastSeen ? ui.timeAgo(g.lastSeen) : '';
+    console.log(`  ${ui.c.red(String(g.occurrences).padStart(5))}  ${ui.truncate(String(g.sample || g.signature).replace(/\s+/g, ' '), 110)}`);
+    const meta = [
+      (g.severities || []).join('/'),
+      (g.environments || []).join(', '),
+      g.exceptionType,
+      last && `last ${last}`,
+      g.sampleTraceIds?.[0] && `trace ${g.sampleTraceIds[0]}`,
+    ].filter(Boolean).join(' · ');
+    if (meta) console.log(ui.c.dim(`         ${meta}`));
+  }
+  console.log('');
+  console.log(ui.c.dim('  A group\'s requests: securenow logs trace <traceId>   Ask why: securenow forensics chat --app <key> "<question>"'));
+  console.log('');
+}
+
 async function logsTrace(args, flags) {
   requireAuth();
   const traceId = args[0];
@@ -499,6 +541,7 @@ module.exports = {
   tracesAnalyze,
   logsList,
   logsTrace,
+  logsErrors,
   notificationsList,
   notificationsRead,
   notificationsReadAll,