import * as plugins from '../plugins.js'; import * as paths from '../paths.js'; import { logger } from '../logger.js'; import { Email } from '../mail/core/classes.email.js'; import type { IAttachment } from '../mail/core/classes.email.js'; import { SecurityLogger, SecurityLogLevel, SecurityEventType } from './classes.securitylogger.js'; import { RustSecurityBridge } from './classes.rustsecuritybridge.js'; import { LRUCache } from 'lru-cache'; /** * Scan result information */ export interface IScanResult { isClean: boolean; // Whether the content is clean (no threats detected) threatType?: string; // Type of threat if detected threatDetails?: string; // Details about the detected threat threatScore: number; // 0 (clean) to 100 (definitely malicious) scannedElements: string[]; // What was scanned (subject, body, attachments, etc.) timestamp: number; // When this scan was performed } /** * Options for content scanner configuration */ export interface IContentScannerOptions { maxCacheSize?: number; // Maximum number of entries to cache cacheTTL?: number; // TTL for cache entries in ms scanSubject?: boolean; // Whether to scan email subjects scanBody?: boolean; // Whether to scan email bodies scanAttachments?: boolean; // Whether to scan attachments maxAttachmentSizeToScan?: number; // Max size of attachments to scan in bytes scanAttachmentNames?: boolean; // Whether to scan attachment filenames blockExecutables?: boolean; // Whether to block executable attachments blockMacros?: boolean; // Whether to block documents with macros customRules?: Array<{ // Custom scanning rules pattern: string | RegExp; // Pattern to match type: string; // Type of threat score: number; // Threat score description: string; // Description of the threat }>; minThreatScore?: number; // Minimum score to consider content as a threat highThreatScore?: number; // Score above which content is considered high threat } /** * Threat categories */ export enum ThreatCategory { SPAM = 'spam', PHISHING = 'phishing', MALWARE = 'malware', EXECUTABLE = 'executable', SUSPICIOUS_LINK = 'suspicious_link', MALICIOUS_MACRO = 'malicious_macro', XSS = 'xss', SENSITIVE_DATA = 'sensitive_data', BLACKLISTED_CONTENT = 'blacklisted_content', CUSTOM_RULE = 'custom_rule' } /** * Content Scanner for detecting malicious email content */ export class ContentScanner { private static instance: ContentScanner; private scanCache: LRUCache; private options: Required; /** * Default options for the content scanner */ private static readonly DEFAULT_OPTIONS: Required = { maxCacheSize: 10000, cacheTTL: 24 * 60 * 60 * 1000, // 24 hours scanSubject: true, scanBody: true, scanAttachments: true, maxAttachmentSizeToScan: 10 * 1024 * 1024, // 10MB scanAttachmentNames: true, blockExecutables: true, blockMacros: true, customRules: [], minThreatScore: 30, // Minimum score to consider content as a threat highThreatScore: 70 // Score above which content is considered high threat }; /** * Constructor for the ContentScanner * @param options Configuration options */ constructor(options: IContentScannerOptions = {}) { // Merge with default options this.options = { ...ContentScanner.DEFAULT_OPTIONS, ...options }; // Initialize cache this.scanCache = new LRUCache({ max: this.options.maxCacheSize, ttl: this.options.cacheTTL, }); logger.log('info', 'ContentScanner initialized'); } /** * Get the singleton instance of the scanner * @param options Configuration options * @returns Singleton scanner instance */ public static getInstance(options: IContentScannerOptions = {}): ContentScanner { if (!ContentScanner.instance) { ContentScanner.instance = new ContentScanner(options); } return ContentScanner.instance; } /** * Scan an email for malicious content. * Delegates text/subject/html/filename pattern scanning to Rust. * Binary attachment scanning (PE headers, VBA macros) stays in TS. * @param email The email to scan * @returns Scan result */ public async scanEmail(email: Email): Promise { try { // Generate a cache key from the email const cacheKey = this.generateCacheKey(email); // Check cache first const cachedResult = this.scanCache.get(cacheKey); if (cachedResult) { logger.log('info', `Using cached scan result for email ${email.getMessageId()}`); return cachedResult; } // Delegate text/subject/html/filename scanning to Rust const bridge = RustSecurityBridge.getInstance(); const rustResult = await bridge.scanContent({ subject: this.options.scanSubject ? email.subject : undefined, textBody: this.options.scanBody ? email.text : undefined, htmlBody: this.options.scanBody ? email.html : undefined, attachmentNames: this.options.scanAttachmentNames ? email.attachments?.map(a => a.filename) ?? [] : [], }); const result: IScanResult = { isClean: true, threatScore: rustResult.threatScore, threatType: rustResult.threatType ?? undefined, threatDetails: rustResult.threatDetails ?? undefined, scannedElements: rustResult.scannedElements, timestamp: Date.now(), }; // Attachment binary scanning stays in TS (PE headers, macro detection) if (this.options.scanAttachments && email.attachments?.length > 0) { for (const attachment of email.attachments) { this.scanAttachmentBinary(attachment, result); } } // Apply custom rules (TS-only, runtime-configured) this.applyCustomRules(email, result); // Determine if the email is clean based on threat score result.isClean = result.threatScore < this.options.minThreatScore; // Save to cache this.scanCache.set(cacheKey, result); // Log high threat findings if (result.threatScore >= this.options.highThreatScore) { this.logHighThreatFound(email, result); } else if (!result.isClean) { this.logThreatFound(email, result); } return result; } catch (error) { logger.log('error', `Error scanning email: ${error.message}`, { messageId: email.getMessageId(), error: error.stack }); // Return a safe default with error indication return { isClean: true, threatScore: 0, scannedElements: ['error'], timestamp: Date.now(), threatType: 'scan_error', threatDetails: `Scan error: ${error.message}` }; } } /** * Generate a cache key from an email * @param email The email to generate a key for * @returns Cache key */ private generateCacheKey(email: Email): string { // Use message ID if available if (email.getMessageId()) { return `email:${email.getMessageId()}`; } // Fallback to a hash of key content const contentToHash = [ email.from, email.subject || '', email.text?.substring(0, 1000) || '', email.html?.substring(0, 1000) || '', email.attachments?.length || 0 ].join(':'); return `email:${plugins.crypto.createHash('sha256').update(contentToHash).digest('hex')}`; } /** * Scan attachment binary content for PE headers and VBA macros. * This stays in TS because it accesses raw Buffer data (too large for IPC). * @param attachment The attachment to scan * @param result The scan result to update */ private scanAttachmentBinary(attachment: IAttachment, result: IScanResult): void { if (!attachment.content) { return; } // Skip large attachments if (attachment.content.length > this.options.maxAttachmentSizeToScan) { return; } const filename = attachment.filename.toLowerCase(); // Check for PE headers (Windows executables disguised with non-.exe extensions) if (attachment.content.length > 64 && attachment.content[0] === 0x4D && attachment.content[1] === 0x5A) { // 'MZ' header result.threatScore += 80; result.threatType = ThreatCategory.EXECUTABLE; result.threatDetails = `Attachment contains executable code: ${filename}`; return; } // Check for VBA macro indicators in Office documents if (this.options.blockMacros && this.likelyContainsMacros(attachment)) { result.threatScore += 60; result.threatType = ThreatCategory.MALICIOUS_MACRO; result.threatDetails = `Attachment appears to contain macros: ${filename}`; } } /** * Apply custom rules (runtime-configured patterns) to the email. * These stay in TS because they are configured at runtime. * @param email The email to check * @param result The scan result to update */ private applyCustomRules(email: Email, result: IScanResult): void { if (!this.options.customRules.length) { return; } const textsToCheck: string[] = []; if (email.subject) textsToCheck.push(email.subject); if (email.text) textsToCheck.push(email.text); if (email.html) textsToCheck.push(email.html); for (const rule of this.options.customRules) { const pattern = rule.pattern instanceof RegExp ? rule.pattern : new RegExp(rule.pattern, 'i'); for (const text of textsToCheck) { if (pattern.test(text)) { result.threatScore += rule.score; result.threatType = rule.type; result.threatDetails = rule.description; return; } } } } /** * Extract text from a binary buffer for scanning * @param buffer Binary content * @returns Extracted text (may be partial) */ private extractTextFromBuffer(buffer: Buffer): string { try { // Limit the amount we convert to avoid memory issues const sampleSize = Math.min(buffer.length, 100 * 1024); // 100KB max sample const sample = buffer.slice(0, sampleSize); // Try to convert to string, filtering out non-printable chars return sample.toString('utf8') .replace(/[\x00-\x09\x0B-\x1F\x7F-\x9F]/g, '') // Remove control chars .replace(/\uFFFD/g, ''); // Remove replacement char } catch (error) { logger.log('warn', `Error extracting text from buffer: ${error.message}`); return ''; } } /** * Check if an Office document likely contains macros * @param attachment The attachment to check * @returns Whether the file likely contains macros */ private likelyContainsMacros(attachment: IAttachment): boolean { const content = this.extractTextFromBuffer(attachment.content); const macroIndicators = [ /vbaProject\.bin/i, /Microsoft VBA/i, /\bVBA\b/, /Auto_Open/i, /AutoExec/i, /DocumentOpen/i, /AutoOpen/i, /\bExecute\(/i, /\bShell\(/i, /\bCreateObject\(/i ]; for (const indicator of macroIndicators) { if (indicator.test(content)) { return true; } } return false; } /** * Log a high threat finding to the security logger * @param email The email containing the threat * @param result The scan result */ private logHighThreatFound(email: Email, result: IScanResult): void { SecurityLogger.getInstance().logEvent({ level: SecurityLogLevel.ERROR, type: SecurityEventType.MALWARE, message: `High threat content detected in email from ${email.from} to ${email.to.join(', ')}`, details: { messageId: email.getMessageId(), threatType: result.threatType, threatDetails: result.threatDetails, threatScore: result.threatScore, scannedElements: result.scannedElements, subject: email.subject }, success: false, domain: email.getFromDomain() }); } /** * Log a threat finding to the security logger * @param email The email containing the threat * @param result The scan result */ private logThreatFound(email: Email, result: IScanResult): void { SecurityLogger.getInstance().logEvent({ level: SecurityLogLevel.WARN, type: SecurityEventType.SPAM, message: `Suspicious content detected in email from ${email.from} to ${email.to.join(', ')}`, details: { messageId: email.getMessageId(), threatType: result.threatType, threatDetails: result.threatDetails, threatScore: result.threatScore, scannedElements: result.scannedElements, subject: email.subject }, success: false, domain: email.getFromDomain() }); } /** * Get threat level description based on score * @param score Threat score * @returns Threat level description */ public static getThreatLevel(score: number): 'none' | 'low' | 'medium' | 'high' { if (score < 20) { return 'none'; } else if (score < 40) { return 'low'; } else if (score < 70) { return 'medium'; } else { return 'high'; } } }