securenow 5.18.0 → 6.0.0

package/docs/ALL-FRAMEWORKS-QUICKSTART.md

@@ -1,1339 +1,455 @@
-# 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.
-
----
-
-## 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 | `0` |
-| `SECURENOW_NO_UUID` | Keep `service.name` equal to your app key (no UUID suffix) | `0` |
-| `SECURENOW_CAPTURE_BODY` | Capture request/response bodies in traces | `0` |
-| `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=0
-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 — set `SECURENOW_CAPTURE_BODY=1` |
-
----
-
-### 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 | **No** — set `SECURENOW_CAPTURE_BODY=0` (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 — set `SECURENOW_CAPTURE_BODY=1` |
-
----
-
-### 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 — set `SECURENOW_CAPTURE_BODY=1` |
-
----
-
-### 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 | **No** — set `SECURENOW_CAPTURE_BODY=0` (payload 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 — set `SECURENOW_CAPTURE_BODY=1` |
-
----
-
-### 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 — set `SECURENOW_CAPTURE_BODY=1` |
-
----
-
-### 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 — set `SECURENOW_CAPTURE_BODY=1` |
-
----
-
-### 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 | **No** — set `SECURENOW_CAPTURE_BODY=0` (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 — set `SECURENOW_CAPTURE_BODY=1` |
-
----
-
-### 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 — Issues, Alerts, Notifications
-
-| Command | What It Does |
-|---------|-------------|
-| `securenow issues` | List security issues |
-| `securenow issues --status open` | Filter by status |
-| `securenow issues show <id>` | Full issue detail + AI analysis |
-| `securenow issues resolve <id>` | Mark issue as resolved |
-| `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 |
-
-### 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 & 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 trusted` | List trusted IPs |
-| `securenow trusted add <ip> --label "office"` | Add a trusted IP |
-| `securenow trusted remove <id>` | Remove a trusted IP |
-
-### 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: '0',  // Required for Hono
-    /* ... 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 | **No** | `require()` or `-r` | Set `SECURENOW_CAPTURE_BODY=0` |
-| 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 | **No** | `require()` or `-r` | Set `SECURENOW_CAPTURE_BODY=0` |
-| 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 | **No** | `-r` flag only (ESM) | Set `SECURENOW_CAPTURE_BODY=0` |
-| 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
-
-Set `SECURENOW_CAPTURE_BODY=0` for Fastify, Hapi, and Hono. These frameworks use custom stream handling that conflicts with the body capture hook.
-
-### 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)
+# Quick Start Guide - All Frameworks
+
+Fast setup guide for SecureNow with any Node.js framework in under 5 minutes.
+
+---
+
+## Universal Setup (Works with Any Framework)
+
+### Step 1: Install
+
+```bash
+npm install securenow
+```
+
+### Step 2: Set Environment Variables
+
+```bash
+export SECURENOW_APPID=my-app
+export SECURENOW_INSTANCE=http://localhost:4318
+export SECURENOW_LOGGING_ENABLED=1
+```
+
+### Step 3: Initialize
+
+**Option A: Using NODE_OPTIONS (No code changes)**
+
+```bash
+NODE_OPTIONS="-r securenow/register -r securenow/console-instrumentation" node app.js
+```
+
+**Option B: Add to your code**
+
+```javascript
+// At the very top of your main file
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+// Rest of your application
+```
+
+**Done!** Your app is now sending traces and logs.
+
+---
+
+## Framework-Specific Quick Starts
+
+### Express.js
+
+```javascript
+// app.js
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+const express = require('express');
+const app = express();
+
+app.get('/', (req, res) => {
+  console.log('Request received');
+  res.send('Hello World');
+});
+
+app.listen(3000);
+```
+
+**Run:**
+```bash
+SECURENOW_APPID=express-app \
+SECURENOW_INSTANCE=http://localhost:4318 \
+node app.js
+```
+
+[Full Express Guide →](./EXPRESS-SETUP-GUIDE.md)
+
+---
+
+### Next.js (App Router)
+
+**1. Create `instrumentation.ts` in project root:**
+
+```typescript
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    process.env.SECURENOW_LOGGING_ENABLED = '1';
+    await import('securenow/register');
+    await import('securenow/console-instrumentation');
+  }
+}
+```
+
+**2. Enable in `next.config.js`:**
+
+```javascript
+module.exports = {
+  experimental: {
+    instrumentationHook: true,
+  },
+};
+```
+
+**3. Create `.env.local`:**
+
+```env
+SECURENOW_APPID=nextjs-app
+SECURENOW_INSTANCE=http://localhost:4318
+```
+
+**4. Run:**
+
+```bash
+npm run dev
+```
+
+[Full Next.js Guide →](./NEXTJS-SETUP-COMPLETE.md)
+
+---
+
+### Fastify
+
+```javascript
+// server.js
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+const fastify = require('fastify')();
+
+fastify.get('/', async () => {
+  console.log('Route called');
+  return { hello: 'world' };
+});
+
+fastify.listen({ port: 3000 });
+```
+
+**Run:**
+```bash
+SECURENOW_APPID=fastify-app node server.js
+```
+
+---
+
+### NestJS
+
+```typescript
+// src/main.ts
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+}
+
+bootstrap();
+```
+
+**Run:**
+```bash
+npm run start
+```
+
+---
+
+### Koa
+
+```javascript
+// app.js
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+const Koa = require('koa');
+const app = new Koa();
+
+app.use(async ctx => {
+  console.log('Request received');
+  ctx.body = 'Hello World';
+});
+
+app.listen(3000);
+```
+
+---
+
+### Hapi
+
+```javascript
+// server.js
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+const Hapi = require('@hapi/hapi');
+
+const init = async () => {
+  const server = Hapi.server({ port: 3000 });
+  
+  server.route({
+    method: 'GET',
+    path: '/',
+    handler: () => {
+      console.log('Route called');
+      return 'Hello World';
+    }
+  });
+  
+  await server.start();
+};
+
+init();
+```
+
+---
+
+## Environment Variables
+
+### Minimal Setup
+
+```bash
+SECURENOW_APPID=my-app
+SECURENOW_INSTANCE=http://localhost:4318
+```
+
+### Recommended Setup
+
+```bash
+SECURENOW_APPID=my-app
+SECURENOW_INSTANCE=http://localhost:4318
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_CAPTURE_BODY=1
+NODE_ENV=development
+```
+
+### Production Setup
+
+```bash
+SECURENOW_APPID=my-app-prod
+SECURENOW_INSTANCE=http://collector.prod:4318
+OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-key
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_NO_UUID=1
+SECURENOW_CAPTURE_BODY=0
+NODE_ENV=production
+```
+
+[Complete Environment Variables Reference →](./ENVIRONMENT-VARIABLES.md)
+
+---
+
+## Logging Examples
+
+### Automatic Console Logging
+
+```javascript
+// All console methods are automatically captured
+console.log('Application started');
+console.info('User action', { userId: 123 });
+console.warn('Warning message');
+console.error('Error occurred', { error: 'details' });
+```
+
+### Direct Logger API
+
+```javascript
+const { getLogger } = require('securenow/tracing');
+const logger = getLogger('my-module', '1.0.0');
+
+logger.emit({
+  severityNumber: 9,
+  severityText: 'INFO',
+  body: 'Custom log message',
+  attributes: {
+    userId: 123,
+    action: 'login',
+  },
+});
+```
+
+[Complete Logging Guide →](./LOGGING-GUIDE.md)
+
+---
+
+## Request Body Capture
+
+Enable request body capture for debugging:
+
+```bash
+export SECURENOW_CAPTURE_BODY=1
+export SECURENOW_MAX_BODY_SIZE=10240  # 10KB
+```
+
+**Automatically redacted:** passwords, tokens, API keys, card numbers, etc.
+
+---
+
+## PM2 Setup
+
+```javascript
+// ecosystem.config.js
+module.exports = {
+  apps: [{
+    name: 'my-app',
+    script: './app.js',
+    instances: 4,
+    exec_mode: 'cluster',
+    node_args: '-r securenow/register -r securenow/console-instrumentation',
+    env: {
+      SECURENOW_APPID: 'my-app',
+      SECURENOW_INSTANCE: 'http://localhost:4318',
+      SECURENOW_LOGGING_ENABLED: '1',
+      SECURENOW_NO_UUID: '1',
+    }
+  }]
+};
+```
+
+```bash
+pm2 start ecosystem.config.js
+```
+
+---
+
+## Docker Setup
+
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm install
+
+COPY . .
+
+ENV SECURENOW_APPID=my-app
+ENV SECURENOW_INSTANCE=http://collector:4318
+ENV SECURENOW_LOGGING_ENABLED=1
+
+EXPOSE 3000
+CMD ["node", "app.js"]
+```
+
+---
+
+## Verification
+
+After starting your app, you should see:
+
+```
+[securenow] OTel SDK started → http://localhost:4318/v1/traces
+[securenow] 📋 Logging: ENABLED → http://localhost:4318/v1/logs
+[securenow] Console instrumentation installed
+```
+
+Check your observability backend - traces and logs should appear within seconds.
+
+---
+
+## Troubleshooting
+
+### Traces Not Appearing
+
+1. Check environment variables:
+   ```bash
+   echo $SECURENOW_APPID
+   echo $SECURENOW_INSTANCE
+   ```
+
+2. Enable debug logging:
+   ```bash
+   export OTEL_LOG_LEVEL=debug
+   node app.js
+   ```
+
+3. Verify collector is running:
+   ```bash
+   curl http://localhost:4318/v1/traces
+   ```
+
+### Logs Not Appearing
+
+1. Check logging is enabled:
+   ```bash
+   echo $SECURENOW_LOGGING_ENABLED  # Should be: 1
+   ```
+
+2. Verify console instrumentation loaded:
+   ```
+   [securenow] Console instrumentation installed
+   ```
+
+3. Check initialization order:
+   ```javascript
+   // ✅ Correct
+   require('securenow/register');
+   require('securenow/console-instrumentation');
+   const express = require('express');
+   
+   // ❌ Wrong
+   const express = require('express');
+   require('securenow/register');
+   ```
+
+---
+
+## Complete Documentation
+
+- **[NPM README](../NPM_README.md)** - Full npm package documentation
+- **[Express Guide](./EXPRESS-SETUP-GUIDE.md)** - Complete Express.js setup
+- **[Next.js Guide](./NEXTJS-SETUP-COMPLETE.md)** - Complete Next.js setup
+- **[Logging Guide](./LOGGING-GUIDE.md)** - Complete logging reference
+- **[Environment Variables](./ENVIRONMENT-VARIABLES.md)** - All variables explained
+
+---
+
+## What Gets Instrumented Automatically
+
+- HTTP/HTTPS (incoming and outgoing)
+- Express.js, Fastify, Koa, Hapi, Next.js
+- PostgreSQL, MySQL, MongoDB, Redis
+- GraphQL, gRPC
+- axios, fetch, node-fetch, got
+- And 50+ more libraries
+
+**No code changes needed!**
+
+---
+
+## Performance
+
+- **< 1% overhead:** Minimal CPU and memory impact
+- **Async processing:** No blocking of requests
+- **Batch export:** Efficient data transmission
+- **Production-ready:** Battle-tested in high-traffic applications
+
+---
+
+## Security
+
+- **Automatic redaction** of sensitive fields
+- **Configurable** field patterns
+- **No local storage** - data goes directly to your backend
+- **Open source** - audit the code yourself
+
+---
+
+## Support
+
+- **Documentation:** [GitHub Docs](https://github.com/your-repo/securenow-npm/tree/main/docs)
+- **Issues:** [GitHub Issues](https://github.com/your-repo/securenow-npm/issues)
+- **Examples:** [GitHub Examples](https://github.com/your-repo/securenow-npm/tree/main/examples)
+
+---
+
+**Get your app observable in under 5 minutes!** 🚀