@sms-florin/mcp-ssrf-scan 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florin Arsenie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# mcp-ssrf-scan
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A static scanner for MCP (Model Context Protocol) servers, built around one
+specific, common, real bug class: **a tool handler making an outbound
+request to a URL the caller controls, with no check on where that URL
+actually points.**
+
+```bash
+npx @sms-florin/mcp-ssrf-scan ./src
+```
+
+## Why this exists
+
+I found this exact bug in production, on my own server, before I ever
+thought about building a scanner for it. [sms-florin](https://flo-voice1.com)
+is a real phone-number-rental API I run — a GOIP webhook route on it
+forwards SMS content from hardware gateways, and an early version of that
+route made an outbound call using a value that, with the wrong input, could
+have reached internal infrastructure instead of the intended destination.
+It got caught and fixed before it mattered, but it's the kind of bug that
+doesn't announce itself — the code runs, the tests pass, nothing looks wrong
+until someone points it at `169.254.169.254` or `localhost:6379`.
+
+MCP tool handlers are the same shape, at scale: a function that takes
+caller-supplied arguments and, somewhere inside, makes a network call.
+[BlueRock scanned 8,000+ public MCP servers and found 36.7% have unbounded
+URI fetch / SSRF flaws](https://www.bluerock.io/post/private-repo-scanning-mcp-servers-secure-by-default)
+— this isn't a theoretical category, it's the single most common finding in
+the largest public scan of real MCP servers to date.
+
+## What it checks
+
+- **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.
+- **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.
+
+## What it is not
+
+This is a regex-based heuristic scanner, not a real AST analyzer or a
+dynamic test. It has false positives (a validated call it doesn't recognize
+as validated) and false negatives (a vulnerable call it doesn't recognize as
+vulnerable, especially across files or through an abstraction layer). Treat
+a `HIGH` finding as "go read this function," not as a confirmed bug — and
+don't assume a clean scan means a server is safe.
+
+## CI usage
+
+Exit code is `1` if any `HIGH` finding is reported, `0` otherwise:
+
+```yaml
+- run: npx @sms-florin/mcp-ssrf-scan ./src
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { scanDirectory } from "./scan.js";
+const COLOR = {
+    high: "\x1b[31m", // red
+    medium: "\x1b[33m", // yellow
+    info: "\x1b[36m", // cyan
+    reset: "\x1b[0m",
+    dim: "\x1b[2m",
+    bold: "\x1b[1m",
+};
+function severityLabel(s) {
+    const colors = { high: COLOR.high, medium: COLOR.medium, info: COLOR.info };
+    return `${colors[s]}${s.toUpperCase()}${COLOR.reset}`;
+}
+function printHelp() {
+    console.log(`mcp-ssrf-scan — a static scanner for MCP server source code
+
+Usage:
+  npx @sms-florin/mcp-ssrf-scan [path]   Scan a directory (default: current directory)
+  npx @sms-florin/mcp-ssrf-scan --help
+
+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)
+
+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.
+
+Exit code is 1 if any HIGH finding is reported, 0 otherwise (so it's usable
+as a CI gate: fail the build on HIGH, let MEDIUM/INFO through as warnings).
+`);
+}
+function main() {
+    const args = process.argv.slice(2);
+    if (args.includes("--help") || args.includes("-h")) {
+        printHelp();
+        process.exit(0);
+    }
+    const target = args.find((a) => !a.startsWith("-")) ?? ".";
+    console.log(`${COLOR.bold}mcp-ssrf-scan${COLOR.reset} — scanning ${target}\n`);
+    const findings = scanDirectory(target);
+    if (findings.length === 0) {
+        console.log("No findings. (Heuristic scan — this is not a guarantee, see --help.)");
+        process.exit(0);
+    }
+    const order = ["high", "medium", "info"];
+    const grouped = order.flatMap((sev) => findings.filter((f) => f.severity === sev));
+    for (const f of grouped) {
+        console.log(`${severityLabel(f.severity)}  ${f.file}:${f.line}  ${COLOR.dim}[${f.rule}]${COLOR.reset}`);
+        console.log(`  ${f.message}`);
+        console.log(`  ${COLOR.dim}${f.snippet}${COLOR.reset}\n`);
+    }
+    const counts = order.map((sev) => `${findings.filter((f) => f.severity === sev).length} ${sev}`);
+    console.log(`${COLOR.bold}${findings.length} finding(s)${COLOR.reset} — ${counts.join(", ")}`);
+    const hasHigh = findings.some((f) => f.severity === "high");
+    process.exit(hasHigh ? 1 : 0);
+}
+main();

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { scanDirectory, scanFile } from "./scan.js";
+export type { Finding, Severity } from "./scan.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { scanDirectory, scanFile } from "./scan.js";

package/dist/scan.d.ts

@@ -0,0 +1,11 @@
+export type Severity = "high" | "medium" | "info";
+export interface Finding {
+    file: string;
+    line: number;
+    severity: Severity;
+    rule: "ssrf" | "secret" | "exec-injection";
+    message: string;
+    snippet: string;
+}
+export declare function scanFile(filePath: string, content: string): Finding[];
+export declare function scanDirectory(root: string): Finding[];

package/dist/scan.js

@@ -0,0 +1,197 @@
+// Static scanner for MCP (Model Context Protocol) servers. Zero dependencies,
+// on purpose — this walks source files with plain regex heuristics instead of
+// a real AST, which means it can be wrong in both directions (false positives
+// on code that's actually fine, false negatives on cleverly-hidden issues).
+// It is a pre-flight smoke test, not a guarantee. Read every HIGH finding
+// yourself before trusting it either way.
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+const SKIP_DIRS = new Set([
+    "node_modules",
+    "dist",
+    "build",
+    ".git",
+    "coverage",
+    ".next",
+    "out",
+]);
+const SOURCE_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
+function walk(dir, out = []) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (SKIP_DIRS.has(entry))
+            continue;
+        const full = join(dir, entry);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory()) {
+            walk(full, out);
+        }
+        else if (SOURCE_EXT.has(entry.slice(entry.lastIndexOf(".")))) {
+            if (/\.(test|spec)\.[tj]sx?$/.test(entry))
+                continue; // skip test files
+            out.push(full);
+        }
+    }
+    return out;
+}
+// Calls that reach the network. Deliberately specific (not a bare "request(")
+// to keep false positives down — MCP SDK code itself uses "request" as a
+// name constantly (handleRequest, RequestSchema, ...) for unrelated things.
+const NETWORK_CALL = /\b(fetch|axios(?:\.(?:get|post|put|patch|delete|request))?|got|undici\.request|http\.(?:get|request)|https\.(?:get|request))\s*\(/;
+// MCP SDK tool-registration shapes this looks for, across the two common
+// patterns (server.tool(...) helper, and the lower-level setRequestHandler).
+const TOOL_HANDLER_START = /\b(?:server|mcpServer|this)\s*\.\s*tool\s*\(|setRequestHandler\s*\(/;
+const VALIDATION_SIGNAL = /\b(isPrivate\w*|privateIP|is_private|ssrf|SSRF|blockedHost|blocklist|blockList|denylist|denyList|allowlist|allowList|isAllowedHost|validateUrl|sanitizeUrl|checkHost|resolveDns)\b/;
+const SECRET_PATTERNS = [
+    { re: /\bsk_live_[A-Za-z0-9]{10,}/, label: "a live Stripe secret key" },
+    { re: /\bsk_test_[A-Za-z0-9]{10,}/, label: "a Stripe test secret key" },
+    { 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*\(/;
+function extractParamNames(block) {
+    // Very rough: pull identifier names out of the first destructured
+    // parameter of the handler function, e.g. async ({ url, target }) => or
+    // function (args) { ... args.url ... }. Good enough to catch the common
+    // "the URL came from the tool's own input" shape without a real parser.
+    const names = new Set();
+    const destructureMatch = block.match(/\(\s*\{([^}]{0,300})\}/);
+    if (destructureMatch) {
+        for (const part of destructureMatch[1].split(",")) {
+            const name = part.trim().split(/[:=]/)[0].trim();
+            if (/^[a-zA-Z_$][\w$]*$/.test(name))
+                names.add(name);
+        }
+    }
+    // Also catch a plain single-arg name (args, input, params) used as
+    // args.url / input.url / params.url later in the block.
+    for (const m of block.matchAll(/\b(args|input|params|req|request)\s*\.\s*([a-zA-Z_$][\w$]*)/g)) {
+        names.add(m[2]);
+    }
+    return [...names];
+}
+function lineAt(content, index) {
+    let line = 1;
+    for (let i = 0; i < index; i++)
+        if (content[i] === "\n")
+            line++;
+    return line;
+}
+export function scanFile(filePath, content) {
+    const findings = [];
+    // --- 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.
+    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);
+        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,
+                    });
+                }
+            }
+            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)) {
+                findings.push({
+                    file: filePath,
+                    line: i + 1,
+                    severity: "medium",
+                    rule: "secret",
+                    message: `Line looks like it contains ${label} committed directly in source.`,
+                    snippet: text.trim().slice(0, 160),
+                });
+                break;
+            }
+        }
+    });
+    // --- exec/eval with a nearby variable (possible command injection)
+    lines.forEach((text, i) => {
+        if (EXEC_CALL.test(text) && /\$\{|`.*\$\{/.test(text + (lines[i + 1] ?? ""))) {
+            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.",
+                snippet: text.trim().slice(0, 160),
+            });
+        }
+    });
+    return findings;
+}
+export function scanDirectory(root) {
+    const files = walk(root);
+    const findings = [];
+    for (const file of files) {
+        let content;
+        try {
+            content = readFileSync(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const f of scanFile(file, content)) {
+            findings.push({ ...f, file: relative(root, file) });
+        }
+    }
+    return findings;
+}

package/dist/scan.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scan.test.js

@@ -0,0 +1,45 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { scanFile } from "./scan.js";
+test("flags an unvalidated fetch inside a tool handler as SSRF (high)", () => {
+    const src = `
+server.tool("fetch_url", "desc", { url: z.string() }, async ({ url }) => {
+  const res = await fetch(url);
+  return res.text();
+});`;
+    const findings = scanFile("server.ts", src);
+    const ssrf = findings.find((f) => f.rule === "ssrf");
+    assert.ok(ssrf, "expected an ssrf finding");
+    assert.equal(ssrf.severity, "high");
+});
+test("downgrades to info when a validation-looking identifier is nearby", () => {
+    const src = `
+server.tool("fetch_url", "desc", { url: z.string() }, async ({ url }) => {
+  if (!isAllowedHost(url)) throw new Error("blocked");
+  const res = await fetch(url);
+  return res.text();
+});`;
+    const findings = scanFile("server.ts", src);
+    const ssrf = findings.find((f) => f.rule === "ssrf");
+    assert.ok(ssrf, "expected an ssrf finding");
+    assert.equal(ssrf.severity, "info");
+});
+test("does not flag a handler whose fetch uses only a literal URL", () => {
+    const src = `
+server.tool("ping", "desc", {}, async () => {
+  const res = await fetch("https://example.com/health");
+  return res.text();
+});`;
+    const findings = scanFile("server.ts", src);
+    assert.equal(findings.filter((f) => f.rule === "ssrf").length, 0);
+});
+test("flags a hardcoded Stripe live key as a secret", () => {
+    const src = `const key = "sk_live_51AbCdEfGhIjKlMnOpQrStUv";`;
+    const findings = scanFile("config.ts", src);
+    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 findings = scanFile("run.ts", src);
+    assert.ok(findings.some((f) => f.rule === "exec-injection"));
+});

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@sms-florin/mcp-ssrf-scan",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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": {
+    "mcp-ssrf-scan": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test dist/*.test.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "security",
+    "ssrf",
+    "static-analysis",
+    "ai-agents",
+    "scanner"
+  ],
+  "author": "Florin Arsenie",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/florin-builds/mcp-ssrf-scan"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/node": "^22.0.0"
+  }
+}