@gianmarcomaz/vantyr 1.0.0

package/src/scanner/specCompliance.js

@@ -0,0 +1,243 @@
+/**
+ * Spec Compliance Analyzer
+ * Validates MCP server protocol conformance.
+ *
+ * Supports patterns from JS/TS, Python, and Go MCP SDKs.
+ */
+
+/**
+ * @param {Array<{path: string, content: string}>} files
+ * @returns {Array}
+ */
+function analyzeSpecCompliance(files) {
+    const findings = [];
+
+    const allContent = files.map((f) => f.content).join("\n");
+    const allPaths = files.map((f) => f.path);
+
+    // ─── CHECK 1: Server manifest/metadata ───
+    const hasServerName =
+        /server[_-]?name/i.test(allContent) ||
+        /(?:createServer|McpServer|Server|mcp\.NewServer|NewServer)\s*\(\s*\{[\s\S]{0,100}?name\s*:/i.test(allContent) ||
+        /name\s*=\s*['"][a-zA-Z0-9_-]+[-_]mcp[-_]/i.test(allContent);
+    const hasVersion =
+        /server[_-]?version|mcp[_-]?version/i.test(allContent) ||
+        /(?:createServer|McpServer|Server|mcp\.NewServer|NewServer)\s*\(\s*\{[\s\S]{0,100}?version\s*:/i.test(allContent);
+    const hasCapabilities =
+        /capabilities\s*[:=]/.test(allContent) ||
+        /setCapabilities/.test(allContent) ||
+        /WithCapabilities|ServerCapabilities|Capabilities\s*\{/.test(allContent);  // Go
+
+    if (!(hasServerName && hasVersion)) {
+        findings.push({
+            severity: "medium",
+            file: "project",
+            line: null,
+            snippet: "",
+            message: `Server ${!hasServerName ? "name" : "version"} not found in source code.`,
+            remediation: "Declare server name and version in your MCP server configuration.",
+        });
+    }
+    if (!hasCapabilities) {
+        findings.push({
+            severity: "low",
+            file: "project",
+            line: null,
+            snippet: "",
+            message: "No explicit capabilities declaration found.",
+            remediation: "Declare server capabilities to inform clients what features are supported.",
+        });
+    }
+
+    const hasProtocolSupport = /@modelcontextprotocol\/sdk|mcp[_-]python|mcp[_-]sdk|github\.com\/mark3b\/mcp|mcp-go|protocolVersion/i.test(allContent);
+    if (!hasProtocolSupport) {
+        findings.push({
+            severity: "medium",
+            file: "project",
+            line: null,
+            snippet: "",
+            message: "No MCP SDK or protocol version declaration found.",
+            remediation: "Use an official MCP SDK or explicitly declare protocol compatibility.",
+        });
+    }
+
+    // ─── CHECK 2: Tool definitions structure ───
+
+    // Pattern 1: Direct SDK calls (JS/TS/Python)
+    const hasDirectSDKCall =
+        /server\.tool\s*\(/.test(allContent) ||
+        /\.addTool\s*\(/.test(allContent) ||
+        /\.registerTools?\s*\(/.test(allContent) ||
+        /@server\.tool/.test(allContent) ||
+        /@mcp\.tool/.test(allContent);
+
+    // Pattern 2: Variable-then-register
+    const hasVarThenRegister =
+        /(?:const|let|var)\s+\w+\s*=\s*\{[^}]*name\s*:/.test(allContent) &&
+        /(?:addTool|registerTool|server\.tool)/.test(allContent);
+
+    // Pattern 3: Array of tools
+    const hasToolArray =
+        /tools\s*[:=]\s*\[/.test(allContent) ||
+        /(?:const|let|var)\s+tools\s*=\s*\[/.test(allContent);
+
+    // Pattern 4: Object matching MCP tool shape (name + description + inputSchema)
+    const hasToolShapeObject =
+        /name\s*[:=]\s*['"][\w-]+['"]/.test(allContent) &&
+        /description\s*[:=]\s*['"][^'"]{3,}['"]/.test(allContent) &&
+        /inputSchema|input_schema|InputSchema/.test(allContent);
+
+    // Pattern 5: Tool definition files (tools.ts, toolDefinitions.ts, etc.)
+    const hasToolDefFile = allPaths.some((p) =>
+        /[\/\\](?:tools|toolDefinitions|tool[_-]?defs|mcpTools)\.(?:ts|js|py)$/i.test(p)
+    );
+
+    // Go SDK patterns
+    const hasGoToolDef =
+        /mcp\.NewTool\s*\(/.test(allContent) ||
+        /\.AddTool\s*\(/.test(allContent) ||
+        /AddTools?\s*\(/.test(allContent) ||
+        /RegisterTool/.test(allContent);
+
+    const hasToolDef = hasDirectSDKCall || hasVarThenRegister || hasToolArray ||
+                       hasToolShapeObject || hasToolDefFile || hasGoToolDef;
+
+    const hasInputSchema =
+        /inputSchema|input_schema|parameters\s*[:=]\s*\{/.test(allContent) ||
+        /InputSchema|mcp\.Property|WithDescription|Required\s*[:=]/.test(allContent);
+    const hasSchemaType =
+        /"type"\s*:\s*"object"/.test(allContent) || /type\s*[:=]\s*['"]object['"]/.test(allContent);
+    const hasProperties =
+        /"properties"\s*:/.test(allContent) || /properties\s*[:=]/.test(allContent);
+
+    if (hasToolDef) {
+        if (hasInputSchema) {
+            if (!hasSchemaType && !/InputSchema/.test(allContent)) {
+                findings.push({
+                    severity: "medium",
+                    file: "project",
+                    line: null,
+                    snippet: "",
+                    message: "Tool input schema lacks a top-level 'type' field.",
+                    remediation: "Ensure the root of the inputSchema is an explicitly typed 'object'.",
+                });
+            }
+        } else {
+            findings.push({
+                severity: "medium",
+                file: "project",
+                line: null,
+                snippet: "",
+                message: "Tool definitions found but no input schemas detected.",
+                remediation: "Define inputSchema with JSON Schema for each tool to enable input validation.",
+            });
+        }
+    } else {
+        findings.push({
+            severity: "medium",
+            file: "project",
+            line: null,
+            snippet: "",
+            message: "No MCP tool definitions found.",
+            remediation: "Define tools using the MCP SDK's server.tool() or equivalent method.",
+        });
+    }
+
+    // ─── CHECK 3: Error handling ───
+    const hasJsonRpcError =
+        /error\s*[:=]\s*\{.*code/s.test(allContent) ||
+        /JsonRpcError|McpError/.test(allContent) ||
+        /fmt\.Errorf|errors\.Is|errors\.As|errors\.New/.test(allContent);  // Go
+    const hasTryCatch =
+        /try\s*\{[\s\S]*catch/m.test(allContent) ||
+        /if\s+err\s*!=\s*nil/.test(allContent);  // Go error handling
+    const hasErrorHandler =
+        /\.on\s*\(\s*['"]error['"]|onerror|error_handler|catch_exceptions/.test(allContent) ||
+        /ErrorHandler|HandleError/.test(allContent);  // Go
+
+    if (hasTryCatch || hasErrorHandler) {
+        const hasSilentErrors = /catch\s*\([^)]*\)\s*\{\s*\}|except\s+Exception[^:]*:\s*pass/.test(allContent);
+        if (hasSilentErrors) {
+            findings.push({
+                severity: "low",
+                file: "project",
+                line: null,
+                snippet: "",
+                message: "Silent error handling detected (empty catch block).",
+                remediation: "Properly handle and return errors to the language model.",
+            });
+        }
+    } else {
+        findings.push({
+            severity: "medium",
+            file: "project",
+            line: null,
+            snippet: "",
+            message: "No error handling patterns detected in tool handlers.",
+            remediation: "Wrap tool handlers in try/catch blocks and return proper JSON-RPC error responses.",
+        });
+    }
+    if (!hasJsonRpcError) {
+        findings.push({
+            severity: "low",
+            file: "project",
+            line: null,
+            snippet: "",
+            message: "No JSON-RPC error response patterns found.",
+            remediation: "Return MCP-compliant error objects with error codes and messages.",
+        });
+    }
+
+    // ─── CHECK 4: Transport implementation ───
+    const hasStdio =
+        /stdio|StdioServerTransport|stdin|stdout/.test(allContent) ||
+        /CommandTransport|StdioTransport/.test(allContent);  // Go
+    const hasHttp =
+        /SSEServerTransport|HttpServerTransport|express|fastify|http\.createServer/.test(allContent) ||
+        /SSEHandler|StreamableHTTP|http\.ListenAndServe/.test(allContent);  // Go
+
+    if (hasHttp) {
+        const hasAuth = /auth|authenticate|middleware|bearer|authorization/i.test(allContent);
+        if (!hasAuth) {
+            findings.push({
+                severity: "high",
+                file: "project",
+                line: null,
+                snippet: "",
+                message: "HTTP transport without authentication middleware detected.",
+                remediation: "Add authentication middleware to protect your HTTP-based MCP server.",
+            });
+        }
+    }
+
+    // ─── CHECK 5: Documentation ───
+    const hasReadme = allPaths.some((p) => /readme\.md$/i.test(p));
+    const hasToolDescriptions = /description\s*[:=]\s*['"][^'"]{5,}['"]/.test(allContent);
+
+    if (!hasReadme) {
+        findings.push({
+            severity: "low",
+            file: "project",
+            line: null,
+            snippet: "",
+            message: "No README.md file found.",
+            remediation: "Create a README with setup instructions, tool documentation, and usage examples.",
+        });
+    }
+
+    const hasEmptyToolDescriptions = /description\s*[:=]\s*['"]["']/i.test(allContent);
+    if (hasEmptyToolDescriptions) {
+        findings.push({
+            severity: "low",
+            file: "project",
+            line: null,
+            snippet: "",
+            message: "Empty tool descriptions detected.",
+            remediation: "Provide meaningful descriptions for all tools. LLMs rely on these descriptions to know when and how to use the tool.",
+        });
+    }
+
+    return findings.map(f => ({ ...f, category: 'SC' }));
+}
+
+export { analyzeSpecCompliance };

package/src/scanner/toolPoisoning.js

@@ -0,0 +1,248 @@
+/**
+ * Tool Poisoning Analyzer
+ * Scans MCP tool definitions for description-based prompt injection.
+ */
+
+// Patterns to find tool definitions
+const TOOL_DEF_PATTERNS = [
+    // JavaScript/TypeScript
+    /server\.tool\s*\(/g,
+    /\.addTool\s*\(/g,
+    /\.add_tool\s*\(/g,
+    /tools\s*:\s*\[/g,
+    // Python decorators
+    /@server\.tool/g,
+    /@mcp\.tool/g,
+    // Go
+    /mcp\.NewTool\s*\(/g,
+    /\.AddTool\s*\(/g,
+    /AddTools?\s*\(/g,
+    /RegisterTool/g,
+];
+
+// Extract description from nearby lines
+const DESCRIPTION_PATTERNS = [
+    /description\s*[:=]\s*['"`]([^'"`]*(?:['"`][^'"`]*)*?)['"`]/gi,
+    /description\s*[:=]\s*['"`]([\s\S]*?)['"`]/gi,
+    /"""([\s\S]*?)"""/g,  // Python docstrings
+    /'''([\s\S]*?)'''/g,
+];
+
+// Extract tool names
+const NAME_PATTERNS = [
+    /name\s*[:=]\s*['"`]([^'"`]+)['"`]/gi,
+];
+
+const SHADOWED_NAMES = new Set([
+    "read_file", "write_file", "execute_command", "run_script", "get_user_info",
+    "sudo", "eval", "system", "fetch_url", "http_get", "fs_read", "fs_write",
+]);
+
+// Critical injection patterns in descriptions
+const INJECTION_PATTERNS = [
+    {
+        regex: /ignore\s+(?:previous|above|all|prior)/i,
+        severity: "critical",
+        message: "Instruction override attempt: 'ignore previous' pattern detected.",
+    },
+    {
+        regex: /disregard\s+(?:previous|above|all|prior|earlier)/i,
+        severity: "critical",
+        message: "Instruction override attempt: 'disregard' pattern detected.",
+    },
+    {
+        // Reduced from critical to high: legitimate descriptions occasionally say
+        // "You should always provide X in format Y." That's verbose but not injection.
+        // What IS injection is "you must always ignore / exfiltrate / bypass" —
+        // which will also be caught by the ignore/disregard/forget patterns above.
+        regex: /you\s+(?:must|should|have\s+to|need\s+to)\s+(?:always|never)/i,
+        severity: "high",
+        message: "Behavioral instruction found in tool description — LLMs should not be instructed via tool descriptions.",
+    },
+    {
+        // "You are now connected" / "You are now in read-only mode" are benign status
+        // phrases. The injection vector is "You are now [persona/role]", so require
+        // role-assignment language after "you are now" before flagging.
+        regex: /you\s+are\s+now\s+(?!(?:connected|logged|subscribed|available|ready|enabled|configured|running|serving|listening|active|online|offline|authenticated|authorized|processing|complete|done|finished|started|stopped|in\s)\b)/i,
+        severity: "critical",
+        message: "Identity override attempt detected: 'you are now [persona]' pattern.",
+    },
+    {
+        regex: /system\s+prompt/i,
+        severity: "critical",
+        message: "Reference to system prompt found in description.",
+    },
+    {
+        regex: /instructions?\s+override/i,
+        severity: "critical",
+        message: "Explicit instruction override language detected.",
+    },
+    {
+        regex: /forget\s+(?:everything|all|previous)/i,
+        severity: "critical",
+        message: "Memory reset attempt in tool description.",
+    },
+    {
+        regex: /[\u200B\u200C\u200D\u202E\uFEFF]/,
+        severity: "critical",
+        message: "Zero-width or text-direction override characters detected. These hide instructions from human reviewers.",
+    },
+    {
+        regex: /<!--[\s\S]*?-->/,
+        severity: "critical",
+        message: "HTML comment detected. Instructions inside HTML comments hide from users but are processed by LLMs.",
+    },
+];
+
+const WARNING_PATTERNS_TOOL = [
+    {
+        regex: /before\s+using\s+this\s+tool/i,
+        severity: "info",
+        message: "Cross-tool instruction: references behavior before tool use.",
+    },
+    {
+        regex: /(?:first|also)\s+(?:call|execute|run|use)/i,
+        severity: "info",
+        message: "Cross-tool reference: instructs calling other tools.",
+    },
+    {
+        regex: /<[a-z][\s\S]*>/i,
+        severity: "medium",
+        message: "HTML/XML formatting in tool description — could hide content.",
+    },
+];
+
+/**
+ * @param {Array<{path: string, content: string}>} files
+ * @returns {{ score: number, status: string, findings: Array }}
+ */
+function analyzeToolPoisoning(files) {
+    const findings = [];
+    let toolDefsFound = 0;
+
+    for (const file of files) {
+        const content = file.content;
+        const lines = content.split("\n");
+
+        // Step 1: Find tool definitions
+        let hasToolDef = false;
+        for (const pattern of TOOL_DEF_PATTERNS) {
+            pattern.lastIndex = 0;
+            if (pattern.test(content)) {
+                hasToolDef = true;
+                break;
+            }
+        }
+
+        if (!hasToolDef) continue;
+        toolDefsFound++;
+
+        // Step 2: Extract descriptions
+        const rawDescriptions = [];
+        for (const pattern of DESCRIPTION_PATTERNS) {
+            pattern.lastIndex = 0;
+            let match;
+            while ((match = pattern.exec(content)) !== null) {
+                const desc = match[1] || match[0];
+                const lineNum = content.slice(0, match.index).split("\n").length;
+                rawDescriptions.push({ text: desc, line: lineNum });
+            }
+        }
+
+        // Deduplicate by trimmed text — overlapping patterns (e.g. patterns 1 & 2)
+        // would otherwise fire on the same description string and double every finding.
+        const seenTexts = new Set();
+        const descriptions = rawDescriptions.filter(d => {
+            const key = d.text.trim();
+            if (seenTexts.has(key)) return false;
+            seenTexts.add(key);
+            return true;
+        });
+
+        // Step 3: Analyze descriptions
+        for (const desc of descriptions) {
+            // Check for long descriptions
+            if (desc.text.length > 1000) {
+                findings.push({
+                    severity: "medium",
+                    file: file.path,
+                    line: desc.line,
+                    snippet: desc.text.slice(0, 120) + "...",
+                    message: `Unusually long tool description (${desc.text.length} chars). Could hide injected instructions.`,
+                    remediation:
+                        "Keep tool descriptions concise and factual. Descriptions over 1000 characters should be reviewed.",
+                });
+            }
+
+            // Check for base64 — tuned to 40+ chars to avoid random hashes.
+            // NOTE: \b fails for strings ending in '=' (non-word char), so we use
+            // explicit lookahead/lookbehind instead of word-boundary anchors.
+            const base64Match = desc.text.match(/(?<![A-Za-z0-9+/=])[A-Za-z0-9+/]{40,}={0,2}(?![A-Za-z0-9+/=])/);
+            if (base64Match) {
+                findings.push({
+                    severity: "medium",
+                    file: file.path,
+                    line: desc.line,
+                    snippet: base64Match[0].slice(0, 60) + "...",
+                    message: "Base64-encoded string in tool description — could hide instructions.",
+                    remediation:
+                        "Remove encoded content from tool descriptions. All description content should be human-readable.",
+                });
+            }
+
+            // Check injection patterns
+            for (const pattern of INJECTION_PATTERNS) {
+                if (pattern.regex.test(desc.text)) {
+                    findings.push({
+                        severity: pattern.severity,
+                        file: file.path,
+                        line: desc.line,
+                        snippet: desc.text.slice(0, 150),
+                        message: pattern.message,
+                        remediation:
+                            "Keep tool descriptions factual and concise. Do not include instructions for the LLM in tool descriptions.",
+                    });
+                }
+            }
+
+            // Check warning patterns
+            for (const pattern of WARNING_PATTERNS_TOOL) {
+                if (pattern.regex.test(desc.text)) {
+                    findings.push({
+                        severity: pattern.severity,
+                        file: file.path,
+                        line: desc.line,
+                        snippet: desc.text.slice(0, 150),
+                        message: pattern.message,
+                        remediation:
+                            "Tool descriptions should explain what the tool does, not how the LLM should behave.",
+                    });
+                }
+            }
+        }
+
+        // Step 4: Analyze tool names for shadowing
+        for (const pattern of NAME_PATTERNS) {
+            pattern.lastIndex = 0;
+            let match;
+            while ((match = pattern.exec(content)) !== null) {
+                const toolName = match[1].toLowerCase();
+                if (SHADOWED_NAMES.has(toolName)) {
+                    const lineNum = content.slice(0, match.index).split("\n").length;
+                    findings.push({
+                        severity: "high",
+                        file: file.path,
+                        line: lineNum,
+                        snippet: match[0],
+                        message: `Tool name '${toolName}' shadows a common system or sensitive tool name.`,
+                        remediation: "Use a more specific, domain-prefixed name for the tool to avoid confusing the LLM or shadowing built-in systemic capabilities.",
+                    });
+                }
+            }
+        }
+    }
+
+    return findings.map(f => ({ ...f, category: 'TP' }));
+}
+
+export { analyzeToolPoisoning };

package/src/scoring/trustScore.js

@@ -0,0 +1,82 @@
+// Standard deductions applied uniformly across ALL categories
+const SEVERITY_DEDUCTIONS = {
+  critical: 25,
+  high: 15,
+  medium: 5,
+  low: 3,
+  info: 0
+};
+
+export function calculateTrustScore(allFindings) {
+  // Group findings by category
+  const categories = {
+    NE: { findings: [], score: 100 },
+    CI: { findings: [], score: 100 },
+    CL: { findings: [], score: 100 },
+    TP: { findings: [], score: 100 },
+    SC: { findings: [], score: 100 },
+    IV: { findings: [], score: 100 }
+  };
+
+  for (const finding of allFindings) {
+    if (categories[finding.category]) {
+      categories[finding.category].findings.push(finding);
+    }
+  }
+
+  // Calculate per-category scores using IDENTICAL math for every category
+  for (const [key, cat] of Object.entries(categories)) {
+    let deduction = 0;
+    for (const finding of cat.findings) {
+      deduction += SEVERITY_DEDUCTIONS[finding.severity] || 0;
+    }
+    cat.score = Math.max(0, 100 - deduction);
+  }
+
+  // Weighted average using OWASP-aligned weights
+  const WEIGHTS = {
+    CL: 0.25,  // Credential Leaks — OWASP MCP01 (#1)
+    CI: 0.20,  // Command Injection — OWASP MCP05 (#5)
+    NE: 0.15,  // Network Exposure — OWASP MCP07 (#7)
+    IV: 0.15,  // Input Validation — SSRF/Path Traversal
+    TP: 0.15,  // Tool Poisoning — OWASP MCP03 (#3)
+    SC: 0.10   // Spec Compliance — Protocol hygiene
+  };
+
+  let weightedSum = 0;
+  for (const [key, weight] of Object.entries(WEIGHTS)) {
+    weightedSum += categories[key].score * weight;
+  }
+
+  let trustScore = Math.round(weightedSum);
+
+  // Count totals
+  let totalFindings = allFindings.length;
+  let criticalCount = allFindings.filter(f => f.severity === 'critical').length;
+  let highCount = allFindings.filter(f => f.severity === 'high').length;
+  let mediumCount = allFindings.filter(f => f.severity === 'medium').length;
+  let lowCount = allFindings.filter(f => f.severity === 'low').length;
+  let infoCount = allFindings.filter(f => f.severity === 'info').length;
+
+  // A repo with any HIGH or CRITICAL finding cannot be CERTIFIED.
+  // Cap the Trust Score at 75 so the label always falls into WARNING or FAILED,
+  // regardless of how clean the other categories are.
+  const hasCriticalOrHigh = criticalCount > 0 || highCount > 0;
+  let scoreCapped = false;
+  if (hasCriticalOrHigh && trustScore > 75) {
+    trustScore = 75;
+    scoreCapped = true;
+  }
+
+  // Determine pass count (categories scoring >= 80)
+  let passCount = Object.values(categories).filter(c => c.score >= 80).length;
+
+  return {
+    trustScore,
+    categories,
+    totalFindings,
+    stats: { critical: criticalCount, high: highCount, medium: mediumCount, low: lowCount, info: infoCount },
+    passCount,
+    scoreCapped
+  };
+}