@panguard-ai/core 0.1.0

package/dist/index.js

@@ -0,0 +1,31 @@
+/**
+ * Panguard AI - Core Package
+ * Panguard 安全平台 - 核心套件
+ *
+ * Core shared modules for the Panguard AI platform.
+ * Provides types, i18n, utilities, discovery, monitoring, rules, AI, and adapters.
+ * 核心共用模組，提供類型、國際化、工具函式、偵察、監控、規則、AI 和對接器。
+ *
+ * @module @panguard-ai/core
+ */
+// i18n / 國際化
+export { initI18n, getI18n, changeLanguage, t, resetI18n } from './i18n/index.js';
+// Utils / 工具函式
+export { createLogger, setLogLevel, validateInput, sanitizeString, validateFilePath, } from './utils/index.js';
+// Discovery engine / 偵察引擎
+export { DISCOVERY_VERSION, detectOS, getNetworkInterfaces, scanOpenPorts, getActiveConnections, getGateway, getDnsServers, getDnsServersAsync, detectServices, detectSecurityTools, checkFirewall, auditUsers, calculateRiskScore, getRiskLevel, OsqueryProvider, createOsqueryProvider, } from './discovery/index.js';
+// Rules engine / 規則引擎
+export { RULES_VERSION, RuleEngine, parseSigmaYaml, parseSigmaFile, matchEvent, matchEventAgainstRules, loadRulesFromDirectory, watchRulesDirectory, YaraScanner, } from './rules/index.js';
+// Monitor engine / 監控引擎
+export { MONITOR_VERSION, MonitorEngine, LogMonitor, NetworkMonitor, ProcessMonitor, FileMonitor, checkThreatIntel, isPrivateIP, addThreatIntelEntry, getThreatIntelEntries, setFeedManager, getFeedManager, normalizeLogEvent, normalizeNetworkEvent, normalizeProcessEvent, normalizeFileEvent, DEFAULT_MONITOR_CONFIG, ThreatIntelFeedManager, } from './monitor/index.js';
+// Scoring / 安全分數
+export { calculateSecurityScore, scoreToGrade, scoreToColor, generateScoreSummary, AchievementTracker, ACHIEVEMENTS, } from './scoring/index.js';
+// AI / LLM interface / AI/LLM 介面
+export { AI_VERSION, createLLM } from './ai/index.js';
+// Adapters / 對接器
+export { ADAPTERS_VERSION, BaseAdapter, mapSeverity, mapEventSource, DefenderAdapter, WazuhAdapter, SyslogAdapter, parseSyslogMessage, AdapterRegistry, } from './adapters/index.js';
+// CLI utilities / CLI 工具
+export { c, colorSeverity, colorScore, colorGrade, Spinner, spinner, ProgressBar, progressBar, table, box, banner, header, symbols, divider, scoreDisplay, statusPanel, stripAnsi, formatDuration, timeAgo, visLen, promptSelect, promptText, promptConfirm, WizardEngine, } from './cli/index.js';
+/** Core package version / 核心套件版本 */
+export const CORE_VERSION = '0.1.0';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH,aAAa;AACb,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAElF,eAAe;AACf,OAAO,EACL,YAAY,EACZ,WAAW,EACX,aAAa,EACb,cAAc,EACd,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAG1B,0BAA0B;AAC1B,OAAO,EACL,iBAAiB,EACjB,QAAQ,EACR,oBAAoB,EACpB,aAAa,EACb,oBAAoB,EACpB,UAAU,EACV,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,eAAe,EACf,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAsB9B,sBAAsB;AACtB,OAAO,EACL,aAAa,EACb,UAAU,EACV,cAAc,EACd,cAAc,EACd,UAAU,EACV,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACnB,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAW1B,wBAAwB;AACxB,OAAO,EACL,eAAe,EACf,aAAa,EACb,UAAU,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAa5B,iBAAiB;AACjB,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAU5B,iCAAiC;AACjC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAStD,iBAAiB;AACjB,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,cAAc,EACd,eAAe,EACf,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAQ7B,yBAAyB;AACzB,OAAO,EACL,CAAC,EACD,aAAa,EACb,UAAU,EACV,UAAU,EACV,OAAO,EACP,OAAO,EACP,WAAW,EACX,WAAW,EACX,KAAK,EACL,GAAG,EACH,MAAM,EACN,MAAM,EACN,OAAO,EACP,OAAO,EACP,YAAY,EACZ,WAAW,EACX,SAAS,EACT,cAAc,EACd,OAAO,EACP,MAAM,EACN,YAAY,EACZ,UAAU,EACV,aAAa,EACb,YAAY,GACb,MAAM,gBAAgB,CAAC;AAcxB,oCAAoC;AACpC,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC"}

package/dist/monitor/event-normalizer.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Event normalizer - converts raw events to SecurityEvent format
+ * 事件正規化器 - 將原始事件轉換為 SecurityEvent 格式
+ *
+ * @module @panguard-ai/core/monitor/event-normalizer
+ */
+import type { SecurityEvent } from '../types.js';
+/**
+ * Raw log event input
+ * 原始日誌事件輸入
+ */
+interface RawLogEvent {
+    /** Log message / 日誌訊息 */
+    message: string;
+    /** Log source identifier / 日誌來源識別碼 */
+    source: string;
+    /** Event timestamp / 事件時間戳 */
+    timestamp?: Date;
+}
+/**
+ * Raw network connection input
+ * 原始網路連線輸入
+ */
+interface RawNetworkConnection {
+    /** Local IP address / 本地 IP 位址 */
+    localAddr: string;
+    /** Local port / 本地埠號 */
+    localPort: number;
+    /** Remote IP address / 遠端 IP 位址 */
+    remoteAddr: string;
+    /** Remote port / 遠端埠號 */
+    remotePort: number;
+    /** Connection state / 連線狀態 */
+    state: string;
+    /** Associated process name / 關聯程序名稱 */
+    process?: string;
+}
+/**
+ * Raw process input
+ * 原始程序輸入
+ */
+interface RawProcess {
+    /** Process ID / 程序 ID */
+    pid: number;
+    /** Process name / 程序名稱 */
+    name: string;
+    /** Executable path / 可執行檔路徑 */
+    path?: string;
+    /** User running the process / 執行程序的使用者 */
+    user?: string;
+    /** Full command line / 完整命令列 */
+    command?: string;
+}
+/**
+ * Raw file event input
+ * 原始檔案事件輸入
+ */
+interface RawFileEvent {
+    /** File path / 檔案路徑 */
+    path: string;
+    /** Action performed / 執行的動作 */
+    action: 'modified' | 'created' | 'deleted';
+    /** Previous hash / 先前的雜湊 */
+    oldHash?: string;
+    /** New hash / 新的雜湊 */
+    newHash?: string;
+}
+/**
+ * Normalize a raw log event into a SecurityEvent
+ * 將原始日誌事件正規化為 SecurityEvent
+ *
+ * @param raw - Raw log event / 原始日誌事件
+ * @returns Normalized SecurityEvent / 正規化的 SecurityEvent
+ */
+export declare function normalizeLogEvent(raw: RawLogEvent): SecurityEvent;
+/**
+ * Normalize a network connection into a SecurityEvent
+ * 將網路連線正規化為 SecurityEvent
+ *
+ * @param connection - Raw network connection / 原始網路連線
+ * @returns Normalized SecurityEvent / 正規化的 SecurityEvent
+ */
+export declare function normalizeNetworkEvent(connection: RawNetworkConnection): SecurityEvent;
+/**
+ * Normalize a process event into a SecurityEvent
+ * 將程序事件正規化為 SecurityEvent
+ *
+ * @param process - Raw process info / 原始程序資訊
+ * @param action - Process action / 程序動作
+ * @returns Normalized SecurityEvent / 正規化的 SecurityEvent
+ */
+export declare function normalizeProcessEvent(process: RawProcess, action: 'started' | 'stopped'): SecurityEvent;
+/**
+ * Normalize a file event into a SecurityEvent
+ * 將檔案事件正規化為 SecurityEvent
+ *
+ * @param file - Raw file event / 原始檔案事件
+ * @returns Normalized SecurityEvent / 正規化的 SecurityEvent
+ */
+export declare function normalizeFileEvent(file: RawFileEvent): SecurityEvent;
+export {};
+//# sourceMappingURL=event-normalizer.d.ts.map

package/dist/monitor/event-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-normalizer.d.ts","sourceRoot":"","sources":["../../src/monitor/event-normalizer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAyB,MAAM,aAAa,CAAC;AAExE;;;GAGG;AACH,UAAU,WAAW;IACnB,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED;;;GAGG;AACH,UAAU,oBAAoB;IAC5B,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,UAAU,UAAU;IAClB,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,UAAU,YAAY;IACpB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;IAC3C,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA8ED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,aAAa,CAcjE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,oBAAoB,GAAG,aAAa,CAqBrF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,SAAS,GAAG,SAAS,GAC5B,aAAa,CAqBf;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,aAAa,CAiCpE"}

package/dist/monitor/event-normalizer.js

@@ -0,0 +1,195 @@
+/**
+ * Event normalizer - converts raw events to SecurityEvent format
+ * 事件正規化器 - 將原始事件轉換為 SecurityEvent 格式
+ *
+ * @module @panguard-ai/core/monitor/event-normalizer
+ */
+import { randomUUID } from 'node:crypto';
+import { hostname, platform } from 'node:os';
+/** Current hostname cached / 快取的目前主機名稱 */
+const currentHost = hostname();
+/**
+ * Determine the EventSource based on the current platform
+ * 根據目前平台決定 EventSource
+ *
+ * @returns EventSource for the current OS / 目前作業系統的 EventSource
+ */
+function getPlatformLogSource() {
+    const os = platform();
+    if (os === 'win32')
+        return 'windows_event';
+    return 'syslog';
+}
+/**
+ * Parse severity from log message content by matching keywords
+ * 通過匹配關鍵字從日誌訊息內容解析嚴重等級
+ *
+ * @param message - Log message to parse / 要解析的日誌訊息
+ * @returns Severity level / 嚴重等級
+ */
+function parseSeverityFromMessage(message) {
+    const lower = message.toLowerCase();
+    if (lower.includes('critical') || lower.includes('emergency') || lower.includes('fatal')) {
+        return 'critical';
+    }
+    if (lower.includes('error') || lower.includes('fail') || lower.includes('denied')) {
+        return 'high';
+    }
+    if (lower.includes('warn') || lower.includes('warning') || lower.includes('suspicious')) {
+        return 'medium';
+    }
+    if (lower.includes('notice') || lower.includes('auth')) {
+        return 'low';
+    }
+    return 'info';
+}
+/**
+ * Extract a basic MITRE ATT&CK category from message patterns
+ * 從訊息模式中擷取基本的 MITRE ATT&CK 分類
+ *
+ * @param message - Log message / 日誌訊息
+ * @returns Category string / 分類字串
+ */
+function extractCategoryFromMessage(message) {
+    const lower = message.toLowerCase();
+    if (lower.includes('login') ||
+        lower.includes('auth') ||
+        lower.includes('ssh') ||
+        lower.includes('logon')) {
+        return 'Initial Access';
+    }
+    if (lower.includes('sudo') || lower.includes('privilege') || lower.includes('elevation')) {
+        return 'Privilege Escalation';
+    }
+    if (lower.includes('firewall') || lower.includes('iptables') || lower.includes('blocked')) {
+        return 'Defense Evasion';
+    }
+    if (lower.includes('cron') || lower.includes('scheduled') || lower.includes('persistence')) {
+        return 'Persistence';
+    }
+    if (lower.includes('download') || lower.includes('curl') || lower.includes('wget')) {
+        return 'Command and Control';
+    }
+    if (lower.includes('exec') || lower.includes('spawn') || lower.includes('script')) {
+        return 'Execution';
+    }
+    return 'General';
+}
+/**
+ * Normalize a raw log event into a SecurityEvent
+ * 將原始日誌事件正規化為 SecurityEvent
+ *
+ * @param raw - Raw log event / 原始日誌事件
+ * @returns Normalized SecurityEvent / 正規化的 SecurityEvent
+ */
+export function normalizeLogEvent(raw) {
+    return {
+        id: randomUUID(),
+        timestamp: raw.timestamp ?? new Date(),
+        source: getPlatformLogSource(),
+        severity: parseSeverityFromMessage(raw.message),
+        category: extractCategoryFromMessage(raw.message),
+        description: raw.message,
+        raw,
+        host: currentHost,
+        metadata: {
+            logSource: raw.source,
+        },
+    };
+}
+/**
+ * Normalize a network connection into a SecurityEvent
+ * 將網路連線正規化為 SecurityEvent
+ *
+ * @param connection - Raw network connection / 原始網路連線
+ * @returns Normalized SecurityEvent / 正規化的 SecurityEvent
+ */
+export function normalizeNetworkEvent(connection) {
+    const description = `Network connection: ${connection.localAddr}:${connection.localPort} -> ${connection.remoteAddr}:${connection.remotePort} [${connection.state}]${connection.process ? ` (${connection.process})` : ''}`;
+    return {
+        id: randomUUID(),
+        timestamp: new Date(),
+        source: 'network',
+        severity: 'info',
+        category: 'Network Activity',
+        description,
+        raw: connection,
+        host: currentHost,
+        metadata: {
+            localAddr: connection.localAddr,
+            localPort: connection.localPort,
+            remoteAddr: connection.remoteAddr,
+            remotePort: connection.remotePort,
+            state: connection.state,
+            process: connection.process,
+        },
+    };
+}
+/**
+ * Normalize a process event into a SecurityEvent
+ * 將程序事件正規化為 SecurityEvent
+ *
+ * @param process - Raw process info / 原始程序資訊
+ * @param action - Process action / 程序動作
+ * @returns Normalized SecurityEvent / 正規化的 SecurityEvent
+ */
+export function normalizeProcessEvent(process, action) {
+    const description = `Process ${action}: ${process.name} (PID: ${process.pid})${process.user ? ` by ${process.user}` : ''}`;
+    return {
+        id: randomUUID(),
+        timestamp: new Date(),
+        source: 'process',
+        severity: 'info',
+        category: action === 'started' ? 'Execution' : 'General',
+        description,
+        raw: { ...process, action },
+        host: currentHost,
+        metadata: {
+            pid: process.pid,
+            processName: process.name,
+            action,
+            path: process.path,
+            user: process.user,
+            command: process.command,
+        },
+    };
+}
+/**
+ * Normalize a file event into a SecurityEvent
+ * 將檔案事件正規化為 SecurityEvent
+ *
+ * @param file - Raw file event / 原始檔案事件
+ * @returns Normalized SecurityEvent / 正規化的 SecurityEvent
+ */
+export function normalizeFileEvent(file) {
+    const actionLabels = {
+        modified: 'modified',
+        created: 'created',
+        deleted: 'deleted',
+    };
+    const description = `File ${actionLabels[file.action]}: ${file.path}`;
+    let severity = 'info';
+    if (file.action === 'modified' && file.oldHash && file.newHash && file.oldHash !== file.newHash) {
+        severity = 'medium';
+    }
+    if (file.action === 'deleted') {
+        severity = 'low';
+    }
+    return {
+        id: randomUUID(),
+        timestamp: new Date(),
+        source: 'file',
+        severity,
+        category: 'Defense Evasion',
+        description,
+        raw: file,
+        host: currentHost,
+        metadata: {
+            filePath: file.path,
+            action: file.action,
+            oldHash: file.oldHash,
+            newHash: file.newHash,
+        },
+    };
+}
+//# sourceMappingURL=event-normalizer.js.map

package/dist/monitor/event-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-normalizer.js","sourceRoot":"","sources":["../../src/monitor/event-normalizer.ts"],"names":[],"mappings":"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"}

package/dist/monitor/file-monitor.d.ts

@@ -0,0 +1,90 @@
+/**
+ * File integrity monitoring via hash comparison
+ * 透過雜湊比對進行檔案完整性監控
+ *
+ * Periodically computes SHA-256 hashes of watched files and detects
+ * creation, modification, and deletion events.
+ * 定期計算受監控檔案的 SHA-256 雜湊值，並偵測建立、修改和刪除事件。
+ *
+ * @module @panguard-ai/core/monitor/file-monitor
+ */
+import { EventEmitter } from 'node:events';
+import type { FileHashRecord } from './types.js';
+/**
+ * FileMonitor - monitors file integrity by comparing SHA-256 hashes
+ * FileMonitor - 透過比較 SHA-256 雜湊值監控檔案完整性
+ *
+ * Events emitted:
+ * - 'file_changed': SecurityEvent - when a file hash changes / 當檔案雜湊值改變時
+ * - 'file_created': SecurityEvent - when a new file is detected / 當偵測到新檔案時
+ * - 'file_deleted': SecurityEvent - when a watched file is removed / 當受監控檔案被移除時
+ * - 'error': Error - when file checking encounters an error / 當檔案檢查遇到錯誤時
+ *
+ * @example
+ * ```typescript
+ * const monitor = new FileMonitor(['/etc/passwd', '/etc/shadow'], 60000);
+ * monitor.on('file_changed', (event) => console.log('Changed:', event));
+ * monitor.start();
+ * ```
+ */
+export declare class FileMonitor extends EventEmitter {
+    /** Whether the monitor is currently running / 監控器是否正在執行 */
+    private running;
+    /** Polling timer / 輪詢計時器 */
+    private timer?;
+    /** Stored file hash records / 儲存的檔案雜湊記錄 */
+    private fileHashes;
+    /** Paths to watch / 要監控的路徑 */
+    private watchPaths;
+    /** Polling interval in milliseconds / 輪詢間隔（毫秒） */
+    private pollInterval;
+    /**
+     * Create a new FileMonitor instance
+     * 建立新的 FileMonitor 實例
+     *
+     * @param watchPaths - Array of file paths to monitor / 要監控的檔案路徑陣列
+     * @param pollInterval - Polling interval in ms (default 60000) / 輪詢間隔毫秒數（預設 60000）
+     */
+    constructor(watchPaths: string[], pollInterval?: number);
+    /**
+     * Start monitoring file integrity
+     * 開始監控檔案完整性
+     */
+    start(): void;
+    /**
+     * Stop monitoring and clean up
+     * 停止監控並清理
+     */
+    stop(): void;
+    /**
+     * Check if the monitor is currently running
+     * 檢查監控器是否正在執行
+     *
+     * @returns True if running / 如果正在執行則為 true
+     */
+    isRunning(): boolean;
+    /**
+     * Compute the SHA-256 hash of a file
+     * 計算檔案的 SHA-256 雜湊值
+     *
+     * @param filePath - Path to the file / 檔案路徑
+     * @returns Hex-encoded SHA-256 hash / 十六進位編碼的 SHA-256 雜湊值
+     */
+    computeHash(filePath: string): Promise<string>;
+    /**
+     * Get the current file hash records
+     * 取得目前的檔案雜湊記錄
+     *
+     * @returns Map of file path to hash record / 檔案路徑到雜湊記錄的映射
+     */
+    getFileHashes(): ReadonlyMap<string, FileHashRecord>;
+    /**
+     * Check all watched files for changes
+     * 檢查所有受監控檔案的變更
+     *
+     * Compares current hashes with stored hashes and emits appropriate events.
+     * 比較目前雜湊值與儲存的雜湊值，並發出適當的事件。
+     */
+    private checkFiles;
+}
+//# sourceMappingURL=file-monitor.d.ts.map

package/dist/monitor/file-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-monitor.d.ts","sourceRoot":"","sources":["../../src/monitor/file-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAM3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAY,SAAQ,YAAY;IAC3C,2DAA2D;IAC3D,OAAO,CAAC,OAAO,CAAS;IACxB,4BAA4B;IAC5B,OAAO,CAAC,KAAK,CAAC,CAAiC;IAC/C,2CAA2C;IAC3C,OAAO,CAAC,UAAU,CAA0C;IAC5D,8BAA8B;IAC9B,OAAO,CAAC,UAAU,CAAW;IAC7B,kDAAkD;IAClD,OAAO,CAAC,YAAY,CAAS;IAE7B;;;;;;OAMG;gBACS,UAAU,EAAE,MAAM,EAAE,EAAE,YAAY,SAAQ;IAMtD;;;OAGG;IACH,KAAK,IAAI,IAAI;IAmBb;;;OAGG;IACH,IAAI,IAAI,IAAI;IAeZ;;;;;OAKG;IACH,SAAS,IAAI,OAAO;IAIpB;;;;;;OAMG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKpD;;;;;OAKG;IACH,aAAa,IAAI,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC;IAIpD;;;;;;OAMG;YACW,UAAU;CA2GzB"}

package/dist/monitor/file-monitor.js

@@ -0,0 +1,222 @@
+/**
+ * File integrity monitoring via hash comparison
+ * 透過雜湊比對進行檔案完整性監控
+ *
+ * Periodically computes SHA-256 hashes of watched files and detects
+ * creation, modification, and deletion events.
+ * 定期計算受監控檔案的 SHA-256 雜湊值，並偵測建立、修改和刪除事件。
+ *
+ * @module @panguard-ai/core/monitor/file-monitor
+ */
+import { EventEmitter } from 'node:events';
+import { createHash } from 'node:crypto';
+import { readFile, stat } from 'node:fs/promises';
+import { createLogger } from '../utils/index.js';
+import { normalizeFileEvent } from './event-normalizer.js';
+const logger = createLogger('file-monitor');
+/**
+ * FileMonitor - monitors file integrity by comparing SHA-256 hashes
+ * FileMonitor - 透過比較 SHA-256 雜湊值監控檔案完整性
+ *
+ * Events emitted:
+ * - 'file_changed': SecurityEvent - when a file hash changes / 當檔案雜湊值改變時
+ * - 'file_created': SecurityEvent - when a new file is detected / 當偵測到新檔案時
+ * - 'file_deleted': SecurityEvent - when a watched file is removed / 當受監控檔案被移除時
+ * - 'error': Error - when file checking encounters an error / 當檔案檢查遇到錯誤時
+ *
+ * @example
+ * ```typescript
+ * const monitor = new FileMonitor(['/etc/passwd', '/etc/shadow'], 60000);
+ * monitor.on('file_changed', (event) => console.log('Changed:', event));
+ * monitor.start();
+ * ```
+ */
+export class FileMonitor extends EventEmitter {
+    /** Whether the monitor is currently running / 監控器是否正在執行 */
+    running = false;
+    /** Polling timer / 輪詢計時器 */
+    timer;
+    /** Stored file hash records / 儲存的檔案雜湊記錄 */
+    fileHashes = new Map();
+    /** Paths to watch / 要監控的路徑 */
+    watchPaths;
+    /** Polling interval in milliseconds / 輪詢間隔（毫秒） */
+    pollInterval;
+    /**
+     * Create a new FileMonitor instance
+     * 建立新的 FileMonitor 實例
+     *
+     * @param watchPaths - Array of file paths to monitor / 要監控的檔案路徑陣列
+     * @param pollInterval - Polling interval in ms (default 60000) / 輪詢間隔毫秒數（預設 60000）
+     */
+    constructor(watchPaths, pollInterval = 60000) {
+        super();
+        this.watchPaths = watchPaths;
+        this.pollInterval = pollInterval;
+    }
+    /**
+     * Start monitoring file integrity
+     * 開始監控檔案完整性
+     */
+    start() {
+        if (this.running) {
+            logger.warn('FileMonitor is already running');
+            return;
+        }
+        this.running = true;
+        logger.info(`FileMonitor started (watching ${this.watchPaths.length} paths, poll interval: ${this.pollInterval}ms)`);
+        // Run an initial check immediately / 立即執行首次檢查
+        void this.checkFiles();
+        this.timer = setInterval(() => {
+            void this.checkFiles();
+        }, this.pollInterval);
+    }
+    /**
+     * Stop monitoring and clean up
+     * 停止監控並清理
+     */
+    stop() {
+        if (!this.running) {
+            logger.warn('FileMonitor is not running');
+            return;
+        }
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        this.running = false;
+        logger.info('FileMonitor stopped');
+    }
+    /**
+     * Check if the monitor is currently running
+     * 檢查監控器是否正在執行
+     *
+     * @returns True if running / 如果正在執行則為 true
+     */
+    isRunning() {
+        return this.running;
+    }
+    /**
+     * Compute the SHA-256 hash of a file
+     * 計算檔案的 SHA-256 雜湊值
+     *
+     * @param filePath - Path to the file / 檔案路徑
+     * @returns Hex-encoded SHA-256 hash / 十六進位編碼的 SHA-256 雜湊值
+     */
+    async computeHash(filePath) {
+        const content = await readFile(filePath);
+        return createHash('sha256').update(content).digest('hex');
+    }
+    /**
+     * Get the current file hash records
+     * 取得目前的檔案雜湊記錄
+     *
+     * @returns Map of file path to hash record / 檔案路徑到雜湊記錄的映射
+     */
+    getFileHashes() {
+        return this.fileHashes;
+    }
+    /**
+     * Check all watched files for changes
+     * 檢查所有受監控檔案的變更
+     *
+     * Compares current hashes with stored hashes and emits appropriate events.
+     * 比較目前雜湊值與儲存的雜湊值，並發出適當的事件。
+     */
+    async checkFiles() {
+        const currentPaths = new Set();
+        for (const filePath of this.watchPaths) {
+            currentPaths.add(filePath);
+            try {
+                const fileStat = await stat(filePath);
+                const currentHash = await this.computeHash(filePath);
+                const now = new Date().toISOString();
+                const existingRecord = this.fileHashes.get(filePath);
+                if (!existingRecord) {
+                    // New file detected (first check or newly created)
+                    // 偵測到新檔案（首次檢查或新建立）
+                    this.fileHashes.set(filePath, {
+                        path: filePath,
+                        hash: currentHash,
+                        lastChecked: now,
+                        size: fileStat.size,
+                    });
+                    // Only emit file_created if this is not the first run
+                    // 僅在非首次執行時發出 file_created 事件
+                    if (this.fileHashes.size >
+                        this.watchPaths.length - (this.watchPaths.length - currentPaths.size)) {
+                        // We check if we have seen at least one full cycle
+                        // The first poll populates the baseline, subsequent polls detect changes
+                    }
+                    // Emit file_created for files discovered after initial baseline
+                    // 為在初始基線之後發現的檔案發出 file_created
+                    // On first run, we just store the baseline without emitting
+                    // 首次執行時，我們只儲存基線而不發出事件
+                }
+                else if (existingRecord.hash !== currentHash) {
+                    // File has been modified / 檔案已被修改
+                    const oldHash = existingRecord.hash;
+                    this.fileHashes.set(filePath, {
+                        path: filePath,
+                        hash: currentHash,
+                        lastChecked: now,
+                        size: fileStat.size,
+                    });
+                    const event = normalizeFileEvent({
+                        path: filePath,
+                        action: 'modified',
+                        oldHash,
+                        newHash: currentHash,
+                    });
+                    this.emit('file_changed', event);
+                    logger.info(`File modified: ${filePath}`, {
+                        oldHash: oldHash.substring(0, 12),
+                        newHash: currentHash.substring(0, 12),
+                    });
+                }
+                else {
+                    // File unchanged, update last checked time
+                    // 檔案未變更，更新最後檢查時間
+                    existingRecord.lastChecked = now;
+                }
+            }
+            catch (err) {
+                const error = err;
+                if (error.code === 'ENOENT') {
+                    // File does not exist / 檔案不存在
+                    const existingRecord = this.fileHashes.get(filePath);
+                    if (existingRecord) {
+                        // File was previously tracked but now deleted
+                        // 檔案先前被追蹤但現在已被刪除
+                        this.fileHashes.delete(filePath);
+                        const event = normalizeFileEvent({
+                            path: filePath,
+                            action: 'deleted',
+                            oldHash: existingRecord.hash,
+                        });
+                        this.emit('file_deleted', event);
+                        logger.info(`File deleted: ${filePath}`);
+                    }
+                }
+                else {
+                    logger.error(`Failed to check file: ${filePath}`, { error: String(err) });
+                    this.emit('error', err instanceof Error ? err : new Error(String(err)));
+                }
+            }
+        }
+        // Check for files that were being tracked but are no longer in watchPaths
+        // 檢查先前被追蹤但不再在 watchPaths 中的檔案
+        for (const [trackedPath, record] of this.fileHashes) {
+            if (!currentPaths.has(trackedPath)) {
+                this.fileHashes.delete(trackedPath);
+                const event = normalizeFileEvent({
+                    path: trackedPath,
+                    action: 'deleted',
+                    oldHash: record.hash,
+                });
+                this.emit('file_deleted', event);
+            }
+        }
+    }
+}
+//# sourceMappingURL=file-monitor.js.map