@sms-florin/mcp-ssrf-scan 0.3.0 → 0.4.0

package/README.md

@@ -32,13 +32,21 @@ the largest public scan of real MCP servers to date.
 
 - **SSRF** (the headline check): a tool handler (`server.tool(...)` /
   `setRequestHandler(...)`) that passes a caller-controlled value into
-  `fetch`/`axios`/`http.request`/`https.request`/`got`, with no
-  validation-looking identifier (`allowlist`, `isPrivateIP`, `ssrf`, ...)
-  anywhere nearby.
+  `fetch`/`axios`/`http.request`/`https.request`/`got` *as the host* — a
+  caller value that only fills a path segment under a fixed or configured base
+  URL is not reported — with no validation-looking identifier (`allowlist`,
+  `isPrivateIP`, `ssrf`, ...) anywhere nearby.
 - **Hardcoded secrets** — Stripe/AWS/GitHub/Google key patterns, and a
-  generic `password`/`apiKey`/`token` = "literal string" check.
-- **exec/Function injection** — `exec()`/`new Function()` next to a
-  template literal, the shape a command-injection bug usually has.
+  generic `password`/`apiKey`/`token` = "literal string" check (placeholders,
+  env var names and values without a mix of letters and digits are ignored).
+- **exec/Function injection** — `child_process.exec()`/`execSync()` or
+  `new Function()` called with an interpolated string, the shape a
+  command-injection bug usually has. `db.exec()`, `RegExp.exec()` and values
+  wrapped in a shell-escape helper are not reported.
+
+Test, e2e, script, example and docs directories are skipped by default (run
+with `--include-tests` to scan them too). On a 2026-10-19 scan of 36 public MCP
+servers this cut 482 findings to 28.
 
 ## What it is not
 

package/dist/cli.js

@@ -26,13 +26,16 @@ What it checks:
   - SSRF: a tool handler making an outbound request with a caller-controlled
     URL and no nearby host/IP validation
   - Hardcoded secrets (Stripe/AWS/GitHub/Google keys, generic credential strings)
-  - exec()/Function() calls next to a template literal (possible command injection)
+  - child_process exec()/new Function() calls with an interpolated string
+    (possible command injection)
 
 This is a heuristic, regex-based scanner, not a full AST analyzer — it can
 miss real issues and flag things that are actually fine. Treat every HIGH
 finding as "go read this function," not as a confirmed bug.
 
 Options:
+  --include-tests     Also scan test, e2e, script, example and docs directories
+                      (skipped by default — they are the main source of noise)
   --json              Print findings as JSON instead of the human-readable list
   --sarif             Print findings as SARIF 2.1.0 (GitHub/GitLab code scanning,
                       VS Code); rules carry OWASP MCP Top 10 tags where one fits
@@ -126,7 +129,7 @@ async function main() {
     const target = args.find((a, i) => !a.startsWith("-") && !valueFlags.has(args[i - 1])) ?? ".";
     const asJson = args.includes("--json");
     const asSarif = args.includes("--sarif");
-    const findings = scanDirectory(target);
+    const findings = scanDirectory(target, { includeTests: args.includes("--include-tests") });
     const hasHigh = findings.some((f) => f.severity === "high");
     if (asSarif) {
         const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));

package/dist/scan.d.ts

@@ -8,4 +8,6 @@ export interface Finding {
     snippet: string;
 }
 export declare function scanFile(filePath: string, content: string): Finding[];
-export declare function scanDirectory(root: string): Finding[];
+export declare function scanDirectory(root: string, options?: {
+    includeTests?: boolean;
+}): Finding[];

package/dist/scan.js

@@ -14,9 +14,30 @@ const SKIP_DIRS = new Set([
     "coverage",
     ".next",
     "out",
+    "vendor",
+    ".turbo",
 ]);
+// Directories and file suffixes that hold tests, scripts, demos and docs. A
+// scan of 36 public MCP servers (2026-10-19) showed these produce most of the
+// noise: e2e helpers named `exec`, fixture credentials, benchmark scripts.
+// Skipped by default, scanned with --include-tests.
+const TEST_DIRS = new Set([
+    "test",
+    "tests",
+    "__tests__",
+    "__mocks__",
+    "e2e",
+    "scripts",
+    "examples",
+    "example",
+    "docs",
+    "fixtures",
+    "bench",
+    "benchmarks",
+]);
+const TEST_FILE = /\.(test|spec|e2e|unit|story|stories|mock)\.[tj]sx?$/;
 const SOURCE_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
-function walk(dir, out = []) {
+function walk(dir, includeTests, out = []) {
     let entries;
     try {
         entries = readdirSync(dir);
@@ -27,6 +48,8 @@ function walk(dir, out = []) {
     for (const entry of entries) {
         if (SKIP_DIRS.has(entry))
             continue;
+        if (!includeTests && TEST_DIRS.has(entry))
+            continue;
         const full = join(dir, entry);
         let st;
         try {
@@ -36,11 +59,11 @@ function walk(dir, out = []) {
             continue;
         }
         if (st.isDirectory()) {
-            walk(full, out);
+            walk(full, includeTests, out);
         }
         else if (SOURCE_EXT.has(entry.slice(entry.lastIndexOf(".")))) {
-            if (/\.(test|spec)\.[tj]sx?$/.test(entry))
-                continue; // skip test files
+            if (!includeTests && TEST_FILE.test(entry))
+                continue;
             out.push(full);
         }
     }
@@ -60,12 +83,32 @@ const SECRET_PATTERNS = [
     { re: /\bAKIA[0-9A-Z]{16}\b/, label: "an AWS access key ID" },
     { re: /\bghp_[A-Za-z0-9]{36}\b/, label: "a GitHub personal access token" },
     { re: /\bAIza[0-9A-Za-z\-_]{35}\b/, label: "a Google API key" },
-    {
-        re: /\b(api[_-]?key|apikey|secret|password|token)\s*[:=]\s*["'][^"'\s]{10,}["']/i,
-        label: "a hardcoded credential-looking string",
-    },
 ];
-const EXEC_CALL = /\b(child_process\.)?exec(?:Sync)?\s*\(|new Function\s*\(/;
+// The generic "name = 'value'" shape is where most secret false positives came
+// from (UI labels, env var names, placeholders), so the value must look real.
+const GENERIC_SECRET = /\b(api[_-]?key|apikey|secret|password|token)\s*[:=]\s*["']([^"'\s]{16,})["']/i;
+const PLACEHOLDER = /(your|example|placeholder|dummy|changeme|xxxx|test|sample|fake|redacted|<|>|\*\*\*)/i;
+function looksLikeRealSecret(value) {
+    if (!/\d/.test(value) || !/[A-Za-z]/.test(value))
+        return false;
+    if (PLACEHOLDER.test(value))
+        return false;
+    if (/^[A-Z0-9_]+$/.test(value))
+        return false; // an env var name, not a value
+    if (/^(https?:|\.{0,2}\/)/.test(value))
+        return false; // URL or path
+    if (/\$\{|process\.env/.test(value))
+        return false;
+    return true;
+}
+// Real shell execution only: child_process exec/execSync (bare name needs the
+// file to import child_process, so db.exec()/regex.exec() never match) and
+// `new Function(`.
+const CP_IMPORT = /\bchild_process\b/;
+const EXEC_BARE = /(?<![.\w$])(exec|execSync)\s*\(/g;
+const EXEC_CP = /\b(?:child_process|childProcess|cp)\s*\.\s*(?:exec|execSync)\s*\(/g;
+const NEW_FUNCTION = /new Function\s*\(/g;
+const SHELL_QUOTE = /\b(shellEscape|escapeShell|shellQuote|quote|shQuote)\s*\(/;
 function extractParamNames(block) {
     // Very rough: pull identifier names out of the first destructured
     // parameter of the handler function, e.g. async ({ url, target }) => or
@@ -94,60 +137,130 @@ function lineAt(content, index) {
             line++;
     return line;
 }
+// True when `index` sits inside a quoted string or a comment on its line — a
+// "fetch (" inside a .describe('...to fetch (from ...)') is not a network call
+// (real false positive from a public MCP server, 2026-10-19).
+function inStringOrComment(content, index) {
+    const lineStart = content.lastIndexOf("\n", index - 1) + 1;
+    const before = content.slice(lineStart, index);
+    if (/^\s*(\/\/|\/\*|\*)/.test(before))
+        return true;
+    if (/(^|[^:"'`])\/\//.test(before))
+        return true;
+    for (const q of ["'", '"', "`"]) {
+        const count = (before.match(new RegExp(`(?<!\\\\)${q}`, "g")) ?? []).length;
+        if (count % 2 === 1)
+            return true;
+    }
+    return false;
+}
+// The text of a call's first argument, from just after its "(" to the first
+// top-level comma or the closing ")".
+function firstArgument(content, afterParen) {
+    let depth = 0;
+    let quote = "";
+    const limit = Math.min(content.length, afterParen + 600);
+    for (let i = afterParen; i < limit; i++) {
+        const c = content[i];
+        if (quote) {
+            if (c === "\\")
+                i++;
+            else if (c === quote)
+                quote = "";
+            continue;
+        }
+        if (c === "'" || c === '"' || c === "`")
+            quote = c;
+        else if (c === "(" || c === "[" || c === "{")
+            depth++;
+        else if (c === ")" || c === "]" || c === "}") {
+            if (depth === 0)
+                return content.slice(afterParen, i);
+            depth--;
+        }
+        else if (c === "," && depth === 0)
+            return content.slice(afterParen, i);
+    }
+    return content.slice(afterParen, limit);
+}
+function paramRegex(p) {
+    // `p` as a bare identifier, or as a property of the handler's input object.
+    return new RegExp(`(?:(?<![\\w$.])|(?<=\\b(?:args|input|params|req|request)\\.))${p}\\b`);
+}
+// Does this URL expression let the caller choose the *host*? A caller value
+// that only fills a path or query segment under a fixed or configured base
+// (`${config.baseUrl}/jobs/${encodeURIComponent(id)}`) is not SSRF.
+function callerControlsHost(arg, params) {
+    const a = arg.trim();
+    if (!params.some((p) => paramRegex(p).test(a)))
+        return false;
+    // Fixed scheme+host or a relative path up front: host is not caller-chosen.
+    if (/^["'`]\s*(https?:\/\/|\/)/.test(a) && !/^["'`]\$\{/.test(a))
+        return false;
+    // Template literal that opens with something that is not a param (a
+    // configured base URL): the param only lands in the path.
+    const tpl = a.match(/^`\$\{([^}]+)\}/);
+    if (tpl && !params.some((p) => paramRegex(p).test(tpl[1])))
+        return false;
+    // `base + something` where base is not a param.
+    const concat = a.match(/^([A-Za-z_$][\w$.]*)\s*\+/);
+    if (concat && !params.some((p) => paramRegex(p).test(concat[1])))
+        return false;
+    return true;
+}
 export function scanFile(filePath, content) {
     const findings = [];
+    const lines = content.split("\n");
     // --- SSRF: look inside each tool-handler block for a network call whose
-    // target looks like it came from the handler's own input, with no nearby
-    // validation keyword.
+    // URL argument lets the caller choose the host, with no nearby validation.
     let searchFrom = 0;
     while (true) {
         const startMatch = TOOL_HANDLER_START.exec(content.slice(searchFrom));
         if (!startMatch)
             break;
         const absoluteStart = searchFrom + startMatch.index;
-        // Capture a bounded window after the match as "the handler body" — a
-        // real brace-matcher would be more precise, but a fixed window keeps
-        // this dependency-free and is plenty for a single handler in practice.
-        const block = content.slice(absoluteStart, absoluteStart + 4000);
+        // Bounded window after the match as "the handler body" — a real
+        // brace-matcher would be more precise, but a fixed window keeps this
+        // dependency-free. It stops at the next handler so one handler's code is
+        // never judged against another's parameters.
+        const rest = content.slice(absoluteStart + 1, absoluteStart + 4000);
+        const next = TOOL_HANDLER_START.exec(rest);
+        const block = content.slice(absoluteStart, absoluteStart + 1 + (next ? next.index : rest.length));
         const paramNames = extractParamNames(block);
-        const netMatch = NETWORK_CALL.exec(block);
-        if (netMatch) {
-            const callLineAbs = absoluteStart + netMatch.index;
-            // Look at the network-call line plus the next 2 lines for the actual URL argument.
-            const argWindow = content.slice(callLineAbs, callLineAbs + 300);
-            const usesParam = paramNames.some((p) => new RegExp(`\\b${p}\\b`).test(argWindow));
-            const isLiteralOnly = /\(\s*["'`][^$]/.test(argWindow) && !usesParam;
-            if (usesParam) {
-                const nearbyValidation = VALIDATION_SIGNAL.test(block);
-                const line = lineAt(content, callLineAbs);
-                const snippet = content.split("\n")[line - 1]?.trim().slice(0, 160) ?? "";
-                if (!nearbyValidation) {
-                    findings.push({
-                        file: filePath,
-                        line,
-                        severity: "high",
-                        rule: "ssrf",
-                        message: "Outbound network call inside a tool handler appears to use a caller-controlled value with no nearby host/IP validation — possible SSRF. A tool argument can reach your server's internal network (cloud metadata endpoint, localhost services, private IPs) unless the destination is checked first.",
-                        snippet,
-                    });
-                }
-                else {
-                    findings.push({
-                        file: filePath,
-                        line,
-                        severity: "info",
-                        rule: "ssrf",
-                        message: "Outbound network call uses a caller-controlled value, but a validation-looking identifier (allowlist/blocklist/isPrivate/...) was found nearby — looks handled, verify it actually runs before the request, not after.",
-                        snippet,
-                    });
-                }
+        for (const netMatch of block.matchAll(new RegExp(NETWORK_CALL.source, "g"))) {
+            const callAbs = absoluteStart + netMatch.index;
+            if (inStringOrComment(content, callAbs))
+                continue;
+            const arg = firstArgument(content, callAbs + netMatch[0].length);
+            if (!callerControlsHost(arg, paramNames))
+                continue;
+            const nearbyValidation = VALIDATION_SIGNAL.test(block);
+            const line = lineAt(content, callAbs);
+            const snippet = lines[line - 1]?.trim().slice(0, 160) ?? "";
+            if (!nearbyValidation) {
+                findings.push({
+                    file: filePath,
+                    line,
+                    severity: "high",
+                    rule: "ssrf",
+                    message: "Outbound network call inside a tool handler appears to use a caller-controlled URL with no nearby host/IP validation — possible SSRF. A tool argument can reach your server's internal network (cloud metadata endpoint, localhost services, private IPs) unless the destination is checked first.",
+                    snippet,
+                });
+            }
+            else {
+                findings.push({
+                    file: filePath,
+                    line,
+                    severity: "info",
+                    rule: "ssrf",
+                    message: "Outbound network call uses a caller-controlled URL, but a validation-looking identifier (allowlist/blocklist/isPrivate/...) was found nearby — looks handled, verify it actually runs before the request, not after.",
+                    snippet,
+                });
             }
-            void isLiteralOnly; // literal-only calls are fine, nothing to report
         }
         searchFrom = absoluteStart + Math.max(startMatch[0].length, 1);
     }
     // --- Secrets
-    const lines = content.split("\n");
     lines.forEach((text, i) => {
         for (const { re, label } of SECRET_PATTERNS) {
             if (re.test(text)) {
@@ -159,27 +272,52 @@ export function scanFile(filePath, content) {
                     message: `Line looks like it contains ${label} committed directly in source.`,
                     snippet: text.trim().slice(0, 160),
                 });
-                break;
+                return;
             }
         }
-    });
-    // --- exec/eval with a nearby variable (possible command injection)
-    lines.forEach((text, i) => {
-        if (EXEC_CALL.test(text) && /\$\{|`.*\$\{/.test(text + (lines[i + 1] ?? ""))) {
+        const generic = GENERIC_SECRET.exec(text);
+        if (generic && looksLikeRealSecret(generic[2])) {
             findings.push({
                 file: filePath,
                 line: i + 1,
-                severity: "high",
-                rule: "exec-injection",
-                message: "exec()/Function() call next to a template literal — if any part of that string comes from tool input, this is a command/code-injection risk, not just a style issue.",
+                severity: "medium",
+                rule: "secret",
+                message: "Line looks like it contains a hardcoded credential-looking string committed directly in source.",
                 snippet: text.trim().slice(0, 160),
             });
         }
     });
+    // --- exec/eval with an interpolated string (possible command injection)
+    const importsChildProcess = CP_IMPORT.test(content);
+    const execStarts = [];
+    const patterns = importsChildProcess ? [EXEC_BARE, EXEC_CP, NEW_FUNCTION] : [EXEC_CP, NEW_FUNCTION];
+    for (const re of patterns) {
+        for (const m of content.matchAll(re)) {
+            execStarts.push({ index: m.index, callEnd: m.index + m[0].length });
+        }
+    }
+    for (const { index, callEnd } of execStarts) {
+        if (inStringOrComment(content, index))
+            continue;
+        const arg = firstArgument(content, callEnd);
+        if (!/\$\{|["'`]\s*\+\s*[A-Za-z_$]|[A-Za-z_$][\w$.]*\s*\+\s*["'`]/.test(arg))
+            continue;
+        if (SHELL_QUOTE.test(arg))
+            continue; // interpolated values are shell-escaped
+        const line = lineAt(content, index);
+        findings.push({
+            file: filePath,
+            line,
+            severity: "high",
+            rule: "exec-injection",
+            message: "exec()/Function() call with an interpolated string — if any part of that string comes from tool input, this is a command/code-injection risk, not just a style issue.",
+            snippet: lines[line - 1]?.trim().slice(0, 160) ?? "",
+        });
+    }
     return findings;
 }
-export function scanDirectory(root) {
-    const files = walk(root);
+export function scanDirectory(root, options = {}) {
+    const files = walk(root, options.includeTests ?? false);
     const findings = [];
     for (const file of files) {
         let content;

package/dist/scan.test.js

@@ -39,7 +39,66 @@ test("flags a hardcoded Stripe live key as a secret", () => {
     assert.ok(findings.some((f) => f.rule === "secret"));
 });
 test("flags exec() next to a template literal as possible injection", () => {
-    const src = `exec(\`ls \${userInput}\`);`;
+    const src = `import { exec } from "node:child_process";\nexec(\`ls \${userInput}\`);`;
     const findings = scanFile("run.ts", src);
     assert.ok(findings.some((f) => f.rule === "exec-injection"));
 });
+// --- False positives seen in a scan of 36 public MCP servers (2026-10-19) ---
+test("does not flag a caller value used only in the path under a configured base URL", () => {
+    const src = `
+server.tool("get_job", "desc", { jobId: z.string() }, async ({ jobId }) => {
+  const res = await fetch(\`\${gatewayUrl}/api/jobs/\${encodeURIComponent(jobId)}\`);
+  return res.text();
+});`;
+    assert.equal(scanFile("server.ts", src).filter((f) => f.rule === "ssrf").length, 0);
+});
+test("does not flag the word 'fetch (' inside a string or comment", () => {
+    const src = `
+server.tool("memory", "desc", { id: z.number() }, async ({ id }) => {
+  const schema = z.number().describe('Decision id to fetch (from an index_only query).');
+  // fetch (id) later
+  return id;
+});`;
+    assert.equal(scanFile("server.ts", src).filter((f) => f.rule === "ssrf").length, 0);
+});
+test("still flags a template URL that starts with the caller's value", () => {
+    const src = `
+server.tool("fetch_url", "desc", { url: z.string() }, async ({ url }) => {
+  const res = await fetch(\`\${url}/robots.txt\`);
+  return res.text();
+});`;
+    assert.equal(scanFile("server.ts", src).filter((f) => f.rule === "ssrf" && f.severity === "high").length, 1);
+});
+test("does not judge one handler's fetch against another handler's parameters", () => {
+    const src = `
+server.tool("a", "desc", { url: z.string() }, async ({ url }) => { return url; });
+server.tool("b", "desc", {}, async () => { const url = "https://example.com"; return fetch(url); });`;
+    assert.equal(scanFile("server.ts", src).filter((f) => f.rule === "ssrf").length, 0);
+});
+test("does not flag SQLite db.exec or RegExp.exec as command injection", () => {
+    const src = `
+import { DatabaseSync } from "node:sqlite";
+db.exec(\`DROP TABLE IF EXISTS \${table}\`);
+const m = new RegExp(\`\${name}=(\\\\w+)\`).exec(attrs);`;
+    assert.equal(scanFile("store.ts", src).filter((f) => f.rule === "exec-injection").length, 0);
+});
+test("does not flag a bare exec() when the file never imports child_process", () => {
+    const src = "exec(`ls ${dir}`);";
+    assert.equal(scanFile("helper.ts", src).filter((f) => f.rule === "exec-injection").length, 0);
+});
+test("does not flag exec when the interpolated value is shell-escaped", () => {
+    const src = `import { execSync } from "child_process";\nexecSync(\`ls \${shellEscape(dir)}\`);`;
+    assert.equal(scanFile("run.ts", src).filter((f) => f.rule === "exec-injection").length, 0);
+});
+test("ignores placeholder and env-var-name values in the generic secret rule", () => {
+    const src = [
+        'const apiKey = "your-api-key-goes-here-123";',
+        'const token = "GITHUB_PERSONAL_ACCESS_TOKEN";',
+        'const password = "labelOnlyNoDigitsHereAtAll";',
+    ].join("\n");
+    assert.equal(scanFile("config.ts", src).filter((f) => f.rule === "secret").length, 0);
+});
+test("still flags a realistic hardcoded credential", () => {
+    const src = 'const apiKey = "a8f3k29dLq0x7Zm41PqW";';
+    assert.equal(scanFile("config.ts", src).filter((f) => f.rule === "secret").length, 1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sms-florin/mcp-ssrf-scan",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A static scanner for MCP servers that catches the exact bug class behind most real MCP SSRF reports: a tool handler making an outbound request to a caller-controlled URL with no host validation.",
   "type": "module",
   "bin": {