contextguard 0.1.8 → 0.2.1

package/dist/policy.js

@@ -0,0 +1,273 @@
+"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.DEFAULT_POLICY = exports.createPolicyChecker = void 0;
+/**
+ * Initialize patterns for detecting sensitive data
+ */
+const initSensitiveDataPatterns = () => [
+    // Generic secrets
+    /(?:password|secret|api[_-]?key|token)\s*[:=]\s*['"]?[\w\-.]+['"]?/gi,
+    // Email addresses
+    /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
+    // Social Security Numbers
+    /\b\d{3}-\d{2}-\d{4}\b/g,
+    // OpenAI API keys
+    /sk-[a-zA-Z0-9]{20,}/g,
+    // GitHub tokens
+    /ghp_[a-zA-Z0-9]{36}/g,
+    // AWS Access Keys
+    /AKIA[0-9A-Z]{16}/g,
+    // Stripe API keys
+    /sk_(live|test)_[a-zA-Z0-9]{24,}/g,
+];
+/**
+ * Initialize patterns for detecting SQL injection
+ */
+const initSQLInjectionPatterns = () => [
+    /\bUNION\b.{0,50}\bSELECT\b/gi,
+    /\bDROP\b\s+\b(TABLE|DATABASE|SCHEMA)\b/gi,
+    /\bDELETE\b\s+\bFROM\b/gi,
+    /\bTRUNCATE\b\s+\bTABLE\b/gi,
+    /\bINSERT\b\s+\bINTO\b.{0,50}\bVALUES\b/gi,
+    /\bEXEC\s*\(|\bEXECUTE\s*\(/gi,
+    /--\s*$|\/\*[\s\S]*?\*\//gm,
+    /\bOR\b\s+['"]?\d+['"]?\s*=\s*['"]?\d+['"]?/gi,
+    /'\s*OR\s*'1'\s*=\s*'1/gi,
+    /;\s*(DROP|DELETE|INSERT|UPDATE|CREATE|ALTER)\b/gi,
+];
+/**
+ * Initialize patterns for detecting XSS attacks
+ */
+const initXSSPatterns = () => [
+    /<script[\s>]/gi,
+    /javascript:/gi,
+    /on\w+\s*=\s*["']?[^"'>]*/gi, // onerror=, onload=, onclick=, etc.
+    /<iframe[\s>]/gi,
+    /<object[\s>]/gi,
+    /<embed[\s>]/gi,
+    /eval\s*\(/gi,
+    /document\.(cookie|write|location)/gi,
+    /window\.(location|open)\s*[=(]/gi,
+    /<img[^>]+src\s*=\s*["']?javascript:/gi,
+];
+/**
+ * Initialize patterns for detecting prompt injection
+ */
+const initPromptInjectionPatterns = () => [
+    /ignore\s+(previous|all)\s+(instructions|prompts)/gi,
+    /system:\s*you\s+are\s+now/gi,
+    /forget\s+(everything|all)/gi,
+    /new\s+instructions:/gi,
+    /\[INST\].*?\[\/INST\]/gs,
+    /<\|im_start\|>/g,
+    /disregard\s+previous/gi,
+    /override\s+previous/gi,
+];
+/**
+ * Create a policy checker with the given configuration
+ * @param config - Policy configuration
+ * @returns Policy checker functions
+ */
+const createPolicyChecker = (config) => {
+    const sensitiveDataPatterns = initSensitiveDataPatterns();
+    const promptInjectionPatterns = initPromptInjectionPatterns();
+    const sqlInjectionPatterns = initSQLInjectionPatterns();
+    const xssPatterns = initXSSPatterns();
+    return {
+        /**
+         * Check text for prompt injection attempts
+         */
+        checkPromptInjection: (text) => {
+            if (!config.enablePromptInjectionDetection) {
+                return [];
+            }
+            const violations = [];
+            for (const pattern of promptInjectionPatterns) {
+                const matches = text.match(pattern);
+                if (matches) {
+                    violations.push(`Potential prompt injection detected: "${matches[0].substring(0, 50)}..."`);
+                }
+            }
+            return violations;
+        },
+        /**
+         * Check text for sensitive data exposure
+         */
+        checkSensitiveData: (text) => {
+            if (!config.enableSensitiveDataDetection) {
+                return [];
+            }
+            const violations = [];
+            for (const pattern of sensitiveDataPatterns) {
+                const matches = text.match(pattern);
+                if (matches) {
+                    violations.push(`Sensitive data pattern detected (redacted): ${pattern.source.substring(0, 30)}...`);
+                }
+            }
+            return violations;
+        },
+        /**
+         * Check file path for security violations
+         */
+        checkFileAccess: (filePath) => {
+            if (!config.enablePathTraversalPrevention) {
+                return [];
+            }
+            const violations = [];
+            // Check for path traversal
+            if (filePath.includes("..")) {
+                violations.push(`Path traversal attempt detected: ${filePath}`);
+            }
+            // Check for dangerous system paths
+            const dangerousPaths = [
+                "/etc",
+                "/root",
+                "/sys",
+                "/proc",
+                "C:\\Windows\\System32",
+            ];
+            if (dangerousPaths.some((dangerous) => filePath.startsWith(dangerous))) {
+                violations.push(`Access to dangerous path detected: ${filePath}`);
+            }
+            // Check against allowed paths whitelist
+            if (config.allowedFilePaths.length > 0) {
+                const isAllowed = config.allowedFilePaths.some((allowed) => filePath.startsWith(allowed));
+                if (!isAllowed) {
+                    violations.push(`File path not in allowed list: ${filePath}`);
+                }
+            }
+            return violations;
+        },
+        /**
+         * Check if rate limit is exceeded
+         */
+        checkRateLimit: (timestamps) => {
+            const oneMinuteAgo = Date.now() - 60000;
+            const recentCalls = timestamps.filter((t) => t > oneMinuteAgo);
+            return recentCalls.length < config.maxToolCallsPerMinute;
+        },
+        /**
+         * Check text against blocked patterns
+         */
+        checkBlockedPatterns: (text) => {
+            const violations = [];
+            for (const pattern of config.blockedPatterns) {
+                if (text.toLowerCase().includes(pattern.toLowerCase())) {
+                    violations.push(`Blocked pattern detected: "${pattern}"`);
+                }
+            }
+            return violations;
+        },
+        /**
+         * Check if a tool is allowed or blocked
+         */
+        checkToolAccess: (toolName) => {
+            const violations = [];
+            if (config.blockedTools.includes(toolName)) {
+                violations.push(`Tool "${toolName}" is explicitly blocked`);
+            }
+            else if (config.allowedTools.length > 0 &&
+                !config.allowedTools.includes(toolName)) {
+                violations.push(`Tool "${toolName}" is not in the allowed list: [${config.allowedTools.join(", ")}]`);
+            }
+            return violations;
+        },
+        /**
+         * Check text for SQL injection attempts
+         */
+        checkSQLInjection: (text) => {
+            if (!config.enableSQLInjectionDetection) {
+                return [];
+            }
+            const violations = [];
+            for (const pattern of sqlInjectionPatterns) {
+                if (pattern.test(text)) {
+                    violations.push(`SQL injection pattern detected: ${pattern.source.substring(0, 40)}...`);
+                    pattern.lastIndex = 0; // reset stateful regex
+                }
+            }
+            return violations;
+        },
+        /**
+         * Check text for XSS attack patterns
+         */
+        checkXSS: (text) => {
+            if (!config.enableXSSDetection) {
+                return [];
+            }
+            const violations = [];
+            for (const pattern of xssPatterns) {
+                if (pattern.test(text)) {
+                    violations.push(`XSS pattern detected: ${pattern.source.substring(0, 40)}...`);
+                    pattern.lastIndex = 0; // reset stateful regex
+                }
+            }
+            return violations;
+        },
+        /**
+         * Check text against custom user-defined rules
+         */
+        checkCustomRules: (text) => {
+            const violations = [];
+            for (const rule of config.customRules) {
+                try {
+                    const regex = new RegExp(rule.pattern, "gi");
+                    if (regex.test(text)) {
+                        violations.push(`Custom rule "${rule.name}" triggered`);
+                    }
+                }
+                catch {
+                    // Invalid regex pattern — skip silently
+                }
+            }
+            return violations;
+        },
+        /**
+         * Check if blocking mode is enabled
+         */
+        isBlockingMode: () => {
+            return config.mode === "block";
+        },
+        /**
+         * Get the full configuration
+         */
+        getConfig: () => {
+            return config;
+        },
+    };
+};
+exports.createPolicyChecker = createPolicyChecker;
+exports.DEFAULT_POLICY = {
+    id: "",
+    agent_id: "",
+    created_at: "",
+    updated_at: "",
+    maxToolCallsPerMinute: 30,
+    blockedPatterns: [],
+    allowedFilePaths: [],
+    alertThreshold: 5,
+    enablePromptInjectionDetection: true,
+    enableSensitiveDataDetection: true,
+    enablePathTraversalPrevention: true,
+    enableSQLInjectionDetection: true,
+    enableSemanticDetection: false,
+    enableXSSDetection: true,
+    customRules: [],
+    mode: "monitor",
+    logPath: "mcp_security.log",
+    enableProFeatures: false,
+    licenseFilePath: ".contextguard-license",
+    transport: "stdio",
+    port: 3100,
+    targetUrl: "",
+    allowedTools: [],
+    blockedTools: [],
+    alertWebhook: "",
+    alertOnSeverity: ["HIGH", "CRITICAL"],
+};

package/dist/premium-features.d.ts

@@ -0,0 +1,364 @@
+/**
+ * Copyright (c) 2025 Amir Mironi
+ *
+ * Premium/Enterprise Features for ContextGuard
+ * These features require a valid license key
+ */
+export declare enum LicenseTier {
+    FREE = "free",
+    PRO = "pro",
+    ENTERPRISE = "enterprise"
+}
+export interface LicenseInfo {
+    tier: LicenseTier;
+    key: string;
+    expiresAt: Date;
+    features: string[];
+    organizationId?: string;
+    maxUsers?: number;
+}
+export interface AnalyticsData {
+    timestamp: Date;
+    eventType: string;
+    severity: string;
+    metadata: Record<string, unknown>;
+}
+export interface ComplianceReport {
+    reportId: string;
+    generatedAt: Date;
+    standard: "SOC2" | "GDPR" | "HIPAA";
+    findings: ComplianceFinding[];
+    status: "PASS" | "FAIL" | "WARNING";
+}
+export interface ComplianceFinding {
+    control: string;
+    status: "PASS" | "FAIL" | "WARNING";
+    details: string;
+    remediation?: string;
+}
+export interface CustomRule {
+    id: string;
+    name: string;
+    description: string;
+    pattern: RegExp;
+    severity: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+    action: "LOG" | "BLOCK";
+    enabled: boolean;
+}
+export interface TeamMember {
+    userId: string;
+    email: string;
+    role: "ADMIN" | "MEMBER" | "VIEWER";
+    permissions: string[];
+}
+/**
+ * License Manager - Validates and manages license keys
+ */
+export declare class LicenseManager {
+    private licenseInfo;
+    private licenseFilePath;
+    constructor(licenseFilePath?: string);
+    private loadLicense;
+    validateLicense(): boolean;
+    getTier(): LicenseTier;
+    hasFeature(feature: string): boolean;
+    getLicenseInfo(): LicenseInfo | null;
+}
+/**
+ * Web Dashboard Analytics - Collects and aggregates security metrics
+ * PRO FEATURE
+ */
+export declare class DashboardAnalytics {
+    private licenseManager;
+    private analyticsData;
+    private readonly maxStoredEvents;
+    constructor(licenseManager: LicenseManager);
+    trackEvent(eventType: string, severity: string, metadata: Record<string, unknown>): void;
+    getMetrics(timeRange: "1h" | "24h" | "7d" | "30d"): Record<string, unknown>;
+    private groupBy;
+    private getTimeline;
+}
+/**
+ * Team Collaboration Manager
+ * PRO FEATURE
+ */
+export declare class TeamCollaboration {
+    private licenseManager;
+    private teamMembers;
+    constructor(licenseManager: LicenseManager);
+    addMember(member: TeamMember): boolean;
+    removeMember(userId: string): boolean;
+    getMember(userId: string): TeamMember | undefined;
+    listMembers(): TeamMember[];
+    hasPermission(userId: string, permission: string): boolean;
+}
+/**
+ * Custom Detection Rules Engine
+ * PRO FEATURE
+ */
+export declare class CustomRulesEngine {
+    private licenseManager;
+    private rules;
+    constructor(licenseManager: LicenseManager);
+    addRule(rule: CustomRule): boolean;
+    removeRule(ruleId: string): boolean;
+    evaluateRules(text: string): Array<{
+        rule: CustomRule;
+        matches: string[];
+    }>;
+    listRules(): CustomRule[];
+}
+/**
+ * SSO/SAML Authentication Provider
+ * ENTERPRISE FEATURE
+ */
+export declare class SSOProvider {
+    private licenseManager;
+    private samlConfig;
+    constructor(licenseManager: LicenseManager);
+    configureSAML(config: Record<string, unknown>): boolean;
+    validateSAMLToken(token: string): {
+        valid: boolean;
+        userId?: string;
+    };
+}
+/**
+ * Advanced ML-Based Detection
+ * PRO FEATURE
+ */
+export declare class MLDetectionEngine {
+    private licenseManager;
+    private anomalyThreshold;
+    constructor(licenseManager: LicenseManager);
+    detectAnomalies(text: string, _context?: Record<string, unknown>): {
+        isAnomaly: boolean;
+        confidence: number;
+        reason?: string;
+    };
+}
+/**
+ * Compliance Reporting Generator
+ * PRO FEATURE
+ */
+export declare class ComplianceReporter {
+    private licenseManager;
+    constructor(licenseManager: LicenseManager);
+    generateReport(standard: "SOC2" | "GDPR" | "HIPAA", _events?: Array<Record<string, unknown>>): ComplianceReport | null;
+    exportReport(report: ComplianceReport, format: "JSON" | "PDF"): string;
+}
+/**
+ * Priority Support Manager
+ * PRO/ENTERPRISE FEATURE
+ */
+export declare class PrioritySupport {
+    private licenseManager;
+    constructor(licenseManager: LicenseManager);
+    createTicket(subject: string, description: string, priority: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL"): {
+        ticketId: string;
+        sla: string;
+    } | null;
+}
+/**
+ * SLA Monitor
+ * ENTERPRISE FEATURE
+ */
+export declare class SLAMonitor {
+    private licenseManager;
+    private uptimeStart;
+    private downtimeEvents;
+    constructor(licenseManager: LicenseManager);
+    recordDowntime(): void;
+    recordUptime(): void;
+    getUptimePercentage(): number;
+}
+/**
+ * MCP Traceability - Track which user used which MCP, tool, and context
+ * PRO FEATURE
+ */
+export interface MCPTraceRecord {
+    traceId: string;
+    timestamp: Date;
+    userId: string;
+    userEmail?: string;
+    sessionId: string;
+    mcpServerName: string;
+    mcpServerId: string;
+    mcpServerVersion?: string;
+    toolName: string;
+    toolMethod?: string;
+    toolParameters: Record<string, unknown>;
+    contextUsed: ContextSnapshot;
+    executionTimeMs: number;
+    status: "success" | "failure" | "blocked" | "timeout";
+    errorMessage?: string;
+    responseSize?: number;
+    responseType?: string;
+    securityLevel: "public" | "internal" | "confidential" | "restricted";
+    dataClassification?: "public" | "pii" | "phi" | "financial";
+    complianceTags: string[];
+    threatDetected: boolean;
+    securityViolations: string[];
+    tokensUsed?: number;
+    apiCallsCount?: number;
+    dataTransferredBytes?: number;
+    metadata?: Record<string, unknown>;
+    tags?: string[];
+}
+export interface ContextSnapshot {
+    filesAccessed: Array<{
+        path: string;
+        operation: "read" | "write" | "delete" | "list";
+        size?: number;
+    }>;
+    envVarsAccessed: string[];
+    externalApisCalled: Array<{
+        url: string;
+        method: string;
+        statusCode?: number;
+    }>;
+    databaseQueries?: Array<{
+        query: string;
+        database: string;
+        rowsAffected?: number;
+    }>;
+    memoryUsedMB?: number;
+    cpuTimeMs?: number;
+    userPrompt?: string;
+    userPromptHash?: string;
+}
+export interface TraceabilityQuery {
+    userId?: string;
+    userIds?: string[];
+    mcpServerName?: string;
+    toolName?: string;
+    sessionId?: string;
+    status?: string;
+    threatDetected?: boolean;
+    startDate?: Date;
+    endDate?: Date;
+    limit?: number;
+    offset?: number;
+    sortBy?: string;
+    sortOrder?: "asc" | "desc";
+}
+export interface UsageStatistics {
+    totalTraces: number;
+    uniqueUsers: number;
+    uniqueMCPServers: number;
+    uniqueTools: number;
+    byMCPServer: Record<string, {
+        count: number;
+        successRate: number;
+        avgExecutionTimeMs: number;
+        totalTokensUsed: number;
+    }>;
+    byTool: Record<string, {
+        count: number;
+        successRate: number;
+        avgExecutionTimeMs: number;
+    }>;
+    byUser: Record<string, {
+        count: number;
+        mcpServersUsed: string[];
+        toolsUsed: string[];
+        totalExecutionTimeMs: number;
+    }>;
+    securityEvents: {
+        totalThreats: number;
+        threatsBySeverity: Record<string, number>;
+        blockedRequests: number;
+    };
+    timeline: Array<{
+        timestamp: Date;
+        count: number;
+        successCount: number;
+        failureCount: number;
+    }>;
+}
+export declare class MCPTraceabilityManager {
+    private licenseManager;
+    private traces;
+    private readonly maxTraces;
+    private persistenceEnabled;
+    constructor(licenseManager: LicenseManager, persistenceEnabled?: boolean);
+    /**
+     * Record a new trace entry
+     */
+    recordTrace(trace: Omit<MCPTraceRecord, "traceId" | "timestamp">): string | null;
+    /**
+     * Query traces with filters
+     */
+    queryTraces(query: TraceabilityQuery): MCPTraceRecord[];
+    /**
+     * Get trace by ID
+     */
+    getTrace(traceId: string): MCPTraceRecord | null;
+    /**
+     * Get usage statistics
+     */
+    getUsageStatistics(query?: TraceabilityQuery): UsageStatistics;
+    /**
+     * Export traces for compliance/audit
+     */
+    exportTraces(query: TraceabilityQuery, format: "JSON" | "CSV"): string;
+    /**
+     * Get user activity timeline
+     */
+    getUserActivityTimeline(userId: string, startDate: Date, endDate: Date): Array<MCPTraceRecord>;
+    /**
+     * Detect anomalous usage patterns
+     */
+    detectAnomalies(userId?: string): Array<{
+        type: string;
+        severity: "LOW" | "MEDIUM" | "HIGH";
+        description: string;
+        traces: MCPTraceRecord[];
+    }>;
+    private persistTrace;
+    private getEmptyStatistics;
+}
+/**
+ * Context Tracker - Track context usage and data flow
+ * PRO FEATURE
+ */
+export declare class ContextTracker {
+    private licenseManager;
+    private activeContexts;
+    constructor(licenseManager: LicenseManager);
+    /**
+     * Start tracking context for a session
+     */
+    startTracking(sessionId: string): void;
+    /**
+     * Record file access
+     */
+    recordFileAccess(sessionId: string, path: string, operation: "read" | "write" | "delete" | "list", size?: number): void;
+    /**
+     * Record environment variable access
+     */
+    recordEnvVarAccess(sessionId: string, varName: string): void;
+    /**
+     * Record external API call
+     */
+    recordApiCall(sessionId: string, url: string, method: string, statusCode?: number): void;
+    /**
+     * Record database query
+     */
+    recordDatabaseQuery(sessionId: string, query: string, database: string, rowsAffected?: number): void;
+    /**
+     * Get context snapshot
+     */
+    getContextSnapshot(sessionId: string): ContextSnapshot | null;
+    /**
+     * Stop tracking and return final snapshot
+     */
+    stopTracking(sessionId: string): ContextSnapshot | null;
+    /**
+     * Analyze context for security risks
+     */
+    analyzeContextSecurity(context: ContextSnapshot): Array<{
+        risk: string;
+        severity: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+        details: string;
+    }>;
+}