securenow 6.0.2 → 6.1.0

package/README.md

@@ -1,6 +1,6 @@
 # SecureNow
 
-OpenTelemetry instrumentation for Node.js and Next.js applications - send **traces and logs** to SigNoz or any OTLP-compatible backend.
+OpenTelemetry instrumentation for Node.js, Next.js, and Nuxt applications - send **traces and logs** to any OTLP-compatible backend (including SecureNow).
 
 **Official npm package:** [securenow](http://securenow.ai/)
 
@@ -8,73 +8,152 @@ OpenTelemetry instrumentation for Node.js and Next.js applications - send **trac
 
 ## 🚀 Quick Start
 
-### For Next.js Applications
-
-**The easiest way to add observability to Next.js!**
+### For Any Node.js App (Express, Fastify, NestJS, Koa, Hapi, etc.)
 
 ```bash
-# Just install - setup is automatic!
+# 1. Install
 npm install securenow
+
+# 2. Set env vars
+export SECURENOW_APPID=my-app
+export SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
+
+# 3. Add -r securenow/register to your start command
+node -r securenow/register src/app.js
+```
+
+That's it. One `-r` flag is all you need — ESM and CJS apps are handled automatically (Node >=20.6 auto-registers the ESM loader hook).
+
+> **package.json** example:
+> ```json
+> "scripts": {
+>   "start": "node -r securenow/register src/index.js",
+>   "dev": "node -r securenow/register --watch src/index.js"
+> }
+> ```
+
+You can also use `NODE_OPTIONS` so your existing scripts stay unchanged:
+```bash
+NODE_OPTIONS="-r securenow/register" npm start
 ```
 
-**🎉 The installer will automatically:**
-- Detect your Next.js project
-- Create `instrumentation.ts` (or `.js`)
-- Create `.env.local` template
+See the [All Frameworks Quick Start](./docs/ALL-FRAMEWORKS-QUICKSTART.md) for tested setup guides.
 
-**Just answer "Y" when prompted!**
+---
 
-Then configure your `.env.local`:
+### For Next.js Applications
 
 ```bash
-SECURENOW_APPID=my-nextjs-app
-SECURENOW_INSTANCE=http://your-signoz-server:4318
+# 1. Install
+npm install securenow
+
+# 2. Auto-scaffold instrumentation files
+npx securenow init --key snk_live_abc123...
+```
+
+This creates `instrumentation.ts` and tells you to wrap your `next.config.js`:
+
+```javascript
+// next.config.js
+const { withSecureNow } = require('securenow/nextjs-webpack-config');
+
+module.exports = withSecureNow({
+  // your existing config
+});
 ```
 
-**Alternative:** Use the CLI command
+`withSecureNow()` auto-detects Next.js 14 vs 15 and sets the correct externalization config. No manual `serverExternalPackages` list needed.
+
+Configure `.env.local`:
+
 ```bash
-npx securenow init
+SECURENOW_APPID=my-nextjs-app
+SECURENOW_INSTANCE=http://your-otlp-collector:4318
+SECURENOW_API_KEY=snk_live_abc123...
 ```
 
-**Done!** 🎉 See [Next.js Complete Guide](./docs/NEXTJS-GUIDE.md) for details.
+**Done!** See [Next.js Complete Guide](./docs/NEXTJS-GUIDE.md) for details.
 
 ---
 
-### For Node.js Applications (Express, Fastify, NestJS, etc.)
-
-#### Tracing Only
+### For Nuxt 3 Applications
 
 ```bash
 # 1. Install
 npm install securenow
+```
 
-# 2. Set environment variables
-export SECURENOW_APPID=my-app
-export SECURENOW_INSTANCE=http://your-signoz-server:4318
+Add the module to your `nuxt.config.ts`:
 
-# 3. Run with preload
-NODE_OPTIONS="-r securenow/register" node app.js
-# or
-NODE_OPTIONS="-r securenow/register" npm start
+```ts
+export default defineNuxtConfig({
+  modules: ['securenow/nuxt'],
+});
 ```
 
-#### Tracing + Logging (Recommended)
+Set environment variables in `.env`:
 
 ```bash
-# 1. Install
-npm install securenow
+SECURENOW_APPID=my-nuxt-app
+SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
+```
 
-# 2. Set environment variables
-export SECURENOW_APPID=my-app
-export SECURENOW_INSTANCE=http://your-signoz-server:4318
-export SECURENOW_LOGGING_ENABLED=1
+**Done!** All server-side requests are now traced automatically. The firewall also activates automatically when `SECURENOW_API_KEY` is set. See the [Nuxt 3 Complete Guide](./docs/NUXT-GUIDE.md) for details.
+
+---
+
+### CLI -- Manage Everything from the Terminal
+
+```bash
+# Set up your project (auto-detects framework, creates instrumentation files)
+npx securenow init --key snk_live_abc123...
+
+# Authenticate
+npx securenow login
+
+# Create an app and get the key
+npx securenow apps create my-app
+
+# Set it as default so you don't need --app every time
+npx securenow config set defaultApp <key>
 
-# 3. Run with preload (adds logging)
-NODE_OPTIONS="-r securenow/register -r securenow/console-instrumentation" node app.js
+# View traces, logs
+npx securenow traces
+npx securenow logs
 
-# Now all console.log/info/warn/error automatically go to SigNoz!
+# IP intelligence, forensic queries, blocklist
+npx securenow ip 1.2.3.4
+npx securenow forensics "show top attacking IPs in the last hour"
+npx securenow blocklist add 1.2.3.4 --reason "scanner"
+
+# Firewall — automatic IP blocking
+npx securenow firewall status
+npx securenow firewall test-ip 1.2.3.4
+
+# False-positive triage from the terminal (full parity with the dashboard)
+npx securenow fp ai-fill --description "Stripe webhook POST to /api/stripe/webhook"
+npx securenow fp mark <notification-id> <ip> --reason "Known partner IP"
+
+# Telemetry from scripts/CI — no SDK boot required
+npx securenow log send "Deploy succeeded" --level info --attrs version=1.2.3
+npx securenow test-span                              # verify collector connectivity
+
+# Diagnostics & utilities
+npx securenow doctor                                 # probe OTLP + API endpoints
+npx securenow env                                    # show resolved config
+npx securenow redact '{"user":"a","password":"s"}'   # preview redaction
+npx securenow cidr match 10.0.0.5 10.0.0.0/8         # exit 0 = hit, 2 = miss
+
+# Full dashboard overview
+npx securenow status
 ```
 
+Run `npx securenow help` for all commands. See the [CLI Reference](#cli-reference) below.
+
+> **Full CLI/SDK parity (v6.1.0+).** Every SDK export has a CLI counterpart: `redactSensitiveData` → `securenow redact`, `createMatcher` → `securenow cidr match`, `getLogger().emit()` → `securenow log send`, `SECURENOW_TEST_SPAN` → `securenow test-span`, `node -r securenow/firewall-only` → `securenow run --firewall-only`.
+
+---
+
 ---
 
 ## 📦 Installation
@@ -97,9 +176,9 @@ pnpm add securenow
 # Required: Your application identifier
 SECURENOW_APPID=my-app-name
 
-# Optional: Your SigNoz/OTLP collector endpoint
+# Optional: Your OTLP collector endpoint
 # Default: https://freetrial.securenow.ai:4318
-SECURENOW_INSTANCE=http://your-signoz-server:4318
+SECURENOW_INSTANCE=http://your-otlp-collector:4318
 
 # Optional: Enable Logging
 SECURENOW_LOGGING_ENABLED=1                 # Enable automatic log collection
@@ -114,6 +193,9 @@ OTEL_EXPORTER_OTLP_HEADERS="x-api-key=..."  # Authentication headers
 SECURENOW_CAPTURE_BODY=1                    # Capture request bodies in traces
 SECURENOW_MAX_BODY_SIZE=10240               # Max body size in bytes
 SECURENOW_SENSITIVE_FIELDS="field1,field2"  # Additional fields to redact
+
+# Optional: Multipart body capture (file upload metadata)
+SECURENOW_CAPTURE_MULTIPART=1               # Capture multipart field names, values & file metadata
 ```
 
 ### Legacy Environment Variables (still supported)
@@ -131,6 +213,7 @@ SecureNow automatically instruments:
 
 ### Web Frameworks
 - ✅ Next.js (App Router & Pages Router)
+- ✅ Nuxt 3 (Nitro server)
 - ✅ Express.js
 - ✅ Fastify
 - ✅ NestJS
@@ -161,10 +244,14 @@ SecureNow automatically instruments:
 
 ### Quick Starts
 - **[Next.js Quick Start](./docs/NEXTJS-QUICKSTART.md)** - Get started in 30 seconds
+- **[Nuxt 3 Guide](./docs/NUXT-GUIDE.md)** - One-line Nuxt module setup
 - **[Logging Quick Start](./docs/LOGGING-QUICKSTART.md)** - Add logging in 2 minutes
 
 ### Complete Guides
+- **[Firewall Guide](./docs/FIREWALL-GUIDE.md)** - Automatic multi-layer IP blocking
+- **[API Keys Guide](./docs/API-KEYS-GUIDE.md)** - API key management and scopes
 - **[Next.js Complete Guide](./docs/NEXTJS-GUIDE.md)** - Full Next.js integration guide
+- **[Nuxt 3 Complete Guide](./docs/NUXT-GUIDE.md)** - Full Nuxt 3 integration guide
 - **[Logging Complete Guide](./docs/LOGGING-GUIDE.md)** - Full logging setup for all frameworks
 - **[📚 Complete Documentation](./docs/INDEX.md)** - All guides and references
 
@@ -173,7 +260,177 @@ SecureNow automatically instruments:
 
 ---
 
-## 🆘 Support
+## CLI Reference
+
+After installing the package, the `securenow` CLI is available via `npx securenow` or globally after `npm install -g securenow`.
+
+### Run (convenience wrapper)
+
+| Command | Description |
+|---------|-------------|
+| `securenow run <script>` | Run a Node.js app with `-r securenow/register` injected |
+| `securenow run --watch <script>` | Same, with Node.js watch mode |
+
+Most users won't need this — just add `-r securenow/register` to your existing start script.
+
+### Authentication
+
+| Command | Description |
+|---------|-------------|
+| `securenow login` | Log in via browser (opens OAuth flow) |
+| `securenow login --token <TOKEN>` | Log in with a token (for CI/headless) |
+| `securenow login --local` | Log in and save credentials to the current project only |
+| `securenow logout` | Clear stored credentials |
+| `securenow logout --local` | Clear project-local credentials only |
+| `securenow whoami` | Show current session info (including auth source) |
+
+### Applications
+
+| Command | Description |
+|---------|-------------|
+| `securenow apps` | List all applications |
+| `securenow apps create <name>` | Create app and get the app key |
+| `securenow apps info <id>` | Show application details |
+| `securenow apps delete <id>` | Delete an application |
+| `securenow apps default <key>` | Set default app for all commands |
+
+### Observability
+
+| Command | Description |
+|---------|-------------|
+| `securenow traces --app <key>` | List recent traces |
+| `securenow traces show <traceId>` | Show trace spans |
+| `securenow traces analyze <traceId>` | AI security analysis of a trace |
+| `securenow logs --app <key>` | View logs (with `--minutes`, `--level`) |
+| `securenow logs trace <traceId>` | View logs for a specific trace |
+| `securenow analytics` | Response code analytics overview |
+| `securenow status` | Full dashboard summary |
+
+### Detect & Respond
+
+| Command | Description |
+|---------|-------------|
+| `securenow notifications` | List notifications |
+| `securenow notifications unread` | Show unread count |
+| `securenow notifications read <id>` | Mark notification as read |
+| `securenow notifications read-all` | Mark all as read |
+| `securenow alerts rules` | List alert rules (status, applications, schedule) |
+| `securenow alerts rules show <id>` | Show one rule (includes all-apps vs explicit apps) |
+| `securenow alerts rules update <id> --applications-all` | Set rule to all current & future apps |
+| `securenow alerts rules update <id> --apps k1,k2` | Scope rule to specific app keys |
+| `securenow alerts channels` | List alert channels |
+| `securenow alerts history` | View alert history |
+
+### Investigate
+
+| Command | Description |
+|---------|-------------|
+| `securenow ip <address>` | IP intelligence lookup (geo, abuse score, verdict) |
+| `securenow ip traces <address>` | Show traces originating from an IP |
+| `securenow forensics "<query>"` | Natural language forensic query (NL to SQL) |
+| `securenow forensics library` | View saved query library |
+| `securenow api-map` | View discovered API endpoints |
+| `securenow api-map stats` | API map statistics |
+
+### Firewall
+
+| Command | Description |
+|---------|-------------|
+| `securenow firewall status` | Show firewall status, active layers, and API key info |
+| `securenow firewall test-ip <ip>` | Check if an IP would be blocked by the current blocklist |
+| `securenow run --firewall-only <script>` | Run a Node.js app with the firewall preloaded but **no** OTel tracing overhead |
+
+### Remediation
+
+| Command | Description |
+|---------|-------------|
+| `securenow blocklist` | List blocked IPs |
+| `securenow blocklist add <ip>` | Block an IP (`--reason <reason>`) |
+| `securenow blocklist remove <id>` | Remove from blocklist |
+| `securenow blocklist stats` | Blocklist statistics |
+| `securenow allowlist` | List allowed IPs (restrict-mode) |
+| `securenow allowlist add <ip>` | Allow an IP (`--label`, `--reason`) |
+| `securenow allowlist remove <id>` | Remove from allowlist |
+| `securenow trusted` | List trusted IPs |
+| `securenow trusted add <ip>` | Add trusted IP (`--label <label>`) |
+| `securenow trusted remove <id>` | Remove trusted IP |
+
+### False-Positive Management
+
+Full false-positive triage without leaving the terminal — mirrors the web dashboard one-for-one.
+
+| Command | Description |
+|---------|-------------|
+| `securenow fp` / `securenow fp list` | List all exclusion rules |
+| `securenow fp show <id>` | Show rule details (conditions, scope, match mode) |
+| `securenow fp create --conditions '[...]'` | Create a raw exclusion rule |
+| `securenow fp create --path /api/events --method POST --path-safe standard --ua-safe standard --reason "..."` | Create with safe-value presets |
+| `securenow fp edit <id> [--active true\|false] [--conditions '[...]']` | Edit an existing rule |
+| `securenow fp delete <id> [--yes]` | Delete a rule |
+| `securenow fp test-body '<json>' --conditions '[...]'` | Test conditions against a request body |
+| `securenow fp dry-run --conditions '[...]'` | Dry-run against the last 3 days of live traces |
+| `securenow fp ai-fill --description "Stripe webhook POST to /api/stripe/webhook"` | AI-generate exclusion conditions |
+| `securenow fp mark <notification-id> <ip>` | Mark an IP as false positive on a specific notification |
+
+### Telemetry
+
+Emit OTLP logs and spans from the shell — for cron jobs, CI pipelines, and scripts. No SDK boot required.
+
+| Command | Description |
+|---------|-------------|
+| `securenow log send "<message>" [--level info\|warn\|error] [--attrs k=v,k=v]` | Send a single log record via OTLP/HTTP |
+| `securenow test-span [<name>]` | Emit a test span to verify collector connectivity |
+
+### Utilities
+
+SDK helpers surfaced as CLI commands — debug redaction, test CIDR matching, inspect config without writing Node.
+
+| Command | Description |
+|---------|-------------|
+| `securenow redact '<json>' [--fields f1,f2]` | Redact sensitive fields (also accepts `@file.json`) |
+| `securenow cidr match <ip> <cidr1,cidr2>` | Check if an IP matches a CIDR list (exit `0` hit / `2` miss) |
+| `securenow cidr parse <cidr>` | Parse a CIDR — print network, broadcast, mask, size |
+| `securenow env [--json]` | Show resolved config (service name, endpoints, env vars) |
+| `securenow doctor [--json]` | End-to-end diagnostic: probe OTLP + API, check config |
+
+### Settings
+
+| Command | Description |
+|---------|-------------|
+| `securenow instances` | List ClickHouse instances |
+| `securenow instances test <id>` | Test instance connection |
+| `securenow config get` | Show all config values |
+| `securenow config set <key> <value>` | Set a config value |
+| `securenow config path` | Show config file locations |
+| `securenow init [--key <KEY>]` | Auto-scaffold instrumentation for your framework |
+| `securenow version` | Show CLI version |
+
+### Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output as JSON (works on every command) |
+| `--help` | Show help for any command |
+| `--app <key>` | Specify app key (or set default with `config set defaultApp`) |
+| `--local` | Save/clear credentials per-project (login/logout only) |
+
+### Configuration
+
+Credentials and settings are stored in `~/.securenow/` (global) or `.securenow/` (per-project):
+
+| File | Purpose |
+|------|---------|
+| `~/.securenow/config.json` | API URL, default app, preferences |
+| `~/.securenow/credentials.json` | Auth token — global (restricted permissions) |
+| `.securenow/credentials.json` | Auth token — project-local (use `login --local`) |
+
+**Credential resolution order:** `SECURENOW_TOKEN` env var → project `.securenow/credentials.json` → global `~/.securenow/credentials.json`.
+
+Override the API URL with `securenow config set apiUrl <url>` or the `SECURENOW_API_URL` environment variable.
+
+---
+
+## Support
 
 - **Website:** [securenow.ai](http://securenow.ai/)
 - **Issues:** Report bugs and request features
@@ -181,6 +438,6 @@ SecureNow automatically instruments:
 
 ---
 
-## 📄 License
+## License
 
 ISC