securenow 6.0.2 → 6.1.0

package/SKILL-CLI.md

@@ -0,0 +1,454 @@
+# SecureNow CLI — Agent Skill
+
+Use the `securenow` CLI to perform security DevOps from the terminal: manage apps, investigate threats, control the firewall, analyze traces, handle false positives, and run instrumented Node.js processes. Every command supports `--json` for machine-readable output.
+
+## Installation
+
+```bash
+# Install globally (recommended for CLI usage)
+npm install -g securenow
+
+# Or install per-project and use via npx
+npm install securenow
+npx securenow <command>
+```
+
+**Full parity with the SDK:** every capability the `securenow` Node SDK exposes has a CLI counterpart — redaction, CIDR matching, log/span emission, firewall preload, config inspection. If you can do it in code, you can do it from the terminal.
+
+### Authenticate
+
+```bash
+securenow login             # opens browser OAuth; stores JWT in ~/.securenow/credentials.json
+securenow login --token <JWT>   # headless / CI login (get token from dashboard Settings)
+securenow login --local     # save credentials to this project only (.securenow/)
+securenow whoami             # verify session (shows auth source)
+```
+
+**Per-project credentials:** Use `--local` to keep separate logins in different project directories on the same machine. Credentials resolve in order: `SECURENOW_TOKEN` env var → project `.securenow/credentials.json` → global `~/.securenow/credentials.json`.
+
+### Integrate With Your App
+
+The CLI can also instrument any Node.js app at launch — no code changes:
+
+```bash
+# Express, Fastify, NestJS, Koa, Hapi, raw Node.js
+securenow run src/index.js
+
+# Or via the Node preload flag
+node -r securenow/register src/index.js
+```
+
+For Next.js, run the interactive scaffolding:
+
+```bash
+securenow init --key snk_live_...
+```
+
+This auto-detects your framework and creates the necessary `instrumentation.ts`, `next.config.js` changes, and writes your API key to `.env.local`.
+
+### Install This Skill in Cursor
+
+Save this file as `.cursor/skills/securenow-cli/SKILL.md` in your project. Your AI agent will auto-discover it whenever you ask about CLI commands, security investigations, or firewall management.
+
+## Configuration
+
+Config lives in `~/.securenow/` (global) and optionally `.securenow/` (per-project):
+
+| File | Content |
+|------|---------|
+| `~/.securenow/config.json` | `apiUrl`, `appUrl`, `defaultApp`, `output` |
+| `~/.securenow/credentials.json` | `token`, `email`, `expiresAt` (global) |
+| `.securenow/credentials.json` | `token`, `email`, `expiresAt` (project-local, use `login --local`) |
+
+**Credential resolution order:** `SECURENOW_TOKEN` env var → `.securenow/credentials.json` (project) → `~/.securenow/credentials.json` (global).
+
+```bash
+securenow config set apiUrl https://api.securenow.ai
+securenow config set defaultApp my-app-key
+securenow config get                     # show all
+securenow config get defaultApp          # show one
+securenow config path                    # print file paths + active auth source
+```
+
+Environment overrides: `SECURENOW_TOKEN` (JWT), `SECURENOW_API_URL`, `SECURENOW_APP_URL`, `SECURENOW_APP` (default app key).
+
+## Global Flags
+
+| Flag | Short | Effect |
+|------|-------|--------|
+| `--json` | `-j` | JSON output (pipe-friendly) |
+| `--help` | | Show help for any command |
+| `--verbose` | `-v` | Verbose output |
+| `--force` | `-f` | Skip confirmations |
+| `--yes` | `-y` | Auto-confirm prompts |
+
+Debug mode: `SECURENOW_DEBUG=1 securenow <cmd>` prints stack traces on errors.
+
+---
+
+## Command Reference
+
+### Run — Instrument Any Node.js App
+
+```bash
+securenow run <script>                       # auto-detect CJS/ESM, inject OTel preload
+securenow run --watch src/index.js           # pass Node flags through
+securenow run --inspect src/server.js --port 3000
+securenow run --firewall-only app.js         # preload firewall only (no tracing overhead)
+securenow src/index.js                       # shorthand — auto-detected as "run"
+```
+
+Spawns `node --require securenow/register [--import otel/hook.mjs] <script>`. ESM detection uses nearest `package.json` `"type"` field or `.mjs`/`.cjs` extension. With `--firewall-only`, uses `securenow/firewall-only` instead (dotenv + firewall, no OpenTelemetry).
+
+### Authentication
+
+```bash
+securenow login                   # browser-based OAuth (stores in global ~/.securenow/)
+securenow login --token <JWT>     # headless / CI login
+securenow login --local           # save credentials to project .securenow/ (per-project session)
+securenow logout                  # clear active credentials (local if present, else global)
+securenow logout --local          # clear project-local credentials only
+securenow whoami                  # show email, user ID, API URL, auth source, expiry, default app
+```
+
+### Applications
+
+```bash
+securenow apps                               # list all apps (default subcommand)
+securenow apps list                          # same as above
+securenow apps create <name> [--hosts h1,h2] [--instance <id>]   # interactive instance picker
+securenow apps info <id>                     # show app details
+securenow apps delete <id> [--force]         # delete an app
+securenow apps default <app-key>             # set default app for all commands
+securenow apps discover [appId] [--domain example.com]  # discover subdomains, add as apps
+securenow apps scan [--yes]                  # scan all app domains for new subdomains
+```
+
+### Init — Project Setup
+
+```bash
+securenow init [--key <API_KEY>]
+```
+
+Auto-detects framework (Next.js, Nuxt, Express, Fastify, Koa, Hapi, Node) from `package.json`. Then:
+- **Next.js**: creates `instrumentation.ts/js`, suggests `withSecureNow()` in `next.config`
+- **Nuxt**: tells you to add `securenow/nuxt` to modules
+- **Node/Express/etc.**: suggests adding `-r securenow/register` to start script
+- Writes `SECURENOW_API_KEY` to `.env.local` or `.env` if `--key` provided
+
+### Dashboard & Status
+
+```bash
+securenow status [--app <key>]               # dashboard overview
+securenow analytics [--app <key>]            # response analytics
+```
+
+---
+
+### Traces
+
+```bash
+securenow traces [--app <key>] [--limit N] [--start ISO] [--end ISO]
+securenow traces list --app my-app --limit 50
+securenow traces show <traceId>              # full trace detail with spans
+securenow traces analyze <traceId>           # AI-powered trace analysis
+```
+
+### Logs
+
+```bash
+securenow logs [--app <key>] [--limit N] [--minutes M] [--level error|warn|info]
+securenow logs list --app my-app --minutes 30 --level error
+securenow logs trace <traceId>               # logs correlated to a specific trace
+```
+
+### Notifications
+
+```bash
+securenow notifications [--limit N] [--page P]
+securenow notifications list --limit 20
+securenow notifications read <id>            # mark one as read
+securenow notifications read-all             # mark all as read
+securenow notifications unread               # unread count
+```
+
+### Alerts
+
+```bash
+securenow alerts                             # list alert rules (default)
+securenow alerts rules                       # list alert rules (columns: Status, Applications, Schedule)
+securenow alerts rules show <id>            # one rule; JSON: --json
+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 channels                    # list alert channels (Slack, email, etc.)
+securenow alerts history [--limit N]         # past triggered alerts
+```
+
+---
+
+### IP Intelligence
+
+```bash
+securenow ip <ip-address>                    # lookup (geo, ASN, threat score, reputation)
+securenow ip lookup <ip-address>             # same as above
+securenow ip traces <ip-address>             # traces originating from this IP
+```
+
+### Forensics — Natural Language Security Queries
+
+```bash
+securenow forensics "show me all SQL injection attempts in the last 24h"
+securenow forensics query "top 10 IPs by blocked requests" --app my-app
+securenow forensics chat --app my-app        # interactive forensics chat session
+securenow forensics library                  # view saved/template queries
+```
+
+### API Map
+
+```bash
+securenow api-map                            # list discovered API endpoints
+securenow api-map list                       # same
+securenow api-map stats                      # endpoint statistics
+```
+
+---
+
+### Firewall
+
+```bash
+securenow firewall                           # show status (default)
+securenow firewall status                    # layers, sync time, blocked count, API key info
+securenow firewall test-ip <ip>              # check if IP would be blocked
+```
+
+### Blocklist — Block Malicious IPs
+
+```bash
+securenow blocklist                          # list blocked IPs
+securenow blocklist list
+securenow blocklist add <ip> [--reason "Brute force"]
+securenow blocklist remove <id>
+securenow blocklist stats                    # block counts, top reasons
+```
+
+### Allowlist — Restrict to Known IPs
+
+```bash
+securenow allowlist                          # list allowed IPs
+securenow allowlist list
+securenow allowlist add <ip> [--label "Office"] [--reason "Corporate VPN"]
+securenow allowlist remove <id>
+securenow allowlist stats
+```
+
+### Trusted Proxies
+
+```bash
+securenow trusted                            # list trusted IPs
+securenow trusted list
+securenow trusted add <ip> [--label "CloudFlare edge"]
+securenow trusted remove <id>
+```
+
+---
+
+### False Positive Management
+
+The `fp` command manages exclusion rules that prevent known-safe traffic from triggering security alerts.
+
+```bash
+securenow fp                                 # list all exclusion rules
+securenow fp list
+securenow fp show <id>                       # rule details
+securenow fp delete <id> [--yes]
+
+# Create exclusion rules
+securenow fp create \
+  --conditions '[{"field":"http.target","op":"starts_with","value":"/api/health"}]' \
+  --match-mode all \
+  --rule-scope any_rule \
+  --reason "Health check endpoint"
+
+# Shorthand safe-value presets
+securenow fp create \
+  --path /api/events \
+  --method POST \
+  --path-safe standard \
+  --ua-safe standard \
+  --headers-safe standard \
+  --query-keys page,limit \
+  --headers-keys host,content-type \
+  --reason "Event webhook"
+
+# Edit an existing rule
+securenow fp edit <id> [--active true|false] [--conditions '[...]']
+
+# Test conditions against a request body
+securenow fp test-body '{"user":"admin"}' --conditions '[{"field":"body.user","op":"eq","value":"admin"}]'
+securenow fp test-body @request.json --conditions '[...]'
+
+# Dry-run conditions against the last 3 days of live traces
+securenow fp dry-run --conditions '[{"field":"http.target","op":"starts_with","value":"/api/webhook"}]'
+
+# AI-generate exclusion conditions from a description
+securenow fp ai-fill --description "Stripe webhook POST to /api/stripe/webhook" \
+  --context '{"method":"POST","path":"/api/stripe/webhook"}'
+
+# Mark an IP as false positive on a specific notification
+securenow fp mark <notification-id> <ip> \
+  [--conditions '[...]'] \
+  [--reason "Known partner IP"] \
+  [--rule-scope this_rule|specific_rules|all_existing|any_rule] \
+  [--target-rules id1,id2]
+```
+
+**Condition fields:** `http.target`, `http.method`, `http.url`, `http.user_agent`, `http.request.header.*`, `body.*`, `http.status_code`, `net.peer.ip`, and more.
+
+**Operators:** `eq`, `neq`, `contains`, `not_contains`, `starts_with`, `ends_with`, `regex`, `in`, `not_in`, `exists`, `not_exists`, `gt`, `lt`, `gte`, `lte`.
+
+**Match modes:** `all` (AND logic), `any` (OR logic).
+
+**Rule scopes:** `this_rule` (single alert rule), `specific_rules` (comma-separated IDs via `--target-rules`), `all_existing` (all current rules), `any_rule` (all current and future rules).
+
+**Safe-value presets:** `standard` or `strict`. These auto-generate conditions that whitelist common safe patterns for paths, query strings, user-agents, and headers.
+
+---
+
+### Instances
+
+```bash
+securenow instances                          # list ClickHouse instances
+securenow instances list
+securenow instances test <id>                # test connection
+```
+
+---
+
+### Telemetry — Emit Logs and Spans From the Shell
+
+Mirrors the SDK's `getLogger()` and tracing APIs. Useful for cron jobs, shell scripts, and CI pipelines that need to push events into SecureNow without booting the full OTel SDK.
+
+```bash
+# Send a structured log record to the OTLP collector
+securenow log send "Deployment completed" --level info --attrs version=1.2.3,service=api
+securenow log send "Backup failed" --level error --attrs host=db-01
+
+# Emit a test span to verify the collector accepts OTLP traffic
+securenow test-span
+securenow test-span "ci.smoke-test"          # custom span name
+```
+
+Both commands use the resolved `SECURENOW_INSTANCE` / `OTEL_EXPORTER_OTLP_*` endpoints. Honors `OTEL_EXPORTER_OTLP_HEADERS` for API-key auth. Returns non-zero on HTTP errors so CI/cron can detect failures.
+
+### Utilities — Redaction, CIDR, Diagnostics
+
+These mirror the SDK exports (`redactSensitiveData`, `createMatcher`, `parseCidr`) so agents can validate behavior without writing Node.
+
+```bash
+# Redact sensitive fields (password, token, card, ssn, etc.)
+securenow redact '{"user":"alice","password":"s3cret","card":"4242"}'
+securenow redact @request.json --fields internal_id,sessionHash
+
+# CIDR operations — match an IP against a list, or parse a range
+securenow cidr match 10.0.0.5 10.0.0.0/24,192.168.0.0/16
+securenow cidr parse 10.0.0.0/24             # network, broadcast, mask, size
+
+# Show resolved config (service name, endpoints, env vars, firewall layers)
+securenow env                                # human-readable
+securenow env --json                         # pipe to jq
+
+# End-to-end diagnostic: probe OTLP + API endpoints, check config
+securenow doctor                             # exits 0 if healthy, 1 otherwise
+securenow doctor --json
+```
+
+The `redact` command accepts a JSON string or `@path/to/file.json`, layers your `--fields` flag on top of `DEFAULT_SENSITIVE_FIELDS`, and also honors `SECURENOW_SENSITIVE_FIELDS` from the env. Exit code from `cidr match` is `0` if the IP matches the list, `2` otherwise — scriptable.
+
+---
+
+## Workflow Examples for Agentic AI
+
+### Investigate a Security Alert
+
+```bash
+securenow notifications list --limit 5 --json
+# IMPORTANT: parse the ipInvestigations array for each notification — see statuses below
+securenow ip <attacker-ip> --json
+securenow ip traces <attacker-ip> --json
+securenow traces show <trace-id> --json
+securenow traces analyze <trace-id> --json
+# Decision: block the IP
+securenow blocklist add <attacker-ip> --reason "Automated: SQL injection detected"
+```
+
+#### Notification IP Investigation Statuses
+
+Each notification contains an `ipInvestigations` array. **Every IP has its own `status` field** that you MUST check before taking action or raising flags. Do not rely only on top-level notification fields — always cross-reference each IP's individual investigation status.
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| `open` | Still needs review — no determination yet | Investigate: run `securenow ip <ip>`, check traces, decide to block or dismiss |
+| `false_positive` | Trusted/dismissed by exclusion rule, verified bot, or trusted IP list | **Skip** — greyed out in UI, no action needed |
+| `blocked` | Already on the user's blocklist | **Skip** — already handled |
+| `clean` | Pipeline analyzed and cleared as benign | **Skip** — verified safe |
+
+**Critical workflow rule:** When investigating notifications, iterate `ipInvestigations[]` and **only flag or act on IPs with `status: "open"`**. IPs marked `false_positive`, `blocked`, or `clean` have already been triaged — do not re-flag them.
+
+### Triage and Suppress a False Positive
+
+```bash
+securenow notifications list --json
+# Identify a false positive notification
+securenow fp ai-fill --description "Stripe webhook calls to /api/stripe/webhook"
+# Review the suggested conditions, then create the rule
+securenow fp create --conditions '<ai-suggested-conditions>' --rule-scope any_rule --reason "Stripe webhook"
+# Or directly mark the notification's IP as FP
+securenow fp mark <notification-id> <ip> --rule-scope this_rule --reason "Known Stripe IP"
+```
+
+### Onboard a New Application
+
+```bash
+securenow apps create my-new-app --hosts api.example.com,app.example.com
+securenow apps default my-new-app
+securenow init --key snk_live_abc123...
+securenow run src/index.js
+securenow status --json
+```
+
+### Security Posture Check
+
+```bash
+securenow status --json
+securenow firewall status --json
+securenow blocklist stats --json
+securenow api-map stats --json
+securenow forensics "summarize all attacks in the last 7 days"
+```
+
+### Discover Attack Surface
+
+```bash
+securenow apps discover --domain example.com
+securenow apps scan --yes
+securenow api-map list --json
+securenow api-map stats --json
+```
+
+---
+
+## Output Parsing
+
+All commands support `--json` for structured output. When piping to other tools or parsing programmatically, always use `--json`. Table output is the default for human readability.
+
+## Error Handling
+
+| Exit code / Error | Meaning | Recovery |
+|------------------|---------|----------|
+| `Session expired` | JWT expired | `securenow login` (or `login --local`) |
+| `Not logged in` | No token found | `securenow login` or set `SECURENOW_TOKEN` env var |
+| `Access denied (403)` | Insufficient plan or permissions | Upgrade plan or check user role |
+| `Cannot connect` | API unreachable | Check `SECURENOW_API_URL` or network |
+| `Unknown command` | Typo or unrecognized command | `securenow help` |
+
+Set `SECURENOW_DEBUG=1` for full stack traces on any error.

package/cidr.js

@@ -0,0 +1,83 @@
+'use strict';
+
+/**
+ * Bitmask-based CIDR matching. No regex on user input — prevents ReDoS.
+ * All operations use unsigned 32-bit integers for IPv4 addresses.
+ */
+
+function ipToInt(ip) {
+  const parts = ip.split('.');
+  if (parts.length !== 4) return null;
+  let result = 0;
+  for (let i = 0; i < 4; i++) {
+    const n = parseInt(parts[i], 10);
+    if (isNaN(n) || n < 0 || n > 255) return null;
+    result = (result << 8) + n;
+  }
+  return result >>> 0;
+}
+
+function parseCidr(cidr) {
+  const slash = cidr.indexOf('/');
+  if (slash === -1) return null;
+  const ip = cidr.slice(0, slash);
+  const bits = parseInt(cidr.slice(slash + 1), 10);
+  if (isNaN(bits) || bits < 0 || bits > 32) return null;
+  const network = ipToInt(ip);
+  if (network === null) return null;
+  const mask = bits === 0 ? 0 : (~((1 << (32 - bits)) - 1)) >>> 0;
+  return { network: (network & mask) >>> 0, mask };
+}
+
+function matchesCidr(ipInt, cidrEntry) {
+  return ((ipInt & cidrEntry.mask) >>> 0) === cidrEntry.network;
+}
+
+/**
+ * Create a matcher from a list of IPs and CIDRs.
+ * Returns { isBlocked(ip), stats() }.
+ * Exact IPs use a Set for O(1) lookup; CIDRs use array scan (typically < 100 entries).
+ */
+function createMatcher(ipList) {
+  const exactSet = new Set();
+  const cidrRanges = [];
+
+  for (const entry of ipList) {
+    const trimmed = (entry || '').trim();
+    if (!trimmed) continue;
+
+    if (trimmed.includes('/')) {
+      const parsed = parseCidr(trimmed);
+      if (parsed) cidrRanges.push(parsed);
+    } else {
+      const normalized = trimmed.replace(/^::ffff:/, '');
+      exactSet.add(normalized);
+    }
+  }
+
+  function isBlocked(ip) {
+    if (!ip) return false;
+    const normalized = ip.replace(/^::ffff:/, '');
+
+    if (exactSet.has(normalized)) return true;
+
+    if (cidrRanges.length > 0) {
+      const ipInt = ipToInt(normalized);
+      if (ipInt !== null) {
+        for (const cidr of cidrRanges) {
+          if (matchesCidr(ipInt, cidr)) return true;
+        }
+      }
+    }
+
+    return false;
+  }
+
+  function stats() {
+    return { exact: exactSet.size, cidr: cidrRanges.length, total: exactSet.size + cidrRanges.length };
+  }
+
+  return { isBlocked, stats };
+}
+
+module.exports = { ipToInt, parseCidr, matchesCidr, createMatcher };