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

package/README.md

@@ -57,6 +57,54 @@ Exit code is `1` if any `HIGH` finding is reported, `0` otherwise:
 - run: npx @sms-florin/mcp-ssrf-scan ./src
 ```
 
+`--json` prints findings as JSON instead of the human-readable list.
+
+`--sarif` prints SARIF 2.1.0 for code-scanning UIs. Secret findings are tagged
+OWASP MCP01 (Token Mismanagement & Secret Exposure) and exec findings MCP05
+(Command Injection & Execution). The OWASP MCP Top 10 has no SSRF entry, so
+the SSRF rule carries no OWASP tag.
+
+### GitLab CI component
+
+```yaml
+include:
+  - component: gitlab.com/florin-builds/mcp-ssrf-scan/scan@~latest
+    inputs:
+      path: ./src
+```
+
+Inputs: `stage` (default `test`), `path` (default `.`), `node_image` (default
+`node:22-alpine`). The job fails on any HIGH finding and keeps
+`mcp-ssrf-scan.sarif` as an artifact.
+
+## mcp-ssrf-scan Cloud (optional, paid)
+
+The CLI above is free and stays free. [mcp-ssrf-scan Cloud](https://mcpscan.flo-voice1.com)
+($15/month, up to 10 repos) adds what a CI gate alone can't: every run is
+uploaded and diffed against the previous scan of that repo, so the CLI
+prints exactly what's **new since the last scan** and what got **fixed**,
+and every scan stays browsable on a dashboard for 90 days.
+
+```yaml
+# GitHub Actions
+- run: npx @sms-florin/mcp-ssrf-scan@latest ./src --upload
+  env:
+    MCP_SSRF_SCAN_KEY: ${{ secrets.MCP_SSRF_SCAN_KEY }}
+```
+
+```yaml
+# GitLab CI (MCP_SSRF_SCAN_KEY as a masked CI/CD variable)
+mcp-ssrf-scan:
+  image: node:22
+  script:
+    - npx @sms-florin/mcp-ssrf-scan@latest ./src --upload
+```
+
+Repo, branch and commit come from the CI environment (or `--repo owner/name`).
+Only findings are uploaded — path, line, rule, message and the flagged line
+— never your source. A failed upload only prints a warning; the exit code is
+always decided by the findings alone.
+
 ## License
 
 MIT

package/dist/cli.js

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { toSarif } from "./sarif.js";
 import { scanDirectory } from "./scan.js";
 const COLOR = {
     high: "\x1b[31m", // red
@@ -29,33 +32,127 @@ 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:
+  --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
+  --upload            Upload this scan to mcp-ssrf-scan Cloud (needs MCP_SSRF_SCAN_KEY)
+                      and print what's new/fixed since the last scan of this repo
+  --repo owner/name   Repo name for --upload (auto-detected in GitHub Actions,
+                      GitLab CI, or from the git remote)
+
 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).
+A failed --upload only prints a warning — it never changes the exit code.
 `);
 }
-function main() {
+function flagValue(args, name) {
+    const i = args.indexOf(name);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+function git(...cmd) {
+    try {
+        return execFileSync("git", cmd, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// owner/name from GitHub Actions, GitLab CI, or the local git remote.
+function detectRepo() {
+    const env = process.env;
+    if (env.GITHUB_REPOSITORY)
+        return { repo: env.GITHUB_REPOSITORY, ref: env.GITHUB_REF_NAME, commit: env.GITHUB_SHA };
+    if (env.CI_PROJECT_PATH)
+        return { repo: env.CI_PROJECT_PATH, ref: env.CI_COMMIT_REF_NAME, commit: env.CI_COMMIT_SHA };
+    const remote = git("config", "--get", "remote.origin.url");
+    const repo = remote?.replace(/\.git$/, "").match(/[:/]([^/:]+\/[^/]+)$/)?.[1];
+    return { repo, ref: git("rev-parse", "--abbrev-ref", "HEAD"), commit: git("rev-parse", "HEAD") };
+}
+// Uploads to mcp-ssrf-scan Cloud (paid, optional). A failed upload is a
+// warning, never a build failure — the exit code stays purely about findings,
+// so an outage on our side can't break someone's pipeline.
+async function upload(findings, args) {
+    const key = process.env.MCP_SSRF_SCAN_KEY;
+    if (!key) {
+        console.error(`${COLOR.high}--upload needs MCP_SSRF_SCAN_KEY${COLOR.reset} (get one at https://mcpscan.flo-voice1.com) — skipping upload.`);
+        return;
+    }
+    const detected = detectRepo();
+    const repo = flagValue(args, "--repo") ?? detected.repo;
+    if (!repo) {
+        console.error("Could not detect the repo name — pass --repo owner/name. Skipping upload.");
+        return;
+    }
+    const base = process.env.MCP_SSRF_SCAN_URL ?? "https://mcpscan.flo-voice1.com";
+    try {
+        const res = await fetch(`${base}/api/scans`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+            body: JSON.stringify({ repo, ref: detected.ref, commit: detected.commit, findings }),
+            signal: AbortSignal.timeout(20_000),
+        });
+        const data = (await res.json());
+        if (!res.ok) {
+            console.error(`${COLOR.high}Upload failed:${COLOR.reset} ${data.error ?? `HTTP ${res.status}`}`);
+            return;
+        }
+        console.log(`\n${COLOR.bold}Uploaded to mcp-ssrf-scan Cloud${COLOR.reset} — ${repo}`);
+        if (data.baseline) {
+            console.log("First scan of this repo: saved as the baseline, future runs show what changed.");
+        }
+        else {
+            console.log(`${data.newFindings.length} new since the last scan, ${data.fixedFindings.length} fixed.`);
+            for (const f of data.newFindings) {
+                console.log(`  ${COLOR.bold}NEW${COLOR.reset} ${severityLabel(f.severity)}  ${f.file}:${f.line}  ${COLOR.dim}[${f.rule}]${COLOR.reset}`);
+            }
+            for (const f of data.fixedFindings) {
+                console.log(`  ${COLOR.dim}FIXED ${f.severity.toUpperCase()}  ${f.file}:${f.line}  [${f.rule}]${COLOR.reset}`);
+            }
+        }
+        console.log(`${COLOR.dim}${data.dashboardUrl}${COLOR.reset}`);
+    }
+    catch (error) {
+        console.error(`${COLOR.high}Upload failed:${COLOR.reset} ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async 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 valueFlags = new Set(["--repo"]);
+    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);
-    if (findings.length === 0) {
-        console.log("No findings. (Heuristic scan — this is not a guarantee, see --help.)");
-        process.exit(0);
+    const hasHigh = findings.some((f) => f.severity === "high");
+    if (asSarif) {
+        const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        console.log(JSON.stringify(toSarif(findings, pkg.version), null, 2));
     }
-    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`);
+    else if (asJson) {
+        console.log(JSON.stringify({ target, findings }, null, 2));
     }
-    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");
+    else {
+        console.log(`${COLOR.bold}mcp-ssrf-scan${COLOR.reset} — scanning ${target}\n`);
+        if (findings.length === 0) {
+            console.log("No findings. (Heuristic scan — this is not a guarantee, see --help.)");
+        }
+        else {
+            const order = ["high", "medium", "info"];
+            for (const f of order.flatMap((sev) => findings.filter((x) => x.severity === sev))) {
+                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(", ")}`);
+        }
+    }
+    if (args.includes("--upload"))
+        await upload(findings, args);
     process.exit(hasHigh ? 1 : 0);
 }
 main();

package/dist/sarif.d.ts

@@ -0,0 +1,44 @@
+import type { Finding } from "./scan.js";
+export declare function toSarif(findings: Finding[], version: string): {
+    $schema: string;
+    version: string;
+    runs: {
+        tool: {
+            driver: {
+                name: string;
+                version: string;
+                informationUri: string;
+                rules: {
+                    id: "ssrf" | "secret" | "exec-injection";
+                    name: string;
+                    shortDescription: {
+                        text: string;
+                    };
+                    properties: {
+                        tags: string[];
+                    };
+                }[];
+            };
+        };
+        results: {
+            ruleId: "ssrf" | "secret" | "exec-injection";
+            level: string;
+            message: {
+                text: string;
+            };
+            locations: {
+                physicalLocation: {
+                    artifactLocation: {
+                        uri: string;
+                    };
+                    region: {
+                        startLine: number;
+                        snippet: {
+                            text: string;
+                        };
+                    };
+                };
+            }[];
+        }[];
+    }[];
+};

package/dist/sarif.js

@@ -0,0 +1,55 @@
+// OWASP MCP Top 10 (2025) has no SSRF entry, so that rule is left unmapped
+// rather than forced into a category it doesn't belong to.
+const RULES = {
+    ssrf: {
+        name: "McpToolSsrf",
+        description: "Outbound request in a tool handler uses a caller-controlled URL with no host/IP validation.",
+    },
+    secret: {
+        name: "HardcodedSecret",
+        description: "Hardcoded credential or API key in source.",
+        owasp: "MCP01:2025 Token Mismanagement & Secret Exposure",
+    },
+    "exec-injection": {
+        name: "ExecInjection",
+        description: "exec()/Function() call next to a template literal, possible command injection.",
+        owasp: "MCP05:2025 Command Injection & Execution",
+    },
+};
+const LEVEL = { high: "error", medium: "warning", info: "note" };
+export function toSarif(findings, version) {
+    return {
+        $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+        version: "2.1.0",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "mcp-ssrf-scan",
+                        version,
+                        informationUri: "https://gitlab.com/florin-builds/mcp-ssrf-scan",
+                        rules: Object.keys(RULES).map((id) => ({
+                            id,
+                            name: RULES[id].name,
+                            shortDescription: { text: RULES[id].description },
+                            properties: RULES[id].owasp ? { tags: ["security", RULES[id].owasp] } : { tags: ["security"] },
+                        })),
+                    },
+                },
+                results: findings.map((f) => ({
+                    ruleId: f.rule,
+                    level: LEVEL[f.severity],
+                    message: { text: f.message },
+                    locations: [
+                        {
+                            physicalLocation: {
+                                artifactLocation: { uri: f.file },
+                                region: { startLine: f.line, snippet: { text: f.snippet } },
+                            },
+                        },
+                    ],
+                })),
+            },
+        ],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sms-florin/mcp-ssrf-scan",
-  "version": "0.1.0",
+  "version": "0.3.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": {