securenow 8.3.0 → 8.5.0

package/NPM_README.md

@@ -263,9 +263,13 @@ npx securenow notifications read-all
 
 ```js
 const securenow = require('securenow/sessions');
-app.use(securenow.guard());   // auto-detects NextAuth/connect.sid/JWT sessions; rejects revoked ones (401)
+// One line: emits session.seen (feeds impossible-travel / concurrent-session
+// detection) AND rejects revoked sessions. Auto-detects NextAuth/connect.sid/JWT.
+app.use(securenow.guard());
 // ...or check manually:
 if (securenow.isRevoked({ sessionId, userId })) return res.status(401).send('re-auth');
+// ...or emit-only (detection without enforcement):
+app.use(securenow.capture());
 ```
 
 Revoke from the CLI (the SDK enforces within ~seconds, outbound-only, fail-open):

package/SKILL-CLI.md

@@ -255,23 +255,37 @@ Write tools still require `confirm:true` plus a reason. False positives should s
 ```bash
 securenow alerts                             # list alert rules (default)
 securenow alerts rules                       # list alert rules (columns: Status, Applications, Schedule)
-securenow alerts rules create \              # NEW: create a custom detection rule from inline 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
   --name "Auth: magic-link brute force" \
   --sql @rule.sql \                          #   SQL, @file, or - for stdin; scope apps with __USER_APP_KEYS__
   --apps key1,key2 \                         #   or --applications-all
   --severity high --schedule "*/15 * * * *" \
   --nlp "single IP flooding /api/auth/signin or /api/auth/callback"
+                                             #   create auto dry-runs + rolls back (deletes) on query failure; --no-validate to skip
 securenow alerts rules show <id>            # one rule; JSON: --json
+securenow alerts rules set-sql <id> --sql @new.sql   # replace a CUSTOM rule's SQL in place (alias: update <id> --sql)
+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 a rule query
-securenow alerts rules dry-run-query <id> --sql @candidate.sql --app <key> --wait
+securenow alerts rules test <id> --mode dry_run --wait  # validate an existing rule's query
+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
 securenow alerts channels                    # list alert channels (Slack, email, etc.)
 securenow alerts history [--limit N]         # past triggered alerts
 ```
 
+**Authoring loop that won't strand a broken rule:** `validate --sql @rule.sql --app <key>`
+(dry-run before anything exists) → `create …` (which itself dry-runs and auto-rolls-back on
+failure) → if you later need to fix it, `set-sql <id> --sql @rule.sql` (custom rules) or
+`delete <id>`. Detection `.sql` files may start with `--`/`/* */` comments. Custom-rule SQL is
+editable; **system**-rule SQL changes go through `tune-query … --apply-globally`. Pick the
+right tenant-scope column per table: logs (`signoz_logs.distributed_logs_v2`) use
+`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`.
 
 MCP parity for noisy alert-rule reviews:

package/cli/security.js

@@ -45,10 +45,16 @@ async function alertRulesRoute(args, flags) {
   if (sub === 'update') {
     return alertRuleUpdate(args.slice(1), flags);
   }
+  if (sub === 'set-sql' || sub === 'edit-sql') {
+    return alertRuleSetSql(args.slice(1), flags);
+  }
+  if (sub === 'delete' || sub === 'rm' || sub === 'remove') {
+    return alertRuleDelete(args.slice(1), flags);
+  }
   if (sub === 'test') {
     return alertRuleTest(args.slice(1), flags);
   }
-  if (sub === 'dry-run-query' || sub === 'candidate-test') {
+  if (sub === 'dry-run-query' || sub === 'candidate-test' || sub === 'validate') {
     return alertRuleCandidateTest(args.slice(1), flags);
   }
   if (sub === 'tune-query' || sub === 'query-update') {
@@ -156,14 +162,35 @@ async function alertRuleCreate(args, flags) {
   }
 
   const s = ui.spinner('Creating alert rule');
+  let createdId = null;
   try {
     const data = await api.post('/alert-rules', body);
     const r = data.alertRule || data;
+    createdId = r._id || r.id || null;
     s.stop('Alert rule created');
+
+    // Transactional safety: `create` only runs scope/safety validation, not a real
+    // query execution — so a query that is valid-but-wrong (e.g. an unknown column)
+    // is accepted and would silently never fire. Custom-rule SQL also can't be
+    // patched via the API, so a broken rule would be stuck. We therefore dry-run the
+    // new scheduled rule and roll it back (delete) on a hard query failure, unless
+    // --no-validate is passed. A "complete" dry-run with 0 rows is healthy, not a failure.
+    const scheduled = r.executionMode !== 'instant' && r.schedule?.enabled !== false;
+    if (createdId && scheduled && !flags['no-validate']) {
+      const v = await validateRuleById(createdId, flags);
+      if (v && v.status === 'failed') {
+        const rolledBack = await api.delete(`/alert-rules/${createdId}`).then(() => true).catch(() => false);
+        ui.error(`Rule query failed validation and was ${rolledBack ? 'rolled back (deleted)' : 'left in place (auto-delete failed — remove it manually)'}:`);
+        ui.error(`  ${v.error || 'unknown query error'}`);
+        ui.info('Fix the SQL and re-create, or validate first: securenow alerts rules validate --sql @rule.sql --app <key>');
+        process.exit(1);
+      }
+    }
+
     if (flags.json) { ui.json(data); return; }
     console.log('');
     ui.keyValue([
-      ['ID', r._id || r.id || '-'],
+      ['ID', createdId || '-'],
       ['Name', r.name || '-'],
       ['Status', r.status || '-'],
       ['Mode', r.executionMode || 'scheduled'],
@@ -172,9 +199,10 @@ async function alertRuleCreate(args, flags) {
       ['Schedule', r.schedule?.enabled === false ? 'disabled' : (r.schedule?.description || r.schedule?.cronExpression || '-')],
       ['Throttle', r.throttle?.enabled ? `${r.throttle.minutes} min` : 'off'],
       ['Query', r.queryMappingId?.name || r.queryMappingId || '-'],
+      ['Validation', flags['no-validate'] ? 'skipped' : 'dry-run clean'],
     ]);
     console.log('');
-    ui.success(`Created. View it with: securenow alerts rules show ${r._id || r.id}`);
+    ui.success(`Created. View it with: securenow alerts rules show ${createdId}`);
   } catch (err) {
     s.fail('Failed to create alert rule');
     throw err;
@@ -223,6 +251,11 @@ async function alertRuleShow(args, flags) {
 
 async function alertRuleUpdate(args, flags) {
   requireAuth();
+  // `update <id> --sql ...` is an alias for set-sql so SQL edits and scope edits
+  // share one verb. set-sql handles its own validation/feedback.
+  if (flags.sql || flags.query || flags.file) {
+    return alertRuleSetSql(args, flags);
+  }
   const id = args[0];
   if (!id) {
     ui.error('Usage: securenow alerts rules update <rule-id> (--applications-all | --apps <k1,k2>)');
@@ -280,6 +313,88 @@ async function alertRuleUpdate(args, flags) {
   }
 }
 
+async function alertRuleSetSql(args, flags) {
+  requireAuth();
+  const id = args[0];
+  const sqlQuery = readSqlArg(flags);
+  if (!id || !sqlQuery) {
+    ui.error('Usage: securenow alerts rules set-sql <rule-id> --sql <sql|@file|-> [--nlp "intent"] [--no-validate]');
+    process.exit(1);
+  }
+  const body = { sqlQuery };
+  if (flags.nlp || flags.text) body.nlpQuery = flags.nlp || flags.text;
+  if (flags.category) body.category = flags.category;
+
+  const s = ui.spinner('Updating rule SQL');
+  try {
+    const data = await api.put(`/alert-rules/${id}`, body);
+    s.stop('Rule SQL updated');
+    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'}`);
+      ui.info('Fix the SQL and run set-sql again, or delete the rule with: securenow alerts rules delete ' + id);
+    } else if (ok) {
+      ui.success('Saved and dry-run clean.');
+    }
+    if (flags.json) ui.json(data);
+  } catch (err) {
+    s.fail('Failed to update rule SQL');
+    throw err;
+  }
+}
+
+async function alertRuleDelete(args, flags) {
+  requireAuth();
+  const id = args[0];
+  if (!id) {
+    ui.error('Usage: securenow alerts rules delete <rule-id> [--yes]');
+    process.exit(1);
+  }
+  if (!flags.force && !flags.yes) {
+    const ok = await ui.confirm(`Delete alert rule ${id}? This cannot be undone (system rules can only be disabled).`);
+    if (!ok) { ui.info('Cancelled'); return; }
+  }
+  const s = ui.spinner('Deleting alert rule');
+  try {
+    const data = await api.delete(`/alert-rules/${id}`);
+    s.stop('Alert rule deleted');
+    if (flags.json) { ui.json(data); return; }
+    ui.success(`Deleted alert rule ${id}`);
+  } catch (err) {
+    s.fail('Failed to delete alert rule');
+    throw err;
+  }
+}
+
+// Run a dry-run test of an existing rule and return { status, error, resultCount }.
+// Used to validate a rule after create/set-sql. Never throws — returns null on error.
+async function validateRuleById(id, flags = {}) {
+  try {
+    let data = await api.post(`/alert-rules/${id}/test`, { mode: 'dry_run' });
+    if (data.testId) {
+      for (let i = 0; i < 40; i++) {
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+        data = await api.get(`/alert-rules/${id}/test/${data.testId}`);
+        if (['complete', 'failed'].includes(data.status)) break;
+      }
+    }
+    return { status: data.status, error: data.error, resultCount: data.resultCount };
+  } catch {
+    return null;
+  }
+}
+
+// Pick an existing rule id to host a candidate dry-run (the test endpoint needs a
+// rule to attach the candidate SQL to). Prefer a system rule (always present on
+// provisioned accounts and never mutated by a dry-run).
+async function resolveHostRuleId() {
+  const data = await api.get('/alert-rules');
+  const rules = data.alertRules || data.rules || [];
+  if (!rules.length) return null;
+  const sys = rules.find((r) => r.isSystem);
+  return (sys || rules[0])._id || (sys || rules[0]).id || null;
+}
+
 function readSqlArg(flags) {
   const raw = flags.sql || flags.query || flags.file;
   if (!raw) return null;
@@ -331,12 +446,24 @@ async function alertRuleTest(args, flags) {
 
 async function alertRuleCandidateTest(args, flags) {
   requireAuth();
-  const id = args[0];
+  let id = args[0];
   const candidateSqlQuery = readSqlArg(flags);
-  if (!id || !candidateSqlQuery) {
-    ui.error('Usage: securenow alerts rules dry-run-query <rule-id> --sql <sql|@file|-> [--app <key>] [--wait]');
+  if (!candidateSqlQuery) {
+    ui.error('Usage: securenow alerts rules validate --sql <sql|@file|-> [--app <key>]   (or dry-run-query <rule-id> --sql ...)');
     process.exit(1);
   }
+  // The test endpoint attaches the candidate SQL to an existing rule. When no
+  // rule id is given, auto-pick a host so a candidate can be validated before any
+  // rule exists for it (every provisioned account has system rules to host on).
+  if (!id) {
+    id = await resolveHostRuleId();
+    if (!id) {
+      ui.error('No existing rule to host the dry-run. Create one rule first, or pass <rule-id>.');
+      process.exit(1);
+    }
+  }
+  // `validate` is meant to return a verdict, so wait for the result by default.
+  const wait = flags.wait || flags['no-wait'] !== true;
 
   const body = { mode: 'dry_run', candidateSqlQuery };
   if (flags.app) body.applicationKey = flags.app;
@@ -344,7 +471,7 @@ async function alertRuleCandidateTest(args, flags) {
   const s = ui.spinner('Starting candidate SQL dry-run');
   try {
     let data = await api.post(`/alert-rules/${id}/test`, body);
-    if (flags.wait && data.testId) {
+    if (wait && data.testId) {
       s.update('Waiting for candidate SQL dry-run results');
       for (let i = 0; i < 40; i++) {
         await new Promise((resolve) => setTimeout(resolve, 2000));

package/cli.js

@@ -255,7 +255,8 @@ const COMMANDS = {
     usage: 'securenow alerts <subcommand> [options]',
     sub: {
       rules: {
-        desc: 'Create, list, show, update, test, or tune alert rules',
+        desc: 'Create, list, show, update, set-sql, validate, delete, test, or tune alert rules',
+        usage: 'securenow alerts rules <list|create|show|update|set-sql|validate|delete|test|dry-run-query|tune-query|exclusions> [options]',
         flags: {
           json: 'Output as JSON',
           name: 'With create: rule name',
@@ -276,9 +277,10 @@ const COMMANDS = {
           app: 'Application key for rule tests',
           mode: 'Rule test mode: dry_run or live',
           wait: 'Wait for rule test completion',
-          sql: 'Detection/candidate/replacement SQL, @file, or - for stdin',
+          sql: 'Detection/candidate/replacement SQL, @file, or - for stdin (create, set-sql, update, validate, dry-run-query, tune-query)',
           query: 'Alias for --sql',
           file: 'Read SQL from a file',
+          'no-validate': 'With create/set-sql: skip the post-write dry-run + rollback',
           reason: 'Audit reason for a write',
           'apply-globally': 'Required for system query tuning',
           'reactivate-paused': 'Reactivate paused system copies after tuning',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securenow",
-  "version": "8.3.0",
+  "version": "8.5.0",
   "description": "OpenTelemetry instrumentation for Node.js, Next.js, and Nuxt - Send traces and logs to any OTLP-compatible backend",
   "type": "commonjs",
   "main": "register.js",

package/sessions.d.ts

@@ -9,6 +9,10 @@ export interface GuardOptions {
   onRevoked?: (req: any, res: any, next: any, ctx: { sessionId: string | null; userId: string | null }) => void;
   /** Background sync interval in ms (default 30000). */
   syncIntervalMs?: number;
+  /** Emit session.seen events for detection (default true). Set false to enforce only. */
+  capture?: boolean;
+  /** Dedup window for session.seen emission, per (session, ip), in ms (default 300000). */
+  captureWindowMs?: number;
 }
 
 /** Start background revocation sync (called automatically by guard()). */
@@ -20,8 +24,14 @@ export function syncOnce(): Promise<boolean>;
 /** Is this session/user currently revoked? */
 export function isRevoked(input: { sessionId?: string | null; userId?: string | null }): boolean;
 
-/** Express-style middleware that rejects revoked sessions/users. Fail-open. */
+/** Express-style middleware: emits session.seen (detection) AND rejects revoked sessions. Fail-open. */
 export function guard(options?: GuardOptions): (req: any, res: any, next: any) => void;
 
+/** Express-style middleware that ONLY emits session.seen (detection feed, no enforcement). */
+export function capture(options?: GuardOptions): (req: any, res: any, next: any) => void;
+
+/** Resolve the client IP from a request (X-Forwarded-For / CF / socket). */
+export function resolveClientIp(req: any): string | null;
+
 /** SHA-256 helper (used to hash raw session tokens consistently). */
 export function sha256(value: string): string;

package/sessions.js

@@ -14,6 +14,7 @@
 
 const crypto = require('crypto');
 const appConfig = require('./app-config');
+const events = require('./events');
 
 let _entries = new Map(); // "type:value" -> expiryMs (0 = never)
 let _etag = null;
@@ -187,6 +188,72 @@ function defaultExtract(req) {
   return { sessionId, userId };
 }
 
+// --- Tier-0 auto-emit of session.seen (feeds session-theft detection) -------
+// Emitting on EVERY request would be huge volume, so we dedup per
+// (session, ip) within a window — enough to capture every new
+// session/network combination, which is what concurrent-network /
+// impossible-travel detection needs.
+const _seen = new Map(); // "sid|ip" -> lastEmitMs
+const _SEEN_MAX = 5000;
+let _captureWindowMs = 5 * 60 * 1000;
+
+function resolveClientIp(req) {
+  const h = (req && req.headers) || {};
+  const xff = h['x-forwarded-for'];
+  if (xff) return String(Array.isArray(xff) ? xff[0] : xff).split(',')[0].trim();
+  if (h['cf-connecting-ip']) return String(h['cf-connecting-ip']).trim();
+  if (h['x-real-ip']) return String(h['x-real-ip']).trim();
+  const sock = req && (req.socket || req.connection);
+  return (sock && sock.remoteAddress) || null;
+}
+
+function emitSessionSeen(sessionId, userId, ip) {
+  if (!sessionId && !userId) return;
+  const key = `${sessionId || ''}|${ip || ''}`;
+  const now = Date.now();
+  const last = _seen.get(key);
+  if (last && now - last < _captureWindowMs) return; // deduped
+  if (_seen.size > _SEEN_MAX) _seen.clear();
+  _seen.set(key, now);
+  try {
+    events.track('session.seen', { sessionId, userId, ip });
+  } catch {
+    /* never throw into the app */
+  }
+}
+
+function extractIdentity(req, getSessionId, getUserId) {
+  let sessionId = null;
+  let userId = null;
+  if (getSessionId || getUserId) {
+    if (getSessionId) sessionId = getSessionId(req);
+    if (getUserId) userId = getUserId(req);
+  } else {
+    const d = defaultExtract(req);
+    sessionId = d.sessionId;
+    userId = d.userId;
+  }
+  return { sessionId, userId };
+}
+
+/**
+ * Middleware that ONLY emits session.seen (detection feed), no enforcement.
+ * Use this if you want SecureNow to see sessions but not block anything.
+ */
+function capture(options = {}) {
+  if (options.captureWindowMs) _captureWindowMs = options.captureWindowMs;
+  const { getSessionId, getUserId } = options;
+  return function securenowSessionCapture(req, res, next) {
+    try {
+      const { sessionId, userId } = extractIdentity(req, getSessionId, getUserId);
+      emitSessionSeen(sessionId, userId, resolveClientIp(req));
+    } catch {
+      /* fail-open */
+    }
+    return next();
+  };
+}
+
 function defaultOnRevoked(req, res) {
   try {
     const clears = SESSION_COOKIES.map((n) => `${n}=; Path=/; Max-Age=0; HttpOnly`);
@@ -211,20 +278,16 @@ function defaultOnRevoked(req, res) {
  */
 function guard(options = {}) {
   start(options);
+  if (options.captureWindowMs) _captureWindowMs = options.captureWindowMs;
   const { getSessionId, getUserId } = options;
   const onRevoked = options.onRevoked || defaultOnRevoked;
+  const doCapture = options.capture !== false; // emit session.seen by default
   return function securenowSessionGuard(req, res, next) {
     try {
-      let sessionId = null;
-      let userId = null;
-      if (getSessionId || getUserId) {
-        if (getSessionId) sessionId = getSessionId(req);
-        if (getUserId) userId = getUserId(req);
-      } else {
-        const d = defaultExtract(req);
-        sessionId = d.sessionId;
-        userId = d.userId;
-      }
+      const { sessionId, userId } = extractIdentity(req, getSessionId, getUserId);
+      // Detect: feed session-theft detection (deduped, fire-and-forget).
+      if (doCapture) emitSessionSeen(sessionId, userId, resolveClientIp(req));
+      // Respond: reject if this session/user has been revoked.
       if (isRevoked({ sessionId, userId })) {
         return onRevoked(req, res, next, { sessionId, userId });
       }
@@ -235,4 +298,4 @@ function guard(options = {}) {
   };
 }
 
-module.exports = { start, syncOnce, isRevoked, guard, sha256 };
+module.exports = { start, syncOnce, isRevoked, guard, capture, resolveClientIp, sha256 };