@nest-omni/core 4.1.3-2 → 4.1.3-22

package/file-upload/services/malicious-file-detector.service.d.ts

@@ -0,0 +1,300 @@
+/**
+ * 检测结果
+ */
+export interface DetectionResult {
+    /** 是否安全 */
+    safe: boolean;
+    /** 威胁列表 */
+    threats: string[];
+    /** 风险评分 0-100 */
+    riskScore: number;
+    /** 是否为恶意软件 */
+    isMalware: boolean;
+    /** 检测详情 */
+    details?: {
+        /** 多编码检测结果 */
+        encodingThreats?: string[];
+        /** 文件结构分析结果 */
+        structureAnalysis?: StructureAnalysisResult;
+        /** ClamAV扫描结果 */
+        clamavResult?: ClamAVResult;
+    };
+}
+/**
+ * 文件结构分析结果
+ */
+export interface StructureAnalysisResult {
+    /** 检测到的异常 */
+    anomalies: string[];
+    /** 风险评分 */
+    riskScore: number;
+    /** 文件类型特征 */
+    characteristics: {
+        /** 是否包含嵌套压缩 */
+        hasNestedArchive?: boolean;
+        /** 是否包含可执行内容 */
+        hasExecutableContent?: boolean;
+        /** 是否包含宏 */
+        hasMacros?: boolean;
+        /** 熵值（用于检测加密/混淆） */
+        entropy?: number;
+    };
+}
+/**
+ * ClamAV扫描结果
+ */
+export interface ClamAVResult {
+    /** 是否已扫描 */
+    scanned: boolean;
+    /** 是否发现病毒 */
+    infected: boolean;
+    /** 病毒签名 */
+    virusName?: string;
+    /** 错误信息 */
+    error?: string;
+}
+/**
+ * 恶意文件检测配置
+ */
+export interface MaliciousDetectorOptions {
+    /** 是否启用恶意文件检测（总开关） */
+    enabled?: boolean;
+    /** 是否启用ClamAV */
+    enableClamAV?: boolean;
+    /** ClamAV模式：'local' | 'remote' */
+    clamavMode?: 'local' | 'remote';
+    /** 本地ClamAV扫描命令（当mode='local'时使用） */
+    clamavCommand?: string;
+    /** 远程ClamAV服务配置（当mode='remote'时使用） */
+    clamavRemote?: {
+        /** 远程服务地址 */
+        host: string;
+        /** 端口号 */
+        port: number;
+        /** 超时时间（毫秒） */
+        timeout?: number;
+    };
+    /** 是否启用多编码检测 */
+    enableMultiEncoding?: boolean;
+    /** 是否启用文件结构分析 */
+    enableStructureAnalysis?: boolean;
+    /** 风险阈值 */
+    riskThreshold?: number;
+    /** 最大并发扫描数（防止 DoS） */
+    maxConcurrentScans?: number;
+    /** 最大扫描文件大小（字节，默认 10MB） */
+    maxScanSize?: number;
+    /** 扫描超时时间（毫秒，默认 60 秒） */
+    scanTimeout?: number;
+}
+/**
+ * 恶意文件检测服务
+ */
+/**
+ * 恶意文件检测服务（增强版）
+ *
+ * 功能：
+ * 1. 多编码检测 - 支持 UTF-8, UTF-16LE, Latin1, ASCII, Base64
+ * 2. 文件结构分析 - 检测嵌套压缩、可执行内容、Office宏、高熵值、多态性
+ * 3. ClamAV集成 - 支持本地命令行和远程服务两种模式
+ *
+ * 使用示例：
+ * ```typescript
+ * // 方式1: 本地ClamAV（需要在当前机器安装）
+ * FileUploadModule.forRoot({
+ *   maliciousDetection: {
+ *     enableClamAV: true,
+ *     clamavMode: 'local',           // 本地模式
+ *     clamavCommand: 'clamdscan',    // 或 'clamscan'
+ *   },
+ * });
+ *
+ * // 方式2: 远程ClamAV服务（推荐用于生产环境）
+ * FileUploadModule.forRoot({
+ *   maliciousDetection: {
+ *     enableClamAV: true,
+ *     clamavMode: 'remote',          // 远程模式
+ *     clamavRemote: {
+ *       host: 'clamav-server.com',   // ClamAV服务器地址
+ *       port: 3310,                  // ClamAV守护进程端口
+ *       timeout: 30000,              // 超时时间(ms)
+ *     },
+ *   },
+ * });
+ *
+ * // 方式3: 仅使用多编码检测和结构分析（无需安装ClamAV）
+ * FileUploadModule.forRoot({
+ *   maliciousDetection: {
+ *     enableClamAV: false,           // 禁用ClamAV
+ *     enableMultiEncoding: true,     // 启用多编码检测
+ *     enableStructureAnalysis: true, // 启用结构分析
+ *     riskThreshold: 50,             // 风险阈值
+ *   },
+ * });
+ *
+ * // 直接使用服务
+ * const result = await maliciousDetector.scanFile('/path/to/file');
+ * console.log('Is Safe:', result.safe);
+ * console.log('Risk Score:', result.riskScore);
+ * console.log('Threats:', result.threats);
+ * console.log('Details:', result.details);
+ * ```
+ *
+ * 远程ClamAV服务部署示例：
+ * ```bash
+ * # Docker部署ClamAV服务
+ * docker run -d -p 3310:3310 \
+ *   --name clamav \
+ *   clamav/clamav:latest
+ *
+ * # 配置clamd.conf允许远程连接
+ * TCPSocket 3310
+ * TCPAddr 0.0.0.0
+ * StreamMaxLength 100M
+ * ```
+ *
+ * 检测结果示例：
+ * ```json
+ * {
+ *   "safe": false,
+ *   "isMalware": true,
+ *   "riskScore": 85,
+ *   "threats": [
+ *     "PE executable header (Windows)",
+ *     "Script tag injection (base64 encoded)",
+ *     "Executable content detected"
+ *   ],
+ *   "details": {
+ *     "encodingThreats": ["Script tag injection (base64 encoded)"],
+ *     "structureAnalysis": {
+ *       "anomalies": ["Executable content detected"],
+ *       "riskScore": 60,
+ *       "characteristics": {
+ *         "hasExecutableContent": true,
+ *         "entropy": 6.8
+ *       }
+ *     },
+ *     "clamavResult": {
+ *       "scanned": true,
+ *       "infected": true,
+ *       "virusName": "Win.Trojan.Agent"
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class MaliciousFileDetector {
+    private readonly options?;
+    private readonly logger;
+    private activeScanCount;
+    private readonly maxConcurrentScans;
+    private readonly maxScanSize;
+    private readonly scanTimeout;
+    private readonly encodings;
+    private readonly maliciousPatterns;
+    private readonly suspiciousSignatures;
+    constructor(options?: MaliciousDetectorOptions);
+    /**
+     * 扫描文件（增强版 - 带并发控制和流式处理）
+     */
+    scanFile(filePath?: string, buffer?: Buffer): Promise<DetectionResult>;
+    /**
+     * 等待直到有可用的扫描槽位
+     */
+    private waitForScanSlot;
+    /**
+     * 执行实际的扫描操作
+     */
+    private performScan;
+    /**
+     * 使用流式处理读取文件（防止大文件占用过多内存）
+     */
+    private readFileStream;
+    /**
+     * 检查签名
+     */
+    private checkSignature;
+    /**
+     * 缓冲区包含检查
+     */
+    private bufferContains;
+    /**
+     * 检查压缩比（简单实现）
+     */
+    private checkCompressionRatio;
+    /**
+     * 检查可疑文件名
+     */
+    private hasSuspiciousName;
+    /**
+     * 检查双扩展名
+     */
+    private hasDoubleExtension;
+    /**
+     * 检查隐藏扩展名技巧
+     */
+    private hasHiddenExtension;
+    /**
+     * 多编码检测（新增）
+     * 通过多种编码方式解析文件内容，检测隐藏的恶意模式
+     */
+    private detectMultiEncodingThreats;
+    /**
+     * 文件结构分析（新增）
+     * 分析文件的深层结构，检测异常特征
+     */
+    private analyzeFileStructure;
+    /**
+     * ClamAV病毒扫描（增强版 - 支持本地/远程）
+     */
+    private scanWithClamAV;
+    /**
+     * 本地ClamAV扫描（增强安全性）
+     */
+    private scanWithLocalClamAV;
+    /**
+     * 验证 ClamAV 命令（仅允许白名单）
+     */
+    private validateClamAVCommand;
+    /**
+     * 验证文件路径，防止命令注入
+     */
+    private validateFilePath;
+    /**
+     * 远程ClamAV扫描（通过ClamAV守护进程的网络接口）
+     */
+    private scanWithRemoteClamAV;
+    /**
+     * 验证 ClamAV 响应格式
+     */
+    private isValidClamAVResponse;
+    /**
+     * 验证病毒名称格式
+     */
+    private isValidVirusName;
+    /**
+     * 检测嵌套压缩文件
+     */
+    private detectNestedArchive;
+    /**
+     * 检测可执行内容
+     */
+    private detectExecutableContent;
+    /**
+     * 检测Office宏
+     */
+    private detectOfficeMacros;
+    /**
+     * 计算Shannon熵值
+     * 用于检测加密或高度压缩的内容
+     */
+    private calculateEntropy;
+    /**
+     * 检测多态性（文件类型伪装）
+     */
+    private detectPolymorphism;
+    /**
+     * 在buffer中查找pattern的位置
+     */
+    private bufferIndexOf;
+}