securenow 6.0.2 → 6.1.0

package/SKILL-API.md

@@ -0,0 +1,634 @@
+# SecureNow SDK — Agent Skill
+
+Instrument any Node.js application with OpenTelemetry tracing, structured logging, request body capture, and a multi-layer IP firewall. Supports Express, Fastify, NestJS, Koa, Hapi, Next.js, Nuxt 3, Vite (browser), and raw `http.createServer` — with zero code changes for most setups.
+
+**CLI parity:** every capability exposed below (redaction, CIDR matching, log/span emission, firewall preload, config inspection) has an equivalent `securenow` CLI command. See [SKILL-CLI.md](./SKILL-CLI.md) for the terminal surface.
+
+## Installation
+
+```bash
+npm install securenow
+```
+
+### Install This Skill in Cursor
+
+Save this file as `.cursor/skills/securenow-api/SKILL.md` in your project. Your AI agent will auto-discover it whenever you ask about integrating securenow, configuring tracing, setting up the firewall, or instrumenting any framework.
+
+## Quick Start — Any Node.js Framework
+
+### 1. Set Environment Variables
+
+```bash
+# .env or .env.local
+SECURENOW_APPID=my-app
+SECURENOW_INSTANCE=https://your-collector:4318
+```
+
+### 2. Run With Instrumentation
+
+**Option A — CLI (recommended):**
+
+```bash
+npx securenow run src/index.js
+```
+
+**Option B — Node preload flag:**
+
+```bash
+node -r securenow/register src/index.js
+```
+
+**Option C — Auto-setup for Next.js:**
+
+```bash
+npx securenow init --key snk_live_...
+```
+
+That's it. Traces and logs flow to your OTLP collector. No code changes for Express, Fastify, NestJS, Koa, Hapi, and raw Node.
+
+### 3. Enable the Firewall (Optional)
+
+Add one more env var to auto-activate IP blocking:
+
+```bash
+SECURENOW_API_KEY=snk_live_abc123...
+```
+
+The firewall syncs your blocklist and enforces it on every request — zero code changes.
+
+---
+
+## Import Map
+
+| Import | Purpose | Type |
+|--------|---------|------|
+| `securenow` / `securenow/register` | Auto-register tracing + firewall (side-effect) | Preload (`-r`) |
+| `securenow/tracing` | Core OTel SDK; exports `getLogger()`, `isLoggingEnabled()` | CJS |
+| `securenow/nextjs` | Next.js instrumentation; exports `registerSecureNow(options?)` | CJS |
+| `securenow/nextjs-webpack-config` | Next.js config wrapper; exports `withSecureNow()`, `getSecureNowWebpackConfig()`, `EXTERNAL_PACKAGES` | CJS |
+| `securenow/nextjs-middleware` | Edge middleware body capture; exports `middleware()`, `redactSensitiveData()`, `DEFAULT_SENSITIVE_FIELDS` | CJS |
+| `securenow/nextjs-wrapper` | Route handler wrappers; exports `withSecureNow()`, `withSecureNowAsync()`, `captureRequestBody()`, `redactSensitiveData()` | CJS |
+| `securenow/nextjs-auto-capture` | Auto-patch Next request for body capture; exports `patchNextRequest()`, `safeBodyCapture()`, `redactSensitiveData()`, `isBodyCaptureEnabled()` | CJS |
+| `securenow/nuxt` | Nuxt 3 module (add to `modules` array) | ESM |
+| `securenow/firewall` | Standalone firewall; exports `init()`, `shutdown()`, `getStats()`, `getMatcher()`, `getAllowlistMatcher()` | CJS |
+| `securenow/firewall-only` | Preload: dotenv + firewall only, no tracing | Preload (`-r`) |
+| `securenow/cidr` | CIDR utilities; exports `createMatcher()`, `ipToInt()`, `parseCidr()`, `matchesCidr()` | CJS |
+| `securenow/resolve-ip` | IP resolution; exports `resolveClientIp()`, `resolveSocketIp()`, `isFromTrustedProxy()` | CJS |
+| `securenow/console-instrumentation` | Console→OTLP bridge; exports `originalConsole`, `restoreConsole()` | CJS |
+| `securenow/web-vite` | Browser OTel (document load, fetch, XHR, user interaction); default export `startSecurenowWeb()` | ESM |
+| `securenow/register-vite` | CJS bridge for Vite preload | CJS |
+
+---
+
+## Framework Integration Guides
+
+### Express / Fastify / NestJS / Koa / Hapi / Raw Node
+
+No code changes. Use the preload:
+
+```bash
+node -r securenow/register app.js
+```
+
+Or with the CLI:
+
+```bash
+npx securenow run app.js
+```
+
+**PM2:**
+
+```javascript
+// ecosystem.config.cjs
+module.exports = {
+  apps: [{
+    name: 'my-app',
+    script: './app.js',
+    instances: 4,
+    node_args: '-r securenow/register',
+    env: {
+      SECURENOW_APPID: 'my-app',
+      SECURENOW_INSTANCE: 'https://your-collector:4318',
+      SECURENOW_NO_UUID: '1',
+    },
+  }],
+};
+```
+
+**Docker:**
+
+```dockerfile
+ENV SECURENOW_APPID=my-app
+ENV SECURENOW_INSTANCE=https://your-collector:4318
+CMD ["node", "-r", "securenow/register", "app.js"]
+```
+
+---
+
+### Next.js
+
+Three files to touch:
+
+**1. `next.config.js`** (or `.mjs` / `.ts`):
+
+```javascript
+const { withSecureNow } = require('securenow/nextjs-webpack-config');
+
+module.exports = withSecureNow({
+  // your existing config
+});
+```
+
+`withSecureNow()` auto-detects Next.js version:
+- **>=15**: sets `serverExternalPackages`
+- **<15**: sets `experimental.serverComponentsExternalPackages` + `experimental.instrumentationHook` + webpack ignore rules
+
+**2. `instrumentation.ts`** (or `.js`, can be in `src/`):
+
+```typescript
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    const { registerSecureNow } = require('securenow/nextjs');
+    registerSecureNow();
+  }
+}
+```
+
+`registerSecureNow(options?)` accepts:
+
+```typescript
+interface RegisterOptions {
+  serviceName?: string;   // override SECURENOW_APPID
+  endpoint?: string;      // override SECURENOW_INSTANCE
+  noUuid?: boolean;       // override SECURENOW_NO_UUID
+  captureBody?: boolean;  // override SECURENOW_CAPTURE_BODY
+}
+```
+
+On Vercel it uses `@vercel/otel`; self-hosted uses vanilla `@opentelemetry/sdk-node`.
+
+**3. `.env.local`:**
+
+```bash
+SECURENOW_APPID=my-nextjs-app
+SECURENOW_INSTANCE=https://your-collector:4318
+```
+
+#### Next.js Body Capture
+
+**Option A — Auto-capture (recommended):**
+
+Add to your `instrumentation.ts`:
+
+```typescript
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    const { registerSecureNow } = require('securenow/nextjs');
+    registerSecureNow({ captureBody: true });
+    require('securenow/nextjs-auto-capture');
+  }
+}
+```
+
+**Option B — Middleware:**
+
+```typescript
+// middleware.ts
+export { middleware } from 'securenow/nextjs-middleware';
+export const config = { matcher: ['/api/:path*'] };
+```
+
+**Option C — Per-route wrapper:**
+
+```typescript
+import { withSecureNow } from 'securenow/nextjs-wrapper';
+
+export const POST = withSecureNow(async (req) => {
+  // handler
+});
+```
+
+#### Next.js with `securenow init`
+
+```bash
+npx securenow init --key snk_live_abc123...
+```
+
+Auto-detects Next.js, creates `instrumentation.ts`, suggests `next.config` changes, writes API key to `.env.local`.
+
+---
+
+### Nuxt 3
+
+**`nuxt.config.ts`:**
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['securenow/nuxt'],
+  securenow: {
+    // optional overrides (defaults come from env vars)
+  },
+});
+```
+
+**`.env`:**
+
+```bash
+SECURENOW_APPID=my-nuxt-app
+SECURENOW_INSTANCE=https://your-collector:4318
+```
+
+The Nuxt module auto-configures Nitro externals, runtime config, and a server plugin that sets up OTel tracing + logging + firewall.
+
+---
+
+### Vite / Browser
+
+```javascript
+import startSecurenowWeb from 'securenow/web-vite';
+
+startSecurenowWeb({
+  serviceName: 'my-frontend',
+  endpoint: 'https://your-collector:4318',
+});
+```
+
+Instruments document load, fetch, XMLHttpRequest, and user interactions with browser-side OpenTelemetry.
+
+---
+
+## Firewall — Multi-Layer IP Blocking
+
+The firewall auto-activates when `SECURENOW_API_KEY` is set. It syncs your blocklist from the SecureNow API and enforces it across up to four layers:
+
+```
+Layer 4: Cloud/Edge WAF    →  blocked at CDN (Cloudflare, AWS WAF, GCP Cloud Armor)
+Layer 3: OS Firewall       →  kernel-level DROP (iptables/nftables)
+Layer 2: TCP Socket        →  socket.destroy() before HTTP parsing
+Layer 1: HTTP Handler      →  403 JSON response (always active)
+```
+
+### Activate
+
+```bash
+# .env
+SECURENOW_API_KEY=snk_live_abc123...     # auto-activates Layer 1
+SECURENOW_FIREWALL_TCP=1                  # opt-in Layer 2
+SECURENOW_FIREWALL_IPTABLES=1             # opt-in Layer 3 (Linux, needs root)
+SECURENOW_FIREWALL_CLOUD=cloudflare       # opt-in Layer 4
+```
+
+### Firewall-Only Mode (No Tracing Overhead)
+
+```bash
+node -r securenow/firewall-only app.js
+
+# Or via the CLI (same effect)
+securenow run --firewall-only app.js
+```
+
+Loads only dotenv + firewall. No OpenTelemetry, no tracing, no external packages needed.
+
+### Programmatic Firewall API
+
+```javascript
+const firewall = require('securenow/firewall');
+
+await firewall.init({
+  apiKey: process.env.SECURENOW_API_KEY,
+  apiUrl: 'https://api.securenow.ai',
+  syncInterval: 300,        // full sync every 5 min
+  versionCheckInterval: 10, // lightweight version check every 10s
+  failMode: 'open',         // 'open' or 'closed'
+  statusCode: 403,
+  log: true,
+  tcp: false,
+  iptables: false,
+  cloud: null,              // 'cloudflare' | 'aws' | 'gcp'
+});
+
+const stats = firewall.getStats();
+const matcher = firewall.getMatcher();       // (ip) => boolean
+const allowMatcher = firewall.getAllowlistMatcher();
+
+await firewall.shutdown();
+```
+
+### Cloud WAF Providers
+
+**Cloudflare:**
+```bash
+SECURENOW_FIREWALL_CLOUD=cloudflare
+CLOUDFLARE_API_TOKEN=your-token
+CLOUDFLARE_ACCOUNT_ID=your-account-id
+```
+
+**AWS WAF:**
+```bash
+SECURENOW_FIREWALL_CLOUD=aws
+AWS_WAF_IP_SET_ID=your-ip-set-id
+# + standard AWS credentials (env, profile, or IAM role)
+```
+Requires peer dep: `npm install @aws-sdk/client-wafv2`
+
+**GCP Cloud Armor:**
+```bash
+SECURENOW_FIREWALL_CLOUD=gcp
+GCP_PROJECT_ID=your-project
+GCP_SECURITY_POLICY=your-policy-name
+```
+Requires peer dep: `npm install @google-cloud/compute`
+
+**Dry-run (log only, no actual WAF changes):**
+```bash
+SECURENOW_FIREWALL_CLOUD_DRY_RUN=1
+```
+
+---
+
+## Logging
+
+Logging is enabled by default (`SECURENOW_LOGGING_ENABLED=1`). Logs are exported to your OTLP collector alongside traces.
+
+### Get a Logger
+
+```javascript
+const { getLogger } = require('securenow/tracing');
+
+const logger = getLogger('my-module', '1.0.0');
+if (logger) {
+  logger.emit({ body: 'User login succeeded', severityText: 'INFO', attributes: { userId: '123' } });
+}
+```
+
+**CLI equivalent** (for shell scripts, cron, CI):
+
+```bash
+securenow log send "User login succeeded" --level info --attrs userId=123
+securenow test-span "ci.smoke-test"          # emit a span without booting the SDK
+```
+
+### Console Instrumentation
+
+When tracing is active, `console.log/warn/error` are automatically patched to emit OTLP log records correlated with the active trace span. To access the original console:
+
+```javascript
+const { originalConsole, restoreConsole } = require('securenow/console-instrumentation');
+originalConsole.log('This bypasses OTLP');
+restoreConsole(); // undo the patch
+```
+
+---
+
+## IP Resolution Utilities
+
+```javascript
+const { resolveClientIp, resolveSocketIp, isFromTrustedProxy } = require('securenow/resolve-ip');
+
+// From an HTTP request (respects X-Forwarded-For from trusted proxies)
+const clientIp = resolveClientIp(req);
+
+// Direct socket IP
+const socketIp = resolveSocketIp(req);
+
+// Check if request comes from a trusted proxy
+const trusted = isFromTrustedProxy(req);
+```
+
+### CIDR Matching
+
+```javascript
+const { createMatcher, ipToInt, parseCidr, matchesCidr } = require('securenow/cidr');
+
+const isBlocked = createMatcher(['10.0.0.0/8', '192.168.1.0/24']);
+isBlocked('10.0.0.5');   // true
+isBlocked('8.8.8.8');    // false
+```
+
+**CLI equivalent:**
+
+```bash
+securenow cidr match 10.0.0.5 10.0.0.0/8,192.168.1.0/24    # exit 0 = match, 2 = miss
+securenow cidr parse 10.0.0.0/8                             # network/broadcast/mask/size
+```
+
+---
+
+## Sensitive Data Redaction
+
+Available from multiple entry points (`securenow/nextjs-middleware`, `securenow/nextjs-wrapper`, `securenow/nextjs-auto-capture`):
+
+```javascript
+const { redactSensitiveData, DEFAULT_SENSITIVE_FIELDS } = require('securenow/nextjs-middleware');
+
+const safe = redactSensitiveData({ username: 'alice', password: 's3cret', token: 'abc' });
+// { username: 'alice', password: '[REDACTED]', token: '[REDACTED]' }
+```
+
+**Auto-redacted fields:** `password`, `passwd`, `pwd`, `secret`, `token`, `api_key`, `apikey`, `access_token`, `auth`, `credentials`, `mysql_pwd`, `stripeToken`, `card`, `cardnumber`, `ccv`, `cvc`, `cvv`, `ssn`, `pin`.
+
+Add custom fields via `SECURENOW_SENSITIVE_FIELDS=field1,field2`.
+
+**CLI equivalent** (for piping, scripts, debugging what a payload looks like post-redaction):
+
+```bash
+securenow redact '{"user":"alice","password":"s3cret"}'
+securenow redact @request.json --fields internal_id,sessionHash
+```
+
+---
+
+## Environment Variables — Complete Reference
+
+### Required
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SECURENOW_APPID` | Service name / app identifier | *(auto-generated with UUID)* |
+| `SECURENOW_INSTANCE` | OTLP collector base URL | `https://freetrial.securenow.ai:4318` |
+
+### Service Naming
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OTEL_SERVICE_NAME` | OpenTelemetry standard; overrides `SECURENOW_APPID` | — |
+| `SECURENOW_NO_UUID` | `1` to use exact app ID without UUID suffix | `0` |
+| `SECURENOW_STRICT` | `1` to exit if APPID missing in PM2 cluster | `0` |
+
+### OTLP Connection
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Standard OTel endpoint; overrides `SECURENOW_INSTANCE` | — |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Override traces endpoint specifically | `{instance}/v1/traces` |
+| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Override logs endpoint specifically | `{instance}/v1/logs` |
+| `OTEL_EXPORTER_OTLP_HEADERS` | Comma-separated `key=value` headers for OTLP requests | — |
+
+### Behavior
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SECURENOW_LOGGING_ENABLED` | Enable OTLP log export | `1` |
+| `SECURENOW_CAPTURE_BODY` | Capture HTTP request bodies | `0` |
+| `SECURENOW_MAX_BODY_SIZE` | Max body size in bytes | `10240` |
+| `SECURENOW_CAPTURE_MULTIPART` | Capture multipart/form-data (streaming, metadata only) | `0` |
+| `SECURENOW_SENSITIVE_FIELDS` | Comma-separated extra fields to redact | — |
+| `SECURENOW_DISABLE_INSTRUMENTATIONS` | Comma-separated packages to skip (e.g. `fs,dns`) | — |
+| `SECURENOW_TEST_SPAN` | `1` to emit a test span on startup | `0` |
+| `SECURENOW_HIDE_BANNER` | `1` to suppress free-trial upgrade banner | `0` |
+| `OTEL_LOG_LEVEL` | SDK log level: `none`, `error`, `warn`, `info`, `debug` | `none` |
+| `NODE_ENV` | Sent as `deployment.environment` attribute | `production` |
+
+### Firewall
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SECURENOW_API_KEY` | API key (`snk_live_...`); activates firewall when set | — |
+| `SECURENOW_API_URL` | SecureNow API base URL | `https://api.securenow.ai` |
+| `SECURENOW_FIREWALL_ENABLED` | Master kill-switch (`0` to disable) | `1` |
+| `SECURENOW_FIREWALL_VERSION_INTERVAL` | Seconds between lightweight version checks | `10` |
+| `SECURENOW_FIREWALL_SYNC_INTERVAL` | Full blocklist refresh interval in seconds | `300` |
+| `SECURENOW_FIREWALL_FAIL_MODE` | `open` (allow all when unavailable) or `closed` | `open` |
+| `SECURENOW_FIREWALL_STATUS_CODE` | HTTP status for blocked requests | `403` |
+| `SECURENOW_FIREWALL_LOG` | Log blocked requests | `1` |
+| `SECURENOW_FIREWALL_TCP` | Enable Layer 2 TCP blocking | `0` |
+| `SECURENOW_FIREWALL_IPTABLES` | Enable Layer 3 iptables/nftables | `0` |
+| `SECURENOW_FIREWALL_CLOUD` | Cloud WAF: `cloudflare`, `aws`, or `gcp` | — |
+| `SECURENOW_FIREWALL_CLOUD_DRY_RUN` | `1` to log cloud pushes without applying | `0` |
+| `SECURENOW_TRUSTED_PROXIES` | Comma-separated trusted proxy IPs | — |
+
+**Resilience:** The firewall SDK includes a circuit breaker (opens after 5 consecutive errors, 2-min cooldown), in-flight request guards (prevents overlapping requests), 429 Retry-After support, and exponential backoff on both version checks and initial sync retries.
+
+### Cloud WAF Provider Variables
+
+| Provider | Variables |
+|----------|-----------|
+| Cloudflare | `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` |
+| AWS WAF | `AWS_WAF_IP_SET_ID`, `AWS_WAF_IP_SET_NAME`, `AWS_WAF_SCOPE` |
+| GCP | `GCP_PROJECT_ID`, `GCP_SECURITY_POLICY` |
+
+### Priority Order
+
+**Service name:** `OTEL_SERVICE_NAME` > `SECURENOW_APPID` > auto-generated
+
+**Endpoint:** `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` > `OTEL_EXPORTER_OTLP_ENDPOINT` > `SECURENOW_INSTANCE` > `https://freetrial.securenow.ai:4318`
+
+---
+
+## Recipes for Agentic AI
+
+### Add Observability to an Existing Express App
+
+```bash
+npm install securenow
+```
+
+Create `.env`:
+```
+SECURENOW_APPID=my-express-api
+SECURENOW_INSTANCE=https://your-collector:4318
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_CAPTURE_BODY=1
+```
+
+Update `package.json`:
+```json
+{ "scripts": { "start": "node -r securenow/register src/index.js" } }
+```
+
+No code changes to the application needed.
+
+### Add Observability + Firewall to a Next.js App
+
+```bash
+npm install securenow
+npx securenow init --key snk_live_abc123...
+```
+
+The `init` command creates `instrumentation.ts` and suggests `next.config` changes. Then set env vars in `.env.local`:
+
+```
+SECURENOW_APPID=my-nextjs-app
+SECURENOW_INSTANCE=https://your-collector:4318
+SECURENOW_API_KEY=snk_live_abc123...
+SECURENOW_CAPTURE_BODY=1
+```
+
+### Enable Firewall With Zero Tracing Overhead
+
+For apps that only need IP blocking:
+
+```bash
+node -r securenow/firewall-only app.js
+```
+
+Set `SECURENOW_API_KEY` in the environment. No other configuration needed.
+
+### Production Hardened Configuration
+
+```bash
+SECURENOW_APPID=prod-api
+SECURENOW_INSTANCE=https://collector.prod.internal:4318
+SECURENOW_NO_UUID=1
+SECURENOW_STRICT=1
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_CAPTURE_BODY=0
+SECURENOW_API_KEY=snk_live_abc123...
+SECURENOW_FIREWALL_TCP=1
+SECURENOW_FIREWALL_SYNC_INTERVAL=30
+SECURENOW_FIREWALL_FAIL_MODE=open
+OTEL_LOG_LEVEL=error
+NODE_ENV=production
+```
+
+### Instrument a Docker Container
+
+```dockerfile
+FROM node:20-slim
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY . .
+
+ENV SECURENOW_APPID=my-service
+ENV SECURENOW_INSTANCE=http://otel-collector:4318
+ENV SECURENOW_NO_UUID=1
+ENV SECURENOW_API_KEY=snk_live_abc123...
+
+CMD ["node", "-r", "securenow/register", "src/index.js"]
+```
+
+### Kubernetes with Separate Trace/Log Collectors
+
+```bash
+SECURENOW_APPID=k8s-service
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://tempo:4318/v1/traces
+OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://loki:4318/v1/logs
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_NO_UUID=1
+```
+
+---
+
+## Verification
+
+On startup, securenow logs its configuration:
+
+```
+[securenow] pid=12345 SECURENOW_APPID="my-app" → service.name=my-app
+[securenow] OTel SDK started → https://collector:4318/v1/traces
+[securenow] Logging: ENABLED → https://collector:4318/v1/logs
+[securenow] Request body capture: ENABLED (max: 10240 bytes)
+[securenow] Firewall: ENABLED
+[securenow] Firewall: synced 142 blocked IPs
+```
+
+Use `OTEL_LOG_LEVEL=debug` and `SECURENOW_TEST_SPAN=1` to troubleshoot connectivity issues.
+
+**CLI equivalent** (works without booting the SDK — useful when the app won't start):
+
+```bash
+securenow env                     # show resolved service name, endpoints, env vars
+securenow doctor                  # probe OTLP + API endpoints, exits 1 on failure
+securenow test-span               # send a real span to the collector
+```