securenow 5.10.2 → 5.11.0

package/cli.js

@@ -119,6 +119,32 @@ const COMMANDS = {
     },
     defaultSub: 'rules',
   },
+  fp: {
+    desc: 'Manage false-positive exclusion rules',
+    usage: 'securenow fp <subcommand> [options]',
+    flags: { json: 'Output as JSON', conditions: 'JSON array of conditions', 'match-mode': 'Match mode: all (AND) or any (OR)', 'rule-scope': 'Scope: this_rule | specific_rules | all_existing | any_rule', 'target-rules': 'Comma-separated rule IDs (when --rule-scope specific_rules)', 'path-safe': 'Add path_safe_values condition (standard|strict)', 'query-safe': 'Add query_safe_values condition (standard|strict)', 'query-keys': 'Allowed query param names (comma-separated)', 'ua-safe': 'Add ua_safe_values condition (standard|strict)', 'headers-safe': 'Add headers_safe_values condition (standard|strict)', 'headers-keys': 'Allowed header names (comma-separated)' },
+    sub: {
+      list: { desc: 'List all exclusion rules', run: (a, f) => require('./cli/fp').list(a, f) },
+      show: { desc: 'Show exclusion rule details', usage: 'securenow fp show <id>', run: (a, f) => require('./cli/fp').show(a, f) },
+      create: { desc: 'Create an exclusion rule', usage: 'securenow fp create [--conditions \'[...]\'] [--path /api/event] [--method POST] [--path-safe standard] [--ua-safe standard] [--headers-safe standard] [--query-keys page,limit] [--headers-keys host,content-type] [--reason "..."] [--rule-scope any_rule|specific_rules|all_existing] [--target-rules id1,id2]', run: (a, f) => require('./cli/fp').create(a, f) },
+      edit: { desc: 'Edit an exclusion rule', usage: 'securenow fp edit <id> [--active true/false] [--conditions \'[...]\']', run: (a, f) => require('./cli/fp').edit(a, f) },
+      delete: { desc: 'Delete an exclusion rule', usage: 'securenow fp delete <id> [--yes]', run: (a, f) => require('./cli/fp').remove(a, f) },
+      'test-body': { desc: 'Test a request body against conditions', usage: 'securenow fp test-body <body|@file> --conditions \'[...]\'', run: (a, f) => require('./cli/fp').testBody(a, f) },
+      'dry-run': { desc: 'Dry-run conditions against live traces (last 3 days)', usage: 'securenow fp dry-run --conditions \'[...]\'', run: (a, f) => require('./cli/fp').dryRun(a, f) },
+      'ai-fill': { desc: 'AI-generate exclusion conditions', usage: 'securenow fp ai-fill [--description "..."] [--context \'{"method":"POST",...}\']', run: (a, f) => require('./cli/fp').aiFill(a, f) },
+      mark: { desc: 'Mark an IP as false positive on a notification', usage: 'securenow fp mark <notification-id> <ip> [--conditions \'[...]\'] [--reason "..."] [--rule-scope this_rule|specific_rules|all_existing|any_rule] [--target-rules id1,id2]', run: (a, f) => require('./cli/fp').mark(a, f) },
+    },
+    defaultSub: 'list',
+  },
+  firewall: {
+    desc: 'Firewall status and IP testing',
+    usage: 'securenow firewall <subcommand> [options]',
+    sub: {
+      status: { desc: 'Show firewall status, layers, and blocklist info', run: (a, f) => require('./cli/firewall').status(a, f) },
+      'test-ip': { desc: 'Check if an IP would be blocked', usage: 'securenow firewall test-ip <ip>', run: (a, f) => require('./cli/firewall').testIp(a, f) },
+    },
+    defaultSub: 'status',
+  },
   blocklist: {
     desc: 'Manage IP blocklist',
     usage: 'securenow blocklist <subcommand> [options]',
@@ -305,8 +331,9 @@ function showHelp(commandName) {
     'Authentication': ['login', 'logout', 'whoami'],
     'Applications': ['apps', 'init', 'status'],
     'Observe': ['traces', 'logs', 'analytics'],
-    'Detect & Respond': ['issues', 'notifications', 'alerts'],
+    'Detect & Respond': ['issues', 'notifications', 'alerts', 'fp'],
     'Investigate': ['ip', 'forensics', 'api-map'],
+    'Firewall': ['firewall'],
     'Remediation': ['blocklist', 'trusted'],
     'Settings': ['instances', 'config', 'version'],
   };

package/console-instrumentation.js

@@ -1,147 +1,147 @@
-'use strict';
-
-/**
- * Console instrumentation helper for securenow
- * 
- * This module wraps the default console methods (log, info, warn, error, debug)
- * to automatically send logs to OpenTelemetry / any OTLP-compatible backend.
- * 
- * Usage:
- *   1. Enable logging: SECURENOW_LOGGING_ENABLED=1
- *   2. Import this file AFTER securenow is initialized
- *   3. Use console.log/info/warn/error as normal
- * 
- * Example:
- *   // At the top of your app.js or index.js
- *   require('securenow/register'); // or use NODE_OPTIONS
- *   require('securenow/console-instrumentation');
- *   
- *   // Now all console calls are captured
- *   console.log('Application started');
- *   console.error('An error occurred');
- */
-
-const tracing = require('./tracing');
-
-if (!tracing.isLoggingEnabled()) {
-  console.warn('[securenow] Console instrumentation loaded but logging is not enabled. Set SECURENOW_LOGGING_ENABLED=1 to enable.');
-}
-
-// Get a logger instance
-const logger = tracing.getLogger('console', '1.0.0');
-
-if (!logger) {
-  console.warn('[securenow] Console instrumentation: No logger available. Logging will not work.');
-  module.exports = {};
-  return;
-}
-
-if (console.__securenow_patched) {
-  console.warn('[securenow] Console already instrumented by tracing.js — skipping to avoid duplicate logs.');
-  module.exports = {};
-  return;
-}
-
-// Store original console methods
-const originalConsole = {
-  log: console.log,
-  info: console.info,
-  warn: console.warn,
-  error: console.error,
-  debug: console.debug,
-};
-
-// Map severity levels (OpenTelemetry standard)
-const SeverityNumber = {
-  DEBUG: 5,
-  INFO: 9,
-  WARN: 13,
-  ERROR: 17,
-};
-
-/**
- * Format arguments into a log message
- */
-function formatMessage(args) {
-  return args
-    .map((arg) => {
-      if (typeof arg === 'object' && arg !== null) {
-        try {
-          return JSON.stringify(arg);
-        } catch (e) {
-          return String(arg);
-        }
-      }
-      return String(arg);
-    })
-    .join(' ');
-}
-
-const { context, trace } = require('@opentelemetry/api');
-
-/**
- * Emit a log record, correlating with the active trace/span when available
- */
-function emitLog(severityNumber, severityText, args) {
-  const message = formatMessage(args);
-  
-  try {
-    const activeCtx = context.active();
-    const spanCtx = trace.getSpanContext(activeCtx);
-    logger.emit({
-      severityNumber,
-      severityText,
-      body: message,
-      attributes: {
-        'log.source': 'console',
-        'log.method': severityText.toLowerCase(),
-      },
-      ...(spanCtx && { context: activeCtx }),
-    });
-  } catch (e) {
-    // Silently fail to avoid breaking the application
-  }
-}
-
-// Override console.log
-console.log = function (...args) {
-  emitLog(SeverityNumber.INFO, 'INFO', args);
-  originalConsole.log.apply(console, args);
-};
-
-// Override console.info
-console.info = function (...args) {
-  emitLog(SeverityNumber.INFO, 'INFO', args);
-  originalConsole.info.apply(console, args);
-};
-
-// Override console.warn
-console.warn = function (...args) {
-  emitLog(SeverityNumber.WARN, 'WARN', args);
-  originalConsole.warn.apply(console, args);
-};
-
-// Override console.error
-console.error = function (...args) {
-  emitLog(SeverityNumber.ERROR, 'ERROR', args);
-  originalConsole.error.apply(console, args);
-};
-
-// Override console.debug
-console.debug = function (...args) {
-  emitLog(SeverityNumber.DEBUG, 'DEBUG', args);
-  originalConsole.debug.apply(console, args);
-};
-
-console.log('[securenow] Console instrumentation installed - all console logs will be sent to any OTLP-compatible backend');
-
-module.exports = {
-  originalConsole,
-  restoreConsole: () => {
-    console.log = originalConsole.log;
-    console.info = originalConsole.info;
-    console.warn = originalConsole.warn;
-    console.error = originalConsole.error;
-    console.debug = originalConsole.debug;
-  },
-};
+'use strict';
+
+/**
+ * Console instrumentation helper for securenow
+ * 
+ * This module wraps the default console methods (log, info, warn, error, debug)
+ * to automatically send logs to OpenTelemetry / any OTLP-compatible backend.
+ * 
+ * Usage:
+ *   1. Enable logging: SECURENOW_LOGGING_ENABLED=1
+ *   2. Import this file AFTER securenow is initialized
+ *   3. Use console.log/info/warn/error as normal
+ * 
+ * Example:
+ *   // At the top of your app.js or index.js
+ *   require('securenow/register'); // or use NODE_OPTIONS
+ *   require('securenow/console-instrumentation');
+ *   
+ *   // Now all console calls are captured
+ *   console.log('Application started');
+ *   console.error('An error occurred');
+ */
+
+const tracing = require('./tracing');
+
+if (!tracing.isLoggingEnabled()) {
+  console.warn('[securenow] Console instrumentation loaded but logging is not enabled. Set SECURENOW_LOGGING_ENABLED=1 to enable.');
+}
+
+// Get a logger instance
+const logger = tracing.getLogger('console', '1.0.0');
+
+if (!logger) {
+  console.warn('[securenow] Console instrumentation: No logger available. Logging will not work.');
+  module.exports = {};
+  return;
+}
+
+if (console.__securenow_patched) {
+  console.warn('[securenow] Console already instrumented by tracing.js — skipping to avoid duplicate logs.');
+  module.exports = {};
+  return;
+}
+
+// Store original console methods
+const originalConsole = {
+  log: console.log,
+  info: console.info,
+  warn: console.warn,
+  error: console.error,
+  debug: console.debug,
+};
+
+// Map severity levels (OpenTelemetry standard)
+const SeverityNumber = {
+  DEBUG: 5,
+  INFO: 9,
+  WARN: 13,
+  ERROR: 17,
+};
+
+/**
+ * Format arguments into a log message
+ */
+function formatMessage(args) {
+  return args
+    .map((arg) => {
+      if (typeof arg === 'object' && arg !== null) {
+        try {
+          return JSON.stringify(arg);
+        } catch (e) {
+          return String(arg);
+        }
+      }
+      return String(arg);
+    })
+    .join(' ');
+}
+
+const { context, trace } = require('@opentelemetry/api');
+
+/**
+ * Emit a log record, correlating with the active trace/span when available
+ */
+function emitLog(severityNumber, severityText, args) {
+  const message = formatMessage(args);
+  
+  try {
+    const activeCtx = context.active();
+    const spanCtx = trace.getSpanContext(activeCtx);
+    logger.emit({
+      severityNumber,
+      severityText,
+      body: message,
+      attributes: {
+        'log.source': 'console',
+        'log.method': severityText.toLowerCase(),
+      },
+      ...(spanCtx && { context: activeCtx }),
+    });
+  } catch (e) {
+    // Silently fail to avoid breaking the application
+  }
+}
+
+// Override console.log
+console.log = function (...args) {
+  emitLog(SeverityNumber.INFO, 'INFO', args);
+  originalConsole.log.apply(console, args);
+};
+
+// Override console.info
+console.info = function (...args) {
+  emitLog(SeverityNumber.INFO, 'INFO', args);
+  originalConsole.info.apply(console, args);
+};
+
+// Override console.warn
+console.warn = function (...args) {
+  emitLog(SeverityNumber.WARN, 'WARN', args);
+  originalConsole.warn.apply(console, args);
+};
+
+// Override console.error
+console.error = function (...args) {
+  emitLog(SeverityNumber.ERROR, 'ERROR', args);
+  originalConsole.error.apply(console, args);
+};
+
+// Override console.debug
+console.debug = function (...args) {
+  emitLog(SeverityNumber.DEBUG, 'DEBUG', args);
+  originalConsole.debug.apply(console, args);
+};
+
+console.log('[securenow] Console instrumentation installed - all console logs will be sent to any OTLP-compatible backend');
+
+module.exports = {
+  originalConsole,
+  restoreConsole: () => {
+    console.log = originalConsole.log;
+    console.info = originalConsole.info;
+    console.warn = originalConsole.warn;
+    console.error = originalConsole.error;
+    console.debug = originalConsole.debug;
+  },
+};

package/docs/ALL-FRAMEWORKS-QUICKSTART.md

@@ -24,7 +24,7 @@ Protect any Node.js app in minutes. This guide covers **installation, CLI comman
 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](#step-7--block--manage-ips)
+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)
@@ -1087,6 +1087,45 @@ npx securenow blocklist add 185.220.101.1 --reason "brute force login attempts"
 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

package/docs/API-KEYS-GUIDE.md

@@ -0,0 +1,215 @@
+# SecureNow API Keys
+
+API keys provide programmatic access to the SecureNow platform. They support granular feature-level permissions, application scoping, IP allowlisting, and secure one-time-copy generation.
+
+---
+
+## Creating an API Key
+
+### From the Dashboard
+
+1. Go to **Settings → API Keys**
+2. Click **Create API Key**
+3. Enter a name (e.g., "Production Firewall", "CI/CD Pipeline")
+4. Select the scopes (permissions) you need
+5. Optionally restrict to specific applications and IP addresses
+6. Click **Create**
+7. **Copy the key immediately** — it will only be shown once
+
+### From the CLI
+
+```bash
+npx securenow login
+npx securenow firewall status
+```
+
+The `securenow init` and `securenow login` commands can automatically provision a firewall API key for you.
+
+---
+
+## Key Format
+
+All API keys use the format:
+
+```
+snk_live_<64 hex characters>
+```
+
+Example: `snk_live_a1b2c3d4e5f6...`
+
+The `snk_live_` prefix makes it easy to identify SecureNow keys in your codebase and credential scanners.
+
+---
+
+## Scopes (Permissions)
+
+Each API key has a set of scopes that control what it can access. Scopes follow the `resource:action` pattern.
+
+| Scope | Description |
+|-------|-------------|
+| `firewall:read` | Read the blocklist (used by the firewall SDK) |
+| `blocklist:read` | List and check blocked IPs |
+| `blocklist:write` | Add and remove blocked IPs |
+| `applications:read` | List and view applications |
+| `applications:write` | Create and delete applications |
+| `traces:read` | Query traces |
+| `logs:read` | Query logs |
+| `issues:read` | List and view security issues |
+| `issues:write` | Resolve and manage issues |
+| `alerts:read` | View alert rules, channels, and history |
+| `alerts:write` | Create and manage alert rules |
+| `analytics:read` | View analytics data |
+| `forensics:read` | Run forensic queries |
+| `ip:read` | IP intelligence lookups |
+| `trusted:read` | List trusted IPs |
+| `trusted:write` | Manage trusted IPs |
+| `notifications:read` | List notifications |
+| `notifications:write` | Mark notifications as read |
+| `api-map:read` | View API map |
+| `instances:read` | List instances |
+| `false-positives:read` | List false positive rules |
+| `false-positives:write` | Create and manage false positive rules |
+
+### Principle of Least Privilege
+
+Only grant the scopes your use case requires:
+
+- **Firewall SDK:** `firewall:read`
+- **CI/CD monitoring:** `issues:read`, `traces:read`
+- **Automated remediation:** `blocklist:read`, `blocklist:write`
+- **Dashboard integration:** all `*:read` scopes
+
+---
+
+## Application Scoping
+
+Restrict an API key to specific applications. When set, the key can only access data for those applications.
+
+Leave empty to allow access to all applications on your account.
+
+---
+
+## IP Allowlisting
+
+Restrict an API key to specific client IPs or CIDR ranges. When set, requests from other IPs are rejected with 403.
+
+```
+34.56.78.90
+10.0.0.0/24
+```
+
+Leave empty to allow from any IP.
+
+---
+
+## Using API Keys
+
+### In HTTP Requests
+
+Pass the API key in the `Authorization` header:
+
+```bash
+curl -s https://api.securenow.ai/api/v1/blocklist \
+  -H "Authorization: Bearer snk_live_abc123..."
+```
+
+### In the Firewall SDK
+
+Set the `SECURENOW_API_KEY` environment variable:
+
+```bash
+SECURENOW_API_KEY=snk_live_abc123...
+```
+
+The firewall SDK reads this automatically on startup.
+
+### In CI/CD
+
+```yaml
+# GitHub Actions example
+env:
+  SECURENOW_API_KEY: ${{ secrets.SECURENOW_API_KEY }}
+
+steps:
+  - run: |
+      ISSUES=$(curl -s https://api.securenow.ai/api/v1/issues \
+        -H "Authorization: Bearer $SECURENOW_API_KEY")
+      echo "$ISSUES" | jq '.issues | length'
+```
+
+---
+
+## Key Management
+
+### Viewing Keys
+
+```bash
+# From the CLI
+npx securenow api-keys list
+```
+
+Or go to **Settings → API Keys** in the dashboard. You'll see the key name, last 4 characters, status, scopes, and last used timestamp.
+
+### Revoking a Key
+
+```bash
+npx securenow api-keys revoke <key-id>
+```
+
+Or click **Revoke** in the dashboard. Revoked keys immediately stop working. This cannot be undone.
+
+### Regenerating a Key
+
+Regeneration creates a new key with the same name, scopes, and settings. The old key is automatically revoked.
+
+---
+
+## Rate Limits
+
+API keys are subject to rate limiting:
+
+| Endpoint | Limit |
+|----------|-------|
+| General API (`/api/*`) | 600 requests/minute |
+| Firewall sync (`/api/firewall/*`) | 120 requests/minute |
+
+Rate limit headers are included in every response:
+
+```
+X-RateLimit-Limit: 600
+X-RateLimit-Remaining: 597
+X-RateLimit-Reset: 1712534400
+```
+
+---
+
+## Security Best Practices
+
+1. **Never commit API keys to source control.** Use `.env` files or secret managers.
+2. **Use the minimum scopes required.** A firewall key only needs `firewall:read`.
+3. **Restrict by IP when possible.** Server keys should be locked to your server IPs.
+4. **Rotate keys periodically.** Use the regenerate feature to rotate without downtime.
+5. **Monitor usage.** Check the "last used" timestamp and known IPs in the dashboard.
+6. **Revoke unused keys.** Delete keys that are no longer in use.
+
+---
+
+## API Versioning
+
+All API endpoints are available at both `/api/` and `/api/v1/`. We recommend using the versioned path for stability:
+
+```bash
+# Recommended
+https://api.securenow.ai/api/v1/blocklist
+
+# Also works (unversioned)
+https://api.securenow.ai/api/blocklist
+```
+
+---
+
+## Related Documentation
+
+- [Firewall Guide](./FIREWALL-GUIDE.md) — Automatic IP blocking setup
+- [Environment Variables Reference](./ENVIRONMENT-VARIABLES.md) — All configuration options
+- [All Frameworks Quick Start](./ALL-FRAMEWORKS-QUICKSTART.md) — Framework setup guides