@guardbee/mcp-tool-poisoning-scanner 0.1.0

package/dist/server.js

@@ -0,0 +1,71 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { instrumentServer } from "@guardbee/mcp-telemetry";
+import { z } from "zod";
+import { scanText, scanFile, scanDirectory } from "./scanner.js";
+import { DESCRIPTION_INJECTION_PATTERNS, MISMATCH_SINK_RULES } from "./patterns.js";
+function formatFindings(findings, scannedFiles, durationMs) {
+    if (findings.length === 0) {
+        return `✅ No tool-poisoning or confused-deputy findings. Scanned ${scannedFiles} file(s) in ${durationMs}ms.`;
+    }
+    const bySeverity = { critical: 0, high: 0, medium: 0 };
+    for (const f of findings)
+        bySeverity[f.severity]++;
+    const lines = [
+        `⚠️  Found ${findings.length} finding(s) in ${scannedFiles} file(s) (${durationMs}ms)`,
+        `   Critical: ${bySeverity.critical}  High: ${bySeverity.high}  Medium: ${bySeverity.medium}`,
+        "",
+    ];
+    for (const f of findings) {
+        const loc = f.file ? `${f.file}:${f.line}:${f.column}` : `line ${f.line}:${f.column}`;
+        lines.push(`[${f.severity.toUpperCase()}] ${f.patternName} (${f.category})`);
+        lines.push(`  Location       : ${loc}`);
+        lines.push(`  Match          : ${f.match}`);
+        lines.push(`  Recommendation : ${f.recommendation}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+export async function startServer() {
+    const server = new McpServer({
+        name: "guardbee-tool-poisoning-scanner",
+        version: "0.1.0",
+    });
+    instrumentServer(server, "tool-poisoning-scanner");
+    server.tool("scan_text", "Scan MCP server source for tool poisoning (hidden instructions embedded in a tool's `description` string, read by the calling LLM as trusted context) and confused-deputy tools (a name/description promising read-only behavior while the handler has a shell/eval/file-write/env-dump sink).", {
+        content: z.string().describe("The source code to scan"),
+        label: z.string().optional().describe("Optional label shown in findings (e.g. filename)"),
+    }, async ({ content, label }) => {
+        const findings = scanText(content, label);
+        return { content: [{ type: "text", text: formatFindings(findings, 1, 0) }] };
+    });
+    server.tool("scan_file", "Scan a single file for tool-poisoning and confused-deputy patterns in MCP tool registrations", { path: z.string().describe("Absolute or relative path to the file to scan") }, async ({ path: filePath }) => {
+        const { findings, skipped } = scanFile(filePath);
+        if (skipped) {
+            return { content: [{ type: "text", text: `⏭️  File skipped (binary, too large, or unreadable): ${filePath}` }] };
+        }
+        return { content: [{ type: "text", text: formatFindings(findings, 1, 0) }] };
+    });
+    server.tool("scan_directory", "Recursively scan a directory of MCP server source for tool-poisoning and confused-deputy patterns", {
+        path: z.string().describe("Absolute or relative path to the directory to scan"),
+        maxFiles: z.number().optional().describe("Maximum number of files to scan (default: 5000)"),
+        include: z.array(z.string()).optional().describe("Only scan files whose path contains one of these strings"),
+        exclude: z.array(z.string()).optional().describe("Skip files/dirs whose path contains one of these strings"),
+    }, async ({ path: dirPath, maxFiles, include, exclude }) => {
+        const result = scanDirectory(dirPath, { maxFiles, include, exclude });
+        return { content: [{ type: "text", text: formatFindings(result.findings, result.scannedFiles, result.durationMs) }] };
+    });
+    server.tool("list_patterns", "List every description-injection phrase and confused-deputy sink rule this scanner detects", {}, async () => {
+        const lines = ["[description-injection]"];
+        for (const p of DESCRIPTION_INJECTION_PATTERNS)
+            lines.push(`  • ${p.name} (${p.id}, ${p.severity})`);
+        lines.push("", "[confused-deputy]", "  A tool whose name/description implies read-only/informational behavior, but whose handler contains:");
+        for (const r of MISMATCH_SINK_RULES)
+            lines.push(`  • ${r.category} (${r.id}, ${r.severity})`);
+        lines.push("", "Scope: the MCP TypeScript SDK's `server.tool(name, description, schema, handler)` convenience form. Raw setRequestHandler()-style tool lists and non-JS/TS servers are not covered — see README.");
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@guardbee/mcp-tool-poisoning-scanner",
+  "version": "0.1.0",
+  "description": "MCP server that scans other MCP servers' tool definitions for tool poisoning (hidden instructions embedded in a tool's description, read as trusted context by the calling LLM) and confused-deputy mismatches (a tool's name/description promises read-only behavior while its handler has a shell/eval/file-write/env-dump sink)",
+  "type": "module",
+  "bin": {
+    "guardbee-tool-poisoning-scanner": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "TR.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^4.5.4",
+    "@guardbee/mcp-telemetry": "^0.1.2"
+  },
+  "keywords": [
+    "mcp",
+    "security",
+    "ai-security",
+    "mcp-security",
+    "tool-poisoning",
+    "prompt-injection",
+    "guardbee",
+    "devtools"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GuardBee/guardbee-mcp.git",
+    "directory": "packages/tool-poisoning-scanner"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js",
+    "test": "vitest run"
+  }
+}