contextguard 0.1.8 → 0.2.1

package/dist/agent.js

@@ -0,0 +1,376 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Amir Mironi
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgent = void 0;
+const child_process_1 = require("child_process");
+const policy_1 = require("./policy");
+const logger_1 = require("./logger");
+const supabase_client_1 = require("./lib/supabase-client");
+const mcp_1 = require("./types/mcp");
+/**
+ * Merge policy with defaults
+ */
+const mergePolicyWithDefaults = (policy) => ({
+    ...policy_1.DEFAULT_POLICY,
+    ...policy,
+});
+/**
+ * Create an MCP security agent
+ * @param serverCommand - Command to start MCP server
+ * @param policyConfig - Policy configuration
+ * @param supabaseConfig - Optional Supabase configuration
+ * @returns Agent functions
+ */
+const createAgent = (serverCommand, policyConfig = {}, supabaseConfig) => {
+    const config = mergePolicyWithDefaults(policyConfig);
+    const policy = (0, policy_1.createPolicyChecker)(config);
+    // Create Supabase client if config provided
+    const supabaseClient = supabaseConfig
+        ? (0, supabase_client_1.createSupabaseClient)(supabaseConfig)
+        : undefined;
+    const logger = (0, logger_1.createLogger)(config.logPath, supabaseClient, supabaseConfig?.agentId, config.alertWebhook, config.alertOnSeverity);
+    const sessionId = (0, mcp_1.generateSessionId)();
+    const state = {
+        process: null,
+        toolCallTimestamps: [],
+        clientMessageBuffer: "",
+        serverMessageBuffer: "",
+    };
+    /**
+     * Extract file paths from message parameters
+     */
+    const extractFilePaths = (message) => [
+        message.params?.arguments?.path,
+        message.params?.arguments?.filePath,
+        message.params?.arguments?.file,
+        message.params?.arguments?.directory,
+        message.params?.path,
+        message.params?.filePath,
+    ].filter((path) => typeof path === "string");
+    /**
+     * Handle tool call with security checks
+     */
+    const handleToolCall = (message) => {
+        const violations = [];
+        let shouldBlock = false;
+        // Rate limiting
+        const now = Date.now();
+        state.toolCallTimestamps.push(now);
+        // Clean up old timestamps
+        const oneMinuteAgo = now - 60000;
+        state.toolCallTimestamps = state.toolCallTimestamps.filter((t) => t > oneMinuteAgo);
+        if (!policy.checkRateLimit(state.toolCallTimestamps)) {
+            violations.push("Rate limit exceeded for tool calls");
+            shouldBlock = policy.isBlockingMode();
+            logger.logEvent("RATE_LIMIT_EXCEEDED", "HIGH", {
+                method: message.method,
+                toolName: message.params?.name,
+            }, sessionId);
+        }
+        // Check tool allowlist / blocklist
+        if (message.params?.name) {
+            violations.push(...policy.checkToolAccess(message.params.name));
+        }
+        // Check parameters for security issues
+        const paramsStr = JSON.stringify(message.params);
+        violations.push(...policy.checkPromptInjection(paramsStr));
+        violations.push(...policy.checkSensitiveData(paramsStr));
+        violations.push(...policy.checkBlockedPatterns(paramsStr));
+        violations.push(...policy.checkSQLInjection(paramsStr));
+        violations.push(...policy.checkXSS(paramsStr));
+        violations.push(...policy.checkCustomRules(paramsStr));
+        // Check file paths
+        const filePathParams = extractFilePaths(message);
+        for (const filePath of filePathParams) {
+            violations.push(...policy.checkFileAccess(filePath));
+        }
+        // Log tool call
+        logger.logEvent("TOOL_CALL", violations.length > 0 ? "HIGH" : "LOW", {
+            toolName: message.params?.name,
+            hasViolations: violations.length > 0,
+            violations,
+        }, sessionId);
+        // In blocking mode, any violation blocks
+        if (violations.length > 0 && policy.isBlockingMode()) {
+            shouldBlock = true;
+        }
+        return { violations, shouldBlock };
+    };
+    /**
+     * Handle security violations
+     */
+    const handleViolations = (message, violations, shouldBlock) => {
+        logger.logEvent("SECURITY_VIOLATION", "CRITICAL", {
+            violations,
+            message,
+            blocked: shouldBlock,
+        }, sessionId);
+        console.error(`\n⚠️  SECURITY VIOLATIONS DETECTED:\n${violations.join("\n")}\n`);
+        if (shouldBlock) {
+            console.error("🚫 REQUEST BLOCKED\n");
+            // Send error response
+            if (message.id !== undefined) {
+                const errorResponse = {
+                    jsonrpc: message.jsonrpc,
+                    id: message.id,
+                    error: {
+                        code: -32000,
+                        message: "Security violation: Request blocked",
+                        data: { violations },
+                    },
+                };
+                process.stdout.write(JSON.stringify(errorResponse) + "\n");
+            }
+        }
+        else {
+            // Monitor mode: log and warn but still forward
+            console.error('⚠️  MONITOR MODE — request forwarded (set mode: "block" to block)\n');
+        }
+    };
+    /**
+     * Handle parse errors
+     */
+    const handleParseError = (err, line) => {
+        logger.logEvent("PARSE_ERROR", "MEDIUM", {
+            error: err instanceof Error ? err.message : String(err),
+            line: line.substring(0, 100),
+        }, sessionId);
+        console.error(`Failed to parse client message: ${err}`);
+    };
+    /**
+     * Handle sensitive data leak in server response
+     */
+    const handleSensitiveDataLeak = (message, violations) => {
+        logger.logEvent("SENSITIVE_DATA_LEAK", "CRITICAL", {
+            violations,
+            responseId: message.id,
+            blocked: policy.isBlockingMode(),
+        }, sessionId);
+        console.error(`\n🚨 SENSITIVE DATA DETECTED IN RESPONSE:\n${violations.join("\n")}\n`);
+        if (policy.isBlockingMode()) {
+            console.error("🚫 RESPONSE BLOCKED\n");
+            // Send sanitized error response
+            if (message.id !== undefined) {
+                const errorResponse = {
+                    jsonrpc: message.jsonrpc,
+                    id: message.id,
+                    error: {
+                        code: -32001,
+                        message: "Security violation: Response contains sensitive data",
+                        data: { violations },
+                    },
+                };
+                process.stdout.write(JSON.stringify(errorResponse) + "\n");
+            }
+            return false; // Don't forward
+        }
+        else {
+            console.error("⚠️  MONITOR MODE — response forwarded\n");
+            return true; // Forward anyway
+        }
+    };
+    /**
+     * Process a single client message
+     */
+    const processClientMessage = (line) => {
+        try {
+            const message = JSON.parse(line);
+            logger.logEvent("CLIENT_REQUEST", "LOW", {
+                method: message.method,
+                id: message.id,
+            }, sessionId);
+            const violations = [];
+            let shouldBlock = false;
+            // Handle tool calls with security checks
+            if (message.method === "tools/call") {
+                const result = handleToolCall(message);
+                violations.push(...result.violations);
+                shouldBlock = result.shouldBlock;
+            }
+            // Handle violations
+            if (violations.length > 0) {
+                handleViolations(message, violations, shouldBlock);
+                if (shouldBlock) {
+                    return; // Don't forward blocked requests
+                }
+            }
+            // Forward to server
+            if (state.process?.stdin) {
+                state.process.stdin.write(line + "\n");
+            }
+        }
+        catch (err) {
+            handleParseError(err, line);
+            // Forward unparseable messages
+            if (state.process?.stdin) {
+                state.process.stdin.write(line + "\n");
+            }
+        }
+    };
+    /**
+     * Handle client input (buffered line-by-line)
+     */
+    const handleClientInput = (input) => {
+        state.clientMessageBuffer += input;
+        const lines = state.clientMessageBuffer.split("\n");
+        state.clientMessageBuffer = lines.pop() || "";
+        for (const line of lines) {
+            if (line.trim()) {
+                processClientMessage(line);
+            }
+        }
+    };
+    /**
+     * Process a single server message
+     */
+    const processServerMessage = (line) => {
+        let shouldForward = true;
+        try {
+            const message = JSON.parse(line);
+            // Check for sensitive data in response
+            const violations = [];
+            const responseStr = JSON.stringify(message.result || message);
+            violations.push(...policy.checkSensitiveData(responseStr));
+            if (violations.length > 0) {
+                shouldForward = handleSensitiveDataLeak(message, violations);
+            }
+            else {
+                logger.logEvent("SERVER_RESPONSE", "LOW", {
+                    id: message.id,
+                    hasError: !!message.error,
+                }, sessionId);
+            }
+        }
+        catch (err) {
+            // Log parse errors for server output
+            logger.logEvent("SERVER_PARSE_ERROR", "LOW", {
+                error: err instanceof Error ? err.message : String(err),
+                line: line.substring(0, 100),
+            }, sessionId);
+        }
+        // Forward the line if not blocked
+        if (shouldForward) {
+            process.stdout.write(line + "\n");
+        }
+    };
+    /**
+     * Handle server output (buffered line-by-line)
+     */
+    const handleServerOutput = (output) => {
+        state.serverMessageBuffer += output;
+        const lines = state.serverMessageBuffer.split("\n");
+        state.serverMessageBuffer = lines.pop() || "";
+        for (const line of lines) {
+            if (line.trim()) {
+                processServerMessage(line);
+            }
+        }
+    };
+    /**
+     * Handle process exit
+     */
+    const handleProcessExit = (code) => {
+        logger.logEvent("SERVER_EXIT", "MEDIUM", { exitCode: code }, sessionId);
+        console.error("\n=== MCP Security Statistics ===");
+        console.error(JSON.stringify(logger.getStatistics(), null, 2));
+        const finish = () => setImmediate(() => process.exit(code || 0));
+        if (supabaseClient && supabaseConfig?.agentId) {
+            supabaseClient
+                .updateAgentStatus(supabaseConfig.agentId, "offline")
+                .catch(() => { })
+                .finally(finish);
+        }
+        else {
+            finish();
+        }
+    };
+    return {
+        /**
+         * Start the MCP server wrapper
+         */
+        start: async () => {
+            // Fetch policy from Supabase if configured
+            if (supabaseClient && supabaseConfig?.agentId) {
+                try {
+                    const remotePolicy = await supabaseClient.fetchPolicy(supabaseConfig.agentId);
+                    if (remotePolicy) {
+                        console.log("✓ Loaded policy from Supabase");
+                        // Merge remote policy with local config
+                        Object.assign(config, remotePolicy);
+                    }
+                }
+                catch (error) {
+                    console.warn("⚠ Failed to fetch policy from Supabase:", error);
+                }
+                // Update agent status to online
+                await supabaseClient.updateAgentStatus(supabaseConfig.agentId, "online");
+                // Send periodic heartbeats every 30 seconds
+                const heartbeatInterval = setInterval(() => {
+                    supabaseClient
+                        .updateAgentStatus(supabaseConfig.agentId, "online")
+                        .catch(() => { });
+                }, 30000);
+                heartbeatInterval.unref();
+            }
+            state.process = (0, child_process_1.spawn)(serverCommand[0], serverCommand.slice(1), {
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            if (!state.process.stdout ||
+                !state.process.stdin ||
+                !state.process.stderr) {
+                throw new Error("Failed to create child process streams");
+            }
+            logger.logEvent("SERVER_START", "LOW", {
+                command: serverCommand.join(" "),
+                pid: state.process.pid,
+            }, sessionId);
+            // Pipe stderr to parent process
+            state.process.stderr.pipe(process.stderr);
+            // Handle server output
+            state.process.stdout.on("data", (data) => {
+                handleServerOutput(data.toString());
+            });
+            // Handle client input
+            process.stdin.on("data", (data) => {
+                handleClientInput(data.toString());
+            });
+            // Handle process exit
+            state.process.on("exit", (code) => {
+                handleProcessExit(code);
+            });
+            // Handle process errors
+            state.process.on("error", (err) => {
+                logger.logEvent("SERVER_ERROR", "HIGH", { error: err.message }, sessionId);
+                console.error("Server process error:", err);
+            });
+            // Graceful shutdown on SIGTERM/SIGINT
+            const shutdown = (signal) => {
+                logger.logEvent("AGENT_SHUTDOWN", "MEDIUM", { signal }, sessionId);
+                if (state.process)
+                    state.process.kill();
+                const finish = () => process.exit(0);
+                if (supabaseClient && supabaseConfig?.agentId) {
+                    supabaseClient
+                        .updateAgentStatus(supabaseConfig.agentId, "offline")
+                        .catch(() => { })
+                        .finally(finish);
+                }
+                else {
+                    finish();
+                }
+            };
+            process.on("SIGTERM", () => shutdown("SIGTERM"));
+            process.on("SIGINT", () => shutdown("SIGINT"));
+        },
+        /**
+         * Get the security logger instance
+         */
+        getLogger: () => logger,
+    };
+};
+exports.createAgent = createAgent;

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2026 Amir Mironi
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Main CLI entry point
+ */
+export declare function main(): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Copyright (c) 2026 Amir Mironi
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const agent_1 = require("./agent");
+const sse_proxy_1 = require("./sse-proxy");
+const policy_1 = require("./policy");
+const init_1 = require("./init");
+/**
+ * Display help message
+ */
+function showHelp() {
+    console.log(`
+MCP Security Wrapper - ContextGuard
+
+Usage:
+  # Auto-patch Claude Desktop config (recommended)
+  contextguard init --api-key <key>
+
+  # stdio transport (Claude Desktop)
+  contextguard --server "node server.js" --config config.json
+
+  # SSE/HTTP transport proxy
+  contextguard --transport sse --port 3100 --target http://localhost:3000 --config config.json
+
+Commands:
+  init                  Auto-patch claude_desktop_config.json
+
+Init options:
+  --api-key <key>       Your ContextGuard API key (required)
+  --config <file>       Path to claude_desktop_config.json (auto-detected if omitted)
+  --dry-run             Preview changes without writing
+
+Options:
+  --server <cmd>        Command to start MCP server (stdio mode)
+  --transport <type>    stdio | sse | http  (default: stdio)
+  --port <n>            Proxy listen port   (SSE/HTTP mode, default: 3100)
+  --target <url>        Upstream server URL (SSE/HTTP mode)
+  --config <file>       Path to security config JSON (optional)
+  --help                Show this help
+
+Configuration File Format (JSON):
+  {
+    "mode": "monitor",                          // "monitor" (log only) | "block" (block + log)
+    "maxToolCallsPerMinute": 30,
+    "enablePromptInjectionDetection": true,
+    "enableSensitiveDataDetection": true,
+    "enablePathTraversalPrevention": true,
+    "enableSQLInjectionDetection": true,
+    "enableXSSDetection": true,
+    "enableSemanticDetection": false,
+    "blockedPatterns": ["ignore previous", "system prompt"],
+    "allowedFilePaths": ["/safe/path"],
+    "allowedTools": [],
+    "blockedTools": [],
+    "customRules": [{ "name": "my-rule", "pattern": "\\bforbidden\\b" }],
+    "alertWebhook": "https://hooks.example.com/alert",
+    "alertOnSeverity": ["HIGH", "CRITICAL"],
+    "logPath": "mcp_security.log"
+  }
+
+For more information, visit: https://contextguard.dev
+  `);
+}
+/**
+ * Parse command line arguments
+ * @returns Parsed arguments
+ */
+function parseArgs() {
+    const args = process.argv.slice(2);
+    let serverCommand = "";
+    let configFile = "";
+    let transport = "stdio";
+    let port = 3100;
+    let targetUrl = "";
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--server" && args[i + 1]) {
+            serverCommand = args[i + 1];
+            i++;
+        }
+        else if (args[i] === "--config" && args[i + 1]) {
+            configFile = args[i + 1];
+            i++;
+        }
+        else if (args[i] === "--transport" && args[i + 1]) {
+            transport = args[i + 1];
+            i++;
+        }
+        else if (args[i] === "--port" && args[i + 1]) {
+            port = parseInt(args[i + 1], 10);
+            i++;
+        }
+        else if (args[i] === "--target" && args[i + 1]) {
+            targetUrl = args[i + 1];
+            i++;
+        }
+    }
+    return { serverCommand, configFile, transport, port, targetUrl };
+}
+/**
+ * Parse a shell command string into an array of arguments,
+ * respecting single and double quoted strings.
+ */
+function parseCommand(cmd) {
+    const tokens = [];
+    let current = "";
+    let inQuote = "";
+    for (const char of cmd) {
+        if (inQuote) {
+            if (char === inQuote)
+                inQuote = "";
+            else
+                current += char;
+        }
+        else if (char === '"' || char === "'") {
+            inQuote = char;
+        }
+        else if (char === " ") {
+            if (current) {
+                tokens.push(current);
+                current = "";
+            }
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current)
+        tokens.push(current);
+    return tokens;
+}
+/**
+ * Load configuration from file
+ * @param configFile - Path to config file
+ * @returns Security configuration
+ */
+function loadConfig(configFile) {
+    if (!fs.existsSync(configFile)) {
+        console.error(`Error: Config file not found: ${configFile}`);
+        process.exit(1);
+    }
+    try {
+        const config = JSON.parse(fs.readFileSync(configFile, "utf-8"));
+        // validateConfig(config);
+        return config;
+    }
+    catch (error) {
+        console.error(`Error: Failed to load config file: ${error}`);
+        process.exit(1);
+    }
+    // TypeScript doesn't know process.exit() never returns
+    return {};
+}
+/**
+ * Main CLI entry point
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    // Show help if requested or no args
+    if (args.length === 0 || args.includes("--help")) {
+        showHelp();
+        process.exit(0);
+    }
+    // init subcommand — auto-patch claude_desktop_config.json
+    if (args[0] === "init") {
+        await (0, init_1.runInit)(args.slice(1));
+        return;
+    }
+    // Parse arguments
+    const { serverCommand, configFile, transport, port, targetUrl } = parseArgs();
+    // Load configuration
+    let config = {};
+    if (configFile) {
+        config = loadConfig(configFile);
+    }
+    // Merge with defaults
+    const fullConfig = { ...policy_1.DEFAULT_POLICY, ...config };
+    // CLI flags override config file
+    if (transport !== "stdio") {
+        fullConfig.transport = transport;
+    }
+    if (port !== 3100) {
+        fullConfig.port = port;
+    }
+    if (targetUrl) {
+        fullConfig.targetUrl = targetUrl;
+    }
+    const effectiveTransport = fullConfig.transport || "stdio";
+    // SSE/HTTP transport mode
+    if (effectiveTransport === "sse" || effectiveTransport === "http") {
+        if (!fullConfig.targetUrl && !targetUrl) {
+            console.error("Error: --target <url> is required for SSE/HTTP transport");
+            process.exit(1);
+        }
+        const proxy = (0, sse_proxy_1.createSSEProxy)(fullConfig);
+        proxy.start(fullConfig.port || 3100, fullConfig.targetUrl || targetUrl);
+        return;
+    }
+    // stdio transport mode
+    if (!serverCommand) {
+        console.error("Error: --server argument is required for stdio transport");
+        console.error("Run 'contextguard --help' for usage information");
+        process.exit(1);
+    }
+    // Load Supabase configuration from environment
+    const supabaseConfig = process.env.SUPABASE_URL && process.env.SUPABASE_SERVICE_KEY
+        ? {
+            url: process.env.SUPABASE_URL,
+            serviceKey: process.env.SUPABASE_SERVICE_KEY,
+            agentId: process.env.AGENT_ID || "default-agent",
+        }
+        : undefined;
+    if (supabaseConfig) {
+        console.log(`✓ Supabase integration enabled (Agent ID: ${supabaseConfig.agentId})`);
+    }
+    // Start REST-based heartbeat if CONTEXTGUARD_API_KEY is set
+    const cgApiKey = process.env.CONTEXTGUARD_API_KEY;
+    if (cgApiKey) {
+        const baseUrl = process.env.CONTEXTGUARD_BASE_URL || "https://contextguard.dev";
+        const agentId = process.env.AGENT_ID || `${os.hostname()}-${process.pid}`;
+        const sendHeartbeat = async () => {
+            try {
+                await fetch(`${baseUrl}/api/agents/heartbeat`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        Authorization: `Bearer ${cgApiKey}`,
+                    },
+                    body: JSON.stringify({
+                        agent_id: agentId,
+                        name: agentId,
+                        hostname: os.hostname(),
+                        version: process.env.npm_package_version || "unknown",
+                        mcp_server_command: serverCommand,
+                    }),
+                });
+            }
+            catch {
+                // silently ignore — don't break the agent if dashboard is unreachable
+            }
+        };
+        sendHeartbeat();
+        const interval = setInterval(sendHeartbeat, 30000);
+        interval.unref();
+        console.log(`✓ ContextGuard monitoring enabled (Agent ID: ${agentId})`);
+    }
+    // Create and start agent
+    const agent = (0, agent_1.createAgent)(parseCommand(serverCommand), config, supabaseConfig);
+    await agent.start();
+}
+// Run CLI if this is the main module
+if (require.main === module) {
+    main().catch((err) => {
+        console.error("Fatal error:", err);
+        process.exit(1);
+    });
+}