@anomira/node-sdk 0.1.5 → 0.1.7

package/README.md

@@ -11,9 +11,9 @@ npm install @anomira/node-sdk
 ## Quick Start
 
 ```js
-import { SentinelAPI } from "@anomira/node-sdk";
+import { Anomira } from "@anomira/node-sdk";
 
-const sentinel = new SentinelAPI({
+const sentinel = new Anomira({
   apiKey:    process.env.SENTINEL_API_KEY,
   appId:     process.env.SENTINEL_APP_ID,
   ingestUrl: process.env.SENTINEL_INGEST_URL,
@@ -25,11 +25,11 @@ const sentinel = new SentinelAPI({
 
 ```js
 import express from "express";
-import { SentinelAPI } from "@anomira/node-sdk";
+import { Anomira } from "@anomira/node-sdk";
 
 const app = express();
 
-const sentinel = new SentinelAPI({
+const sentinel = new Anomira({
   apiKey:    process.env.SENTINEL_API_KEY,
   appId:     process.env.SENTINEL_APP_ID,
   ingestUrl: process.env.SENTINEL_INGEST_URL,
@@ -56,11 +56,11 @@ app.listen(3000);
 
 ```js
 import Fastify from "fastify";
-import { SentinelAPI } from "@anomira/node-sdk";
+import { Anomira } from "@anomira/node-sdk";
 
 const app = Fastify();
 
-const sentinel = new SentinelAPI({
+const sentinel = new Anomira({
   apiKey:    process.env.SENTINEL_API_KEY,
   appId:     process.env.SENTINEL_APP_ID,
   ingestUrl: process.env.SENTINEL_INGEST_URL,
@@ -116,6 +116,28 @@ if (match?.rule.action === "block") {
 }
 ```
 
+## Shadow Endpoint Detection
+
+Register your known API routes on startup so Anomira can flag any undeclared endpoint that appears in live traffic. Endpoints that receive requests but were never declared show up in the **API Surface Map** as shadow endpoints.
+
+```js
+// Call once after your routes are registered
+await sentinel.declareEndpoints([
+  { method: "POST", path: "/api/auth/login",           auth: false },
+  { method: "POST", path: "/api/auth/register",        auth: false },
+  { method: "GET",  path: "/api/users/:id",            auth: true  },
+  { method: "GET",  path: "/api/orders",               auth: true  },
+  { method: "POST", path: "/api/orders",               auth: true  },
+  { method: "GET",  path: "/api/health",               auth: false },
+]);
+```
+
+Express-style `:param` segments are normalized automatically — `/users/:id` and `/users/:userId` both map to `/users/{id}` to match discovered traffic.
+
+Use `auth: false` for public endpoints. Authenticated endpoints default to `auth: true`.
+
+Shadow detection from declared endpoints only activates once your org has registered at least one endpoint, so it won't produce noise on fresh deployments before you call this method.
+
 ## Secret Scanner CLI
 
 Scan your codebase for hardcoded secrets, API keys, BVN/NIN numbers, and PII before they reach production.

package/dist/cli.cjs

@@ -5606,17 +5606,15 @@ var creator = {
 
 // src/sensitive.ts
 var PATTERNS = [
-  // ── Cryptographic keys and certificates ───────────────────────────────────
+  // ── Cryptographic private keys ────────────────────────────────────────────
+  // NOTE: -----BEGIN CERTIFICATE----- is intentionally excluded — public
+  // certificates are designed to be public and committing them is correct.
+  // Only PRIVATE keys are dangerous.
   {
     type: "private_key",
     label: "Private Key",
     regex: /-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/
   },
-  {
-    type: "certificate",
-    label: "Certificate / Public Key",
-    regex: /-----BEGIN CERTIFICATE-----/
-  },
   // ── Cloud provider credentials ────────────────────────────────────────────
   {
     // AWS access key ID — highly specific, almost no false positives
@@ -5731,26 +5729,30 @@ var PATTERNS = [
     regex: /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/
   },
   {
-    // Generic API key / token assigned to a keyword (must have 20+ char value)
+    // Generic API key / token — only flag QUOTED literals, not variable/env references.
+    // Skips: api_key = process.env.KEY, token = myVar
+    // Matches: api_key = "sk-abc123...", bearer: "eyJhb..."
     type: "api_key",
     label: "API Key / Token",
-    regex: /\b(?:api[_-]?key|access[_-]?token|auth[_-]?token|bearer|client[_-]?secret)\s*[:=]\s*["']?[A-Za-z0-9_.\/+\-]{20,}["']?/i
+    regex: /\b(?:api[_-]?key|access[_-]?token|auth[_-]?token|bearer|client[_-]?secret)\s*[:=]\s*["'][A-Za-z0-9_.\/+\-]{20,}["']/i
   },
   // ── Password fields ───────────────────────────────────────────────────────
   {
-    // Password/secret keyword immediately followed by a non-placeholder value
-    // Avoids false positives on "password: ${PASSWORD}" or "password: xxxx"
+    // Only flag QUOTED string literals after a password/secret keyword.
+    // Skips: process.env.*, variable references, undefined/null, template literals.
+    // Matches: password: "hunter2", secret: 'abc123def', pass="hardcoded!"
     type: "password",
-    label: "Password / Secret",
-    regex: /\b(?:password|passwd|pwd|pass|secret|credentials?)\s*[:=]\s*["']?(?!\$\{)[^\s"'$]{6,}["']?/i
+    label: "Hardcoded Password",
+    regex: /\b(?:password|passwd|pwd|pass|secret|credentials?)\s*[:=]\s*["'][^"'$\s]{6,}["']/i
   },
   // ── Nigeria-specific PII ──────────────────────────────────────────────────
   {
-    // BVN / NIN: 11 digits, first digit 1-9 (not a phone starting with 0)
-    // Require a non-digit boundary on both sides to reduce false positives
+    // BVN / NIN: 11 digits, first digit 1-9 (not a phone number starting with 0)
+    // Exclude: inside URLs (preceded by / : @ - %), hex strings (followed by a-f),
+    // and UUIDs/hashes (surrounded by alphanumeric chars)
     type: "bvn",
     label: "BVN / NIN",
-    regex: /(?<!\d)[1-9]\d{10}(?!\d)/
+    regex: /(?<![/\-:@%=a-fA-F\w])[1-9]\d{10}(?![a-fA-F\d])/
   },
   {
     // Nigerian phone numbers: 080x, 081x, 070x, 090x, 091x — or with +234 prefix
@@ -5843,8 +5845,28 @@ var SKIP_DIRS = /* @__PURE__ */ new Set([
   ".turbo",
   ".cache",
   "tmp",
-  "temp"
+  "temp",
+  // Test directories — skipped by default, use --include-tests to scan them
+  "tests",
+  "test",
+  "__tests__",
+  "spec",
+  "__spec__",
+  "fixtures",
+  "__fixtures__",
+  "mocks",
+  "__mocks__"
 ]);
+var TEST_FILE_PATTERNS = [
+  ".test.js",
+  ".test.ts",
+  ".test.jsx",
+  ".test.tsx",
+  ".spec.js",
+  ".spec.ts",
+  ".spec.jsx",
+  ".spec.tsx"
+];
 function shannonEntropy(str) {
   const freq = {};
   for (const ch of str) freq[ch] = (freq[ch] ?? 0) + 1;
@@ -5876,7 +5898,12 @@ var SECRETLINT_CONFIG = {
     }
   ]
 };
-function shouldScan(filePath) {
+function isTestFile(filePath) {
+  const base = path2__default.default.basename(filePath);
+  return TEST_FILE_PATTERNS.some((p) => base.endsWith(p));
+}
+function shouldScan(filePath, includeTests) {
+  if (!includeTests && isTestFile(filePath)) return false;
   const ext = path2__default.default.extname(filePath);
   const base = path2__default.default.basename(filePath);
   if (base.startsWith(".env")) return true;
@@ -5957,14 +5984,14 @@ async function scanFile(filePath, strict) {
   }
   return violations;
 }
-function* walkDir(dir) {
+function* walkDir(dir, includeTests) {
   const entries = fs__default.default.readdirSync(dir, { withFileTypes: true });
   for (const entry of entries) {
     if (SKIP_DIRS.has(entry.name)) continue;
     const full = path2__default.default.join(dir, entry.name);
     if (entry.isDirectory()) {
-      yield* walkDir(full);
-    } else if (entry.isFile() && shouldScan(full)) {
+      yield* walkDir(full, includeTests);
+    } else if (entry.isFile() && shouldScan(full, includeTests)) {
       yield full;
     }
   }
@@ -5976,6 +6003,7 @@ async function main() {
   const quiet = args.includes("--quiet") || args.includes("-q");
   const jsonOut = args.includes("--json");
   const strict = args.includes("--strict");
+  const includeTests = args.includes("--include-tests");
   if (args.includes("--help") || args.includes("-h") || args[0] === "help") {
     console.log(`
 ${c.bold}Anomira Secret Scanner${c.reset}
@@ -5989,10 +6017,11 @@ Detection layers:
   Layer 3  Entropy    \u2014 High-entropy string detection (--strict only)
 
 Options:
-  --strict      Enable entropy analysis (catches unknown secrets, more noise)
-  --quiet, -q   Only print violations (suppress summary header)
-  --json        Machine-readable JSON output (for CI pipelines)
-  --help, -h    Show this help
+  --strict           Enable entropy analysis (catches unknown secrets, more noise)
+  --include-tests    Also scan test files (*.test.*, *.spec.*, tests/ dirs \u2014 skipped by default)
+  --quiet, -q        Only print violations (suppress summary header)
+  --json             Machine-readable JSON output (for CI pipelines)
+  --help, -h         Show this help
 
 Examples:
   npx @anomira/node-sdk scan ./src
@@ -6016,7 +6045,7 @@ ${c.bold}${c.cyan}Anomira Secret Scanner${c.reset}`);
     console.log(`${c.grey}Layers:  secretlint + custom patterns${strict ? " + entropy" : ""}${c.reset}
 `);
   }
-  const files = fs__default.default.statSync(target).isDirectory() ? [...walkDir(target)] : [target];
+  const files = fs__default.default.statSync(target).isDirectory() ? [...walkDir(target, includeTests)] : [target];
   const allViolations = [];
   let fileCount = 0;
   for (const file of files) {

package/dist/index.cjs

@@ -109,10 +109,10 @@ var EventBuffer = class {
     }
   }
   log(...args) {
-    if (this.opts.debug) console.log("[SentinelAPI]", ...args);
+    if (this.opts.debug) console.log("[Anomira]", ...args);
   }
   warn(...args) {
-    console.warn("[SentinelAPI]", ...args);
+    console.warn("[Anomira]", ...args);
   }
 };
 function sleep(ms) {
@@ -199,17 +199,15 @@ async function checkGeoVelocity(userId, ip, tsMs, lookupUrl) {
 
 // src/sensitive.ts
 var PATTERNS = [
-  // ── Cryptographic keys and certificates ───────────────────────────────────
+  // ── Cryptographic private keys ────────────────────────────────────────────
+  // NOTE: -----BEGIN CERTIFICATE----- is intentionally excluded — public
+  // certificates are designed to be public and committing them is correct.
+  // Only PRIVATE keys are dangerous.
   {
     type: "private_key",
     label: "Private Key",
     regex: /-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/
   },
-  {
-    type: "certificate",
-    label: "Certificate / Public Key",
-    regex: /-----BEGIN CERTIFICATE-----/
-  },
   // ── Cloud provider credentials ────────────────────────────────────────────
   {
     // AWS access key ID — highly specific, almost no false positives
@@ -324,26 +322,30 @@ var PATTERNS = [
     regex: /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/
   },
   {
-    // Generic API key / token assigned to a keyword (must have 20+ char value)
+    // Generic API key / token — only flag QUOTED literals, not variable/env references.
+    // Skips: api_key = process.env.KEY, token = myVar
+    // Matches: api_key = "sk-abc123...", bearer: "eyJhb..."
     type: "api_key",
     label: "API Key / Token",
-    regex: /\b(?:api[_-]?key|access[_-]?token|auth[_-]?token|bearer|client[_-]?secret)\s*[:=]\s*["']?[A-Za-z0-9_.\/+\-]{20,}["']?/i
+    regex: /\b(?:api[_-]?key|access[_-]?token|auth[_-]?token|bearer|client[_-]?secret)\s*[:=]\s*["'][A-Za-z0-9_.\/+\-]{20,}["']/i
   },
   // ── Password fields ───────────────────────────────────────────────────────
   {
-    // Password/secret keyword immediately followed by a non-placeholder value
-    // Avoids false positives on "password: ${PASSWORD}" or "password: xxxx"
+    // Only flag QUOTED string literals after a password/secret keyword.
+    // Skips: process.env.*, variable references, undefined/null, template literals.
+    // Matches: password: "hunter2", secret: 'abc123def', pass="hardcoded!"
     type: "password",
-    label: "Password / Secret",
-    regex: /\b(?:password|passwd|pwd|pass|secret|credentials?)\s*[:=]\s*["']?(?!\$\{)[^\s"'$]{6,}["']?/i
+    label: "Hardcoded Password",
+    regex: /\b(?:password|passwd|pwd|pass|secret|credentials?)\s*[:=]\s*["'][^"'$\s]{6,}["']/i
   },
   // ── Nigeria-specific PII ──────────────────────────────────────────────────
   {
-    // BVN / NIN: 11 digits, first digit 1-9 (not a phone starting with 0)
-    // Require a non-digit boundary on both sides to reduce false positives
+    // BVN / NIN: 11 digits, first digit 1-9 (not a phone number starting with 0)
+    // Exclude: inside URLs (preceded by / : @ - %), hex strings (followed by a-f),
+    // and UUIDs/hashes (surrounded by alphanumeric chars)
     type: "bvn",
     label: "BVN / NIN",
-    regex: /(?<!\d)[1-9]\d{10}(?!\d)/
+    regex: /(?<![/\-:@%=a-fA-F\w])[1-9]\d{10}(?![a-fA-F\d])/
   },
   {
     // Nigerian phone numbers: 080x, 081x, 070x, 090x, 091x — or with +234 prefix
@@ -410,7 +412,7 @@ var DEFAULT_INGEST_URL = "https://ingest.anomira.io/v1/events";
 var DEFAULT_BATCH_SIZE = 100;
 var DEFAULT_FLUSH_MS = 5e3;
 var DEFAULT_MAX_RETRIES = 3;
-var SentinelClient = class {
+var AnomiraClient = class {
   constructor(config) {
     this.logBuffer = [];
     this.logFlushTimer = null;
@@ -509,7 +511,7 @@ var SentinelClient = class {
       console[method] = (...args) => {
         original(...args);
         const first = args[0];
-        if (typeof first === "string" && first.startsWith("[SentinelAPI]")) return;
+        if (typeof first === "string" && first.startsWith("[Anomira]")) return;
         const message = args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ");
         const ctx = requestContext.getStore();
         this.log(level, message, {
@@ -533,7 +535,7 @@ var SentinelClient = class {
       const data = await res.json();
       this.blockedIpCache = new Set(data.ips ?? []);
       if (this.config.debug && this.blockedIpCache.size > 0) {
-        this._origLog(`[SentinelAPI] blocklist refreshed \u2014 ${this.blockedIpCache.size} blocked IPs`);
+        this._origLog(`[Anomira] blocklist refreshed \u2014 ${this.blockedIpCache.size} blocked IPs`);
       }
     } catch {
     }
@@ -561,7 +563,7 @@ var SentinelClient = class {
         })() : void 0
       }));
       if (this.config.debug && this.compiledRules.length > 0) {
-        this._origLog(`[SentinelAPI] firewall rules refreshed \u2014 ${this.compiledRules.length} active rules`);
+        this._origLog(`[Anomira] firewall rules refreshed \u2014 ${this.compiledRules.length} active rules`);
       }
     } catch {
     }
@@ -612,7 +614,7 @@ var SentinelClient = class {
         signal: AbortSignal.timeout(8e3)
       });
       if (this.config.debug) {
-        this._origLog(`[SentinelAPI] [logs] \u2705 sent ${batch.length} log entries (${res.status})`);
+        this._origLog(`[Anomira] [logs] \u2705 sent ${batch.length} log entries (${res.status})`);
       }
     } catch {
       this.logBuffer.unshift(...batch);
@@ -631,24 +633,24 @@ var SentinelClient = class {
         signal: AbortSignal.timeout(5e3)
       });
       if (res.status >= 300 && res.status < 400) {
-        this._origWarn(`[SentinelAPI] \u274C Wrong ingest URL \u2014 got redirect to ${res.headers.get("location")}. Check SENTINEL_INGEST_URL.`);
+        this._origWarn(`[Anomira] \u274C Wrong ingest URL \u2014 got redirect to ${res.headers.get("location")}. Check SENTINEL_INGEST_URL.`);
         return;
       }
       if (res.ok) {
-        this._origLog(`[SentinelAPI] \u2705 Connected (appId: ${this.config.appId.slice(0, 8)}\u2026)`);
+        this._origLog(`[Anomira] \u2705 Connected (appId: ${this.config.appId.slice(0, 8)}\u2026)`);
         return;
       }
       if (res.status === 401) {
-        this._origWarn("[SentinelAPI] \u274C Invalid API key \u2014 check your SENTINEL_API_KEY");
+        this._origWarn("[Anomira] \u274C Invalid API key \u2014 check your SENTINEL_API_KEY");
         return;
       }
       if (res.status === 403) {
-        this._origWarn("[SentinelAPI] \u274C App not found or appId mismatch \u2014 check your SENTINEL_APP_ID");
+        this._origWarn("[Anomira] \u274C App not found or appId mismatch \u2014 check your SENTINEL_APP_ID");
         return;
       }
-      this._origWarn(`[SentinelAPI] \u26A0\uFE0F  Ingest returned HTTP ${res.status} \u2014 check your configuration`);
+      this._origWarn(`[Anomira] \u26A0\uFE0F  Ingest returned HTTP ${res.status} \u2014 check your configuration`);
     } catch {
-      this._origWarn("[SentinelAPI] \u26A0\uFE0F  Could not reach ingest endpoint \u2014 check SENTINEL_INGEST_URL (current: " + this.config.ingestUrl + ")");
+      this._origWarn("[Anomira] \u26A0\uFE0F  Could not reach ingest endpoint \u2014 check SENTINEL_INGEST_URL (current: " + this.config.ingestUrl + ")");
     }
   }
   // ─── Public API ────────────────────────────────────────────────────────────
@@ -745,7 +747,7 @@ var SentinelClient = class {
     });
   }
   /**
-   * Send a structured log entry to the SentinelAPI Logs dashboard.
+   * Send a structured log entry to the Anomira Logs dashboard.
    *
    * ```ts
    * sentinel.log("info",  "User registered",         { userId: user.id });
@@ -761,16 +763,47 @@ var SentinelClient = class {
       rest["sensitiveLeaks"] = leaks.map((l) => l.type);
       if (this.config.debug) {
         this._origWarn(
-          `[SentinelAPI] \u26A0\uFE0F  Sensitive data in log (${leaks.map((l) => l.label).join(", ")}): "${message.slice(0, 60)}\u2026"`
+          `[Anomira] \u26A0\uFE0F  Sensitive data in log (${leaks.map((l) => l.label).join(", ")}): "${message.slice(0, 60)}\u2026"`
         );
       }
     }
     this.logBuffer.push({ level, service: service ?? this.config.service, message, meta: rest, ts: Date.now() });
     if (this.config.debug && leaks.length === 0) {
-      this._origLog(`[SentinelAPI] log:${level} ${message}`);
+      this._origLog(`[Anomira] log:${level} ${message}`);
     }
     if (this.logBuffer.length >= 50) void this.#flushLogs();
   }
+  /**
+   * Declare your API's known endpoints so Anomira can flag undiscovered
+   * traffic as shadow endpoints.
+   *
+   * Call this once on startup after your routes are registered:
+   *
+   * ```ts
+   * await sentinel.declareEndpoints([
+   *   { method: "GET",  path: "/api/users/:id",  auth: true  },
+   *   { method: "POST", path: "/api/orders",     auth: true  },
+   *   { method: "GET",  path: "/api/health",     auth: false },
+   * ]);
+   * ```
+   */
+  async declareEndpoints(endpoints) {
+    if (this.disabled || endpoints.length === 0) return;
+    const url = this.config.ingestUrl.replace(/\/v1\/events$/, "/v1/declare-endpoints");
+    try {
+      await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.config.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": `@anomira/node-sdk/0.1.0`
+        },
+        body: JSON.stringify({ appId: this.config.appId, endpoints }),
+        signal: AbortSignal.timeout(1e4)
+      });
+    } catch {
+    }
+  }
   /**
    * Flush all pending events immediately.
    * Useful before a graceful shutdown outside of the process lifecycle hooks.
@@ -1111,10 +1144,11 @@ function createFastifyPlugin2(client) {
   };
 }
 
+exports.Anomira = AnomiraClient;
 exports.EventName = EventName;
-exports.SentinelAPI = SentinelClient;
+exports.SentinelAPI = AnomiraClient;
 exports.createExpressMiddleware = createExpressMiddleware2;
 exports.createFastifyPlugin = createFastifyPlugin2;
-exports.default = SentinelClient;
+exports.default = AnomiraClient;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map