contextguard 0.1.7 → 0.2.0

package/dist/types/types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Copyright (c) 2025 Amir Mironi
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Re-export AgentPolicy from database types
+ */
+export type { AgentPolicy } from "./database.types";
+/**
+ * Security event severity levels
+ */
+export type SecuritySeverity = "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+/**
+ * Security event logged by the system
+ */
+export interface SecurityEvent {
+    /** ISO timestamp of the event */
+    timestamp: string;
+    /** Type of security event */
+    eventType: string;
+    /** Severity level */
+    severity: SecuritySeverity;
+    /** Additional event details */
+    details: Record<string, unknown>;
+    /** Session identifier */
+    sessionId: string;
+}
+/**
+ * MCP JSON-RPC message structure
+ */
+export interface MCPMessage {
+    /** JSON-RPC version */
+    jsonrpc: string;
+    /** Request/response ID */
+    id?: string | number;
+    /** Method name for requests */
+    method?: string;
+    /** Method parameters */
+    params?: {
+        name?: string;
+        arguments?: Record<string, string>;
+        path?: string;
+        filePath?: string;
+        [key: string]: unknown;
+    };
+    /** Response result */
+    result?: unknown;
+    /** Error object */
+    error?: unknown;
+}
+/**
+ * Statistics about security events
+ */
+export interface SecurityStatistics {
+    /** Total number of events logged */
+    totalEvents: number;
+    /** Events grouped by type */
+    eventsByType: Record<string, number>;
+    /** Events grouped by severity */
+    eventsBySeverity: Record<string, number>;
+    /** Most recent events */
+    recentEvents: SecurityEvent[];
+}

package/dist/types/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Copyright (c) 2025 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 });

package/dist/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Copyright (c) 2025 Amir Mironi
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Security configuration options for the MCP wrapper
+ */
+export interface CgPolicyType {
+    /** Maximum number of tool calls allowed per minute (default: 30) */
+    maxToolCallsPerMinute?: number;
+    /** Patterns to block in tool calls */
+    blockedPatterns?: string[];
+    /** Allowed file paths for file operations (empty = all allowed) */
+    allowedFilePaths?: string[];
+    /** Number of violations before triggering alerts (default: 5) */
+    alertThreshold?: number;
+    /** Enable prompt injection detection (default: true) */
+    enablePromptInjectionDetection?: boolean;
+    /** Enable sensitive data detection (default: true) */
+    enableSensitiveDataDetection?: boolean;
+    /** Path to security log file */
+    logPath?: string;
+    /** Enable pro features (requires license) */
+    enableProFeatures?: boolean;
+    /** License file path for pro features */
+    licenseFilePath?: string;
+}
+/**
+ * Security event severity levels
+ */
+export type SecuritySeverity = "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+/**
+ * Security event logged by the system
+ */
+export interface SecurityEvent {
+    /** ISO timestamp of the event */
+    timestamp: string;
+    /** Type of security event */
+    eventType: string;
+    /** Severity level */
+    severity: SecuritySeverity;
+    /** Additional event details */
+    details: Record<string, unknown>;
+    /** Session identifier */
+    sessionId: string;
+}
+/**
+ * MCP JSON-RPC message structure
+ */
+export interface MCPMessage {
+    /** JSON-RPC version */
+    jsonrpc: string;
+    /** Request/response ID */
+    id?: string | number;
+    /** Method name for requests */
+    method?: string;
+    /** Method parameters */
+    params?: {
+        name?: string;
+        arguments?: Record<string, string>;
+        path?: string;
+        filePath?: string;
+        [key: string]: unknown;
+    };
+    /** Response result */
+    result?: unknown;
+    /** Error object */
+    error?: unknown;
+}
+/**
+ * Statistics about security events
+ */
+export interface SecurityStatistics {
+    /** Total number of events logged */
+    totalEvents: number;
+    /** Events grouped by type */
+    eventsByType: Record<string, number>;
+    /** Events grouped by severity */
+    eventsBySeverity: Record<string, number>;
+    /** Most recent events */
+    recentEvents: SecurityEvent[];
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Copyright (c) 2025 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 });

package/dist/wrapper.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Copyright (c) 2025 Amir Mironi
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { SecurityConfig } from "./types";
+import { SecurityLogger } from "./security-logger";
+import { MCPTraceabilityManager } from "./premium-features";
+/**
+ * MCP Security Wrapper
+ * Wraps MCP servers with security monitoring and optional pro features
+ */
+export declare class MCPSecurityWrapper {
+    private serverCommand;
+    private policy;
+    private logger;
+    private process;
+    private toolCallTimestamps;
+    private sessionId;
+    private clientMessageBuffer;
+    private serverMessageBuffer;
+    private licenseManager?;
+    private traceabilityManager?;
+    private contextTracker?;
+    private proFeaturesEnabled;
+    private databaseReporter?;
+    private databaseEnabled;
+    constructor(serverCommand: string[], config?: SecurityConfig);
+    /**
+     * Generate a unique session ID
+     * @returns 8-character hex session ID
+     */
+    private generateSessionId;
+    /**
+     * Initialize pro features if license is valid
+     * @param licenseFilePath - Path to license file
+     */
+    private initializeProFeatures;
+    /**
+     * Initialize database reporting for UI integration
+     * @param dbConfig - Database configuration
+     */
+    private initializeDatabaseReporting;
+    /**
+     * Start the MCP server wrapper
+     */
+    start(): Promise<void>;
+    /**
+     * Handle client input (buffered line-by-line)
+     * @param input - Raw input from client
+     */
+    private handleClientInput;
+    /**
+     * Process a single client message
+     * @param line - JSON-RPC message line
+     */
+    private processClientMessage;
+    /**
+     * Handle tool call with security checks and traceability
+     * @param message - MCP message
+     * @returns Violations and block status
+     */
+    private handleToolCall;
+    /**
+     * Extract file paths from message parameters
+     * @param message - MCP message
+     * @returns Array of file paths
+     */
+    private extractFilePaths;
+    /**
+     * Handle security violations
+     * @param message - Original message
+     * @param violations - List of violations
+     * @param shouldBlock - Whether to block the request
+     */
+    private handleViolations;
+    /**
+     * Handle parse errors
+     * @param err - Error object
+     * @param line - Original line that failed to parse
+     */
+    private handleParseError;
+    /**
+     * Handle server output (buffered line-by-line)
+     * @param output - Raw output from server
+     */
+    private handleServerOutput;
+    /**
+     * Process a single server message
+     * @param line - JSON-RPC message line
+     */
+    private processServerMessage;
+    /**
+     * Handle sensitive data leak in server response
+     * @param message - Server message
+     * @param violations - List of violations
+     */
+    private handleSensitiveDataLeak;
+    /**
+     * Handle process exit
+     * @param code - Exit code
+     */
+    private handleProcessExit;
+    /**
+     * Get the security logger instance
+     * @returns SecurityLogger instance
+     */
+    getLogger(): SecurityLogger;
+    /**
+     * Get the traceability manager (pro feature)
+     * @returns MCPTraceabilityManager instance or undefined
+     */
+    getTraceabilityManager(): MCPTraceabilityManager | undefined;
+}

package/dist/wrapper.js

@@ -0,0 +1,417 @@
+"use strict";
+/**
+ * Copyright (c) 2025 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.MCPSecurityWrapper = void 0;
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
+const security_policy_1 = require("./security-policy");
+const security_logger_1 = require("./security-logger");
+const config_1 = require("./config");
+const premium_features_1 = require("./premium-features");
+const database_1 = require("./database");
+/**
+ * MCP Security Wrapper
+ * Wraps MCP servers with security monitoring and optional pro features
+ */
+class MCPSecurityWrapper {
+    constructor(serverCommand, config = {}) {
+        this.process = null;
+        this.toolCallTimestamps = [];
+        this.clientMessageBuffer = "";
+        this.serverMessageBuffer = "";
+        this.proFeaturesEnabled = false;
+        this.databaseEnabled = false;
+        const fullConfig = (0, config_1.mergeConfig)(config);
+        this.serverCommand = serverCommand;
+        this.policy = new security_policy_1.SecurityPolicy(fullConfig);
+        this.logger = new security_logger_1.SecurityLogger(fullConfig.logPath);
+        this.sessionId = this.generateSessionId();
+        // Initialize pro features if enabled
+        if (fullConfig.enableProFeatures) {
+            this.initializeProFeatures(fullConfig.licenseFilePath);
+        }
+        // Initialize database reporting if enabled
+        if (fullConfig.enableDatabaseReporting) {
+            this.initializeDatabaseReporting(fullConfig.database);
+        }
+    }
+    /**
+     * Generate a unique session ID
+     * @returns 8-character hex session ID
+     */
+    generateSessionId() {
+        return (0, crypto_1.createHash)("md5")
+            .update(Date.now().toString())
+            .digest("hex")
+            .substring(0, 8);
+    }
+    /**
+     * Initialize pro features if license is valid
+     * @param licenseFilePath - Path to license file
+     */
+    initializeProFeatures(licenseFilePath) {
+        try {
+            this.licenseManager = new premium_features_1.LicenseManager(licenseFilePath);
+            if (this.licenseManager.validateLicense()) {
+                this.proFeaturesEnabled = true;
+                this.traceabilityManager = new premium_features_1.MCPTraceabilityManager(this.licenseManager);
+                this.contextTracker = new premium_features_1.ContextTracker(this.licenseManager);
+                console.log(`✓ Pro features enabled (${this.licenseManager.getTier()} tier)`);
+            }
+            else {
+                console.warn("⚠ Invalid or expired license. Pro features disabled.");
+            }
+        }
+        catch (error) {
+            console.warn("⚠ Failed to initialize pro features:", error);
+        }
+    }
+    /**
+     * Initialize database reporting for UI integration
+     * @param dbConfig - Database configuration
+     */
+    initializeDatabaseReporting(dbConfig) {
+        try {
+            const databaseConfig = {
+                type: dbConfig.type || "json",
+                dbPath: dbConfig.path,
+                batchSize: dbConfig.batchSize,
+                flushIntervalMs: dbConfig.flushIntervalMs,
+                enabled: true,
+            };
+            this.databaseReporter = database_1.DatabaseReporterFactory.create(databaseConfig);
+            this.databaseEnabled = true;
+            console.log(`✓ Database reporting enabled (${databaseConfig.type})`);
+        }
+        catch (error) {
+            console.warn("⚠ Failed to initialize database reporting:", error);
+        }
+    }
+    /**
+     * Start the MCP server wrapper
+     */
+    async start() {
+        this.process = (0, child_process_1.spawn)(this.serverCommand[0], this.serverCommand.slice(1), {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        if (!this.process.stdout || !this.process.stdin || !this.process.stderr) {
+            throw new Error("Failed to create child process streams");
+        }
+        this.logger.logEvent("SERVER_START", "LOW", {
+            command: this.serverCommand.join(" "),
+            pid: this.process.pid,
+            proFeaturesEnabled: this.proFeaturesEnabled,
+        }, this.sessionId);
+        // Pipe stderr to parent process
+        this.process.stderr.pipe(process.stderr);
+        // Handle server output
+        this.process.stdout.on("data", (data) => {
+            const output = data.toString();
+            this.handleServerOutput(output);
+        });
+        // Handle client input
+        process.stdin.on("data", (data) => {
+            const input = data.toString();
+            this.handleClientInput(input);
+        });
+        // Handle process exit
+        this.process.on("exit", (code) => {
+            this.handleProcessExit(code);
+        });
+        // Handle process errors
+        this.process.on("error", (err) => {
+            this.logger.logEvent("SERVER_ERROR", "HIGH", { error: err.message }, this.sessionId);
+            console.error("Server process error:", err);
+        });
+    }
+    /**
+     * Handle client input (buffered line-by-line)
+     * @param input - Raw input from client
+     */
+    handleClientInput(input) {
+        this.clientMessageBuffer += input;
+        const lines = this.clientMessageBuffer.split("\n");
+        this.clientMessageBuffer = lines.pop() || "";
+        for (const line of lines) {
+            if (line.trim()) {
+                this.processClientMessage(line);
+            }
+        }
+    }
+    /**
+     * Process a single client message
+     * @param line - JSON-RPC message line
+     */
+    processClientMessage(line) {
+        try {
+            const message = JSON.parse(line);
+            this.logger.logEvent("CLIENT_REQUEST", "LOW", {
+                method: message.method,
+                id: message.id,
+            }, this.sessionId);
+            const violations = [];
+            let shouldBlock = false;
+            // Handle tool calls with security checks
+            if (message.method === "tools/call") {
+                const result = this.handleToolCall(message);
+                violations.push(...result.violations);
+                shouldBlock = result.shouldBlock;
+            }
+            // Handle violations
+            if (violations.length > 0) {
+                this.handleViolations(message, violations, shouldBlock);
+                if (shouldBlock) {
+                    return; // Don't forward blocked requests
+                }
+            }
+            // Forward to server
+            if (this.process && this.process.stdin) {
+                this.process.stdin.write(line + "\n");
+            }
+        }
+        catch (err) {
+            this.handleParseError(err, line);
+            // Forward unparseable messages
+            if (this.process && this.process.stdin) {
+                this.process.stdin.write(line + "\n");
+            }
+        }
+    }
+    /**
+     * Handle tool call with security checks and traceability
+     * @param message - MCP message
+     * @returns Violations and block status
+     */
+    handleToolCall(message) {
+        const violations = [];
+        let shouldBlock = false;
+        // Rate limiting
+        const now = Date.now();
+        this.toolCallTimestamps.push(now);
+        // Clean up old timestamps
+        const oneMinuteAgo = now - 60000;
+        this.toolCallTimestamps = this.toolCallTimestamps.filter((t) => t > oneMinuteAgo);
+        if (!this.policy.checkRateLimit(this.toolCallTimestamps)) {
+            violations.push("Rate limit exceeded for tool calls");
+            shouldBlock = true;
+            this.logger.logEvent("RATE_LIMIT_EXCEEDED", "HIGH", {
+                method: message.method,
+                toolName: message.params?.name,
+            }, this.sessionId);
+        }
+        // Check parameters for security issues
+        const paramsStr = JSON.stringify(message.params);
+        violations.push(...this.policy.checkPromptInjection(paramsStr));
+        violations.push(...this.policy.checkSensitiveData(paramsStr));
+        // Check file paths
+        const filePathParams = this.extractFilePaths(message);
+        for (const filePath of filePathParams) {
+            violations.push(...this.policy.checkFileAccess(filePath));
+            // Track file access in pro features
+            if (this.contextTracker) {
+                this.contextTracker.recordFileAccess(this.sessionId, filePath, "read");
+            }
+        }
+        // Log tool call
+        this.logger.logEvent("TOOL_CALL", violations.length > 0 ? "HIGH" : "LOW", {
+            toolName: message.params?.name,
+            hasViolations: violations.length > 0,
+            violations,
+        }, this.sessionId);
+        // Report to database if enabled
+        if (this.databaseEnabled && this.databaseReporter) {
+            this.databaseReporter.reportToolCall(this.sessionId, message.params?.name || "unknown", message.params || {}, violations, shouldBlock).catch(err => console.error("Database reporting error:", err));
+        }
+        return { violations, shouldBlock };
+    }
+    /**
+     * Extract file paths from message parameters
+     * @param message - MCP message
+     * @returns Array of file paths
+     */
+    extractFilePaths(message) {
+        return [
+            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 security violations
+     * @param message - Original message
+     * @param violations - List of violations
+     * @param shouldBlock - Whether to block the request
+     */
+    handleViolations(message, violations, shouldBlock) {
+        const event = {
+            timestamp: new Date().toISOString(),
+            sessionId: this.sessionId,
+            eventType: "SECURITY_VIOLATION",
+            severity: "CRITICAL",
+            details: {
+                violations,
+                message: message,
+                blocked: shouldBlock,
+            },
+        };
+        this.logger.logEvent(event.eventType, event.severity, event.details, event.sessionId);
+        // Report to database if enabled
+        if (this.databaseEnabled && this.databaseReporter) {
+            this.databaseReporter.reportEvent(event, {
+                method: message.method,
+                toolName: message.params?.name,
+            }).catch(err => console.error("Database reporting error:", err));
+        }
+        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");
+            }
+        }
+    }
+    /**
+     * Handle parse errors
+     * @param err - Error object
+     * @param line - Original line that failed to parse
+     */
+    handleParseError(err, line) {
+        this.logger.logEvent("PARSE_ERROR", "MEDIUM", {
+            error: err instanceof Error ? err.message : String(err),
+            line: line.substring(0, 100),
+        }, this.sessionId);
+        console.error(`Failed to parse client message: ${err}`);
+    }
+    /**
+     * Handle server output (buffered line-by-line)
+     * @param output - Raw output from server
+     */
+    handleServerOutput(output) {
+        this.serverMessageBuffer += output;
+        const lines = this.serverMessageBuffer.split("\n");
+        this.serverMessageBuffer = lines.pop() || "";
+        for (const line of lines) {
+            if (line.trim()) {
+                this.processServerMessage(line);
+            }
+        }
+    }
+    /**
+     * Process a single server message
+     * @param line - JSON-RPC message line
+     */
+    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(...this.policy.checkSensitiveData(responseStr));
+            if (violations.length > 0) {
+                this.handleSensitiveDataLeak(message, violations);
+                shouldForward = false;
+            }
+            else {
+                this.logger.logEvent("SERVER_RESPONSE", "LOW", {
+                    id: message.id,
+                    hasError: !!message.error,
+                }, this.sessionId);
+            }
+        }
+        catch (err) {
+            // Log parse errors for server output
+            this.logger.logEvent("SERVER_PARSE_ERROR", "LOW", {
+                error: err instanceof Error ? err.message : String(err),
+                line: line.substring(0, 100),
+            }, this.sessionId);
+        }
+        // Forward the line if not blocked
+        if (shouldForward) {
+            process.stdout.write(line + "\n");
+        }
+    }
+    /**
+     * Handle sensitive data leak in server response
+     * @param message - Server message
+     * @param violations - List of violations
+     */
+    handleSensitiveDataLeak(message, violations) {
+        this.logger.logEvent("SENSITIVE_DATA_LEAK", "CRITICAL", {
+            violations,
+            responseId: message.id,
+        }, this.sessionId);
+        console.error(`\n🚨 SENSITIVE DATA DETECTED IN RESPONSE:\n${violations.join("\n")}\n`);
+        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");
+        }
+    }
+    /**
+     * Handle process exit
+     * @param code - Exit code
+     */
+    async handleProcessExit(code) {
+        this.logger.logEvent("SERVER_EXIT", "MEDIUM", { exitCode: code }, this.sessionId);
+        console.error("\n=== MCP Security Statistics ===");
+        console.error(JSON.stringify(this.logger.getStatistics(), null, 2));
+        // Flush and close database reporter
+        if (this.databaseEnabled && this.databaseReporter) {
+            try {
+                await this.databaseReporter.flush();
+                await this.databaseReporter.close();
+                console.log("✓ Database events flushed");
+            }
+            catch (error) {
+                console.error("Failed to flush database:", error);
+            }
+        }
+        // Use setImmediate to allow pending I/O to complete
+        setImmediate(() => {
+            process.exit(code || 0);
+        });
+    }
+    /**
+     * Get the security logger instance
+     * @returns SecurityLogger instance
+     */
+    getLogger() {
+        return this.logger;
+    }
+    /**
+     * Get the traceability manager (pro feature)
+     * @returns MCPTraceabilityManager instance or undefined
+     */
+    getTraceabilityManager() {
+        return this.traceabilityManager;
+    }
+}
+exports.MCPSecurityWrapper = MCPSecurityWrapper;