@dollhousemcp/mcp-server/dist/security/telemetry/SecurityTelemetry.d.ts

DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.

/**
 * Security Telemetry for DollhouseMCP
 *
 * Tracks and aggregates security metrics for blocked attacks,
 * providing insights into threat patterns and system defense effectiveness.
 *
 * Issue #1269: Enhanced telemetry for memory injection protection
 *
 * REFACTOR NOTE:
 * Converted from static class to instance-based for DI architecture compatibility.
 * Security Telemetry is now a singleton service managed by the DI container.
 */
import { SecurityEvent } from '../securityMonitor.js';
export interface AttackVector {
    type: string;
    count: number;
    lastSeen: string;
    severity: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
    blockedPatterns: string[];
}
export interface DeduplicationStats {
    /** Number of repeated events that were suppressed */
    suppressedEvents: number;
    /** Number of unique events that passed through */
    uniqueEvents: number;
    /** Current number of keys in the dedup cache */
    cacheSize: number;
}
export interface SecurityMetrics {
    totalBlockedAttempts: number;
    uniqueAttackVectors: number;
    criticalAttacksBlocked: number;
    highSeverityBlocked: number;
    mediumSeverityBlocked: number;
    lowSeverityBlocked: number;
    topAttackVectors: AttackVector[];
    attacksPerHour: number[];
    deduplication: DeduplicationStats;
    lastUpdated: string;
}
export interface AttackTelemetryEntry {
    timestamp: string;
    attackType: string;
    pattern: string;
    severity: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
    source: string;
    blocked: boolean;
    metadata?: Record<string, any>;
}
/**
 * Security Telemetry Service
 *
 * DI-COMPATIBLE: Instance-based service for dependency injection.
 * Tracks security events, attack patterns, and generates metrics.
 */
export declare class SecurityTelemetry {
    private attackHistory;
    private readonly METRIC_WINDOW_HOURS;
    private readonly attackVectorMap;
    private logListener?;
    private readonly logDedup;
    addLogListener(fn: (entry: AttackTelemetryEntry) => void): () => void;
    /**
     * Create a new SecurityTelemetry instance
     */
    constructor();
    /**
     * Records a blocked attack attempt
     * FIX (PR #1313 review): Use UTC timestamps for consistency across timezones
     */
    recordBlockedAttack(attackType: string, pattern: string, severity: SecurityEvent['severity'], source: string, metadata?: Record<string, any>): void;
    /**
     * Get aggregated security metrics
     */
    getMetrics(): SecurityMetrics;
    /**
     * Returns deduplication statistics for observability.
     * Tracks how many repeated log listener calls were suppressed
     * vs. how many unique events passed through.
     */
    getDeduplicationStats(): DeduplicationStats;
    /**
     * Get attack patterns by type
     */
    getAttackPatternsByType(attackType: string): string[];
    /**
     * Get attack timeline for visualization
     */
    getAttackTimeline(hours?: number): {
        hour: string;
        count: number;
        severity: Record<string, number>;
    }[];
    /**
     * Get summary report for security audits
     */
    generateReport(): string;
    /**
     * Clear old telemetry data
     */
    clearOldData(daysToKeep?: number): void;
    /**
     * Export telemetry data for external analysis
     */
    exportData(): {
        history: AttackTelemetryEntry[];
        vectors: AttackVector[];
        metrics: SecurityMetrics;
    };
    /**
     * Dispose of the telemetry service and clean up resources
     * Implements cleanup for proper DI lifecycle management
     */
    dispose(): Promise<void>;
}
//# sourceMappingURL=SecurityTelemetry.d.ts.map