securenow 5.10.2 → 5.11.1

package/docs/FIREWALL-GUIDE.md

@@ -0,0 +1,388 @@
+# SecureNow Firewall — Automatic IP Blocking for Node.js
+
+Block malicious IPs at your application layer with zero code changes. The firewall syncs your SecureNow blocklist and enforces it across up to four network layers — from HTTP 403 responses all the way down to kernel-level packet drops and cloud-edge WAF rules.
+
+---
+
+## How It Works
+
+```
+Internet Traffic
+      │
+      ▼
+┌──────────────────────────┐
+│ Layer 4: Cloud/Edge WAF  │  Blocked at CDN (Cloudflare, AWS WAF, GCP Cloud Armor)
+└──────────┬───────────────┘
+           ▼
+┌──────────────────────────┐
+│ Layer 3: OS Firewall     │  Dropped at kernel (iptables/nftables)
+└──────────┬───────────────┘
+           ▼
+┌──────────────────────────┐
+│ Layer 2: TCP Socket      │  socket.destroy() — zero bytes sent back
+└──────────┬───────────────┘
+           ▼
+┌──────────────────────────┐
+│ Layer 1: HTTP Handler    │  403 Forbidden JSON response
+└──────────┬───────────────┘
+           ▼
+      Your App
+```
+
+All layers share the same in-memory blocklist, synced every 60 seconds from the SecureNow API. Layer 1 (HTTP) is always active. Layers 2–4 are opt-in via environment variables.
+
+---
+
+## Quick Start
+
+### 1. Get an API Key
+
+```bash
+# Log in to SecureNow
+npx securenow login
+
+# View your firewall status and API key
+npx securenow firewall status
+```
+
+Or create an API key from the dashboard: **Settings → API Keys → Create Key** with the `firewall:read` scope.
+
+### 2. Add the Key to Your Environment
+
+```bash
+# .env
+SECURENOW_API_KEY=snk_live_abc123...
+```
+
+### 3. Start Your App
+
+```bash
+node -r securenow/register app.js
+```
+
+That's it. The firewall auto-activates when `SECURENOW_API_KEY` is present. You'll see:
+
+```
+[securenow] Firewall: ENABLED
+[securenow] Firewall: Layer 1 (HTTP 403)      active
+[securenow] Firewall: Layer 2 (TCP drop)       disabled (set SECURENOW_FIREWALL_TCP=1)
+[securenow] Firewall: Layer 3 (iptables)       disabled (set SECURENOW_FIREWALL_IPTABLES=1)
+[securenow] Firewall: Layer 4 (Cloud WAF)      disabled (set SECURENOW_FIREWALL_CLOUD=cloudflare|aws|gcp)
+[securenow] Firewall: synced 142 blocked IPs (138 exact + 4 CIDR ranges)
+[securenow] Firewall: next sync in 60s
+```
+
+---
+
+## Layers In Detail
+
+### Layer 1: HTTP Handler (default — always on)
+
+Intercepts every incoming HTTP/HTTPS request. Resolves the real client IP (respects `X-Forwarded-For` from trusted proxies), checks against the blocklist, and returns a 403 JSON response if blocked.
+
+```json
+{ "error": "Forbidden" }
+```
+
+Works with every framework: Express, Fastify, Next.js, NestJS, Koa, Hapi, raw `http.createServer`, etc.
+
+**Customize the status code:**
+
+```bash
+SECURENOW_FIREWALL_STATUS_CODE=429
+```
+
+### Layer 2: TCP Socket (`SECURENOW_FIREWALL_TCP=1`)
+
+Destroys the TCP connection before HTTP parsing starts. Zero bytes sent back to the attacker — they see a connection reset, not a response.
+
+```bash
+SECURENOW_FIREWALL_TCP=1
+```
+
+**Caveat:** TCP-level only sees the direct connection IP (no proxy headers). Connections from known proxy IPs are let through to Layer 1 for proper header-based resolution. Most effective for direct-to-server deployments.
+
+### Layer 3: OS Firewall (`SECURENOW_FIREWALL_IPTABLES=1`)
+
+Manages a dedicated `SECURENOW_BLOCK` iptables/nftables chain. True kernel-level `DROP` — packets never reach Node.js.
+
+```bash
+SECURENOW_FIREWALL_IPTABLES=1
+```
+
+**Requirements:**
+- Linux only (skips gracefully on macOS/Windows)
+- Requires `root` or `CAP_NET_ADMIN` capability
+- Auto-detects nftables vs iptables
+- Dedicated chain — never touches your existing rules
+- Max 10,000 rules (configurable)
+- Full cleanup on process shutdown (SIGINT/SIGTERM)
+
+### Layer 4: Cloud/Edge WAF (`SECURENOW_FIREWALL_CLOUD=<provider>`)
+
+Pushes the blocklist to your cloud WAF. Traffic is blocked at the CDN edge before it reaches your server.
+
+#### Cloudflare
+
+```bash
+SECURENOW_FIREWALL_CLOUD=cloudflare
+CLOUDFLARE_API_TOKEN=your-token
+CLOUDFLARE_ACCOUNT_ID=your-account-id
+```
+
+Creates/updates an IP List named `securenow-blocklist` with a WAF custom rule.
+
+#### AWS WAF
+
+```bash
+SECURENOW_FIREWALL_CLOUD=aws
+AWS_WAF_IP_SET_ID=your-ip-set-id
+AWS_WAF_IP_SET_NAME=securenow-blocklist  # optional, default
+AWS_WAF_SCOPE=REGIONAL                    # or CLOUDFRONT
+```
+
+Requires `@aws-sdk/client-wafv2` installed as a peer dependency:
+
+```bash
+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 `@google-cloud/compute` installed as a peer dependency:
+
+```bash
+npm install @google-cloud/compute
+```
+
+#### Dry-Run Mode
+
+Test cloud pushes without applying changes:
+
+```bash
+SECURENOW_FIREWALL_CLOUD_DRY_RUN=1
+```
+
+---
+
+## Environment Variables Reference
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SECURENOW_API_KEY` | *(required)* | API key with `firewall:read` scope |
+| `SECURENOW_API_URL` | `https://api.securenow.ai` | API base URL |
+| `SECURENOW_FIREWALL_ENABLED` | `1` | Master kill-switch (`0` to disable) |
+| `SECURENOW_FIREWALL_SYNC_INTERVAL` | `60` | Seconds between blocklist refreshes |
+| `SECURENOW_FIREWALL_FAIL_MODE` | `open` | `open` = allow when list unavailable; `closed` = block all |
+| `SECURENOW_FIREWALL_STATUS_CODE` | `403` | HTTP status code for blocked requests (Layer 1) |
+| `SECURENOW_FIREWALL_LOG` | `1` | Log blocked requests to console |
+| `SECURENOW_FIREWALL_TCP` | `0` | Enable Layer 2 TCP blocking |
+| `SECURENOW_FIREWALL_IPTABLES` | `0` | Enable Layer 3 iptables/nftables blocking |
+| `SECURENOW_FIREWALL_CLOUD` | *(none)* | Cloud WAF provider: `cloudflare`, `aws`, or `gcp` |
+| `SECURENOW_FIREWALL_CLOUD_DRY_RUN` | `0` | Log cloud pushes without applying |
+| `SECURENOW_TRUSTED_PROXIES` | *(none)* | Comma-separated trusted proxy IPs |
+
+---
+
+## Framework Examples
+
+### Express.js
+
+```bash
+# .env
+SECURENOW_APPID=my-express-app
+SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
+SECURENOW_API_KEY=snk_live_abc123...
+```
+
+```bash
+node -r securenow/register app.js
+```
+
+No code changes needed. The firewall patches `http.createServer` before Express starts.
+
+### Next.js
+
+```bash
+# .env.local
+SECURENOW_APPID=my-nextjs-app
+SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
+SECURENOW_API_KEY=snk_live_abc123...
+```
+
+Works automatically with `instrumentation.ts`:
+
+```typescript
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    await import('securenow/register');
+  }
+}
+```
+
+### PM2 Cluster
+
+```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://freetrial.securenow.ai:4318',
+      SECURENOW_API_KEY: 'snk_live_abc123...',
+      SECURENOW_NO_UUID: '1',
+      SECURENOW_FIREWALL_TCP: '1',
+    }
+  }]
+};
+```
+
+### Docker
+
+```dockerfile
+ENV SECURENOW_APPID=my-app
+ENV SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
+ENV SECURENOW_API_KEY=snk_live_abc123...
+ENV SECURENOW_FIREWALL_TCP=1
+
+CMD ["node", "-r", "securenow/register", "app.js"]
+```
+
+---
+
+## CLI Commands
+
+### Check Firewall Status
+
+```bash
+npx securenow firewall status
+```
+
+Shows: enabled/disabled, active layers, last sync time, blocked IP count, and API key info.
+
+### Test an IP
+
+```bash
+npx securenow firewall test-ip 203.0.113.42
+```
+
+Check whether a specific IP would be blocked by the current blocklist.
+
+### Manage the Blocklist
+
+```bash
+# List blocked IPs
+npx securenow blocklist
+
+# Block an IP
+npx securenow blocklist add 203.0.113.42 --reason "Brute force"
+
+# Unblock
+npx securenow blocklist remove <id>
+
+# Statistics
+npx securenow blocklist stats
+```
+
+Changes take effect on the next sync interval (default 60 seconds).
+
+---
+
+## Security Considerations
+
+### Fail-Open vs Fail-Closed
+
+By default, the firewall operates in **fail-open** mode: if the API is unreachable, all traffic is allowed. This prevents the firewall from accidentally blocking legitimate traffic due to a network issue.
+
+For high-security environments, set `SECURENOW_FIREWALL_FAIL_MODE=closed` to block all traffic when the blocklist is unavailable.
+
+### IP Resolution
+
+The firewall uses the same trusted-proxy-aware IP resolution as SecureNow tracing:
+
+- Only reads `X-Forwarded-For` / `X-Real-IP` when the direct connection comes from a private/trusted IP
+- Walks the header chain from right to left to find the first non-proxy IP
+- Configure additional trusted proxies via `SECURENOW_TRUSTED_PROXIES`
+
+### API Key Security
+
+- The firewall API key only needs the `firewall:read` scope
+- Store it in environment variables or `.env` — never commit it to source control
+- The key is hashed (SHA-256) on the server — SecureNow never stores the plaintext
+
+### Cleanup on Shutdown
+
+All layers clean up on process exit (SIGINT/SIGTERM):
+- Layer 1: restores original `http.createServer`
+- Layer 2: restores original `net.Server.prototype.listen`
+- Layer 3: removes the `SECURENOW_BLOCK` iptables/nftables chain
+- Layer 4: no cleanup needed (cloud rules persist intentionally)
+
+---
+
+## Troubleshooting
+
+### Firewall Not Activating
+
+**Check 1:** Is `SECURENOW_API_KEY` set?
+
+```bash
+echo $SECURENOW_API_KEY
+```
+
+**Check 2:** Is the firewall disabled?
+
+```bash
+# Must NOT be set to 0
+echo $SECURENOW_FIREWALL_ENABLED
+```
+
+**Check 3:** Check the startup log for sync errors:
+
+```
+[securenow] Firewall: initial sync failed: API returned 401
+```
+
+This usually means the API key is invalid or missing the `firewall:read` scope.
+
+### IPs Not Being Blocked
+
+**Check 1:** Is the IP actually in your blocklist?
+
+```bash
+npx securenow blocklist
+npx securenow firewall test-ip 1.2.3.4
+```
+
+**Check 2:** Are you behind a proxy? The firewall needs to see the real client IP. Set `SECURENOW_TRUSTED_PROXIES` to your proxy's IP.
+
+**Check 3:** Is the sync interval too long? Reduce it:
+
+```bash
+SECURENOW_FIREWALL_SYNC_INTERVAL=10
+```
+
+### iptables Layer Not Working
+
+- Must be on Linux
+- Must run as root or with `CAP_NET_ADMIN`
+- Check: `iptables -L SECURENOW_BLOCK` (should show the chain)
+
+---
+
+## Related Documentation
+
+- [API Keys Guide](./API-KEYS-GUIDE.md) — Creating and managing API keys
+- [Environment Variables Reference](./ENVIRONMENT-VARIABLES.md) — All configuration options
+- [All Frameworks Quick Start](./ALL-FRAMEWORKS-QUICKSTART.md) — Framework setup guides
+- [Automatic IP Capture](./AUTOMATIC-IP-CAPTURE.md) — How client IPs are resolved

package/docs/INDEX.md

@@ -78,8 +78,10 @@ Complete documentation for SecureNow - OpenTelemetry instrumentation for Node.js
 - **[Next.js Body Capture Comparison](NEXTJS-BODY-CAPTURE-COMPARISON.md)** - Compare different approaches
 - **[Next.js Wrapper Approach](NEXTJS-WRAPPER-APPROACH.md)** - Using wrapper functions
 
-### 🛡️ Security & Privacy
+### 🛡️ Security & Protection
 
+- **[Firewall Guide](FIREWALL-GUIDE.md)** - Automatic IP blocking (multi-layer: HTTP, TCP, iptables, Cloud WAF)
+- **[API Keys Guide](API-KEYS-GUIDE.md)** - Creating, managing, and securing API keys
 - **[Redaction Examples](REDACTION-EXAMPLES.md)** - How sensitive data is redacted
 - **[Automatic IP Capture](AUTOMATIC-IP-CAPTURE.md)** - IP address and metadata collection
 
@@ -136,6 +138,11 @@ Complete documentation for SecureNow - OpenTelemetry instrumentation for Node.js
 1. Read [Express Body Capture](EXPRESS-BODY-CAPTURE.md)
 2. Check [Request Body Capture](REQUEST-BODY-CAPTURE.md) for general info
 
+### "I want to block malicious IPs automatically"
+1. Start with [Firewall Guide](FIREWALL-GUIDE.md)
+2. Create an API key: [API Keys Guide](API-KEYS-GUIDE.md)
+3. Configure environment variables: [Environment Variables Reference](ENVIRONMENT-VARIABLES.md)
+
 ### "I need to capture IP addresses and headers"
 1. Read [Automatic IP Capture](AUTOMATIC-IP-CAPTURE.md)
 2. Understand redaction: [Redaction Examples](REDACTION-EXAMPLES.md)

package/firewall-cloud.js

@@ -0,0 +1,212 @@
+'use strict';
+
+/**
+ * Layer 4: Cloud/Edge WAF integration.
+ * Pushes the blocklist to the customer's cloud WAF provider so traffic is
+ * blocked at the CDN/edge before it ever reaches the origin server.
+ *
+ * Supported providers: cloudflare, aws, gcp
+ * Cloud SDKs are optional peer dependencies — only required when enabled.
+ * Cloud credentials are never logged.
+ */
+
+const https = require('https');
+
+let _options = null;
+let _active = false;
+let _provider = null;
+let _lastPushTime = 0;
+
+const MIN_PUSH_INTERVAL_MS = 30000;
+
+// ────── Cloudflare ──────
+
+async function cloudflareSync(ips) {
+  const token = process.env.CLOUDFLARE_API_TOKEN;
+  const accountId = process.env.CLOUDFLARE_ACCOUNT_ID;
+  if (!token || !accountId) throw new Error('Missing CLOUDFLARE_API_TOKEN or CLOUDFLARE_ACCOUNT_ID');
+
+  const listName = 'securenow-blocklist';
+
+  const lists = await cfApi('GET', `/accounts/${accountId}/rules/lists`, token);
+  let list = lists.result?.find(l => l.name === listName);
+
+  if (!list) {
+    const created = await cfApi('POST', `/accounts/${accountId}/rules/lists`, token, {
+      name: listName,
+      kind: 'ip',
+      description: 'Managed by SecureNow firewall SDK',
+    });
+    list = created.result;
+  }
+
+  const items = ips.map(ip => ({ ip: ip.includes('/') ? ip : ip + '/32' }));
+
+  await cfApi('PUT', `/accounts/${accountId}/rules/lists/${list.id}/items`, token, items);
+}
+
+function cfApi(method, path, token, body) {
+  return new Promise((resolve, reject) => {
+    const data = body ? JSON.stringify(body) : null;
+    const req = https.request({
+      hostname: 'api.cloudflare.com',
+      path: '/client/v4' + path,
+      method,
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        ...(data ? { 'Content-Length': Buffer.byteLength(data) } : {}),
+      },
+      timeout: 15000,
+    }, (res) => {
+      let chunks = '';
+      res.on('data', c => chunks += c);
+      res.on('end', () => {
+        try { resolve(JSON.parse(chunks)); } catch (e) { reject(new Error(`CF parse error: ${chunks.slice(0, 200)}`)); }
+      });
+    });
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(); reject(new Error('Cloudflare API timeout')); });
+    if (data) req.write(data);
+    req.end();
+  });
+}
+
+// ────── AWS WAF ──────
+
+async function awsSync(ips) {
+  let WAFV2;
+  try {
+    WAFV2 = require('@aws-sdk/client-wafv2');
+  } catch {
+    throw new Error('AWS WAF requires @aws-sdk/client-wafv2 — install it: npm i @aws-sdk/client-wafv2');
+  }
+
+  const ipSetId = process.env.AWS_WAF_IP_SET_ID;
+  const ipSetName = process.env.AWS_WAF_IP_SET_NAME || 'securenow-blocklist';
+  const scope = process.env.AWS_WAF_SCOPE || 'REGIONAL';
+  if (!ipSetId) throw new Error('Missing AWS_WAF_IP_SET_ID');
+
+  const client = new WAFV2.WAFV2Client({});
+
+  const { IPSet, LockToken } = await client.send(new WAFV2.GetIPSetCommand({
+    Name: ipSetName,
+    Scope: scope,
+    Id: ipSetId,
+  }));
+
+  const addresses = ips.map(ip => ip.includes('/') ? ip : ip + '/32');
+
+  await client.send(new WAFV2.UpdateIPSetCommand({
+    Name: ipSetName,
+    Scope: scope,
+    Id: ipSetId,
+    Addresses: addresses,
+    LockToken,
+    Description: 'Managed by SecureNow firewall SDK',
+  }));
+}
+
+// ────── GCP Cloud Armor ──────
+
+async function gcpSync(ips) {
+  let compute;
+  try {
+    compute = require('@google-cloud/compute');
+  } catch {
+    throw new Error('GCP Cloud Armor requires @google-cloud/compute — install it: npm i @google-cloud/compute');
+  }
+
+  const project = process.env.GCP_PROJECT_ID;
+  const policyName = process.env.GCP_SECURITY_POLICY;
+  if (!project || !policyName) throw new Error('Missing GCP_PROJECT_ID or GCP_SECURITY_POLICY');
+
+  const client = new compute.SecurityPoliciesClient();
+  const rulePriority = 2000;
+
+  const srcRanges = ips.map(ip => ip.includes('/') ? ip : ip + '/32');
+
+  try {
+    await client.patchRule({
+      project,
+      securityPolicy: policyName,
+      priority: String(rulePriority),
+      securityPolicyRuleResource: {
+        priority: rulePriority,
+        action: 'deny(403)',
+        match: { versionedExpr: 'SRC_IPS_V1', config: { srcIpRanges: srcRanges } },
+        description: 'Managed by SecureNow firewall SDK',
+      },
+    });
+  } catch (e) {
+    if (e.code === 404 || e.message?.includes('not found')) {
+      await client.addRule({
+        project,
+        securityPolicy: policyName,
+        securityPolicyRuleResource: {
+          priority: rulePriority,
+          action: 'deny(403)',
+          match: { versionedExpr: 'SRC_IPS_V1', config: { srcIpRanges: srcRanges } },
+          description: 'Managed by SecureNow firewall SDK',
+        },
+      });
+    } else {
+      throw e;
+    }
+  }
+}
+
+// ────── Provider dispatch ──────
+
+const PROVIDERS = {
+  cloudflare: cloudflareSync,
+  aws: awsSync,
+  gcp: gcpSync,
+};
+
+// ────── Public API ──────
+
+function init(options) {
+  _options = options;
+  const provider = (options.cloud || '').toLowerCase();
+
+  if (!PROVIDERS[provider]) {
+    if (_options.log) console.warn('[securenow] Firewall cloud: unknown provider "%s", expected cloudflare|aws|gcp', provider);
+    return;
+  }
+
+  _provider = provider;
+  _active = true;
+}
+
+/**
+ * Called by the firewall core after each successful blocklist sync.
+ * Throttled to max 1 push per MIN_PUSH_INTERVAL_MS.
+ * @param {string[]} ips - Array of IPs and CIDRs to push
+ */
+async function sync(ips) {
+  if (!_active || !_provider) return;
+
+  const now = Date.now();
+  if (now - _lastPushTime < MIN_PUSH_INTERVAL_MS) return;
+  _lastPushTime = now;
+
+  const dryRun = process.env.SECURENOW_FIREWALL_CLOUD_DRY_RUN === '1';
+  if (dryRun) {
+    if (_options.log) console.log('[securenow] Firewall cloud: dry-run — would push %d IPs to %s', ips.length, _provider);
+    return;
+  }
+
+  try {
+    await PROVIDERS[_provider](ips);
+    if (_options.log) console.log('[securenow] Firewall cloud: pushed %d IPs to %s', ips.length, _provider);
+  } catch (e) {
+    if (_options.log) console.warn('[securenow] Firewall cloud: push to %s failed:', _provider, e.message);
+  }
+}
+
+function shutdown() {
+  _active = false;
+}
+
+module.exports = { init, sync, shutdown };