securenow 5.18.0 → 6.0.0

package/docs/FIREWALL-GUIDE.md

@@ -1,426 +0,0 @@
-# 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 from the SecureNow API using a version-based protocol. Layer 1 (HTTP) is always active. Layers 2-4 are opt-in via environment variables.
-
-**Sync protocol:**
-- A lightweight version check runs every 10 seconds (uses ETag/304 -- no data transferred when unchanged)
-- Full blocklist sync only when the version changes, or every 5 minutes as a safety net
-- Changes propagate to all running instances in 10-15 seconds
-- Exponential backoff with jitter when the API is temporarily unreachable
-- Automatic localhost fallback when API is co-located (ECONNREFUSED triggers retry on `http://localhost:4000`)
-
----
-
-## 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)
-```
-
-### Firewall-Only Mode (No Tracing)
-
-If you only need IP blocking without OpenTelemetry tracing:
-
-```bash
-node -r securenow/firewall-only app.js
-```
-
-This loads only the firewall with zero OTel dependencies. No `serverExternalPackages`, no `instrumentation.js`, no tracing overhead. Set `SECURENOW_API_KEY` in your environment and you're done.
-
----
-
-## 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. Auto-fallback to `http://localhost:4000` on ECONNREFUSED. |
-| `SECURENOW_FIREWALL_ENABLED` | `1` | Master kill-switch (`0` to disable) |
-| `SECURENOW_FIREWALL_VERSION_INTERVAL` | `10` | Seconds between version checks (lightweight ETag-based) |
-| `SECURENOW_FIREWALL_SYNC_INTERVAL` | `300` | Full blocklist refresh interval in seconds (safety net) |
-| `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 (`0` to silence) |
-| `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...
-```
-
-```javascript
-// next.config.js
-const { withSecureNow } = require('securenow/nextjs-webpack-config');
-module.exports = withSecureNow({ /* your config */ });
-```
-
-```typescript
-// instrumentation.ts
-export async function register() {
-  if (process.env.NEXT_RUNTIME === 'nodejs') {
-    const { registerSecureNow } = require('securenow/nextjs');
-    registerSecureNow();
-  }
-}
-```
-
-The firewall initializes independently from OpenTelemetry -- it works even if tracing setup encounters an error.
-
-### 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 version check (default every 10 seconds). Trusted IP changes also trigger immediate cache invalidation on the API side.
-
----
-
-## 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
-
-### Sync Architecture
-
-The SDK uses a unified sync endpoint (`/firewall/sync`) that combines version checking and data fetching into a single request:
-
-1. **One request per poll** — The SDK sends its current blocklist and allowlist versions. The API responds with version info and only includes full IP lists for lists that have changed.
-2. **HTTP Keep-Alive** — TCP connections are reused across polls. TLS handshake happens once; subsequent requests reuse the socket (~5-10ms vs ~100-200ms per request).
-3. **Automatic fallback** — If the unified endpoint is not available (older API), the SDK falls back to legacy separate endpoints.
-
-### Circuit Breaker & Back-Pressure
-
-- **Circuit breaker** — After 5 consecutive errors, the SDK pauses all polling for 2 minutes. After cooldown, a single probe is sent. If it succeeds, normal polling resumes.
-- **In-flight guard** — Only one poll can be in-flight at a time. If the API is slow, the next scheduled poll is skipped.
-- **429 Retry-After** — When the API returns HTTP 429, all polling pauses for the `Retry-After` duration.
-- **Exponential backoff** — Poll interval doubles on each consecutive error (10s → 20s → 40s → 80s, capped at 120s).
-
-### 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:** Wait 10-15 seconds for version-based propagation. The version check interval defaults to 10 seconds.
-
-**Check 4:** Using PM2? Make sure `node_args: '-r securenow/register'` is in your `ecosystem.config.cjs`. Without it, PM2 restarts skip the SDK entirely.
-
-### 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