securenow 7.6.7 → 7.6.9

package/docs/ALL-FRAMEWORKS-QUICKSTART.md

@@ -1,1388 +0,0 @@
-# SecureNow — Complete Guide for Every Node.js Framework
-
-Protect any Node.js app in minutes. This guide covers **installation, CLI commands, the forensics chat, and IP blocking** for all 11 supported frameworks.
-
-> **v7+ — zero-config shortcut.** For local dev, the short version is:
-> ```bash
-> npm install securenow
-> npx securenow login              # pick/create app in the browser
-> node -r securenow/register app.js
-> ```
-> No `.env` setup. Credentials live in `.securenow/credentials.json` (gitignored automatically). Skip "Step 2 — Set Environment Variables" below unless you're configuring CI / Docker / prod.
-
----
-
-## Table of Contents
-
-1. [Prerequisites](#prerequisites)
-2. [Install & Create Your App](#step-1--install--create-your-app)
-3. [Set Environment Variables](#step-2--set-environment-variables)
-4. [Plug SecureNow into Your Framework](#step-3--plug-securenow-into-your-framework)
-   - [Express.js](#expressjs)
-   - [Fastify](#fastify)
-   - [Koa](#koa)
-   - [NestJS](#nestjs)
-   - [Hapi](#hapi)
-   - [h3 (UnJS / Nitro)](#h3-unjs--nitro)
-   - [Polka](#polka)
-   - [Micro / Raw HTTP](#micro--raw-http)
-   - [Hono](#hono)
-   - [Feathers](#feathers)
-   - [Next.js](#nextjs)
-5. [Verify It Works](#step-4--verify-it-works)
-6. [CLI Command Reference](#step-5--cli-command-reference)
-7. [Forensics Chat — Ask Questions in Plain English](#step-6--forensics-chat--ask-questions-in-plain-english)
-8. [Block & Manage IPs + Firewall](#step-7--block--manage-ips)
-9. [Monitor, Detect & Respond](#step-8--monitor-detect--respond)
-10. [PM2 / Docker Deployment](#deployment)
-11. [Compatibility Matrix](#compatibility-matrix)
-12. [Troubleshooting](#troubleshooting)
-
----
-
-## Prerequisites
-
-| Requirement | Details |
-|-------------|---------|
-| **Node.js** | v16 or later |
-| **npm** | v7 or later |
-| **Account** | Free trial at [app.securenow.ai](https://app.securenow.ai) (no credit card) |
-
----
-
-## Step 1 — Install & Create Your App
-
-### 1a. Install the package
-
-```bash
-npm install securenow
-```
-
-### 1b. Authenticate the CLI
-
-```bash
-npx securenow login
-```
-
-This opens your browser. Log in with your SecureNow account and the CLI receives a session token automatically.
-
-**Alternative — token-based login (CI / headless servers):**
-
-```bash
-npx securenow login --token <YOUR_TOKEN>
-```
-
-Get your CLI token from [app.securenow.ai/dashboard/settings](https://app.securenow.ai/dashboard/settings).
-
-### 1c. Create an application
-
-```bash
-npx securenow apps create my-app
-```
-
-The CLI returns your **app key** and **instance URL**. Copy them — you need both in the next step.
-
-```
-  Name       my-app
-  Key        my-app
-  Instance   Free Trial (https://freetrial.securenow.ai:4318)
-
-  Add to your .env.local:
-    SECURENOW_APPID=my-app
-    SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
-```
-
-### 1d. Set it as the default app (optional)
-
-```bash
-npx securenow config set defaultApp my-app
-```
-
-This lets you run CLI commands like `securenow traces` without passing `--app` every time.
-
----
-
-## Step 2 — Set Environment Variables
-
-Create a `.env` file in your project root:
-
-```env
-SECURENOW_APPID=my-app
-SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_NO_UUID=1
-```
-
-### All Environment Variables
-
-| Variable | Purpose | Default |
-|----------|---------|---------|
-| `SECURENOW_APPID` | Your app key (from `securenow apps create`) | **Required** |
-| `SECURENOW_INSTANCE` | OTLP collector endpoint | `https://freetrial.securenow.ai:4318` |
-| `SECURENOW_LOGGING_ENABLED` | Auto-forward all `console.*` calls as OTLP logs | `1` |
-| `SECURENOW_NO_UUID` | Keep `service.name` equal to your app key (no UUID suffix) | `0` |
-| `SECURENOW_CAPTURE_BODY` | Capture request/response bodies in traces | `1` |
-| `SECURENOW_CAPTURE_MULTIPART` | Capture multipart field/file metadata | `1` |
-| `SECURENOW_MAX_BODY_SIZE` | Max captured body size in bytes | `10240` |
-| `SECURENOW_SENSITIVE_FIELDS` | Extra field names to auto-redact (comma-separated) | — |
-| `SECURENOW_TRUSTED_PROXIES` | Comma-separated proxy IPs for X-Forwarded-For | — |
-| `SECURENOW_DISABLE_INSTRUMENTATIONS` | OTel instrumentation packages to skip (comma-separated) | — |
-| `SECURENOW_HIDE_BANNER` | Hide the free-trial testing banner | `0` |
-| `SECURENOW_STRICT` | Exit if `APPID` is missing in PM2 cluster mode | `0` |
-| `OTEL_LOG_LEVEL` | OTel diagnostic level (`debug`, `info`, `warn`, `error`, `none`) | `none` |
-
-### Production Example
-
-```env
-SECURENOW_APPID=my-app-prod
-SECURENOW_INSTANCE=https://collector.yourcompany.com:4318
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_NO_UUID=1
-SECURENOW_CAPTURE_BODY=1
-SECURENOW_CAPTURE_MULTIPART=1
-SECURENOW_TRUSTED_PROXIES=10.0.0.1,10.0.0.2
-NODE_ENV=production
-```
-
----
-
-## Step 3 — Plug SecureNow into Your Framework
-
-There are two ways to initialize SecureNow. Both work with every framework.
-
-**Option A — Zero code changes (recommended)**
-
-```bash
-node -r securenow/register app.js
-```
-
-**Option B — Add one line to your entry file**
-
-```javascript
-require('securenow/register'); // Must be the very first line
-```
-
-Pick **one** method. Both do the same thing. Below are complete, copy-paste examples for each framework.
-
----
-
-### Express.js
-
-```bash
-npm install securenow express
-```
-
-```javascript
-// app.js
-'use strict';
-require('securenow/register');
-const express = require('express');
-
-const app = express();
-app.use(express.json());
-
-app.get('/health', (req, res) => {
-  res.json({ status: 'ok' });
-});
-
-app.post('/tasks', (req, res) => {
-  const { title } = req.body;
-  if (!title) return res.status(400).json({ error: 'title is required' });
-  console.log('Created task:', title);
-  res.status(201).json({ id: '1', title });
-});
-
-app.listen(3000, () => {
-  console.log('Express app running on port 3000');
-});
-```
-
-```bash
-node app.js
-```
-
-| Feature | Supported |
-|---------|-----------|
-| Traces | Yes |
-| Logs | Yes |
-| Body Capture | Yes - default on |
-
----
-
-### Fastify
-
-```bash
-npm install securenow fastify
-```
-
-```javascript
-// app.js
-'use strict';
-require('securenow/register');
-const Fastify = require('fastify');
-
-const fastify = Fastify({ logger: true });
-
-fastify.get('/health', async () => {
-  return { status: 'ok' };
-});
-
-fastify.post('/tasks', {
-  schema: {
-    body: { type: 'object', required: ['title'], properties: { title: { type: 'string' } } }
-  }
-}, async (request) => {
-  const { title } = request.body;
-  console.log('Created task:', title);
-  return { id: '1', title };
-});
-
-fastify.listen({ port: 3000 }, (err) => {
-  if (err) { fastify.log.error(err); process.exit(1); }
-  console.log('Fastify app running on port 3000');
-});
-```
-
-```bash
-node app.js
-```
-
-| Feature | Supported |
-|---------|-----------|
-| Traces | Yes |
-| Logs | Yes |
-| Body Capture | Yes - default on; set `SECURENOW_CAPTURE_BODY=0` only for a local stream conflict |
-
----
-
-### Koa
-
-```bash
-npm install securenow koa @koa/router koa-bodyparser
-```
-
-```javascript
-// app.js
-'use strict';
-require('securenow/register');
-const Koa = require('koa');
-const Router = require('@koa/router');
-const bodyParser = require('koa-bodyparser');
-
-const app = new Koa();
-const router = new Router();
-
-router.get('/health', (ctx) => {
-  ctx.body = { status: 'ok' };
-});
-
-router.post('/tasks', (ctx) => {
-  const { title } = ctx.request.body;
-  if (!title) { ctx.status = 400; ctx.body = { error: 'title is required' }; return; }
-  console.log('Created task:', title);
-  ctx.status = 201;
-  ctx.body = { id: '1', title };
-});
-
-app.use(bodyParser());
-app.use(router.routes());
-app.use(router.allowedMethods());
-
-app.listen(3000, () => {
-  console.log('Koa app running on port 3000');
-});
-```
-
-```bash
-node app.js
-```
-
-| Feature | Supported |
-|---------|-----------|
-| Traces | Yes |
-| Logs | Yes |
-| Body Capture | Yes - default on |
-
----
-
-### NestJS
-
-```bash
-npm install securenow
-```
-
-NestJS uses TypeScript. Create an `instrument.js` file in your project root to load SecureNow before anything else:
-
-```javascript
-// instrument.js
-require('securenow/register');
-```
-
-Your NestJS entry file stays unchanged:
-
-```typescript
-// src/main.ts
-import 'reflect-metadata';
-import { NestFactory } from '@nestjs/core';
-import { Module, Controller, Get, Post, Body } from '@nestjs/common';
-
-@Controller()
-class AppController {
-  @Get('health')
-  health() {
-    return { status: 'ok' };
-  }
-
-  @Post('tasks')
-  create(@Body() body: { title: string }) {
-    console.log('Created task:', body.title);
-    return { id: '1', title: body.title };
-  }
-}
-
-@Module({ controllers: [AppController] })
-class AppModule {}
-
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  await app.listen(3000);
-  console.log('NestJS app running on port 3000');
-}
-bootstrap();
-```
-
-**Development (ts-node):**
-
-```bash
-node -r ./instrument.js -r ts-node/register src/main.ts
-```
-
-**Production (compiled):**
-
-```bash
-node -r ./instrument.js dist/main.js
-```
-
-Add both to your `package.json`:
-
-```json
-{
-  "scripts": {
-    "start:dev": "node -r ./instrument.js -r ts-node/register src/main.ts",
-    "start": "node -r ./instrument.js dist/main.js"
-  }
-}
-```
-
-| Feature | Supported |
-|---------|-----------|
-| Traces | Yes |
-| Logs | Yes |
-| Body Capture | Yes - default on |
-
----
-
-### Hapi
-
-```bash
-npm install securenow @hapi/hapi
-```
-
-```javascript
-// app.js
-'use strict';
-require('securenow/register');
-const Hapi = require('@hapi/hapi');
-
-const init = async () => {
-  const server = Hapi.server({ port: 3000, host: '0.0.0.0' });
-
-  server.route({
-    method: 'GET', path: '/health',
-    handler: () => ({ status: 'ok' })
-  });
-
-  server.route({
-    method: 'POST', path: '/tasks',
-    options: { payload: { parse: true, allow: 'application/json' } },
-    handler: (request, h) => {
-      const { title } = request.payload || {};
-      if (!title) return h.response({ error: 'title is required' }).code(400);
-      console.log('Created task:', title);
-      return h.response({ id: '1', title }).code(201);
-    }
-  });
-
-  await server.start();
-  console.log('Hapi app running on port 3000');
-};
-
-init().catch((err) => { console.error(err); process.exit(1); });
-```
-
-```bash
-node app.js
-```
-
-| Feature | Supported |
-|---------|-----------|
-| Traces | Yes |
-| Logs | Yes |
-| Body Capture | Yes - default on; set `SECURENOW_CAPTURE_BODY=0` only for a local stream conflict |
-
----
-
-### h3 (UnJS / Nitro)
-
-```bash
-npm install securenow h3
-```
-
-```javascript
-// app.js
-'use strict';
-require('securenow/register');
-const { createApp, createRouter, defineEventHandler, readBody, setResponseStatus, toNodeListener } = require('h3');
-const http = require('http');
-
-const app = createApp();
-const router = createRouter();
-
-router.get('/health', defineEventHandler(() => {
-  return { status: 'ok' };
-}));
-
-router.post('/tasks', defineEventHandler(async (event) => {
-  const body = await readBody(event);
-  if (!body?.title) { setResponseStatus(event, 400); return { error: 'title is required' }; }
-  console.log('Created task:', body.title);
-  setResponseStatus(event, 201);
-  return { id: '1', title: body.title };
-}));
-
-app.use(router);
-
-http.createServer(toNodeListener(app)).listen(3000, () => {
-  console.log('h3 app running on port 3000');
-});
-```
-
-```bash
-node app.js
-```
-
-| Feature | Supported |
-|---------|-----------|
-| Traces | Yes |
-| Logs | Yes |
-| Body Capture | Yes - default on |
-
----
-
-### Polka
-
-```bash
-npm install securenow polka
-```
-
-Polka has no built-in body parser, so add a simple middleware:
-
-```javascript
-// app.js
-'use strict';
-require('securenow/register');
-const polka = require('polka');
-
-function jsonBody(req, res, next) {
-  if (req.method === 'GET' || req.method === 'DELETE') return next();
-  let data = '';
-  req.on('data', chunk => { data += chunk; });
-  req.on('end', () => {
-    try { req.body = JSON.parse(data); } catch { req.body = {}; }
-    next();
-  });
-}
-
-function sendJson(res, status, body) {
-  res.writeHead(status, { 'Content-Type': 'application/json' });
-  res.end(JSON.stringify(body));
-}
-
-polka()
-  .use(jsonBody)
-  .get('/health', (req, res) => sendJson(res, 200, { status: 'ok' }))
-  .post('/tasks', (req, res) => {
-    const { title } = req.body;
-    if (!title) return sendJson(res, 400, { error: 'title is required' });
-    console.log('Created task:', title);
-    sendJson(res, 201, { id: '1', title });
-  })
-  .listen(3000, () => {
-    console.log('Polka app running on port 3000');
-  });
-```
-
-```bash
-node app.js
-```
-
-| Feature | Supported |
-|---------|-----------|
-| Traces | Yes |
-| Logs | Yes |
-| Body Capture | Yes - default on |
-
----
-
-### Micro / Raw HTTP
-
-For apps using the bare `http` module:
-
-```bash
-npm install securenow
-```
-
-```javascript
-// app.js
-'use strict';
-require('securenow/register');
-const http = require('http');
-
-function sendJson(res, status, body) {
-  res.writeHead(status, { 'Content-Type': 'application/json' });
-  res.end(JSON.stringify(body));
-}
-
-function readBody(req) {
-  return new Promise((resolve) => {
-    let data = '';
-    req.on('data', chunk => { data += chunk; });
-    req.on('end', () => {
-      try { resolve(JSON.parse(data)); } catch { resolve({}); }
-    });
-  });
-}
-
-async function handler(req, res) {
-  const url = new URL(req.url, `http://${req.headers.host}`);
-
-  if (url.pathname === '/health' && req.method === 'GET') {
-    return sendJson(res, 200, { status: 'ok' });
-  }
-
-  if (url.pathname === '/tasks' && req.method === 'POST') {
-    const body = await readBody(req);
-    if (!body.title) return sendJson(res, 400, { error: 'title is required' });
-    console.log('Created task:', body.title);
-    return sendJson(res, 201, { id: '1', title: body.title });
-  }
-
-  sendJson(res, 404, { error: 'Not found' });
-}
-
-http.createServer(handler).listen(3000, () => {
-  console.log('HTTP app running on port 3000');
-});
-```
-
-```bash
-node app.js
-```
-
-| Feature | Supported |
-|---------|-----------|
-| Traces | Yes |
-| Logs | Yes |
-| Body Capture | Yes - default on |
-
----
-
-### Hono
-
-```bash
-npm install securenow hono @hono/node-server
-```
-
-Hono uses ESM, so load SecureNow via the `-r` flag (do **not** use `require()` in `.mjs` files):
-
-```javascript
-// app.mjs
-import { serve } from '@hono/node-server';
-import { Hono } from 'hono';
-
-const app = new Hono();
-
-app.get('/health', (c) => c.json({ status: 'ok' }));
-
-app.post('/tasks', async (c) => {
-  const body = await c.req.json();
-  if (!body.title) return c.json({ error: 'title is required' }, 400);
-  console.log('Created task:', body.title);
-  return c.json({ id: '1', title: body.title }, 201);
-});
-
-serve({ fetch: app.fetch, port: 3000 }, () => {
-  console.log('Hono app running on port 3000');
-});
-```
-
-```bash
-node -r securenow/register app.mjs
-```
-
-| Feature | Supported |
-|---------|-----------|
-| Traces | Yes |
-| Logs | Yes |
-| Body Capture | Yes - default on; set `SECURENOW_CAPTURE_BODY=0` only for a local stream conflict |
-
----
-
-### Feathers
-
-```bash
-npm install securenow @feathersjs/feathers @feathersjs/express @feathersjs/errors
-```
-
-Feathers uses Express as its transport, so the setup is identical:
-
-```javascript
-// app.js
-'use strict';
-require('securenow/register');
-const feathers = require('@feathersjs/feathers');
-const express = require('@feathersjs/express');
-const errors = require('@feathersjs/errors');
-
-class TaskService {
-  constructor() { this.tasks = []; this.nextId = 1; }
-
-  async find() { return this.tasks; }
-
-  async create(data) {
-    if (!data.title) throw new errors.BadRequest('title is required');
-    const task = { id: String(this.nextId++), title: data.title };
-    this.tasks.push(task);
-    console.log('Created task:', task.id);
-    return task;
-  }
-}
-
-const app = express(feathers());
-app.use(express.json());
-app.configure(express.rest());
-
-app.get('/health', (req, res) => res.json({ status: 'ok' }));
-app.use('/tasks', new TaskService());
-app.use(express.errorHandler());
-
-app.listen(3000, () => {
-  console.log('Feathers app running on port 3000');
-});
-```
-
-```bash
-node app.js
-```
-
-| Feature | Supported |
-|---------|-----------|
-| Traces | Yes |
-| Logs | Yes |
-| Body Capture | Yes - default on |
-
----
-
-### Next.js
-
-```bash
-npm install securenow
-```
-
-Create `instrumentation.ts` (or `.js`) in your project root (or `src/` if you use that layout):
-
-```typescript
-// instrumentation.ts
-export async function register() {
-  if (process.env.NEXT_RUNTIME === 'nodejs') {
-    await import('securenow/register');
-  }
-}
-```
-
-Add to `.env.local`:
-
-```env
-SECURENOW_APPID=my-nextjs-app
-SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_NO_UUID=1
-```
-
-**Or scaffold it automatically:**
-
-```bash
-npx securenow init
-```
-
-This creates both `instrumentation.ts` and `.env.local` for you.
-
-```bash
-npm run dev
-```
-
-| Feature | Supported |
-|---------|-----------|
-| Traces | Yes |
-| Logs | Yes |
-| Body Capture | Yes |
-
-See the [full Next.js guide](./NEXTJS-SETUP-COMPLETE.md) for App Router, middleware, and server actions.
-
----
-
-## Step 4 — Verify It Works
-
-After starting your app, you should see this in the console:
-
-```
-[securenow] OTel SDK started → https://freetrial.securenow.ai:4318/v1/traces
-[securenow] 📋 Logging: ENABLED → https://freetrial.securenow.ai:4318/v1/logs
-```
-
-Send a test request:
-
-```bash
-curl http://localhost:3000/health
-```
-
-Then check traces from the CLI:
-
-```bash
-npx securenow traces --app my-app
-```
-
-Traces and logs should appear within seconds.
-
----
-
-## Step 5 — CLI Command Reference
-
-The SecureNow CLI is your terminal command center. Below is every command organized by workflow.
-
-### Authentication
-
-| Command | What It Does |
-|---------|-------------|
-| `securenow login` | Opens browser to authenticate (global session) |
-| `securenow login --token <T>` | Authenticate with a token (for CI/CD or headless servers) |
-| `securenow login --local` | Save credentials to this project only (per-project session) |
-| `securenow logout` | Clear stored credentials |
-| `securenow logout --local` | Clear project-local credentials only |
-| `securenow whoami` | Show current session (email, API URL, auth source, expiry, default app) |
-
-**Per-project credentials:** Use `--local` to maintain separate logins for different projects on the same machine. The CLI resolves credentials in order: `SECURENOW_TOKEN` env var → project `.securenow/credentials.json` → global `~/.securenow/credentials.json`.
-
-### App Management
-
-| Command | What It Does |
-|---------|-------------|
-| `securenow apps list` | List all your applications |
-| `securenow apps create <name>` | Create a new app (interactive instance picker) |
-| `securenow apps create <name> --hosts api.example.com` | Create with host binding |
-| `securenow apps info <id>` | Show app details + env variables |
-| `securenow apps delete <id>` | Delete an app |
-| `securenow apps default <key>` | Set default app for CLI commands |
-| `securenow apps discover --domain example.com` | Discover subdomains and add as apps |
-| `securenow apps scan --yes` | Scan all app domains for new subdomains |
-
-### Observe — Traces & Logs
-
-| Command | What It Does |
-|---------|-------------|
-| `securenow traces` | List recent traces |
-| `securenow traces --app my-app --limit 50` | Filtered trace list |
-| `securenow traces show <traceId>` | Show all spans in a trace |
-| `securenow traces analyze <traceId>` | AI-powered security analysis of a trace |
-| `securenow logs` | List recent logs |
-| `securenow logs --app my-app --minutes 30 --level ERROR` | Filtered logs |
-| `securenow logs trace <traceId>` | Show all logs for a specific trace |
-| `securenow analytics --app my-app` | Response code breakdown (2xx/3xx/4xx/5xx) |
-| `securenow status` | Dashboard overview (apps, alerts, protection status) |
-
-### Detect & Respond — Alerts, Notifications, False Positives
-
-| Command | What It Does |
-|---------|-------------|
-| `securenow alerts rules` | List alert rules |
-| `securenow alerts rules show <id>` | One rule (all-apps vs explicit keys) |
-| `securenow alerts rules update <id> --applications-all` | All current & future apps |
-| `securenow alerts rules update <id> --apps k1,k2` | Explicit app keys only |
-| `securenow alerts channels` | List alert channels (email, webhook, Slack) |
-| `securenow alerts history --limit 50` | View past triggered alerts |
-| `securenow notifications` | List notifications |
-| `securenow notifications unread` | Show unread count |
-| `securenow notifications read <id>` | Mark one as read |
-| `securenow notifications read-all` | Mark all as read |
-| `securenow fp` / `fp list` | List FP exclusion rules |
-| `securenow fp show <id>` | Rule detail (conditions, scope, match mode) |
-| `securenow fp create --conditions '[...]'` | Create raw exclusion rule |
-| `securenow fp create --path /api/events --method POST --path-safe standard` | Safe-value preset helper |
-| `securenow fp edit <id> [--active true\|false] [--conditions '[...]']` | Edit existing rule |
-| `securenow fp delete <id> [--yes]` | Delete rule |
-| `securenow fp test-body '<json>' --conditions '[...]'` | Test conditions against a payload |
-| `securenow fp dry-run --conditions '[...]'` | Dry-run against last 3 days of live traces |
-| `securenow fp ai-fill --description "..."` | AI-generate exclusion conditions |
-| `securenow fp mark <notification-id> <ip>` | Mark an IP as FP on a notification in one shot |
-
-### Investigate — IP Intelligence & Forensics
-
-| Command | What It Does |
-|---------|-------------|
-| `securenow ip <ip-address>` | Full IP intelligence report (country, ISP, abuse score, risk factors) |
-| `securenow ip traces <ip-address>` | Show all traces from a specific IP |
-| `securenow forensics "<query>"` | **Chat with your data** — natural language to SQL (see below) |
-| `securenow forensics library` | View saved forensic queries |
-| `securenow api-map` | List all discovered API endpoints |
-| `securenow api-map stats` | API map statistics |
-
-### Remediation — Blocklist, Allowlist & Trusted IPs
-
-| Command | What It Does |
-|---------|-------------|
-| `securenow blocklist` | List all blocked IPs |
-| `securenow blocklist add <ip>` | Block an IP address |
-| `securenow blocklist add <cidr> --reason "brute force"` | Block a CIDR range with reason |
-| `securenow blocklist remove <id>` | Unblock an IP |
-| `securenow blocklist stats` | Blocklist statistics |
-| `securenow allowlist` | List allowed IPs (restrict mode) |
-| `securenow allowlist add <ip> --label "office" --reason "corporate VPN"` | Allow an IP |
-| `securenow allowlist remove <id>` | Remove from allowlist |
-| `securenow trusted` | List trusted IPs |
-| `securenow trusted add <ip> --label "office"` | Add a trusted IP |
-| `securenow trusted remove <id>` | Remove a trusted IP |
-
-### Firewall Runtime
-
-| Command | What It Does |
-|---------|-------------|
-| `securenow firewall status` | Active layers, sync time, blocked count |
-| `securenow firewall test-ip <ip>` | Check if an IP would be blocked |
-| `securenow run --firewall-only <script>` | Preload firewall **without** OTel tracing (zero overhead) |
-
-### Telemetry from the Shell
-
-Mirrors the SDK's `getLogger()` and tracing APIs for scripts, cron, and CI.
-
-| Command | What It Does |
-|---------|-------------|
-| `securenow log send "<msg>" [--level info\|warn\|error] [--attrs k=v]` | Emit an OTLP log record |
-| `securenow test-span [<name>]` | Emit a test span to verify collector connectivity |
-
-### Utilities
-
-SDK helpers surfaced as CLI commands.
-
-| Command | What It Does |
-|---------|-------------|
-| `securenow redact '<json>' [--fields f1,f2]` | Redact sensitive fields (accepts `@file.json`) |
-| `securenow cidr match <ip> <cidrs>` | IP vs. CIDR list (exit 0 hit / 2 miss) |
-| `securenow cidr parse <cidr>` | Parse CIDR — network, broadcast, mask, size |
-| `securenow env [--json]` | Show resolved config (service name, endpoints, env vars) |
-| `securenow doctor [--json]` | Probe OTLP + API endpoints, check config sanity |
-
-### Settings & Config
-
-| Command | What It Does |
-|---------|-------------|
-| `securenow config set <key> <value>` | Set a config value |
-| `securenow config get [key]` | Get a config value (or show all) |
-| `securenow config path` | Show config + credentials file paths |
-| `securenow instances` | List ClickHouse instances |
-| `securenow instances test <id>` | Test an instance connection |
-| `securenow version` | Show CLI version |
-
-### Global Flags
-
-Every command supports:
-
-| Flag | Effect |
-|------|--------|
-| `--json` | Output raw JSON (pipe to `jq`, scripts, etc.) |
-| `--help` | Show help for any command |
-| `--app <key>` | Override the default app for this command |
-
----
-
-## Step 6 — Forensics Chat — Ask Questions in Plain English
-
-The `securenow forensics` command lets you **ask security questions in plain English**. SecureNow translates your question to SQL, runs it against your ClickHouse traces database, and returns the results.
-
-### How to Use
-
-```bash
-npx securenow forensics "your question here"
-```
-
-### Example Queries
-
-**Find suspicious activity:**
-
-```bash
-npx securenow forensics "show me all 401 responses in the last hour"
-```
-
-**Hunt for attackers:**
-
-```bash
-npx securenow forensics "which IPs sent the most requests in the last 24 hours"
-```
-
-**Find slow endpoints:**
-
-```bash
-npx securenow forensics "show the slowest API endpoints this week"
-```
-
-**Investigate a specific IP:**
-
-```bash
-npx securenow forensics "show all requests from 185.220.101.1 in the last 7 days"
-```
-
-**Error analysis:**
-
-```bash
-npx securenow forensics "count 500 errors per endpoint in the last 24 hours"
-```
-
-**Brute force detection:**
-
-```bash
-npx securenow forensics "find IPs that sent more than 100 POST requests to /login today"
-```
-
-**Data exfiltration patterns:**
-
-```bash
-npx securenow forensics "show requests with response bodies larger than 1MB"
-```
-
-### How It Works
-
-1. You type a question in English
-2. SecureNow's AI converts it to a SQL query
-3. The query runs against your ClickHouse traces database
-4. Results are displayed as a table in your terminal
-
-The CLI shows you both the generated SQL and the results:
-
-```
-  Generated SQL
-
-    SELECT ClientIP, count() as cnt FROM traces
-    WHERE Timestamp > now() - INTERVAL 1 HOUR AND ResponseStatusCode = 401
-    GROUP BY ClientIP ORDER BY cnt DESC LIMIT 20
-
-  Results (5 rows)
-
-    ClientIP          cnt
-    185.220.101.1     342
-    45.134.26.8       128
-    ...
-```
-
-### Save & Reuse Queries
-
-View your saved query library:
-
-```bash
-npx securenow forensics library
-```
-
-### Output as JSON
-
-Pipe forensic results to scripts or other tools:
-
-```bash
-npx securenow forensics "top 10 IPs by request count today" --json | jq '.result'
-```
-
----
-
-## Step 7 — Block & Manage IPs
-
-SecureNow gives you full IP lifecycle management — investigate, block, trust, and audit.
-
-### Investigate an IP
-
-Before blocking, look up the IP's intelligence:
-
-```bash
-npx securenow ip 185.220.101.1
-```
-
-Output:
-
-```
-  IP Intelligence: 185.220.101.1
-
-    Country       Germany (DE)
-    ISP           Tor Exit Node
-    Usage Type    Hosting
-    Abuse Score   100/100
-    Malicious     Yes
-    Bot           Yes
-    Total Reports 4,521
-
-  Risk Factors
-    • Known Tor exit node
-    • High abuse confidence score
-    • Associated with brute force attacks
-
-  Attack Types
-    • SSH Brute Force
-    • Web Application Attack
-    • Port Scanning
-```
-
-### See What That IP Did
-
-```bash
-npx securenow ip traces 185.220.101.1
-```
-
-Shows all traced requests from that IP — method, status code, URL, duration, and time.
-
-### Block an IP
-
-```bash
-npx securenow blocklist add 185.220.101.1 --reason "tor exit node, brute force"
-```
-
-Block a CIDR range:
-
-```bash
-npx securenow blocklist add 185.220.101.0/24 --reason "malicious subnet"
-```
-
-Block with an expiration:
-
-```bash
-npx securenow blocklist add 45.134.26.8 --reason "rate limiting" --duration 24h
-```
-
-### View All Blocked IPs
-
-```bash
-npx securenow blocklist
-```
-
-Output:
-
-```
-  ID           IP/CIDR            Reason                    Source     Added        Expires
-  abc123...    185.220.101.1      tor exit node             manual     2 hours ago  permanent
-  def456...    185.220.101.0/24   malicious subnet          manual     1 hour ago   permanent
-  ghi789...    45.134.26.8        rate limiting             manual     30 min ago   2024-01-16
-```
-
-### Unblock an IP
-
-```bash
-npx securenow blocklist remove abc123
-```
-
-### Blocklist Statistics
-
-```bash
-npx securenow blocklist stats
-```
-
-Shows total active blocks, removed blocks, manual vs automated counts, and active automation rules.
-
-### Trust an IP (Whitelist)
-
-Trusted IPs bypass security detections:
-
-```bash
-npx securenow trusted add 203.0.113.50 --label "office VPN"
-```
-
-List trusted IPs:
-
-```bash
-npx securenow trusted
-```
-
-Remove a trusted IP:
-
-```bash
-npx securenow trusted remove <id>
-```
-
-### Full Investigation → Block Workflow
-
-Here is the typical workflow for handling a suspicious IP:
-
-```bash
-# 1. Check forensics for anomalies
-npx securenow forensics "IPs with more than 50 failed login attempts today"
-
-# 2. Pick a suspicious IP and investigate
-npx securenow ip 185.220.101.1
-
-# 3. See exactly what it did
-npx securenow ip traces 185.220.101.1
-
-# 4. Block it
-npx securenow blocklist add 185.220.101.1 --reason "brute force login attempts"
-
-# 5. Verify it's blocked
-npx securenow blocklist
-```
-
-### Enforce the Blocklist on Your App (Firewall)
-
-Once you've built a blocklist, enforce it at your application layer — automatically, with zero code changes:
-
-```bash
-# Add your API key to .env
-SECURENOW_API_KEY=snk_live_abc123...
-```
-
-Restart your app. The firewall syncs the blocklist every 60 seconds and blocks matching IPs with a 403 response:
-
-```
-[securenow] Firewall: ENABLED
-[securenow] Firewall: Layer 1 (HTTP 403)      active
-[securenow] Firewall: synced 142 blocked IPs
-```
-
-Enable additional layers for defense in depth:
-
-```bash
-# TCP-level blocking (zero bytes sent back)
-SECURENOW_FIREWALL_TCP=1
-
-# OS-level blocking (iptables/nftables, Linux only)
-SECURENOW_FIREWALL_IPTABLES=1
-
-# Cloud WAF blocking (Cloudflare, AWS WAF, GCP Cloud Armor)
-SECURENOW_FIREWALL_CLOUD=cloudflare
-```
-
-Check firewall status:
-
-```bash
-npx securenow firewall status
-npx securenow firewall test-ip 185.220.101.1
-```
-
-See the [Firewall Guide](FIREWALL-GUIDE.md) for the full reference.
-
----
-
-## Step 8 — Monitor, Detect & Respond
-
-### Daily Monitoring
-
-```bash
-# Quick overview of all your apps
-npx securenow status
-
-# Check for unread alerts
-npx securenow notifications unread
-
-# List open security issues
-npx securenow issues --status open
-```
-
-### Respond to an Issue
-
-```bash
-# Read the full issue detail (includes AI analysis)
-npx securenow issues show <id>
-
-# If it's resolved, mark it
-npx securenow issues resolve <id>
-```
-
-### AI Trace Analysis
-
-Let SecureNow's AI analyze a suspicious trace for security issues:
-
-```bash
-npx securenow traces analyze <traceId>
-```
-
-Returns a summary, risk level, specific security issues found, and recommended actions.
-
-### Set Up Alerts
-
-Configure alert rules and channels from the [dashboard](https://app.securenow.ai/dashboard), then monitor from the CLI:
-
-```bash
-# List your alert rules
-npx securenow alerts rules
-
-# Show one rule / set application scope (all apps vs explicit keys)
-npx securenow alerts rules show <rule-id>
-npx securenow alerts rules update <rule-id> --applications-all
-npx securenow alerts rules update <rule-id> --apps key1,key2
-
-# List alert channels (email, Slack, webhook)
-npx securenow alerts channels
-
-# View alert history
-npx securenow alerts history --limit 20
-```
-
----
-
-## Deployment
-
-### PM2 Setup (All Frameworks)
-
-```javascript
-// ecosystem.config.cjs
-module.exports = {
-  apps: [{
-    name: 'my-app',
-    script: './app.js',
-    node_args: '-r securenow/register',
-    env: {
-      SECURENOW_APPID: 'my-app',
-      SECURENOW_INSTANCE: 'https://freetrial.securenow.ai:4318',
-      SECURENOW_LOGGING_ENABLED: '1',
-      SECURENOW_NO_UUID: '1',
-      SECURENOW_CAPTURE_BODY: '1',
-      PORT: 3000,
-    }
-  }]
-};
-```
-
-```bash
-pm2 start ecosystem.config.cjs
-```
-
-**NestJS (TypeScript):**
-
-```javascript
-{
-  name: 'my-nestjs-app',
-  script: 'dist/main.js',
-  node_args: '-r ./instrument.js',
-  env: { /* same as above */ }
-}
-```
-
-**Hono (ESM `.mjs`):**
-
-```javascript
-{
-  name: 'my-hono-app',
-  script: 'app.mjs',
-  node_args: '-r securenow/register',
-  env: {
-    SECURENOW_CAPTURE_BODY: '1',
-    SECURENOW_CAPTURE_MULTIPART: '1',
-    /* ... other vars ... */
-  }
-}
-```
-
-### Docker
-
-```dockerfile
-FROM node:20-alpine
-WORKDIR /app
-COPY package*.json ./
-RUN npm install
-COPY . .
-
-ENV SECURENOW_APPID=my-app
-ENV SECURENOW_INSTANCE=https://collector:4318
-ENV SECURENOW_LOGGING_ENABLED=1
-ENV SECURENOW_NO_UUID=1
-
-EXPOSE 3000
-CMD ["node", "-r", "securenow/register", "app.js"]
-```
-
----
-
-## Compatibility Matrix
-
-| Framework | Traces | Logs | Body Capture | Init Method | Notes |
-|-----------|--------|------|--------------|-------------|-------|
-| Express | Yes | Yes | Yes | `require()` or `-r` | Fully compatible |
-| Fastify | Yes | Yes | Yes | `require()` or `-r` | Default on; set `SECURENOW_CAPTURE_BODY=0` only for a local stream conflict |
-| Koa | Yes | Yes | Yes | `require()` or `-r` | Needs `koa-bodyparser` |
-| NestJS | Yes | Yes | Yes | `instrument.js` + `-r ./instrument.js` | Create `instrument.js` with `require('securenow/register')` |
-| Hapi | Yes | Yes | Yes | `require()` or `-r` | Default on; set `SECURENOW_CAPTURE_BODY=0` only for a local stream conflict |
-| h3 | Yes | Yes | Yes | `require()` or `-r` | Uses `toNodeListener()` |
-| Polka | Yes | Yes | Yes | `require()` or `-r` | Needs manual body parser |
-| Micro/HTTP | Yes | Yes | Yes | `require()` or `-r` | Raw `http.createServer` |
-| Hono | Yes | Yes | Yes | `-r` flag only (ESM) | Default on; set `SECURENOW_CAPTURE_BODY=0` only for a local stream conflict |
-| Feathers | Yes | Yes | Yes | `require()` or `-r` | Express transport |
-| Next.js | Yes | Yes | Yes | `instrumentation.ts` | Use `securenow init` |
-
----
-
-## Troubleshooting
-
-### Traces not appearing
-
-1. Verify `SECURENOW_APPID` and `SECURENOW_INSTANCE` are set
-2. Set `SECURENOW_NO_UUID=1` so the dashboard matches your app key exactly
-3. Enable debug logging: `OTEL_LOG_LEVEL=debug node -r securenow/register app.js`
-
-### Logs not appearing
-
-1. Confirm `SECURENOW_LOGGING_ENABLED=1` is set
-2. Check that startup output shows `📋 Logging: ENABLED`
-3. Any `console.log` / `console.error` in your app automatically becomes an OTLP log record
-
-### ESM apps (.mjs / "type": "module")
-
-Use `NODE_OPTIONS="-r securenow/register"` or `node -r securenow/register app.mjs`.
-Do **not** add `require('securenow/register')` inside `.mjs` files.
-
-### Body capture crashes / empty payloads
-
-Body capture is on by default. If a specific framework version or plugin stack reports request-stream conflicts, set `SECURENOW_CAPTURE_BODY=0` as a local override for that app.
-
-### CLI says "Not logged in"
-
-```bash
-npx securenow login
-```
-
-Or re-authenticate with a token:
-
-```bash
-npx securenow login --token <YOUR_TOKEN>
-```
-
-Or set the env var directly:
-
-```bash
-SECURENOW_TOKEN=<YOUR_JWT> npx securenow whoami
-```
-
-### CLI says "Session expired"
-
-Tokens expire after a set period. Re-run `securenow login` to get a fresh session. Use `securenow whoami` to check which credential source is active.
-
----
-
-## Complete Documentation
-
-- [Express Guide](./EXPRESS-SETUP-GUIDE.md)
-- [Next.js Guide](./NEXTJS-SETUP-COMPLETE.md)
-- [Logging Guide](./LOGGING-GUIDE.md)
-- [Environment Variables](./ENVIRONMENT-VARIABLES.md)
-- [Body Capture](./REQUEST-BODY-CAPTURE.md)
-- [NPM README](../NPM_README.md)