@baichen_yu/mcp-guard 0.3.0

package/dist/mcp/types.d.ts

@@ -0,0 +1,75 @@
+export type JsonRpcId = number;
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcSuccess {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    result: unknown;
+}
+export interface JsonRpcErrorShape {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export interface JsonRpcError {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    error: JsonRpcErrorShape;
+}
+export type JsonRpcResponse = JsonRpcSuccess | JsonRpcError;
+export interface ToolDescriptor {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface ServerConfig {
+    stdioCommand?: string;
+    httpUrl?: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    silent?: boolean;
+}
+export type Severity = 'low' | 'medium' | 'high';
+export interface Finding {
+    severity: Severity;
+    ruleId: string;
+    message: string;
+    evidence: string;
+    remediation: string;
+    toolName?: string;
+}
+export interface TestResult {
+    name: string;
+    passed: boolean;
+    durationMs: number;
+    details?: string;
+}
+export interface Report {
+    server: {
+        target: string;
+        transport: 'stdio' | 'http';
+        protocolVersion?: string;
+    };
+    tools: ToolDescriptor[];
+    findings: Finding[];
+    tests: TestResult[];
+    score: number;
+    scoreBreakdown: string[];
+    generatedAt: string;
+}
+export interface NormalizedError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export interface RpcClient {
+    request<T>(method: string, params?: unknown, timeoutOverrideMs?: number): Promise<T>;
+    normalizeError(error: unknown): NormalizedError;
+    close(): Promise<void>;
+}
+export type Profile = 'default' | 'strict' | 'paranoid';

package/dist/mcp/types.js

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

package/dist/registry/validator.d.ts

@@ -0,0 +1,20 @@
+export interface RegistryIssue {
+    severity: 'error' | 'warning';
+    message: string;
+    line: number;
+}
+export interface RegistryEntry {
+    name?: string;
+    repo?: string;
+    transport?: string;
+    install?: string;
+    run?: string;
+    tags?: string[];
+    permissions?: string[];
+    riskNotes?: string;
+    securityNotes?: string;
+    [key: string]: unknown;
+}
+export declare function parseRegistry(raw: string): RegistryEntry[];
+export declare function lintRegistry(raw: string): RegistryIssue[];
+export declare function verifyRegistry(raw: string, sample: number): RegistryIssue[];

package/dist/registry/validator.js

@@ -0,0 +1,98 @@
+import yaml from 'js-yaml';
+function lineOf(raw, needle, fromLine = 1) {
+    const lines = raw.split('\n');
+    for (let i = Math.max(0, fromLine - 1); i < lines.length; i += 1) {
+        if (lines[i].includes(needle))
+            return i + 1;
+    }
+    return 1;
+}
+export function parseRegistry(raw) {
+    const parsed = yaml.load(raw);
+    return (parsed?.servers ?? []);
+}
+function validRepo(value) {
+    if (!value.includes(' ')) {
+        if (value.startsWith('http://') || value.startsWith('https://')) {
+            return /^https?:\/\/[^\s]+$/.test(value);
+        }
+        return true;
+    }
+    return false;
+}
+export function lintRegistry(raw) {
+    const entries = parseRegistry(raw);
+    const issues = [];
+    const seenNames = new Set();
+    const allowedFields = new Set(['name', 'repo', 'transport', 'install', 'run', 'tags', 'permissions', 'riskNotes', 'securityNotes']);
+    entries.forEach((entry, index) => {
+        const anchor = `- name: ${entry.name ?? ''}`;
+        const baseLine = lineOf(raw, anchor);
+        const required = ['name', 'repo', 'transport', 'install', 'run', 'tags', 'permissions'];
+        for (const field of required) {
+            if (!entry[field] || (Array.isArray(entry[field]) && entry[field].length === 0)) {
+                issues.push({
+                    severity: 'error',
+                    message: `Entry #${index + 1} missing required field: ${field}`,
+                    line: lineOf(raw, `${String(field)}:`, baseLine)
+                });
+            }
+        }
+        if (typeof entry.name === 'string') {
+            if (seenNames.has(entry.name)) {
+                issues.push({
+                    severity: 'error',
+                    message: `Duplicate server name: ${entry.name}`,
+                    line: baseLine
+                });
+            }
+            seenNames.add(entry.name);
+        }
+        if (typeof entry.repo === 'string' && !validRepo(entry.repo)) {
+            issues.push({
+                severity: 'error',
+                message: `Entry #${index + 1} has invalid repo value: ${entry.repo}`,
+                line: lineOf(raw, 'repo:', baseLine)
+            });
+        }
+        for (const key of Object.keys(entry)) {
+            if (!allowedFields.has(key)) {
+                issues.push({
+                    severity: 'warning',
+                    message: `Entry #${index + 1} has unknown field: ${key}`,
+                    line: lineOf(raw, `${key}:`, baseLine)
+                });
+            }
+        }
+        if (entry.run && /(rm -rf|curl\s+.*\|\s*sh)/i.test(String(entry.run))) {
+            issues.push({
+                severity: 'warning',
+                message: `Entry #${index + 1} run command appears unsafe`,
+                line: lineOf(raw, 'run:', baseLine)
+            });
+        }
+    });
+    return issues;
+}
+export function verifyRegistry(raw, sample) {
+    const entries = parseRegistry(raw).slice(0, sample);
+    const issues = [];
+    entries.forEach((entry, index) => {
+        const baseLine = lineOf(raw, `- name: ${entry.name ?? ''}`);
+        if (!entry.riskNotes && !entry.securityNotes) {
+            issues.push({
+                severity: 'warning',
+                message: `Entry #${index + 1} should include riskNotes or securityNotes`,
+                line: baseLine
+            });
+        }
+        if (!entry.permissions || entry.permissions.length === 0) {
+            issues.push({
+                severity: 'warning',
+                message: `Entry #${index + 1} should declare permissions`,
+                line: lineOf(raw, 'permissions:', baseLine)
+            });
+        }
+    });
+    return issues;
+}

package/dist/report/json.d.ts

@@ -0,0 +1 @@
+export declare function writeJsonReport<T>(report: T, outDir: string, fileName?: string): Promise<string>;

package/dist/report/json.js

@@ -0,0 +1,8 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export async function writeJsonReport(report, outDir, fileName = 'report.json') {
+    await mkdir(outDir, { recursive: true });
+    const output = join(outDir, fileName);
+    await writeFile(output, JSON.stringify(report, null, 2), 'utf8');
+    return output;
+}

package/dist/report/markdown.d.ts

@@ -0,0 +1,2 @@
+import { Report } from '../mcp/types.js';
+export declare function writeMarkdownReport(report: Report, outDir: string, fileName?: string): Promise<string>;

package/dist/report/markdown.js

@@ -0,0 +1,61 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export async function writeMarkdownReport(report, outDir, fileName = 'report.md') {
+    await mkdir(outDir, { recursive: true });
+    const output = join(outDir, fileName);
+    const passedTests = report.tests.filter((t) => t.passed).length;
+    const passRate = report.tests.length === 0 ? 'n/a' : `${passedTests}/${report.tests.length}`;
+    const lines = [];
+    lines.push('# MCP Guard Report');
+    lines.push('');
+    lines.push('## Summary');
+    lines.push('');
+    lines.push(`- **Risk score:** ${report.score}/100`);
+    lines.push(`- **Key findings:** ${report.findings.length}`);
+    lines.push(`- **Contract tests:** ${passRate}`);
+    lines.push(`- **Generated:** ${report.generatedAt}`);
+    lines.push(`- **Target:** \`${report.server.target}\` (${report.server.transport})`);
+    lines.push('');
+    lines.push('## Tool Inventory');
+    lines.push('');
+    lines.push('| Name | Description |');
+    lines.push('| --- | --- |');
+    for (const tool of report.tools) {
+        lines.push(`| ${tool.name} | ${tool.description ?? ''} |`);
+    }
+    lines.push('');
+    lines.push('## Findings by Severity');
+    lines.push('');
+    for (const severity of ['high', 'medium', 'low']) {
+        const group = report.findings.filter((finding) => finding.severity === severity);
+        lines.push(`### ${severity.toUpperCase()} (${group.length})`);
+        if (group.length === 0) {
+            lines.push('- None');
+        }
+        else {
+            for (const finding of group) {
+                lines.push(`- **${finding.ruleId}**: ${finding.message}`);
+                lines.push(`  - Remediation: ${finding.remediation}`);
+            }
+        }
+        lines.push('');
+    }
+    lines.push('## Contract Test Results');
+    lines.push('');
+    for (const test of report.tests) {
+        lines.push(`- ${test.passed ? '✅' : '❌'} ${test.name} (${test.durationMs} ms): ${test.details ?? ''}`);
+    }
+    lines.push('');
+    lines.push('## Explain Score');
+    lines.push('');
+    if (report.scoreBreakdown.length === 0) {
+        lines.push('- No penalties applied.');
+    }
+    else {
+        for (const item of report.scoreBreakdown) {
+            lines.push(`- ${item}`);
+        }
+    }
+    await writeFile(output, `${lines.join('\n')}\n`, 'utf8');
+    return output;
+}

package/dist/report/sarif.d.ts

@@ -0,0 +1,2 @@
+import { Finding } from '../mcp/types.js';
+export declare function writeSarif(findings: Finding[], outputFile: string): Promise<void>;

package/dist/report/sarif.js

@@ -0,0 +1,33 @@
+import { writeFile } from 'node:fs/promises';
+function levelForSeverity(severity) {
+    if (severity === 'high')
+        return 'error';
+    if (severity === 'medium')
+        return 'warning';
+    return 'note';
+}
+export async function writeSarif(findings, outputFile) {
+    const sarif = {
+        version: '2.1.0',
+        $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'mcp-guard',
+                        rules: findings.map((finding) => ({
+                            id: finding.ruleId,
+                            shortDescription: { text: finding.message }
+                        }))
+                    }
+                },
+                results: findings.map((finding) => ({
+                    ruleId: finding.ruleId,
+                    level: levelForSeverity(finding.severity),
+                    message: { text: `${finding.message} Remediation: ${finding.remediation}` }
+                }))
+            }
+        ]
+    };
+    await writeFile(outputFile, JSON.stringify(sarif, null, 2), 'utf8');
+}

package/dist/scan/scanner.d.ts

@@ -0,0 +1,16 @@
+export interface DiscoveredServer {
+    source: 'claude_desktop' | 'cursor';
+    path: string;
+    name: string;
+    transport: 'stdio' | 'http' | 'unknown';
+    command?: string;
+    rawCommand?: string;
+    permissions?: string[];
+    reachable?: boolean;
+    findingsCount?: number;
+}
+export interface ScanResult {
+    scannedPaths: string[];
+    servers: DiscoveredServer[];
+}
+export declare function scanConfigs(repoPath?: string, directPath?: string): Promise<ScanResult>;

package/dist/scan/scanner.js

@@ -0,0 +1,86 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+const knownConfigNames = ['claude_desktop_config.json', 'claude_desktop_config.jsonc', 'cursor_mcp.json', '.cursor/mcp.json'];
+function sortServers(servers) {
+    return [...servers].sort((a, b) => {
+        const bySource = a.source.localeCompare(b.source);
+        if (bySource !== 0)
+            return bySource;
+        const byName = a.name.localeCompare(b.name);
+        if (byName !== 0)
+            return byName;
+        return a.path.localeCompare(b.path);
+    });
+}
+function stripComments(content) {
+    return content.replace(/^\s*\/\/.*$/gm, '');
+}
+function redact(text) {
+    return text
+        .replace(/(token|api[_-]?key|secret)\s*[:=]\s*["']?[^\s"',}]+/gi, '$1=<redacted>')
+        .replace(/Bearer\s+[A-Za-z0-9._-]+/g, 'Bearer <redacted>');
+}
+function detectTransport(server) {
+    if (typeof server.command === 'string')
+        return 'stdio';
+    if (typeof server.url === 'string' || typeof server.httpUrl === 'string')
+        return 'http';
+    return 'unknown';
+}
+function extractServers(raw, source, path) {
+    const content = stripComments(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        return [];
+    }
+    const mcpServers = (parsed.mcpServers ?? parsed.servers ?? {});
+    return Object.entries(mcpServers).map(([name, value]) => ({
+        source,
+        path,
+        name,
+        transport: detectTransport(value),
+        rawCommand: typeof value.command === 'string' ? String(value.command) : undefined,
+        command: typeof value.command === 'string' ? redact(value.command) : undefined,
+        permissions: Array.isArray(value.permissions) ? value.permissions.map((p) => redact(String(p))) : []
+    }));
+}
+export async function scanConfigs(repoPath, directPath) {
+    const scannedPaths = [];
+    const servers = [];
+    if (directPath) {
+        const absolute = resolve(directPath);
+        const raw = await readFile(absolute, 'utf8');
+        scannedPaths.push(absolute);
+        const source = absolute.toLowerCase().includes('cursor') ? 'cursor' : 'claude_desktop';
+        servers.push(...extractServers(raw, source, absolute));
+        return { scannedPaths: [...scannedPaths].sort(), servers: sortServers(servers) };
+    }
+    if (!repoPath) {
+        return { scannedPaths: [...scannedPaths].sort(), servers: sortServers(servers) };
+    }
+    const root = resolve(repoPath);
+    const queue = [root];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const entries = await readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === 'node_modules' || entry.name === '.git')
+                    continue;
+                queue.push(fullPath);
+                continue;
+            }
+            if (knownConfigNames.some((name) => fullPath.endsWith(name))) {
+                const raw = await readFile(fullPath, 'utf8');
+                scannedPaths.push(fullPath);
+                const source = fullPath.toLowerCase().includes('cursor') ? 'cursor' : 'claude_desktop';
+                servers.push(...extractServers(raw, source, fullPath));
+            }
+        }
+    }
+    return { scannedPaths: [...scannedPaths].sort(), servers: sortServers(servers) };
+}

package/dist/security/profiles.d.ts

@@ -0,0 +1,6 @@
+import { Finding, Profile } from '../mcp/types.js';
+export declare function scoreFindings(findings: Finding[], profile: Profile): {
+    score: number;
+    breakdown: string[];
+};
+export declare function tuneFindingsForProfile(findings: Finding[], profile: Profile): Finding[];

package/dist/security/profiles.js

@@ -0,0 +1,25 @@
+const severityPenaltyByProfile = {
+    default: { low: 5, medium: 12, high: 25 },
+    strict: { low: 8, medium: 15, high: 28 },
+    paranoid: { low: 10, medium: 20, high: 40 }
+};
+export function scoreFindings(findings, profile) {
+    const weights = severityPenaltyByProfile[profile];
+    const penalties = findings.map((finding) => `${finding.ruleId} (${finding.severity}) -${weights[finding.severity]}`);
+    const total = findings.reduce((sum, finding) => sum + weights[finding.severity], 0);
+    return {
+        score: Math.max(0, 100 - total),
+        breakdown: penalties
+    };
+}
+export function tuneFindingsForProfile(findings, profile) {
+    if (profile === 'paranoid') {
+        return findings.map((finding) => {
+            if (finding.ruleId === 'security.shell_injection' || finding.ruleId === 'security.raw_args') {
+                return { ...finding, severity: 'high' };
+            }
+            return finding;
+        });
+    }
+    return findings;
+}

package/dist/security/rules/path_traversal.d.ts

@@ -0,0 +1,2 @@
+import { Finding, ToolDescriptor } from '../../mcp/types.js';
+export declare function pathTraversalRule(tools: ToolDescriptor[]): Finding[];

package/dist/security/rules/path_traversal.js

@@ -0,0 +1,24 @@
+export function pathTraversalRule(tools) {
+    const findings = [];
+    for (const tool of tools) {
+        const schema = tool.inputSchema;
+        const properties = (schema.properties ?? {});
+        for (const [name, value] of Object.entries(properties)) {
+            if (!/(path|file)/i.test(name))
+                continue;
+            const prop = (value ?? {});
+            const hasConstraint = 'pattern' in prop || 'enum' in prop;
+            if (!hasConstraint) {
+                findings.push({
+                    severity: 'high',
+                    ruleId: 'security.path_traversal',
+                    message: `Path-like parameter ${name} on tool ${tool.name} lacks constraints`,
+                    evidence: JSON.stringify(prop),
+                    remediation: 'Add strict pattern (allowlist base path) or enum constraints.',
+                    toolName: tool.name
+                });
+            }
+        }
+    }
+    return findings;
+}

package/dist/security/rules/raw_args.d.ts

@@ -0,0 +1,2 @@
+import { Finding, ToolDescriptor } from '../../mcp/types.js';
+export declare function rawArgsRule(tools: ToolDescriptor[]): Finding[];

package/dist/security/rules/raw_args.js

@@ -0,0 +1,24 @@
+export function rawArgsRule(tools) {
+    const findings = [];
+    for (const tool of tools) {
+        const schema = tool.inputSchema;
+        const properties = (schema.properties ?? {});
+        for (const [name, value] of Object.entries(properties)) {
+            if (!/(argv|flags)/i.test(name))
+                continue;
+            const prop = (value ?? {});
+            const items = (prop.items ?? {});
+            if (prop.type === 'array' && items.type === 'string' && !('enum' in items) && !('maxItems' in prop)) {
+                findings.push({
+                    severity: 'medium',
+                    ruleId: 'security.raw_args',
+                    message: `Raw CLI args array ${name} on tool ${tool.name} is unbounded`,
+                    evidence: JSON.stringify(prop),
+                    remediation: 'Constrain allowed values and maxItems for argv/flags arrays.',
+                    toolName: tool.name
+                });
+            }
+        }
+    }
+    return findings;
+}

package/dist/security/rules/shell_injection.d.ts

@@ -0,0 +1,2 @@
+import { Finding, ToolDescriptor } from '../../mcp/types.js';
+export declare function shellInjectionRule(tools: ToolDescriptor[]): Finding[];

package/dist/security/rules/shell_injection.js

@@ -0,0 +1,23 @@
+export function shellInjectionRule(tools) {
+    const findings = [];
+    for (const tool of tools) {
+        const schema = tool.inputSchema;
+        const properties = (schema.properties ?? {});
+        for (const [name, value] of Object.entries(properties)) {
+            if (!/(args|command|shell)/i.test(name))
+                continue;
+            const prop = (value ?? {});
+            if (prop.type === 'string' && !('enum' in prop)) {
+                findings.push({
+                    severity: 'high',
+                    ruleId: 'security.shell_injection',
+                    message: `Potential command injection param ${name} on tool ${tool.name}`,
+                    evidence: JSON.stringify(prop),
+                    remediation: 'Use enum allowlists and never pass through raw shell commands.',
+                    toolName: tool.name
+                });
+            }
+        }
+    }
+    return findings;
+}

package/dist/security/scorer.d.ts

@@ -0,0 +1,5 @@
+import { Finding, Profile } from '../mcp/types.js';
+export declare function computeRiskScore(findings: Finding[], profile: Profile): {
+    score: number;
+    breakdown: string[];
+};

package/dist/security/scorer.js

@@ -0,0 +1,4 @@
+import { scoreFindings } from './profiles.js';
+export function computeRiskScore(findings, profile) {
+    return scoreFindings(findings, profile);
+}

package/dist/tests/contract/call_tool.d.ts

@@ -0,0 +1,2 @@
+import { RpcClient, TestResult } from '../../mcp/types.js';
+export declare function runCallToolTest(client: RpcClient): Promise<TestResult>;

package/dist/tests/contract/call_tool.js

@@ -0,0 +1,14 @@
+export async function runCallToolTest(client) {
+    const start = Date.now();
+    const response = await client.request('tools/call', {
+        name: 'hello',
+        arguments: { name: 'guard' }
+    });
+    const passed = typeof response.content === 'string' && response.content.includes('guard');
+    return {
+        name: 'call_tool',
+        passed,
+        durationMs: Date.now() - start,
+        details: passed ? response.content : 'Unexpected response format'
+    };
+}

package/dist/tests/contract/cancellation.d.ts

@@ -0,0 +1,2 @@
+import { RpcClient, TestResult } from '../../mcp/types.js';
+export declare function runCancellationTest(client: RpcClient): Promise<TestResult>;

package/dist/tests/contract/cancellation.js

@@ -0,0 +1,22 @@
+export async function runCancellationTest(client) {
+    const start = Date.now();
+    try {
+        const result = await client.request('tools/cancel', { requestId: 42 });
+        return {
+            name: 'cancellation_behavior',
+            passed: result.status === 'cancelled',
+            durationMs: Date.now() - start,
+            details: JSON.stringify(result)
+        };
+    }
+    catch (error) {
+        const normalized = client.normalizeError(error);
+        const isNotSupported = normalized.code === -32601 || /not supported/i.test(normalized.message);
+        return {
+            name: 'cancellation_behavior',
+            passed: isNotSupported,
+            durationMs: Date.now() - start,
+            details: isNotSupported ? 'Cancellation not supported by fixture server (accepted)' : JSON.stringify(normalized)
+        };
+    }
+}

package/dist/tests/contract/error_shapes.d.ts

@@ -0,0 +1,2 @@
+import { RpcClient, TestResult } from '../../mcp/types.js';
+export declare function runErrorShapesTest(client: RpcClient): Promise<TestResult>;

package/dist/tests/contract/error_shapes.js

@@ -0,0 +1,25 @@
+export async function runErrorShapesTest(client) {
+    const start = Date.now();
+    try {
+        await client.request('tools/call', {
+            name: 'hello',
+            arguments: {}
+        });
+        return {
+            name: 'error_shapes',
+            passed: false,
+            durationMs: Date.now() - start,
+            details: 'Expected an error but call succeeded'
+        };
+    }
+    catch (error) {
+        const normalized = client.normalizeError(error);
+        const passed = Number.isInteger(normalized.code) && typeof normalized.message === 'string';
+        return {
+            name: 'error_shapes',
+            passed,
+            durationMs: Date.now() - start,
+            details: JSON.stringify(normalized)
+        };
+    }
+}

package/dist/tests/contract/large_payload.d.ts

@@ -0,0 +1,2 @@
+import { RpcClient, TestResult } from '../../mcp/types.js';
+export declare function runLargePayloadTest(client: RpcClient): Promise<TestResult>;

package/dist/tests/contract/large_payload.js

@@ -0,0 +1,15 @@
+export async function runLargePayloadTest(client) {
+    const start = Date.now();
+    const text = 'x'.repeat(50_000);
+    const response = await client.request('tools/call', {
+        name: 'echo',
+        arguments: { text }
+    }, 3000);
+    const passed = response.content.length === text.length;
+    return {
+        name: 'large_payload',
+        passed,
+        durationMs: Date.now() - start,
+        details: `echoed_length=${response.content.length}`
+    };
+}

package/dist/tests/contract/list_tools.d.ts

@@ -0,0 +1,5 @@
+import { RpcClient, ToolDescriptor, TestResult } from '../../mcp/types.js';
+export declare function runListToolsTest(client: RpcClient): Promise<{
+    result: TestResult;
+    tools: ToolDescriptor[];
+}>;