securenow 8.9.0 → 8.11.0

package/SKILL-CLI.md

@@ -250,9 +250,27 @@ MCP parity:
 
 Write tools still require `confirm:true` plus a reason. False positives should stay restrictive to the app, alert rule, path, method/status, user-agent, body pattern, or other exact evidence the AI report supports. Notification IP investigations can include `metadata.matchedSubdetectors`; prefer that exact field over inferring which subdetector fired from the title or sample body.
 
-### Alerts
-
-```bash
+### Alerts
+
+Before authoring any alert SQL, load the contract shipped by the installed package and compare
+it with fields actually observed for the selected application:
+
+```bash
+securenow telemetry schema --json
+securenow telemetry schema logs --json
+securenow telemetry schema traces --json
+securenow telemetry schema events --json
+securenow telemetry fields --app <key> --env production --since 24h --source all --json
+```
+
+`telemetry schema` is offline and versioned with the SDK. `telemetry fields` requires admin
+auth and telemetry access; it returns names, map scopes, data types, occurrence counts, and
+custom event types, but never customer attribute values. Absence means "not observed in this
+window," not "unsupported." Use only documented fields, and label a rule `READY` only when
+its fields were observed and `alerts rules validate` succeeds. Otherwise label it
+`NEEDS_INSTRUMENTATION`, `NEEDS_BASELINE`, or `NEEDS_CUSTOMER_DECISION` as appropriate.
+
+```bash
 securenow alerts                             # list alert rules (default)
 securenow alerts rules                       # list alert rules (columns: Status, Applications, Schedule)
 securenow alerts rules validate \            # dry-run a candidate query BEFORE creating any rule

package/TELEMETRY-SQL.md

@@ -0,0 +1,98 @@
+# SecureNow telemetry and alert SQL contract
+
+This document is the canonical starting point for humans and coding agents that construct SecureNow alert rules from a customer codebase. The same contract is available as machine-readable JSON:
+
+```bash
+npx securenow telemetry schema --json
+```
+
+The SDK contract tells you which tables and fields are supported. Live field discovery tells you which fields the connected application has actually emitted:
+
+```bash
+npx securenow telemetry fields --app <app-key> --env production --since 24h --json
+```
+
+Do not treat a documented optional or custom field as present until it appears in live discovery or the codebase contains the corresponding instrumentation.
+
+## Alert-rule SQL requirements
+
+- Use ClickHouse SQL.
+- Query `signoz_logs.distributed_logs_v2` for custom events and logs.
+- Query `signoz_traces.distributed_signoz_index_v3` for HTTP spans and traces.
+- Keep `__USER_APP_KEYS__` in every customer-scoped query.
+- For logs, scope with `resources_string['service.name'] IN (__USER_APP_KEYS__)`.
+- For traces, scope with `` `resource_string_service$$name` IN (__USER_APP_KEYS__) ``.
+- Bound the query with a time window.
+- Return an `ip` column and exclude empty IPs when the rule can trigger IP remediation.
+- Use the correct timestamp representation: log timestamps are UInt64 nanoseconds; trace timestamps are `DateTime64(9)`.
+- Validate SQL against the connected SecureNow backend before creating the rule.
+
+## Authoring workflow
+
+```bash
+# 1. Read the exact contract shipped with the installed SDK.
+npx securenow telemetry schema --json
+
+# 2. Discover actual fields and types emitted by this app.
+npx securenow telemetry fields --app <app-key> --env production --since 24h --json
+
+# 3. Avoid duplicating existing coverage.
+npx securenow alerts rules --json
+
+# 4. Validate the candidate before any write.
+npx securenow alerts rules validate --sql @rule.sql --app <app-key>
+
+# 5. Create in detect-only mode and dry-run it.
+npx securenow alerts rules create --name "Auth: OTP send abuse" --sql @rule.sql --apps <app-key>
+npx securenow alerts rules test <rule-id> --mode dry_run --wait
+
+# New custom rules start in detect-only test mode. Promote only after reviewing real matches and false positives.
+npx securenow alerts rules promote <rule-id>
+```
+
+`telemetry schema` works offline. `telemetry fields`, alert-rule validation, and rule management require admin authentication and access to the selected app.
+
+## Custom security events
+
+The SDK accepts arbitrary event names and scalar custom attributes:
+
+```js
+const { track } = require('securenow/events');
+
+track('auth.otp.send.result', {
+  userId,
+  sessionId,
+  ip,
+  attributes: {
+    channel: 'sms',
+    provider: 'twilio',
+    provider_result: 'accepted',
+    destination_hash: sha256(normalizedDestination),
+    cost_units: 1,
+  },
+});
+```
+
+Event properties are stored in the logs table:
+
+| SDK property | Alert SQL field |
+|---|---|
+| Event type | `attributes_string['event.type']` |
+| `userId` | `attributes_string['enduser.id']` |
+| `sessionId` | `attributes_string['session.id']` |
+| `ip` | `attributes_string['http.client_ip']` |
+| `userAgent` | `attributes_string['http.user_agent']` |
+| String custom attribute | `attributes_string['<key>']` |
+| Numeric custom attribute | `attributes_number['<key>']` |
+| Boolean custom attribute | `attributes_bool['<key>']` |
+
+Never send raw passwords, tokens, OTPs, session secrets, email addresses, phone numbers, or other unnecessary personal data. Hash destinations when correlation is required.
+
+## Readiness labels for generated detections
+
+- `READY`: every queried field was observed and the SQL validation passed.
+- `NEEDS_INSTRUMENTATION`: the codebase must add one or more `track()` events or attributes.
+- `NEEDS_BASELINE`: fields and SQL are valid, but the threshold needs production traffic history.
+- `NEEDS_CUSTOMER_DECISION`: cost limits or mitigation behavior require customer approval.
+
+Static repository analysis can produce candidate SQL and exact instrumentation TODOs. Only live field discovery plus SQL validation can justify the `READY` label.

package/cli/agent.js

@@ -0,0 +1,65 @@
+'use strict';
+
+// `securenow agent` — the SOC runbook prompts that SecureNow's retired built-in
+// AI Security Agent used to run on a cron. Print them here so customers can run
+// the same work externally with their own harness (Claude, Hermes, OpenClaw, or
+// any MCP-capable agent), e.g.:
+//
+//   claude -p "$(securenow agent prompt patrol --confirm-writes)"
+//
+// The same prompts are published over MCP via prompts/list (soc_patrol,
+// work_alert_review, work_human_actions, ...).
+
+const ui = require('./ui');
+const { PROMPTS, promptMessages } = require('../mcp/catalog.js');
+
+const PROMPT_ALIASES = {
+  patrol: 'soc_patrol',
+  soc_patrol: 'soc_patrol',
+  'alert-review': 'work_alert_review',
+  work_alert_review: 'work_alert_review',
+  'human-queue': 'work_human_actions',
+  human: 'work_human_actions',
+  work_human_actions: 'work_human_actions',
+};
+
+function promptText(name, args) {
+  const messages = promptMessages(name, args);
+  return messages
+    .map((message) => message?.content?.text || '')
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+async function prompts(args, flags = {}) {
+  const rows = PROMPTS.map((p) => ({ name: p.name, title: p.title, description: p.description }));
+  if (flags.json) return ui.json({ prompts: rows, aliases: PROMPT_ALIASES });
+  ui.heading('SecureNow agent runbook prompts');
+  for (const row of rows) {
+    console.log(`- ${row.name}: ${row.description}`);
+  }
+  console.log('');
+  console.log('Print one with: securenow agent prompt <patrol|alert-review|human-queue|full name>');
+  console.log('Scheduled example: claude -p "$(securenow agent prompt patrol --confirm-writes)"');
+}
+
+async function prompt(args, flags = {}) {
+  const ref = String(args[0] || 'patrol').toLowerCase();
+  const name = PROMPT_ALIASES[ref] || ref;
+  if (!PROMPTS.some((p) => p.name === name)) {
+    throw new Error(`Unknown prompt "${args[0]}". Run \`securenow agent prompts\` to list them.`);
+  }
+  const promptArgs = {
+    confirmWrites: Boolean(flags['confirm-writes'] || flags.confirmWrites || flags.yes),
+  };
+  if (flags.limit) promptArgs.limit = flags.limit;
+  if (flags.search) promptArgs.search = flags.search;
+  if (flags['max-alert-review-groups']) promptArgs.maxAlertReviewGroups = flags['max-alert-review-groups'];
+  if (flags['max-human-rows']) promptArgs.maxHumanRows = flags['max-human-rows'];
+
+  const text = promptText(name, promptArgs);
+  if (flags.json) return ui.json({ name, prompt: text });
+  console.log(text);
+}
+
+module.exports = { prompt, prompts };

package/cli/telemetry.js

@@ -0,0 +1,199 @@
+'use strict';
+
+const schemaContract = require('../telemetry-schema.json');
+const { api, requireAuth } = require('./client');
+const config = require('./config');
+const appConfig = require('../app-config');
+const ui = require('./ui');
+
+function parseDurationToMinutes(value) {
+  if (value == null || value === '') return 24 * 60;
+  const match = String(value).trim().match(/^(\d+)\s*(m|h|d)?$/i);
+  if (!match) return null;
+  const amount = Number.parseInt(match[1], 10);
+  const unit = String(match[2] || 'm').toLowerCase();
+  if (amount < 1) return null;
+  if (unit === 'm') return amount;
+  if (unit === 'h') return amount * 60;
+  if (unit === 'd') return amount * 24 * 60;
+  return null;
+}
+
+function filteredSchema(section) {
+  const selected = String(section || 'all').toLowerCase();
+  if (selected === 'all') return schemaContract;
+  if (selected === 'logs' || selected === 'traces') {
+    return {
+      contract: schemaContract.contract,
+      schemaVersion: schemaContract.schemaVersion,
+      dialect: schemaContract.dialect,
+      ruleContract: schemaContract.ruleContract,
+      table: schemaContract.tables[selected],
+      clientIp: schemaContract.clientIp,
+      templates: schemaContract.templates,
+    };
+  }
+  if (selected === 'events') {
+    return {
+      contract: schemaContract.contract,
+      schemaVersion: schemaContract.schemaVersion,
+      dialect: schemaContract.dialect,
+      ruleContract: schemaContract.ruleContract,
+      storageTable: schemaContract.tables.logs,
+      customEvents: schemaContract.customEvents,
+      templates: { eventFailuresByIp: schemaContract.templates.eventFailuresByIp },
+    };
+  }
+  return null;
+}
+
+async function schema(args, flags) {
+  const section = args[0] || flags.source || 'all';
+  const contract = filteredSchema(section);
+  if (!contract) {
+    ui.error('Unknown schema section. Use all, logs, traces, or events.');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (flags.json) {
+    ui.json(contract);
+    return;
+  }
+
+  console.log('');
+  ui.heading('SecureNow Telemetry & Alert SQL Contract');
+  console.log('');
+  ui.keyValue([
+    ['Schema version', schemaContract.schemaVersion],
+    ['SQL dialect', schemaContract.dialect],
+    ['Tenant placeholder', schemaContract.ruleContract.tenantPlaceholder],
+    ['Required result', 'ip column for IP-remediation rules'],
+  ]);
+
+  const tables = section === 'all'
+    ? Object.entries(schemaContract.tables)
+    : section === 'events'
+      ? [['logs', schemaContract.tables.logs]]
+      : [[section, schemaContract.tables[section]]];
+  console.log('');
+  ui.subheading('Tables');
+  console.log('');
+  ui.table(
+    ['Signal', 'Table', 'Timestamp', 'Tenant scope'],
+    tables.map(([name, table]) => [
+      name,
+      table.name,
+      `${table.timestamp.type} (${table.timestamp.unit})`,
+      table.tenantExpression,
+    ])
+  );
+
+  if (section === 'all' || section === 'events') {
+    console.log('');
+    ui.subheading('Custom event mapping');
+    console.log('');
+    ui.table(
+      ['SDK property', 'SQL field'],
+      Object.entries(schemaContract.customEvents.propertyMapping).map(([property, field]) => [property, field])
+    );
+  }
+
+  console.log('');
+  ui.info('Machine-readable: securenow telemetry schema --json');
+  ui.info('Live verification: securenow telemetry fields --app <key> --env production --since 24h --json');
+  ui.info('Full guide: node_modules/securenow/TELEMETRY-SQL.md');
+  console.log('');
+}
+
+async function fields(args, flags) {
+  requireAuth();
+  const appKey = flags.app || config.getDefaultApp() || appConfig.resolveAppKey();
+  if (!appKey) {
+    ui.error('No app specified. Use --app <key>, run `securenow app connect`, or set a default app.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const sinceMinutes = parseDurationToMinutes(flags.since || '24h');
+  if (sinceMinutes == null || sinceMinutes > 30 * 24 * 60) {
+    ui.error('Invalid --since value. Use a duration such as 30m, 24h, or 7d (maximum 30d).');
+    process.exitCode = 1;
+    return;
+  }
+  const source = String(flags.source || args[0] || 'all').toLowerCase();
+  if (!['all', 'logs', 'traces'].includes(source)) {
+    ui.error('Invalid --source. Use all, logs, or traces.');
+    process.exitCode = 1;
+    return;
+  }
+  const parsedLimit = Number.parseInt(flags.limit || '200', 10);
+  if (!Number.isFinite(parsedLimit) || parsedLimit < 1 || parsedLimit > 500) {
+    ui.error('--limit must be between 1 and 500.');
+    process.exitCode = 1;
+    return;
+  }
+  const environment = flags.env || flags.environment || 'production';
+
+  const spinner = ui.spinner('Discovering observed telemetry fields');
+  try {
+    const data = await api.get('/telemetry/fields', {
+      query: {
+        appKeys: appKey,
+        environment,
+        sinceMinutes,
+        source,
+        limit: parsedLimit,
+      },
+    });
+    spinner.stop(`Found ${(data.fields || []).length} observed field${(data.fields || []).length === 1 ? '' : 's'}`);
+    if (flags.json) {
+      ui.json(data);
+      return;
+    }
+
+    console.log('');
+    ui.heading('Observed Telemetry Fields');
+    console.log('');
+    ui.keyValue([
+      ['App', appKey],
+      ['Environment', (data.environments || [environment]).join(', ')],
+      ['Window', `${sinceMinutes} minutes`],
+      ['Source', source],
+    ]);
+    console.log('');
+    ui.table(
+      ['Signal', 'Scope', 'Type', 'Field', 'Occurrences'],
+      (data.fields || []).map((field) => [
+        field.source,
+        field.fieldScope,
+        field.dataType,
+        field.field,
+        String(field.occurrences || 0),
+      ])
+    );
+
+    if ((data.eventTypes || []).length > 0) {
+      console.log('');
+      ui.subheading('Observed custom event types');
+      console.log('');
+      ui.table(
+        ['Event type', 'Occurrences'],
+        data.eventTypes.map((event) => [event.eventType, String(event.occurrences || 0)])
+      );
+    }
+    console.log('');
+    ui.info(data.note || 'Absence in this window does not prove a field can never be emitted.');
+    console.log('');
+  } catch (error) {
+    spinner.fail('Failed to discover telemetry fields');
+    throw error;
+  }
+}
+
+module.exports = {
+  schema,
+  fields,
+  parseDurationToMinutes,
+  filteredSchema,
+};

package/cli.js

@@ -197,6 +197,44 @@ const COMMANDS = {
     },
     defaultSub: 'list',
   },
+  telemetry: {
+    desc: 'Inspect the alert-SQL telemetry contract and fields observed for an app',
+    usage: 'securenow telemetry <schema|fields> [options]',
+    flags: {
+      app: 'With fields: application key (defaults to connected/default app)',
+      env: 'With fields: environment or all (default: production)',
+      since: 'With fields: observation window such as 30m, 24h, or 7d (maximum 30d)',
+      source: 'Schema section or live signal source',
+      limit: 'With fields: maximum fields per signal (1-500, default 200)',
+      json: 'Machine-readable output',
+    },
+    sub: {
+      schema: {
+        desc: 'Print the packaged ClickHouse tables, fields, mappings, and SQL requirements',
+        usage: 'securenow telemetry schema [all|logs|traces|events] [--json]',
+        flags: {
+          source: 'Schema section: all, logs, traces, or events',
+          json: 'Output the machine-readable contract as JSON',
+        },
+        run: (a, f) => require('./cli/telemetry').schema(a, f),
+      },
+      fields: {
+        desc: 'Discover fields and custom event types actually emitted by an app',
+        usage: 'securenow telemetry fields [--app <key>] [--env production] [--since 24h] [--source all] [--limit 200] [--json]',
+        flags: {
+          app: 'Application key (defaults to connected/default app)',
+          env: 'Environment, comma-separated environments, or all (default: production)',
+          environment: 'Alias for --env',
+          since: 'Observation window such as 30m, 24h, or 7d (maximum 30d)',
+          source: 'Signal source: all, logs, or traces',
+          limit: 'Maximum fields per signal (1-500, default 200)',
+          json: 'Output JSON for agents and scripts',
+        },
+        run: (a, f) => require('./cli/telemetry').fields(a, f),
+      },
+    },
+    defaultSub: 'schema',
+  },
   notifications: {
     desc: 'Manage notifications',
     usage: 'securenow notifications <subcommand> [options]',
@@ -250,6 +288,23 @@ const COMMANDS = {
     },
     defaultSub: 'list',
   },
+  agent: {
+    desc: 'SOC runbook prompts for running the SecureNow agent work with your own harness (Claude, Hermes, OpenClaw, ...)',
+    usage: 'securenow agent <prompt|prompts> [patrol|alert-review|human-queue] [options]',
+    flags: {
+      json: 'Output as JSON',
+      'confirm-writes': 'Emit the prompt variant that allows the external agent to execute decisions',
+      limit: 'Row/group budget baked into the prompt',
+      search: 'Optional search filter baked into the prompt',
+      'max-alert-review-groups': 'SOC patrol: max alert-review root-cause groups per pass',
+      'max-human-rows': 'SOC patrol: max Requires Human rows per pass',
+    },
+    sub: {
+      prompt: { desc: 'Print one runbook prompt (pipe it into your harness or schedule it on a cron)', usage: 'securenow agent prompt <patrol|alert-review|human-queue> [--confirm-writes]', run: (a, f) => require('./cli/agent').prompt(a, f) },
+      prompts: { desc: 'List the available runbook prompts (same catalog as MCP prompts/list)', run: (a, f) => require('./cli/agent').prompts(a, f) },
+    },
+    defaultSub: 'prompts',
+  },
   alerts: {
     desc: 'Manage alerting',
     usage: 'securenow alerts <subcommand> [options]',
@@ -765,7 +820,7 @@ function showHelp(commandName) {
     'Investigate': ['ip', 'forensics'],
     'Firewall': ['firewall'],
     'Remediation': ['automation', 'ratelimit', 'challenge', 'blocklist', 'revoke', 'allowlist', 'trusted'],
-    'Telemetry': ['log', 'event', 'test-span'],
+    'Telemetry': ['telemetry', 'log', 'event', 'test-span'],
     'Utilities': ['redact', 'cidr', 'doctor', 'env', 'mcp'],
     'Settings': ['instances', 'config', 'version'],
   };