securenow 7.7.9 → 7.7.11

package/NPM_README.md

@@ -157,7 +157,8 @@ npx securenow login --global
 # Check who you're logged in as (shows auth source)
 npx securenow whoami
 
-# Already have a firewall key? Store it without re-running login:
+# Need or already have a firewall key? Create or store it without re-running login:
+npx securenow api-key create --name "CLI firewall"
 npx securenow api-key set snk_live_abc123...   # --global for ~/.securenow/
 npx securenow api-key show                     # masked key + source
 npx securenow api-key clear                    # remove just the key
@@ -186,7 +187,7 @@ codex mcp add securenow -- npx securenow mcp
 npx -p securenow securenow-mcp
 ```
 
-The MCP surface exposes tools for applications, traces, logs, firewall, IP intelligence, forensics, notifications, blocklist, allowlist, trusted IPs, and docs-backed prompts/resources. Write actions require `confirm:true` and a reason. Use `securenow_blocklist_unblock` to stop firewall enforcement while keeping the block report/history; `securenow_blocklist_remove` is a compatibility alias.
+The MCP surface exposes tools for applications, traces, logs, firewall, IP intelligence, forensics, notifications, blocklist, allowlist, trusted IPs, rate-limit remediation, and docs-backed prompts/resources. Write actions require `confirm:true` and a reason. Use `securenow_blocklist_unblock` to stop firewall enforcement while keeping the block report/history; `securenow_blocklist_remove` is a compatibility alias.
 
 For hosted clients, SecureNow can expose the same surface at `https://api.securenow.ai/mcp`. The hosted endpoint uses the same API authentication and scope checks as the rest of SecureNow.
 
@@ -256,6 +257,8 @@ npx securenow alerts rules
 npx securenow alerts rules show <rule-id>
 npx securenow alerts rules update <rule-id> --applications-all
 npx securenow alerts rules update <rule-id> --apps key1,key2
+npx securenow alerts rules dry-run-query <rule-id> --sql @candidate.sql --app <key> --wait
+npx securenow alerts rules tune-query <rule-id> --sql @candidate.sql --reason "Preserve exploit detector, remove noisy broad match" --apply-globally --yes
 npx securenow alerts channels
 npx securenow alerts history --limit 20
 ```
@@ -489,7 +492,8 @@ npx securenow logs --json --level error | jq '.logs'
 | | `apps info <id>` | Application details |
 | | `apps delete <id>` | Delete application |
 | | `apps default <key>` | Set default app |
-| **API Key** | `api-key set <snk_live_...> [--global]` | Save firewall key to `.securenow/credentials.json` |
+| **API Key** | `api-key create [--name "CLI firewall"] [--global]` | Mint and save a firewall key with your logged-in session |
+| | `api-key set <snk_live_...> [--global]` | Save firewall key to `.securenow/credentials.json` |
 | | `api-key show` | Show masked key + source |
 | | `api-key clear [--global]` | Remove stored key (leaves session/app) |
 | **Observe** | `traces` | List traces |
@@ -525,6 +529,9 @@ npx securenow logs --json --level error | jq '.logs'
 | | `blocklist unblock <id>` | Unblock IP and retain report/history |
 | | `blocklist remove <id>` | Compatibility alias for unblock |
 | | `blocklist stats` | Block stats |
+| | `ratelimit parse "<request>"` | Fill a rate-limit draft from natural language |
+| | `ratelimit from-text "<request>" --yes` | Create a soft rate-limit rule from natural language |
+| | `ratelimit test <ip> --path /api/login` | Check whether a request would match rate-limit rules |
 | | `allowlist` | Allowed IPs (restrict-mode) |
 | | `allowlist add <ip>` | Allow IP (`--label`, `--reason`) |
 | | `allowlist remove <id>` | Remove from allowlist |
@@ -1287,6 +1294,7 @@ SecureNow provides multiple entry points depending on your needs:
 | `securenow/nuxt` | `modules: ['securenow/nuxt']` | Yes | Yes | Nuxt 3 module |
 | `securenow/nextjs-webpack-config` | `withSecureNow(config)` | - | - | Next.js config wrapper |
 | `securenow/firewall` | `require('securenow/firewall').init({...})` | No | Yes | Programmatic firewall API |
+| `securenow/rate-limits` | `require('securenow/rate-limits').parseRateLimitText(...)` | No | Yes | Rate-limit remediation API helper |
 | `securenow/tracing` | `require('securenow/tracing')` | Yes | No | Programmatic tracing API |
 
 ---

package/README.md

@@ -175,6 +175,7 @@ npx securenow login --global        # save to ~/.securenow/ instead
 npx securenow login --token <TOKEN> # headless (CI)
 npx securenow init --env local      # scaffold framework files + local env scope
 npx securenow credentials runtime --env production # write tokenless production credentials file
+npx securenow api-key create --name "CLI firewall" # mint + store firewall key
 npx securenow api-key set snk_live_... # store firewall key in .securenow/credentials.json
 
 # Apps
@@ -214,7 +215,7 @@ codex mcp add securenow -- npx securenow mcp
 npx -p securenow securenow-mcp
 ```
 
-The MCP server reuses the same project-local `.securenow/credentials.json` as the CLI and SDK. It exposes tools for apps, traces, logs, firewall, IP intelligence, forensics, blocklist/allowlist/trusted IPs, plus resources for the bundled SecureNow docs and setup prompts.
+The MCP server reuses the same project-local `.securenow/credentials.json` as the CLI and SDK. It exposes tools for apps, traces, logs, firewall, IP intelligence, forensics, blocklist/allowlist/trusted IPs, rate-limit remediation, plus resources for the bundled SecureNow docs and setup prompts.
 
 ---
 
@@ -301,6 +302,7 @@ After install, the `securenow` CLI is available via `npx securenow` or globally
 | `securenow logout` | Clear project-local credentials |
 | `securenow logout --global` | Clear ~/.securenow/ instead |
 | `securenow whoami` | Show current session (email, app, expiry) |
+| `securenow api-key create [--name "CLI firewall"]` | Mint and store a firewall key using your session token |
 | `securenow api-key set <snk_live_...>` | Store firewall key in `.securenow/credentials.json` (`--global` for `~/.securenow/`) |
 | `securenow api-key show` | Print masked key + source file |
 | `securenow api-key clear` | Remove stored key (`--global` for `~/.securenow/`) |
@@ -334,6 +336,8 @@ After install, the `securenow` CLI is available via `npx securenow` or globally
 | `securenow notifications` | List notifications |
 | `securenow notifications unread` | Unread count |
 | `securenow alerts rules` | List alert rules |
+| `securenow alerts rules dry-run-query <id> --sql @candidate.sql --wait` | Dry-run candidate alert SQL without saving |
+| `securenow alerts rules tune-query <id> --sql @candidate.sql --apply-globally --yes` | Admin: update a shared system rule query mapping |
 | `securenow alerts history` | Alert history |
 
 ### Investigate
@@ -359,6 +363,8 @@ After install, the `securenow` CLI is available via `npx securenow` or globally
 | `securenow blocklist` | List blocked IPs |
 | `securenow blocklist add <ip> [--reason ...]` | Block an IP |
 | `securenow blocklist unblock <id> [--reason ...]` | Stop enforcement and keep block history |
+| `securenow ratelimit parse "<request>"` | Fill a rate-limit rule draft from natural language |
+| `securenow ratelimit from-text "<request>" --yes` | Create a soft rate-limit rule from natural language |
 | `securenow allowlist add <ip>` | Allow an IP (restrict-mode) |
 | `securenow trusted add <ip>` | Mark an IP as trusted |
 

package/SKILL-API.md

@@ -4,7 +4,9 @@ Instrument any Node.js application with OpenTelemetry tracing, structured loggin
 
 **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.
 
-**MCP parity (v7.5+):** `npx securenow mcp` starts a local stdio MCP server for Codex, Claude, and other MCP clients. It reuses the same `.securenow/credentials.json` file as the CLI/SDK and exposes SecureNow tools, bundled docs resources, and setup prompts to agents.
+**MCP parity (v7.5+):** `npx securenow mcp` starts a local stdio MCP server for Codex, Claude, and other MCP clients. It reuses the same `.securenow/credentials.json` file as the CLI/SDK and exposes SecureNow tools, bundled docs resources, and setup prompts to agents. Alert-rule operators can inspect notifications, read exact `metadata.matchedSubdetectors`, dry-run candidate SQL with `securenow_alert_rule_candidate_test`, and apply global system-rule query fixes with `securenow_alert_rule_query_update` when evidence is clear.
+
+**Noisy alert-rule reviews:** prefer fixing a generic system-rule detector over creating customer-specific false positives. Dry-run candidate SQL first, preserve tenant scoping with `__USER_APP_KEYS__`, keep exploit-specific indicators, then save the shared query mapping only with an audit reason and explicit confirmation.
 
 ## Installation
 
@@ -97,9 +99,10 @@ operator needs to ensure those defaults immediately.
 | `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/nuxt` | Nuxt 3 module (add to `modules` array) | ESM |
+| `securenow/firewall` | Standalone firewall; exports `init()`, `shutdown()`, `getStats()`, `getMatcher()`, `getAllowlistMatcher()` | CJS |
+| `securenow/rate-limits` | Rate-limit remediation API helper; exports `parseRateLimitText()`, `createRateLimitFromText()`, `createRateLimit()`, `listRateLimits()` | 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 |

package/SKILL-CLI.md

@@ -24,7 +24,7 @@ codex mcp add securenow -- npx securenow mcp
 npx -p securenow securenow-mcp
 ```
 
-The MCP server reuses `.securenow/credentials.json` and exposes apps, traces, logs, firewall, IP intelligence, forensics, notifications, remediation tools, bundled docs resources, and setup prompts. Write tools require `confirm:true` plus a reason.
+The MCP server reuses `.securenow/credentials.json` and exposes apps, traces, logs, firewall, IP intelligence, forensics, notifications, remediation tools, alert-rule review/tuning tools, bundled docs resources, and setup prompts. Write tools require `confirm:true` plus a reason.
 
 ### Authenticate
 
@@ -153,16 +153,17 @@ securenow apps scan [--yes]                  # scan all app domains for new subd
 
 Manage the firewall API key stored in the credentials file. Since v7.5.1 the login flow writes `snk_live_...` keys to `.securenow/credentials.json` by default, so no env var is required for local dev.
 
-```bash
-securenow api-key set snk_live_xxxxxxxxxx    # save to project ./.securenow/ (default)
-securenow api-key set snk_live_xxx --global  # save to ~/.securenow/ instead
+```bash
+securenow api-key create --name "CLI firewall" # mint + save a firewall key with your logged-in session
+securenow api-key set snk_live_xxxxxxxxxx    # save to project ./.securenow/ (default)
+securenow api-key set snk_live_xxx --global  # save to ~/.securenow/ instead
 securenow api-key show                       # print the masked current key + its source
 securenow api-key clear                      # remove just the API key (keeps session/app)
 securenow api-key clear --global             # same, but from the global file
 securenow credentials runtime --env production # write .securenow/credentials.production.json for production secret-file deploys
 ```
 
-The key must start with `snk_live_`. `securenow login` with firewall enabled writes the key automatically; use `api-key set` when you already have a key from the dashboard, or to rotate it later.
+The key must start with `snk_live_`. `securenow login` with firewall enabled writes the key automatically; use `api-key create` when you have an account session but no runtime key yet, or `api-key set` when you already have a key from the dashboard.
 
 ### Init — Project Setup
 
@@ -239,7 +240,7 @@ MCP parity:
 - `securenow_human_case_action_update`
 - prompts: `investigate_human_action_row`, `work_human_actions`
 
-Write tools still require `confirm:true` plus a reason. False positives should stay restrictive to the app, alert rule, path, method/status, user-agent, body pattern, or other exact evidence the AI report supports.
+Write tools still require `confirm:true` plus a reason. False positives should stay restrictive to the app, alert rule, path, method/status, user-agent, body pattern, or other exact evidence the AI report supports. Notification IP investigations can include `metadata.matchedSubdetectors`; prefer that exact field over inferring which subdetector fired from the title or sample body.
 
 ### Alerts
 
@@ -250,10 +251,22 @@ securenow alerts rules show <id>            # one rule; JSON: --json
 securenow alerts rules update <id> --applications-all   # all current & future apps
 securenow alerts rules update <id> --apps key1,key2     # explicit app keys only
 securenow alerts rules test <id> --mode dry_run --wait  # validate a rule query
+securenow alerts rules dry-run-query <id> --sql @candidate.sql --app <key> --wait
+securenow alerts rules tune-query <id> --sql @candidate.sql --reason "Preserve exploit detector, remove benign broad match" --apply-globally --yes
 securenow alerts rules exclusions <id> list              # embedded rule exclusions
 securenow alerts channels                    # list alert channels (Slack, email, etc.)
-securenow alerts history [--limit N]         # past triggered alerts
-```
+securenow alerts history [--limit N]         # past triggered alerts
+```
+
+MCP parity for noisy alert-rule reviews:
+
+- `securenow_alert_rule_get`
+- `securenow_alert_rule_candidate_test` dry-runs a full candidate SQL query without saving it.
+- `securenow_alert_rule_test_result` polls the dry-run.
+- `securenow_alert_rule_query_update` updates the shared public query mapping behind a system rule for all customer copies. It is admin-only, requires `confirm:true`, `applyGlobally:true`, `reason`, and SQL that keeps `__USER_APP_KEYS__` tenant scoping.
+- `securenow_alert_rule_exclusion_add` remains the last-resort customer-specific path; it supports restrictive conditions plus `matchMode` and should not be used to hide a generic system-rule bug.
+
+For system-rule tuning, dry-run the candidate SQL first, then save with `tune-query`/`securenow_alert_rule_query_update` only when the guard preserves attack detection. Good guards add exact exploit tokens, dangerous schemes, matched subdetectors, sensitive path/status evidence, malicious user agents, or repeat thresholds; bad guards simply suppress a noisy path.
 
 ---
 
@@ -322,6 +335,21 @@ work:
 - `securenow_blocklist_pending_bulk_reject`
 - prompt: `cleanup_legacy_pending_blocks`
 
+### Rate Limits - Soft Remediation
+
+```bash
+securenow ratelimit list --env production
+securenow ratelimit add 203.0.113.42 --route /api/login --limit 2 --window 1m --duration 24h
+securenow ratelimit parse "rate limit 203.0.113.42 on POST /api/login to 2 attempts per minute"
+securenow ratelimit from-text "rate limit /api/login for this IP to 2 attempts per minute for 24h" --yes
+securenow ratelimit test 203.0.113.42 --path /api/login --method POST
+```
+
+MCP parity:
+
+- `securenow_rate_limit_parse`
+- `securenow_rate_limit_create_from_text`
+
 ### Automation Rules
 
 ```bash

package/cli/apiKey.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const { api, requireAuth } = require('./client');
 const config = require('./config');
 const ui = require('./ui');
 
@@ -8,6 +9,47 @@ function maskKey(key) {
   return `${key.slice(0, 12)}••••••${key.slice(-4)}`;
 }
 
+async function create(args, flags) {
+  requireAuth();
+
+  const name = flags.name || args.join(' ').trim() || 'CLI firewall';
+  const preset = flags.preset || 'firewall';
+  const local = flags.global ? false : true;
+
+  const s = ui.spinner(`Creating ${preset} API key`);
+  try {
+    const result = await api.post('/api-keys', { name, preset });
+    const key = result && result.key;
+    if (!key || !key.startsWith('snk_live_')) {
+      throw new Error('API did not return a valid firewall key');
+    }
+
+    config.setApiKey(key, { local });
+    if (local) config.ensureLocalGitignore();
+    s.stop('API key created and saved');
+
+    if (flags.json) {
+      ui.json({
+        id: result.apiKey?._id || result.apiKey?.id || null,
+        name: result.apiKey?.name || name,
+        preset,
+        key: maskKey(key),
+        savedTo: local ? 'project .securenow/credentials.json' : '~/.securenow/credentials.json',
+      });
+      return;
+    }
+
+    ui.success(`API key saved (${maskKey(key)})`);
+    ui.info(local
+      ? 'Stored in project .securenow/credentials.json (local)'
+      : 'Stored in ~/.securenow/credentials.json (global)');
+    ui.info('The plaintext key is not printed. The SDK will read it from the credentials file.');
+  } catch (err) {
+    s.fail('Failed to create API key');
+    throw err;
+  }
+}
+
 async function set(args, flags) {
   const key = args[0];
   if (!key) {
@@ -52,4 +94,4 @@ async function show() {
   ui.info(`Source: ${config.getAuthSource()}`);
 }
 
-module.exports = { set, clear, show };
+module.exports = { create, set, clear, show };

package/cli/config.js

@@ -47,6 +47,12 @@ function saveJSON(filepath, data) {
   }
 }
 
+function credentialsForWrite(targetFile) {
+  const inherited = loadCredentials() || {};
+  const existing = loadJSON(targetFile);
+  return appConfig.mergeCredentials(inherited, existing) || {};
+}
+
 function credentialsFileForLocal(local) {
   return local ? LOCAL_CREDENTIALS_FILE : CREDENTIALS_FILE;
 }
@@ -113,7 +119,7 @@ function withOnboardingFirewallEnabled(creds) {
 function ensureCredentialDefaults({ local, enableFirewall = false } = {}) {
   const useLocal = local === true || (local == null && hasLocalCredentials());
   const targetFile = credentialsFileForLocal(useLocal);
-  const existing = loadJSON(targetFile);
+  const existing = useLocal ? credentialsForWrite(targetFile) : loadJSON(targetFile);
   const payload = enableFirewall
     ? withOnboardingFirewallEnabled(existing || {})
     : appConfig.withCredentialDefaults(existing || {}) || {};
@@ -168,7 +174,7 @@ function getApp() {
 function setApiKey(apiKey, { local } = {}) {
   const useLocal = local === true || (local == null && hasLocalCredentials());
   const targetFile = credentialsFileForLocal(useLocal);
-  const existing = loadJSON(targetFile);
+  const existing = useLocal ? credentialsForWrite(targetFile) : loadJSON(targetFile);
   saveJSON(targetFile, withOnboardingFirewallEnabled({ ...existing, apiKey }));
 }
 
@@ -189,7 +195,7 @@ function getApiKey() {
 function setApp(app, { local } = {}) {
   const useLocal = local === true || (local == null && hasLocalCredentials());
   const targetFile = credentialsFileForLocal(useLocal);
-  const existing = loadJSON(targetFile);
+  const existing = useLocal ? credentialsForWrite(targetFile) : loadJSON(targetFile);
   saveJSON(targetFile, appConfig.withCredentialDefaults({
     ...existing,
     app: {

package/cli/rateLimits.js

@@ -47,6 +47,54 @@ function describeTarget(rule) {
   return parts.join(' ') || 'all traffic';
 }
 
+function naturalText(args, flags) {
+  return String(flags.text || flags.prompt || flags.query || args.join(' ') || '').trim();
+}
+
+function draftFromFlags(flags) {
+  const draft = {};
+  const appKey = resolveApp(flags);
+  const environment = resolveEnvironment(flags, null);
+  if (appKey) draft.appKey = appKey;
+  if (environment) draft.environment = environment;
+  if (flags.ip) draft.ip = flags.ip;
+  if (flags.route || flags.path || flags.pattern) draft.pathPattern = flags.route || flags.path || flags.pattern;
+  if (flags.mode || flags['path-mode']) draft.pathMatchMode = flags.mode || flags['path-mode'];
+  if (flags.method) draft.method = flags.method;
+  if (flags['key-by'] || flags.keyBy) draft.keyBy = flags['key-by'] || flags.keyBy;
+  if (flags.limit) draft.limit = Number(flags.limit);
+  if (flags.window || flags['window-seconds']) draft.windowSeconds = parseWindow(flags.window || flags['window-seconds']);
+  if (flags.duration) draft.duration = flags.duration;
+  if (flags.reason) draft.reason = flags.reason;
+  if (flags.name) draft.name = flags.name;
+  return draft;
+}
+
+function printParsedDraft(data) {
+  const draft = data.draft || {};
+  ui.keyValue([
+    ['Name', draft.name || '-'],
+    ['Target', describeTarget(draft)],
+    ['Limit', `${draft.limit || '-'} / ${draft.windowSeconds || '-'}s`],
+    ['Key by', draft.keyBy || 'ip'],
+    ['App', draft.appKey || 'all'],
+    ['Environment', draft.environment || 'all'],
+    ['Duration', draft.duration || 'none'],
+    ['Status', draft.status || 'active'],
+    ['Reason', draft.reason || '-'],
+    ['Provider', data.provider || '-'],
+    ['Confidence', data.confidence != null ? String(data.confidence) : '-'],
+  ]);
+  if (Array.isArray(data.missingFields) && data.missingFields.length) {
+    console.log('');
+    console.log(`  ${ui.c.yellow('Missing:')} ${data.missingFields.join(', ')}`);
+  }
+  if (Array.isArray(data.warnings) && data.warnings.length) {
+    console.log('');
+    for (const warning of data.warnings.slice(0, 5)) console.log(`  ${ui.c.yellow('!')} ${warning}`);
+  }
+}
+
 async function list(args, flags) {
   requireAuth();
   const s = ui.spinner('Fetching rate limits');
@@ -76,6 +124,58 @@ async function list(args, flags) {
   }
 }
 
+async function parseText(args, flags) {
+  requireAuth();
+  const text = naturalText(args, flags);
+  if (!text) {
+    ui.error('Usage: securenow ratelimit parse "rate limit /api/login to 2 attempts per minute"');
+    process.exit(1);
+  }
+
+  const s = ui.spinner('Parsing natural-language rate limit');
+  try {
+    const data = await api.post('/rate-limits/parse', { text, draft: draftFromFlags(flags) });
+    s.stop('Rate-limit draft parsed');
+    if (flags.json) { ui.json(data); return; }
+    console.log('');
+    printParsedDraft(data);
+    console.log('');
+    console.log(`  ${ui.c.dim('Create it with:')} securenow ratelimit from-text ${JSON.stringify(text)} --yes`);
+    console.log('');
+  } catch (err) {
+    s.fail('Failed to parse rate limit');
+    throw err;
+  }
+}
+
+async function fromText(args, flags) {
+  requireAuth();
+  const text = naturalText(args, flags);
+  if (!text) {
+    ui.error('Usage: securenow ratelimit from-text "rate limit /api/login to 2 attempts per minute" --yes');
+    process.exit(1);
+  }
+  if (!flags.yes && !flags.force) {
+    const ok = await ui.confirm('Create this rate-limit rule from natural language?');
+    if (!ok) { ui.info('Cancelled'); return; }
+  }
+
+  const s = ui.spinner('Creating rate limit from natural language');
+  try {
+    const data = await api.post('/rate-limits/from-text', { text, draft: draftFromFlags(flags) });
+    s.stop('Rate limit created');
+    if (flags.json) { ui.json(data); return; }
+    const r = data.rateLimit;
+    console.log('');
+    console.log(`  ${ui.c.green('ACTIVE')} ${describeTarget(r)} at ${r.limit}/${r.windowSeconds}s`);
+    console.log(`  ${ui.c.dim('ID:')} ${r.id || r._id}`);
+    console.log('');
+  } catch (err) {
+    s.fail('Failed to create rate limit from text');
+    throw err;
+  }
+}
+
 async function show(args, flags) {
   requireAuth();
   const id = args[0];
@@ -242,4 +342,4 @@ async function test(args, flags) {
   }
 }
 
-module.exports = { list, show, add, enable, disable, remove, test };
+module.exports = { list, show, add, parseText, fromText, enable, disable, remove, test };

package/cli/security.js

@@ -1,8 +1,9 @@
-'use strict';
-
-const { api, requireAuth } = require('./client');
-const config = require('./config');
-const ui = require('./ui');
+'use strict';
+
+const fs = require('fs');
+const { api, requireAuth } = require('./client');
+const config = require('./config');
+const ui = require('./ui');
 
 function resolveApp(flags) {
   return flags.app || config.getDefaultApp();
@@ -44,6 +45,12 @@ async function alertRulesRoute(args, flags) {
   if (sub === 'test') {
     return alertRuleTest(args.slice(1), flags);
   }
+  if (sub === 'dry-run-query' || sub === 'candidate-test') {
+    return alertRuleCandidateTest(args.slice(1), flags);
+  }
+  if (sub === 'tune-query' || sub === 'query-update') {
+    return alertRuleQueryUpdate(args.slice(1), flags);
+  }
   if (sub === 'exclusions') {
     return alertRuleExclusions(args.slice(1), flags);
   }
@@ -180,6 +187,16 @@ async function alertRuleUpdate(args, flags) {
   }
 }
 
+function readSqlArg(flags) {
+  const raw = flags.sql || flags.query || flags.file;
+  if (!raw) return null;
+  if (flags.file) return fs.readFileSync(flags.file, 'utf8');
+  const text = String(raw);
+  if (text === '-') return fs.readFileSync(0, 'utf8');
+  if (text.startsWith('@')) return fs.readFileSync(text.slice(1), 'utf8');
+  return text;
+}
+
 async function alertRuleTest(args, flags) {
   requireAuth();
   const id = args[0];
@@ -219,6 +236,100 @@ async function alertRuleTest(args, flags) {
   }
 }
 
+async function alertRuleCandidateTest(args, flags) {
+  requireAuth();
+  const id = args[0];
+  const candidateSqlQuery = readSqlArg(flags);
+  if (!id || !candidateSqlQuery) {
+    ui.error('Usage: securenow alerts rules dry-run-query <rule-id> --sql <sql|@file|-> [--app <key>] [--wait]');
+    process.exit(1);
+  }
+
+  const body = { mode: 'dry_run', candidateSqlQuery };
+  if (flags.app) body.applicationKey = flags.app;
+
+  const s = ui.spinner('Starting candidate SQL dry-run');
+  try {
+    let data = await api.post(`/alert-rules/${id}/test`, body);
+    if (flags.wait && data.testId) {
+      s.update('Waiting for candidate SQL dry-run results');
+      for (let i = 0; i < 40; i++) {
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+        data = await api.get(`/alert-rules/${id}/test/${data.testId}`);
+        if (['complete', 'failed'].includes(data.status)) break;
+      }
+    }
+    s.stop('Candidate dry-run ready');
+    if (flags.json) { ui.json(data); return; }
+    console.log('');
+    ui.keyValue([
+      ['Test ID', data.testId || '-'],
+      ['Status', data.status || '-'],
+      ['Candidate', data.candidate ? 'yes' : 'no'],
+      ['Current SQL hash', data.currentSqlHash || '-'],
+      ['Candidate SQL hash', data.candidateSqlHash || '-'],
+      ['Result count', String(data.resultCount ?? '-')],
+      ['Error', data.error || '-'],
+    ]);
+    console.log('');
+  } catch (err) {
+    s.fail('Failed to dry-run candidate SQL');
+    throw err;
+  }
+}
+
+async function alertRuleQueryUpdate(args, flags) {
+  requireAuth();
+  const id = args[0];
+  const sqlQuery = readSqlArg(flags);
+  const reason = flags.reason;
+  if (!id || !sqlQuery || !reason) {
+    ui.error('Usage: securenow alerts rules tune-query <rule-id> --sql <sql|@file|-> --reason "..." --apply-globally --yes');
+    process.exit(1);
+  }
+  if (!flags['apply-globally'] && flags.applyGlobally !== true) {
+    ui.error('System query tuning requires --apply-globally.');
+    process.exit(1);
+  }
+
+  if (!flags.force && !flags.yes) {
+    const ok = await ui.confirm('Update the shared system query mapping for all customer copies?');
+    if (!ok) {
+      ui.info('Cancelled');
+      return;
+    }
+  }
+
+  const body = {
+    sqlQuery,
+    reason,
+    applyGlobally: true,
+    reactivatePausedCopies: !!(flags['reactivate-paused'] || flags.reactivatePausedCopies),
+  };
+  if (flags['expected-hash']) body.expectedCurrentSqlHash = flags['expected-hash'];
+  if (flags.notification) body.reviewNotificationId = flags.notification;
+  if (flags.note) body.reviewNote = flags.note;
+
+  const s = ui.spinner('Updating system query mapping');
+  try {
+    const data = await api.put(`/alert-rules/${id}/query-mapping`, body);
+    s.stop('System query mapping updated');
+    if (flags.json) { ui.json(data); return; }
+    console.log('');
+    ui.keyValue([
+      ['Query mapping', data.queryMapping?.name || data.queryMapping?.id || '-'],
+      ['Previous SQL hash', data.queryMapping?.previousSqlHash || '-'],
+      ['New SQL hash', data.queryMapping?.newSqlHash || '-'],
+      ['Affected system rules', String(data.affectedSystemRules ?? '-')],
+      ['Reactivated paused copies', data.reactivatedPausedCopies ? 'yes' : 'no'],
+    ]);
+    console.log('');
+  } catch (err) {
+    s.fail('Failed to update system query mapping');
+    throw err;
+  }
+}
+
 async function alertRuleExclusions(args, flags) {
   requireAuth();
   const id = args[0];

package/cli.js

@@ -77,11 +77,21 @@ const COMMANDS = {
   },
   'api-key': {
     desc: 'Manage the firewall API key stored in .securenow/credentials.json',
-    usage: 'securenow api-key <subcommand> [options]',
-    sub: {
-      set: {
-        desc: 'Save an API key (snk_live_...) to the credentials file',
-        usage: 'securenow api-key set <snk_live_...> [--global]',
+    usage: 'securenow api-key <subcommand> [options]',
+    sub: {
+      create: {
+        desc: 'Create a firewall API key with your session token and save it',
+        usage: 'securenow api-key create [name] [--name <name>] [--preset firewall] [--global]',
+        flags: {
+          name: 'Human-readable key name',
+          preset: 'API key preset to create (default: firewall)',
+          global: 'Save to ~/.securenow/ instead of project-local',
+        },
+        run: (a, f) => require('./cli/apiKey').create(a, f),
+      },
+      set: {
+        desc: 'Save an API key (snk_live_...) to the credentials file',
+        usage: 'securenow api-key set <snk_live_...> [--global]',
         flags: { global: 'Save to ~/.securenow/ instead of project-local' },
         run: (a, f) => require('./cli/apiKey').set(a, f),
       },
@@ -208,16 +218,30 @@ const COMMANDS = {
     desc: 'Manage alerting',
     usage: 'securenow alerts <subcommand> [options]',
     sub: {
-      rules: {
-        desc: 'List, show, or update alert rules',
-        flags: {
-          json: 'Output as JSON',
-          'applications-all': 'With update: scope rule to all apps',
-          'no-applications-all': 'With update: scope to explicit --apps list',
-          apps: 'Comma-separated app keys (with update)',
-        },
-        run: (a, f) => require('./cli/security').alertRulesRoute(a, f),
-      },
+      rules: {
+        desc: 'List, show, update, test, or tune alert rules',
+        flags: {
+          json: 'Output as JSON',
+          'applications-all': 'With update: scope rule to all apps',
+          'no-applications-all': 'With update: scope to explicit --apps list',
+          apps: 'Comma-separated app keys (with update)',
+          app: 'Application key for rule tests',
+          mode: 'Rule test mode: dry_run or live',
+          wait: 'Wait for rule test completion',
+          sql: 'Candidate/replacement SQL, @file, or - for stdin',
+          query: 'Alias for --sql',
+          file: 'Read candidate/replacement SQL from a file',
+          reason: 'Audit reason for a write',
+          'apply-globally': 'Required for system query tuning',
+          'reactivate-paused': 'Reactivate paused system copies after tuning',
+          'expected-hash': 'Expected current SQL SHA-256 hash',
+          notification: 'Review notification id tied to tuning',
+          note: 'Review note tied to tuning',
+          yes: 'Confirm write prompts',
+          force: 'Confirm write prompts',
+        },
+        run: (a, f) => require('./cli/security').alertRulesRoute(a, f),
+      },
       channels: { desc: 'List alert channels', run: (a, f) => require('./cli/security').alertChannelsList(a, f) },
       history: { desc: 'View alert history', flags: { limit: 'Max results' }, run: (a, f) => require('./cli/security').alertHistoryList(a, f) },
     },
@@ -255,7 +279,7 @@ const COMMANDS = {
   },
   ratelimit: {
     desc: 'Manage soft rate-limit remediation rules',
-    usage: 'securenow ratelimit <list|add|show|test|enable|disable|remove> [options]',
+    usage: 'securenow ratelimit <list|add|parse|from-text|show|test|enable|disable|remove> [options]',
     flags: {
       app: 'Scope to app key (defaults to logged-in app)',
       env: 'Scope to environment (default for create/test: production)',
@@ -269,10 +293,13 @@ const COMMANDS = {
       mode: 'Path mode: exact, prefix, or regex',
       method: 'HTTP method, or ALL',
       reason: 'Audit reason',
+      text: 'Natural-language rate-limit request',
     },
     sub: {
       list: { desc: 'List rate-limit remediation rules', run: (a, f) => require('./cli/rateLimits').list(a, f) },
       add: { desc: 'Create a rate-limit rule', usage: 'securenow ratelimit add [ip] --route /api/login --limit 5 --window 1m --duration 24h', run: (a, f) => require('./cli/rateLimits').add(a, f) },
+      parse: { desc: 'Parse natural language into a rate-limit draft', usage: 'securenow ratelimit parse "rate limit /api/login to 2 attempts per minute"', run: (a, f) => require('./cli/rateLimits').parseText(a, f) },
+      'from-text': { desc: 'Create a rate-limit rule from natural language', usage: 'securenow ratelimit from-text "rate limit /api/login to 2 attempts per minute" --yes', run: (a, f) => require('./cli/rateLimits').fromText(a, f) },
       show: { desc: 'Show one rate-limit rule', usage: 'securenow ratelimit show <id>', run: (a, f) => require('./cli/rateLimits').show(a, f) },
       test: { desc: 'Check whether a request would match rate-limit rules', usage: 'securenow ratelimit test <ip> --path /api/login --method POST', run: (a, f) => require('./cli/rateLimits').test(a, f) },
       enable: { desc: 'Enable a rate-limit rule', usage: 'securenow ratelimit enable <id>', run: (a, f) => require('./cli/rateLimits').enable(a, f) },
@@ -283,10 +310,27 @@ const COMMANDS = {
   },
   'rate-limit': {
     desc: 'Alias for ratelimit',
-    usage: 'securenow rate-limit <list|add|show|test|enable|disable|remove> [options]',
+    usage: 'securenow rate-limit <list|add|parse|from-text|show|test|enable|disable|remove> [options]',
+    flags: {
+      app: 'Scope to app key (defaults to logged-in app)',
+      env: 'Scope to environment (default for create/test: production)',
+      environment: 'Alias for --env',
+      json: 'Output as JSON',
+      limit: 'Allowed requests per window',
+      window: 'Window size, e.g. 30s, 1m, 1h',
+      duration: 'Expiry, e.g. 24h or 7d',
+      route: 'Path pattern such as /api/login',
+      path: 'Alias for --route',
+      mode: 'Path mode: exact, prefix, or regex',
+      method: 'HTTP method, or ALL',
+      reason: 'Audit reason',
+      text: 'Natural-language rate-limit request',
+    },
     sub: {
       list: { desc: 'List rate-limit remediation rules', run: (a, f) => require('./cli/rateLimits').list(a, f) },
       add: { desc: 'Create a rate-limit rule', usage: 'securenow rate-limit add [ip] --route /api/login --limit 5 --window 1m --duration 24h', run: (a, f) => require('./cli/rateLimits').add(a, f) },
+      parse: { desc: 'Parse natural language into a rate-limit draft', usage: 'securenow rate-limit parse "rate limit /api/login to 2 attempts per minute"', run: (a, f) => require('./cli/rateLimits').parseText(a, f) },
+      'from-text': { desc: 'Create a rate-limit rule from natural language', usage: 'securenow rate-limit from-text "rate limit /api/login to 2 attempts per minute" --yes', run: (a, f) => require('./cli/rateLimits').fromText(a, f) },
       show: { desc: 'Show one rate-limit rule', usage: 'securenow rate-limit show <id>', run: (a, f) => require('./cli/rateLimits').show(a, f) },
       test: { desc: 'Check whether a request would match rate-limit rules', usage: 'securenow rate-limit test <ip> --path /api/login --method POST', run: (a, f) => require('./cli/rateLimits').test(a, f) },
       enable: { desc: 'Enable a rate-limit rule', usage: 'securenow rate-limit enable <id>', run: (a, f) => require('./cli/rateLimits').enable(a, f) },

package/mcp/catalog.js

@@ -169,7 +169,7 @@ const decisionReportInput = {
     description: 'Structured audit report explaining the decision, evidence reviewed, trace IDs, missing proof, and recommendations.',
   },
   decisionSummary: string('Short decision summary to record on the IP/case history.'),
-  outcome: string('Decision outcome: blocked, false_positive, clean, deferred, case_action, rule_tuning, new_alert_rule, ambiguous, skipped, or other.'),
+  outcome: string('Decision outcome: blocked, rate_limited, false_positive, clean, deferred, case_action, rule_tuning, new_alert_rule, ambiguous, skipped, or other.'),
   evidence: arrayOfStrings('Evidence strings that support the decision.'),
   reviewedHistory: arrayOfStrings('History/proofs reviewed before deciding.'),
   traceIds: arrayOfStrings('Trace IDs reviewed for this decision.'),
@@ -513,7 +513,7 @@ const TOOLS = [
   {
     name: 'securenow_human_action_decision_report_add',
     title: 'Record Human Action Decision Report',
-    description: 'Attach a structured analyst/MCP decision report to one Requires Human IP row without changing its status. Use for skipped, ambiguous, rule-tuning-needed, or already-handled rows. Write action; requires confirmation.',
+    description: 'Attach a structured analyst/MCP decision report to one Requires Human IP row without changing its status. Use for rate-limited, skipped, ambiguous, rule-tuning-needed, or already-handled rows. Write action; requires confirmation.',
     scope: 'notifications:write',
     readOnly: false,
     confirm: true,
@@ -802,6 +802,36 @@ const TOOLS = [
       ...confirmSchema,
     }, ['id', 'confirm', 'reason']),
   },
+  {
+    name: 'securenow_rate_limit_parse',
+    title: 'Parse Rate Limit Text',
+    description: 'Use SecureNow AI to convert natural language into a rate-limit remediation draft without creating it.',
+    scope: 'rate_limits:read',
+    readOnly: true,
+    method: 'POST',
+    endpoint: '/rate-limits/parse',
+    bodyFields: ['text', 'draft'],
+    inputSchema: objectSchema({
+      text: string('Natural-language rate-limit request, e.g. "rate limit /api/login to 2 attempts per minute for this IP".'),
+      draft: { type: 'object', additionalProperties: true, description: 'Optional existing draft fields to preserve or resolve phrases such as "this IP".' },
+    }, ['text']),
+  },
+  {
+    name: 'securenow_rate_limit_create_from_text',
+    title: 'Create Rate Limit From Text',
+    description: 'Create a rate-limit remediation rule from natural language. Write action; requires confirmation.',
+    scope: 'rate_limits:write',
+    readOnly: false,
+    confirm: true,
+    method: 'POST',
+    endpoint: '/rate-limits/from-text',
+    bodyFields: ['text', 'draft', 'reason'],
+    inputSchema: objectSchema({
+      text: string('Natural-language rate-limit request.'),
+      draft: { type: 'object', additionalProperties: true, description: 'Optional existing draft fields or scope hints.' },
+      ...confirmSchema,
+    }, ['text', 'confirm', 'reason']),
+  },
   {
     name: 'securenow_alert_rules_list',
     title: 'List Alert Rules',
@@ -852,6 +882,29 @@ const TOOLS = [
       ...confirmSchema,
     }, ['id', 'confirm', 'reason']),
   },
+  {
+    name: 'securenow_alert_rule_query_update',
+    title: 'Update System Alert Rule Query',
+    description: 'Admin-only: update the shared public query mapping behind a system alert rule for all customer copies. Write action; requires confirmation.',
+    scope: 'alerts:write',
+    readOnly: false,
+    confirm: true,
+    method: 'PUT',
+    endpoint: '/alert-rules/:id/query-mapping',
+    pathParams: ['id'],
+    bodyFields: ['sqlQuery', 'reason', 'expectedCurrentSqlHash', 'applyGlobally', 'reactivatePausedCopies', 'reviewNotificationId', 'reviewNote', 'source'],
+    fixedBody: { applyGlobally: true, source: 'mcp' },
+    inputSchema: objectSchema({
+      id: string('Alert rule id. Must be a system rule.'),
+      sqlQuery: string('Full replacement SQL query. System SQL must keep __USER_APP_KEYS__ for tenant scoping.'),
+      expectedCurrentSqlHash: string('Optional SHA-256 hash of the current SQL to prevent stale overwrites.'),
+      applyGlobally: boolean('Must be true. Updates the shared public query mapping used by all system rule copies.'),
+      reactivatePausedCopies: boolean('Whether to reactivate paused noisy copies after the query is tuned.'),
+      reviewNotificationId: string('Optional notification id tied to this review/tuning action.'),
+      reviewNote: string('Optional review note. Defaults to reason.'),
+      ...confirmSchema,
+    }, ['id', 'sqlQuery', 'confirm', 'reason']),
+  },
   {
     name: 'securenow_alert_rule_test',
     title: 'Test Alert Rule',
@@ -870,6 +923,25 @@ const TOOLS = [
       ...confirmSchema,
     }, ['id', 'confirm', 'reason']),
   },
+  {
+    name: 'securenow_alert_rule_candidate_test',
+    title: 'Dry-Run Candidate Alert Rule SQL',
+    description: 'Dry-run a candidate SQL/query guard for an alert rule without saving it.',
+    scope: 'alerts:write',
+    readOnly: false,
+    confirm: true,
+    method: 'POST',
+    endpoint: '/alert-rules/:id/test',
+    pathParams: ['id'],
+    bodyFields: ['applicationKey', 'candidateSqlQuery'],
+    fixedBody: { mode: 'dry_run' },
+    inputSchema: objectSchema({
+      id: string('Alert rule id.'),
+      applicationKey: string('Application key to test.'),
+      candidateSqlQuery: string('Full candidate SQL query to dry-run without saving.'),
+      ...confirmSchema,
+    }, ['id', 'candidateSqlQuery', 'confirm', 'reason']),
+  },
   {
     name: 'securenow_alert_rule_test_result',
     title: 'Get Alert Rule Test Result',
@@ -1386,9 +1458,11 @@ function promptMessages(name, args = {}) {
             `Fetch page=${page}, limit=${limit} with securenow_human_actions_list, select row ${rowNumber}, then call securenow_notifications_get and securenow_human_action_report for that notificationId and IP.`,
             'Read the AI report, finalDecision, investigation steps, findings, proofs, metadata paths/user agents/status codes, and trace IDs.',
             'Open trace evidence with securenow_traces_show and correlated logs with securenow_logs_for_trace when trace IDs are available.',
-            'Return one clear outcome: Block IP, False Positive, Rule Tuning Needed, or Ambiguous. If evidence is ambiguous, stop and explain what is missing.',
+            'Return one clear outcome: Block IP, Rate Limit, False Positive, Rule Tuning Needed, or Ambiguous. If evidence is ambiguous, stop and explain what is missing.',
+            'Use rate limiting only as temporary soft remediation for repeated route-specific abuse such as login brute force, credential stuffing, scraping/API bursts, enumeration, recon/probing, or repeated noisy payloads where risk/impact evidence is below the block threshold.',
+            'Do not rate-limit instead of blocking when there is confirmed exploit success, token/data exposure, SSRF reachability, file read, RCE, persistence, malware/C2, or riskScore >= 85 with high-confidence malicious evidence. Do not rate-limit benign false positives, trusted monitors, app-server/proxy attribution problems, isolated one-off requests, or broad noisy rules that need alert tuning.',
             confirmWrites
-              ? 'The user requested execution. If evidence supports the decision, call securenow_human_action_block or securenow_human_action_false_positive with confirm:true, a precise reason, and a decisionReport containing summary, evidence, reviewedHistory, traceIds, and missingProof when relevant. If you skip/mark ambiguous but still need to record the audit trail, call securenow_human_action_decision_report_add.'
+              ? 'The user requested execution. If evidence supports the decision, call securenow_human_action_block, securenow_rate_limit_create_from_text plus securenow_human_action_decision_report_add(outcome=rate_limited), or securenow_human_action_false_positive with confirm:true, a precise reason, and a decisionReport containing summary, evidence, reviewedHistory, traceIds, and missingProof when relevant. If you skip/mark ambiguous but still need to record the audit trail, call securenow_human_action_decision_report_add.'
               : 'Do not execute write tools yet. Prepare the recommended decision and exact tool call the user can approve.',
             'If many IPs share the same benign path/status/user-agent pattern, recommend tightening the alert rule with a precise guard instead of reviewing each IP as malicious.',
             'False positives must be narrow: app + alert rule + path + method/status/user-agent/body evidence where possible. Never globally trust an IP by default.',
@@ -1410,12 +1484,14 @@ function promptMessages(name, args = {}) {
             'Work my SecureNow Requires Human queue like a senior security analyst using the MCP tools.',
             `Review up to ${limit} row(s), most urgent first.${args.search ? ` Search filter: ${args.search}.` : ''}`,
             'Start with securenow_human_actions_list. For each row, call securenow_notifications_get and securenow_human_action_report, inspect the AI report/investigation steps/proofs/trace IDs, and fetch trace/log evidence where useful.',
-            'For each row choose exactly one outcome: Block IP, False Positive, Rule Tuning Needed, or Skip because evidence is insufficient. Explain skipped rows.',
+            'For each row choose exactly one outcome: Block IP, Rate Limit, False Positive, Rule Tuning Needed, or Skip because evidence is insufficient. Explain skipped rows.',
+            'Use Rate Limit only for repeated route-specific abuse where temporary friction is safer than blocking: login brute force/credential stuffing, password reset/account enumeration, scraping/API bursts, path or ID enumeration, recon/probing, or repeated noisy payloads without confirmed exploit success.',
+            'Do not rate-limit confirmed high-risk attacks that should be blocked, benign traffic that should be false-positive scoped, broad noisy rules that need tuning, app-server/proxy attribution problems, or isolated one-off requests.',
             confirmWrites
               ? 'The user requested execution. For supported decisions, call the correct write tool with confirm:true, a precise reason, and a decisionReport containing summary, evidence, reviewedHistory, traceIds, and missingProof when relevant, then continue. For skipped/ambiguous/rule-tuning-needed rows that should be auditable without changing IP status, use securenow_human_action_decision_report_add.'
               : 'Do not execute write tools yet. Produce a row-by-row action plan and exact MCP write calls for user approval.',
-            'For block decisions, use securenow_human_action_block. For false positives, use securenow_human_action_false_positive with restrictive conditions. For case-level tune_rule/create_exclusion rows, inspect securenow_notifications_get and then use securenow_human_case_action_update only when the action is safe to approve/reject.',
-            'End with counts: handled, proposed block, proposed false positive, rule tuning needed, skipped, still waiting.',
+            'For block decisions, use securenow_human_action_block. For rate-limit decisions, use securenow_rate_limit_create_from_text and then securenow_human_action_decision_report_add with outcome=rate_limited. For false positives, use securenow_human_action_false_positive with restrictive conditions. For case-level tune_rule/create_exclusion rows, inspect securenow_notifications_get and then use securenow_human_case_action_update only when the action is safe to approve/reject.',
+            'End with counts: handled, proposed block, rate limits created/proposed, proposed false positive, rule tuning needed, skipped, still waiting.',
           ].join('\n'),
         },
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securenow",
-  "version": "7.7.9",
+  "version": "7.7.11",
   "description": "OpenTelemetry instrumentation for Node.js, Next.js, and Nuxt - Send traces and logs to any OTLP-compatible backend",
   "type": "commonjs",
   "main": "register.js",
@@ -79,6 +79,10 @@
     "./firewall": {
       "default": "./firewall.js"
     },
+    "./rate-limits": {
+      "types": "./rate-limits.d.ts",
+      "default": "./rate-limits.js"
+    },
     "./firewall-only": {
       "default": "./firewall-only.js"
     },
@@ -128,6 +132,8 @@
     "resolve-ip.js",
     "cidr.js",
     "firewall.js",
+    "rate-limits.js",
+    "rate-limits.d.ts",
     "firewall-only.js",
     "firewall-tcp.js",
     "firewall-iptables.js",

package/rate-limits.d.ts

@@ -0,0 +1,86 @@
+export interface RateLimitDraft {
+  name?: string;
+  appKey?: string;
+  applicationKey?: string;
+  environment?: string;
+  ip?: string;
+  pathPattern?: string;
+  path?: string;
+  route?: string;
+  pathMatchMode?: 'exact' | 'prefix' | 'regex';
+  method?: 'ALL' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+  keyBy?: 'ip' | 'global';
+  limit?: number;
+  windowSeconds?: number;
+  duration?: string;
+  reason?: string;
+  status?: 'active' | 'disabled';
+}
+
+export interface RateLimitAuthOptions {
+  token?: string;
+  apiKey?: string;
+  authToken?: string;
+}
+
+export interface RateLimitTextOptions extends RateLimitAuthOptions {
+  draft?: RateLimitDraft;
+  reason?: string;
+}
+
+export interface ParsedRateLimitText {
+  success: boolean;
+  draft: RateLimitDraft;
+  payload: Record<string, unknown>;
+  confidence: number;
+  missingFields: string[];
+  warnings: string[];
+  explanation?: string;
+  provider: 'anthropic' | 'local-fallback' | string;
+}
+
+export interface RateLimitRule {
+  id?: string;
+  _id?: string;
+  applicationKey?: string | null;
+  environment?: string | null;
+  name?: string;
+  ip?: string;
+  method?: string;
+  pathPattern?: string;
+  pathMatchMode?: string;
+  keyBy?: string;
+  limit: number;
+  windowSeconds: number;
+  reason?: string;
+  source?: string;
+  status?: string;
+  expiresAt?: string | null;
+  metadata?: Record<string, unknown>;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface RateLimitResponse {
+  success: boolean;
+  rateLimit: RateLimitRule;
+  parsed?: ParsedRateLimitText;
+}
+
+export function parseRateLimitText(text: string, options?: RateLimitTextOptions): Promise<ParsedRateLimitText>;
+export function createRateLimitFromText(text: string, options?: RateLimitTextOptions): Promise<RateLimitResponse>;
+export function createRateLimit(payload: Record<string, unknown>, options?: RateLimitAuthOptions): Promise<RateLimitResponse>;
+export function listRateLimits(query?: Record<string, unknown>, options?: RateLimitAuthOptions): Promise<{
+  success: boolean;
+  rateLimits: RateLimitRule[];
+  total: number;
+  page: number;
+  limit: number;
+}>;
+export function testRateLimit(query?: Record<string, unknown>, options?: RateLimitAuthOptions): Promise<{
+  success: boolean;
+  limited: boolean;
+  matches: RateLimitRule[];
+}>;
+export function updateRateLimit(id: string, payload?: Record<string, unknown>, options?: RateLimitAuthOptions): Promise<RateLimitResponse>;
+export function removeRateLimit(id: string, options?: RateLimitAuthOptions & { reason?: string }): Promise<RateLimitResponse>;

package/rate-limits.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const { api } = require('./cli/client');
+const config = require('./cli/config');
+
+function cleanText(value) {
+  return String(value || '').trim();
+}
+
+function authToken(options = {}) {
+  return (
+    options.token ||
+    options.apiKey ||
+    options.authToken ||
+    process.env.SECURENOW_TOKEN ||
+    process.env.SECURENOW_API_KEY ||
+    config.getToken() ||
+    config.getApiKey() ||
+    undefined
+  );
+}
+
+function requestOptions(options = {}) {
+  const token = authToken(options);
+  return token ? { token } : undefined;
+}
+
+function requireText(text) {
+  const value = cleanText(text);
+  if (!value) throw new Error('text is required');
+  return value;
+}
+
+async function parseRateLimitText(text, options = {}) {
+  return api.post(
+    '/rate-limits/parse',
+    {
+      text: requireText(text),
+      draft: options.draft && typeof options.draft === 'object' ? options.draft : {},
+    },
+    requestOptions(options)
+  );
+}
+
+async function createRateLimitFromText(text, options = {}) {
+  const body = {
+    text: requireText(text),
+    draft: options.draft && typeof options.draft === 'object' ? options.draft : {},
+  };
+  if (options.reason) body.reason = String(options.reason);
+  return api.post('/rate-limits/from-text', body, requestOptions(options));
+}
+
+async function createRateLimit(payload, options = {}) {
+  return api.post('/rate-limits', payload || {}, requestOptions(options));
+}
+
+async function listRateLimits(query = {}, options = {}) {
+  return api.get('/rate-limits', { query, ...(requestOptions(options) || {}) });
+}
+
+async function testRateLimit(query = {}, options = {}) {
+  return api.get('/rate-limits/check', { query, ...(requestOptions(options) || {}) });
+}
+
+async function updateRateLimit(id, payload = {}, options = {}) {
+  if (!id) throw new Error('id is required');
+  return api.put(`/rate-limits/${encodeURIComponent(id)}`, payload, requestOptions(options));
+}
+
+async function removeRateLimit(id, options = {}) {
+  if (!id) throw new Error('id is required');
+  const query = options.reason ? { reason: options.reason } : undefined;
+  return api.delete(`/rate-limits/${encodeURIComponent(id)}`, {
+    query,
+    ...(requestOptions(options) || {}),
+  });
+}
+
+module.exports = {
+  parseRateLimitText,
+  createRateLimitFromText,
+  createRateLimit,
+  listRateLimits,
+  testRateLimit,
+  updateRateLimit,
+  removeRateLimit,
+};

package/resolve-ip.js

@@ -110,8 +110,9 @@ function resolveClientIpWithDetails(request) {
   }
 
   if (LOOPBACK_RE.test(socketIp)) {
-    const hostIp = [...getHostIps()][0] || '';
-    if (hostIp) return { ...details, ip: hostIp, source: 'host-network' };
+    // A localhost request without proxy headers is app/server self-traffic.
+    // Rewriting it to the host's public IP can cause the app to block itself.
+    return { ...details, source: 'loopback' };
   }
 
   if (trustedProxy && getHostIps().has(socketIp)) {