@panguard-ai/threat-cloud 0.1.0

package/dist/audit-logger.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Audit Logger — provenance tracking for all write operations
+ * 稽核日誌 — 所有寫入操作的溯源追蹤
+ *
+ * Every mutation (IoC create/update, sighting, threat upload, rule publish)
+ * is logged with actor, IP, timestamp, and action details.
+ *
+ * @module @panguard-ai/threat-cloud/audit-logger
+ */
+import type Database from 'better-sqlite3';
+import type { AuditAction, AuditLogEntry, AuditLogQuery, PaginatedResponse } from './types.js';
+export declare class AuditLogger {
+    private readonly db;
+    private readonly insertStmt;
+    constructor(db: Database.Database);
+    /**
+     * Log an auditable action.
+     * 記錄可稽核的操作
+     */
+    log(action: AuditAction, entityType: string, entityId: string, context?: {
+        actorHash?: string;
+        ipAddress?: string;
+        details?: Record<string, unknown>;
+    }): void;
+    /**
+     * Hash an API key for audit logging (never log raw keys).
+     * 將 API key 雜湊化用於稽核日誌（永遠不記錄原始 key）
+     */
+    static hashApiKey(apiKey: string): string;
+    /**
+     * Query audit log with filters.
+     * 查詢稽核日誌
+     */
+    query(params: AuditLogQuery): PaginatedResponse<AuditLogEntry>;
+    /**
+     * Get audit trail for a specific entity.
+     * 取得特定實體的稽核記錄
+     */
+    getEntityTrail(entityType: string, entityId: string): AuditLogEntry[];
+    /**
+     * Purge old audit entries beyond retention.
+     * 清除超齡的稽核記錄
+     */
+    purgeOldEntries(olderThan: string): number;
+}
+//# sourceMappingURL=audit-logger.d.ts.map

package/dist/audit-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-logger.d.ts","sourceRoot":"","sources":["../src/audit-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AA2B/F,qBAAa,WAAW;IAGV,OAAO,CAAC,QAAQ,CAAC,EAAE;IAF/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;gBAEnB,EAAE,EAAE,QAAQ,CAAC,QAAQ;IAOlD;;;OAGG;IACH,GAAG,CACD,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC9B,GACL,IAAI;IAWP;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAKzC;;;OAGG;IACH,KAAK,CAAC,MAAM,EAAE,aAAa,GAAG,iBAAiB,CAAC,aAAa,CAAC;IA2C9D;;;OAGG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,EAAE;IAWrE;;;OAGG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;CAI3C"}

package/dist/audit-logger.js

@@ -0,0 +1,105 @@
+/**
+ * Audit Logger — provenance tracking for all write operations
+ * 稽核日誌 — 所有寫入操作的溯源追蹤
+ *
+ * Every mutation (IoC create/update, sighting, threat upload, rule publish)
+ * is logged with actor, IP, timestamp, and action details.
+ *
+ * @module @panguard-ai/threat-cloud/audit-logger
+ */
+import { createHash } from 'node:crypto';
+function rowToEntry(row) {
+    return {
+        id: row.id,
+        action: row.action,
+        entityType: row.entity_type,
+        entityId: row.entity_id,
+        actorHash: row.actor_hash,
+        ipAddress: row.ip_address,
+        details: row.details,
+        createdAt: row.created_at,
+    };
+}
+export class AuditLogger {
+    db;
+    insertStmt;
+    constructor(db) {
+        this.db = db;
+        this.insertStmt = this.db.prepare(`INSERT INTO audit_log (action, entity_type, entity_id, actor_hash, ip_address, details)
+       VALUES (?, ?, ?, ?, ?, ?)`);
+    }
+    /**
+     * Log an auditable action.
+     * 記錄可稽核的操作
+     */
+    log(action, entityType, entityId, context = {}) {
+        this.insertStmt.run(action, entityType, entityId, context.actorHash ?? '', context.ipAddress ?? '', JSON.stringify(context.details ?? {}));
+    }
+    /**
+     * Hash an API key for audit logging (never log raw keys).
+     * 將 API key 雜湊化用於稽核日誌（永遠不記錄原始 key）
+     */
+    static hashApiKey(apiKey) {
+        if (!apiKey)
+            return '';
+        return createHash('sha256').update(apiKey).digest('hex').slice(0, 16);
+    }
+    /**
+     * Query audit log with filters.
+     * 查詢稽核日誌
+     */
+    query(params) {
+        const conditions = [];
+        const values = [];
+        if (params.action) {
+            conditions.push('action = ?');
+            values.push(params.action);
+        }
+        if (params.entityType) {
+            conditions.push('entity_type = ?');
+            values.push(params.entityType);
+        }
+        if (params.entityId) {
+            conditions.push('entity_id = ?');
+            values.push(params.entityId);
+        }
+        if (params.since) {
+            conditions.push('created_at > ?');
+            values.push(params.since);
+        }
+        const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+        const safeLimit = Math.min(Math.max(1, params.limit ?? 50), 500);
+        const total = this.db.prepare(`SELECT COUNT(*) as count FROM audit_log ${where}`).get(...values).count;
+        const rows = this.db
+            .prepare(`SELECT * FROM audit_log ${where} ORDER BY created_at DESC LIMIT ?`)
+            .all(...values, safeLimit);
+        return {
+            items: rows.map(rowToEntry),
+            total,
+            page: 1,
+            limit: safeLimit,
+            hasMore: safeLimit < total,
+        };
+    }
+    /**
+     * Get audit trail for a specific entity.
+     * 取得特定實體的稽核記錄
+     */
+    getEntityTrail(entityType, entityId) {
+        const rows = this.db
+            .prepare(`SELECT * FROM audit_log
+         WHERE entity_type = ? AND entity_id = ?
+         ORDER BY created_at ASC`)
+            .all(entityType, entityId);
+        return rows.map(rowToEntry);
+    }
+    /**
+     * Purge old audit entries beyond retention.
+     * 清除超齡的稽核記錄
+     */
+    purgeOldEntries(olderThan) {
+        const result = this.db.prepare('DELETE FROM audit_log WHERE created_at < ?').run(olderThan);
+        return result.changes;
+    }
+}
+//# sourceMappingURL=audit-logger.js.map

package/dist/audit-logger.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Threat Cloud CLI entry point
+ * 威脅雲 CLI 入口點
+ *
+ * Usage: threat-cloud [--port 8080] [--host 0.0.0.0] [--db ./data/threats.db]
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;GAKG"}

package/dist/cli.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * Threat Cloud CLI entry point
+ * 威脅雲 CLI 入口點
+ *
+ * Usage: threat-cloud [--port 8080] [--host 0.0.0.0] [--db ./data/threats.db]
+ */
+import { ThreatCloudServer } from './server.js';
+const MIN_API_KEY_LENGTH = 32;
+function parseArgs(args) {
+    const config = {};
+    for (let i = 0; i < args.length; i++) {
+        switch (args[i]) {
+            case '--port': {
+                const port = Number(args[++i]);
+                if (isNaN(port) || port < 1 || port > 65535) {
+                    console.error(`Error: Invalid port number. Must be 1-65535.`);
+                    process.exit(1);
+                }
+                config.port = port;
+                break;
+            }
+            case '--host':
+                config.host = args[++i];
+                break;
+            case '--db':
+                config.dbPath = args[++i];
+                break;
+            case '--backup-dir':
+                config.backupDir = args[++i];
+                break;
+            case '--api-key': {
+                const keys = (args[++i] ?? '').split(',').filter(Boolean);
+                const weak = keys.filter((k) => k.length < MIN_API_KEY_LENGTH);
+                if (weak.length > 0) {
+                    console.error(`Error: API keys must be at least ${MIN_API_KEY_LENGTH} characters. ` +
+                        `Generate with: openssl rand -hex 32`);
+                    process.exit(1);
+                }
+                config.apiKeyRequired = true;
+                config.apiKeys = keys;
+                break;
+            }
+            case '--help':
+                console.log(`
+Threat Cloud Server - Collective Threat Intelligence Backend
+
+Usage: threat-cloud [options]
+
+Options:
+  --port <number>      Listen port (default: 8080, range: 1-65535)
+  --host <string>      Listen host (default: 127.0.0.1)
+  --db <path>          SQLite database path (default: ./threat-cloud.db)
+  --api-key <keys>     Comma-separated API keys (min ${MIN_API_KEY_LENGTH} chars each)
+  --backup-dir <path>  Backup directory (default: ./backups)
+  --help               Show this help
+
+Generate API key:
+  openssl rand -hex 32
+`);
+                process.exit(0);
+        }
+    }
+    return config;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    // Environment variables override defaults; CLI args override env
+    const envApiKeys = process.env['TC_API_KEYS']?.split(',').filter(Boolean) ?? [];
+    // Validate env API keys length in production
+    if (process.env['NODE_ENV'] === 'production' && envApiKeys.length === 0) {
+        console.error('Error: TC_API_KEYS is required in production mode.');
+        console.error('Generate with: openssl rand -hex 32');
+        process.exit(1);
+    }
+    const weakEnvKeys = envApiKeys.filter((k) => k.length < MIN_API_KEY_LENGTH);
+    if (weakEnvKeys.length > 0) {
+        console.warn(`WARNING: ${weakEnvKeys.length} API key(s) shorter than ${MIN_API_KEY_LENGTH} chars. ` +
+            `Generate stronger keys with: openssl rand -hex 32`);
+    }
+    const config = {
+        port: args.port ?? Number(process.env['TC_PORT'] ?? '8080'),
+        host: args.host ?? process.env['TC_HOST'] ?? '127.0.0.1',
+        dbPath: args.dbPath ?? process.env['TC_DB_PATH'] ?? './threat-cloud.db',
+        apiKeyRequired: args.apiKeyRequired ?? envApiKeys.length > 0,
+        apiKeys: args.apiKeys ?? envApiKeys,
+        rateLimitPerMinute: 120,
+    };
+    const backupDir = args.backupDir ?? process.env['TC_BACKUP_DIR'] ?? './backups';
+    const server = new ThreatCloudServer(config);
+    const shutdown = async () => {
+        console.log('\nShutting down Threat Cloud server...');
+        await server.stop();
+        process.exit(0);
+    };
+    process.on('SIGINT', () => void shutdown());
+    process.on('SIGTERM', () => void shutdown());
+    await server.start();
+    // Schedule daily backup (3am UTC by default)
+    const runBackup = () => {
+        const dest = server.getScheduler().runBackup(backupDir);
+        if (dest) {
+            console.log(`[Backup] Database backed up to ${dest}`);
+        }
+        else {
+            console.error('[Backup] Database backup failed');
+        }
+    };
+    // Initial backup on startup
+    runBackup();
+    // Daily backup interval
+    setInterval(runBackup, 24 * 60 * 60 * 1000);
+}
+void main();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGhD,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAE9B,SAAS,SAAS,CAAC,IAAc;IAC/B,MAAM,MAAM,GAAmD,EAAE,CAAC;IAClE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,QAAQ,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YAChB,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;gBAC/B,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;oBAC5C,OAAO,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;oBAC9D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAClB,CAAC;gBACD,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;gBACnB,MAAM;YACR,CAAC;YACD,KAAK,QAAQ;gBACX,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;gBACxB,MAAM;YACR,KAAK,MAAM;gBACT,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;gBAC1B,MAAM;YACR,KAAK,cAAc;gBACjB,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;gBAC7B,MAAM;YACR,KAAK,WAAW,CAAC,CAAC,CAAC;gBACjB,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBAC1D,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,kBAAkB,CAAC,CAAC;gBAC/D,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACpB,OAAO,CAAC,KAAK,CACX,oCAAoC,kBAAkB,eAAe;wBACnE,qCAAqC,CACxC,CAAC;oBACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAClB,CAAC;gBACD,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC;gBAC7B,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;gBACtB,MAAM;YACR,CAAC;YACD,KAAK,QAAQ;gBACX,OAAO,CAAC,GAAG,CAAC;;;;;;;;;uDASmC,kBAAkB;;;;;;CAMxE,CAAC,CAAC;gBACK,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAE9C,iEAAiE;IACjE,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IAEhF,6CAA6C;IAC7C,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,YAAY,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxE,OAAO,CAAC,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACpE,OAAO,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAC;QACrD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,kBAAkB,CAAC,CAAC;IAC5E,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,OAAO,CAAC,IAAI,CACV,YAAY,WAAW,CAAC,MAAM,4BAA4B,kBAAkB,UAAU;YACpF,mDAAmD,CACtD,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAiB;QAC3B,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,MAAM,CAAC;QAC3D,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,WAAW;QACxD,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,mBAAmB;QACvE,cAAc,EAAE,IAAI,CAAC,cAAc,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;QAC5D,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,UAAU;QACnC,kBAAkB,EAAE,GAAG;KACxB,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,WAAW,CAAC;IAEhF,MAAM,MAAM,GAAG,IAAI,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAE7C,MAAM,QAAQ,GAAG,KAAK,IAAI,EAAE;QAC1B,OAAO,CAAC,GAAG,CAAC,wCAAwC,CAAC,CAAC;QACtD,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAC;IAE7C,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IAErB,6CAA6C;IAC7C,MAAM,SAAS,GAAG,GAAG,EAAE;QACrB,MAAM,IAAI,GAAG,MAAM,CAAC,YAAY,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QACxD,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,CAAC,GAAG,CAAC,kCAAkC,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACnD,CAAC;IACH,CAAC,CAAC;IAEF,4BAA4B;IAC5B,SAAS,EAAE,CAAC;IAEZ,wBAAwB;IACxB,WAAW,CAAC,SAAS,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;AAC9C,CAAC;AAED,KAAK,IAAI,EAAE,CAAC"}

package/dist/correlation-engine.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Threat Correlation Engine
+ * 威脅關聯引擎
+ *
+ * Groups related threat events into campaigns based on:
+ * 1. Same source IP within a time window (IP cluster)
+ * 2. Same attack pattern across multiple IPs (pattern cluster)
+ *
+ * @module @panguard-ai/threat-cloud/correlation-engine
+ */
+import type Database from 'better-sqlite3';
+import type { CorrelationConfig, Campaign, CampaignScanResult, CampaignStats, PaginationParams, PaginatedResponse, EnrichedThreatEvent } from './types.js';
+export declare class CorrelationEngine {
+    private readonly db;
+    private readonly config;
+    constructor(db: Database.Database, config?: Partial<CorrelationConfig>);
+    /** Create campaigns table if not exists / 建立 campaigns 表 */
+    private ensureTable;
+    /**
+     * Scan for new campaigns in uncorrelated events.
+     * 掃描未關聯的事件，建立新的攻擊活動
+     */
+    scanForCampaigns(): CampaignScanResult;
+    /** Get campaign by ID / 取得 campaign */
+    getCampaign(campaignId: string): Campaign | null;
+    /** List campaigns / 列表 campaigns */
+    listCampaigns(pagination: PaginationParams, status?: string): PaginatedResponse<Campaign>;
+    /** Get campaign events / 取得 campaign 事件 */
+    getCampaignEvents(campaignId: string): EnrichedThreatEvent[];
+    /** Get campaign statistics / 取得攻擊活動統計 */
+    getCampaignStats(): CampaignStats;
+    /** Cluster events by time window / 依時間窗口聚類事件 */
+    private clusterByTimeWindow;
+    /** Generate deterministic campaign ID / 產生確定性 campaign ID */
+    private generateCampaignId;
+    /** Pick the maximum severity / 選擇最高嚴重度 */
+    private pickMaxSeverity;
+    /** Upsert campaign / 新增或更新攻擊活動 */
+    private upsertCampaign;
+}
+//# sourceMappingURL=correlation-engine.d.ts.map

package/dist/correlation-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation-engine.d.ts","sourceRoot":"","sources":["../src/correlation-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EACV,iBAAiB,EACjB,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAgDpB,qBAAa,iBAAiB;IAI1B,OAAO,CAAC,QAAQ,CAAC,EAAE;IAHrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;gBAGxB,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACtC,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC;IAMrC,4DAA4D;IAC5D,OAAO,CAAC,WAAW;IAuBnB;;;OAGG;IACH,gBAAgB,IAAI,kBAAkB;IAiJtC,uCAAuC;IACvC,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAOhD,oCAAoC;IACpC,aAAa,CAAC,UAAU,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC;IAyBzF,2CAA2C;IAC3C,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,mBAAmB,EAAE;IA2B5D,yCAAyC;IACzC,gBAAgB,IAAI,aAAa;IAmCjC,gDAAgD;IAChD,OAAO,CAAC,mBAAmB;IAoB3B,6DAA6D;IAC7D,OAAO,CAAC,kBAAkB;IAO1B,0CAA0C;IAC1C,OAAO,CAAC,eAAe;IAQvB,kCAAkC;IAClC,OAAO,CAAC,cAAc;CA+BvB"}

package/dist/correlation-engine.js

@@ -0,0 +1,313 @@
+/**
+ * Threat Correlation Engine
+ * 威脅關聯引擎
+ *
+ * Groups related threat events into campaigns based on:
+ * 1. Same source IP within a time window (IP cluster)
+ * 2. Same attack pattern across multiple IPs (pattern cluster)
+ *
+ * @module @panguard-ai/threat-cloud/correlation-engine
+ */
+import { createHash } from 'node:crypto';
+/** Default config / 預設配置 */
+const DEFAULT_CONFIG = {
+    timeWindowMinutes: 60,
+    minEventsForCampaign: 3,
+    minIPsForPatternCampaign: 5,
+    scanWindowHours: 24,
+};
+/** Convert DB row to Campaign / 轉換 DB 列 */
+function rowToCampaign(row) {
+    return {
+        campaignId: row.campaign_id,
+        name: row.name,
+        campaignType: row.campaign_type,
+        firstSeen: row.first_seen,
+        lastSeen: row.last_seen,
+        eventCount: row.event_count,
+        uniqueIPs: row.unique_ips,
+        attackTypes: JSON.parse(row.attack_types),
+        mitreTechniques: JSON.parse(row.mitre_techniques),
+        regions: JSON.parse(row.regions),
+        severity: row.severity,
+        status: row.status,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+export class CorrelationEngine {
+    db;
+    config;
+    constructor(db, config) {
+        this.db = db;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.ensureTable();
+    }
+    /** Create campaigns table if not exists / 建立 campaigns 表 */
+    ensureTable() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS campaigns (
+        campaign_id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        campaign_type TEXT NOT NULL CHECK(campaign_type IN ('ip_cluster','pattern_cluster','manual')),
+        first_seen TEXT NOT NULL,
+        last_seen TEXT NOT NULL,
+        event_count INTEGER NOT NULL DEFAULT 0,
+        unique_ips INTEGER NOT NULL DEFAULT 0,
+        attack_types TEXT NOT NULL DEFAULT '[]',
+        mitre_techniques TEXT NOT NULL DEFAULT '[]',
+        regions TEXT NOT NULL DEFAULT '[]',
+        severity TEXT NOT NULL DEFAULT 'medium',
+        status TEXT NOT NULL DEFAULT 'active' CHECK(status IN ('active','resolved','false_positive')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_campaigns_status ON campaigns(status);
+      CREATE INDEX IF NOT EXISTS idx_campaigns_last_seen ON campaigns(last_seen);
+    `);
+    }
+    /**
+     * Scan for new campaigns in uncorrelated events.
+     * 掃描未關聯的事件，建立新的攻擊活動
+     */
+    scanForCampaigns() {
+        const startTime = Date.now();
+        let newCampaigns = 0;
+        const updatedCampaigns = 0;
+        let eventsCorrelated = 0;
+        const sinceDate = new Date(Date.now() - this.config.scanWindowHours * 60 * 60 * 1000).toISOString();
+        // Fetch uncorrelated events within scan window
+        const events = this.db
+            .prepare(`SELECT id, attack_source_ip, attack_type, mitre_techniques, timestamp, region, severity
+         FROM enriched_threats
+         WHERE campaign_id IS NULL AND received_at > ?
+         ORDER BY timestamp ASC`)
+            .all(sinceDate);
+        if (events.length === 0) {
+            return {
+                newCampaigns: 0,
+                updatedCampaigns: 0,
+                eventsCorrelated: 0,
+                duration: Date.now() - startTime,
+            };
+        }
+        // --- IP Cluster detection ---
+        const byIP = new Map();
+        for (const e of events) {
+            const list = byIP.get(e.attack_source_ip) ?? [];
+            list.push(e);
+            byIP.set(e.attack_source_ip, list);
+        }
+        const assignedIds = new Set();
+        const updateCampaignId = this.db.prepare('UPDATE enriched_threats SET campaign_id = ? WHERE id = ?');
+        this.db.transaction(() => {
+            for (const [ip, ipEvents] of byIP) {
+                if (ipEvents.length < this.config.minEventsForCampaign)
+                    continue;
+                // Check time window clustering
+                const clustered = this.clusterByTimeWindow(ipEvents);
+                for (const cluster of clustered) {
+                    if (cluster.length < this.config.minEventsForCampaign)
+                        continue;
+                    const campaignId = this.generateCampaignId(cluster.map((e) => e.id));
+                    const attackTypes = [...new Set(cluster.map((e) => e.attack_type))];
+                    const allTechniques = cluster.flatMap((e) => JSON.parse(e.mitre_techniques));
+                    const techniques = [...new Set(allTechniques)];
+                    const regions = [...new Set(cluster.map((e) => e.region))];
+                    const timestamps = cluster.map((e) => e.timestamp).sort();
+                    const maxSeverity = this.pickMaxSeverity(cluster.map((e) => e.severity));
+                    this.upsertCampaign({
+                        campaignId,
+                        name: `IP ${ip}: ${attackTypes.join(', ')}`,
+                        campaignType: 'ip_cluster',
+                        firstSeen: timestamps[0],
+                        lastSeen: timestamps[timestamps.length - 1],
+                        eventCount: cluster.length,
+                        uniqueIPs: 1,
+                        attackTypes,
+                        mitreTechniques: techniques,
+                        regions,
+                        severity: maxSeverity,
+                    });
+                    for (const e of cluster) {
+                        updateCampaignId.run(campaignId, e.id);
+                        assignedIds.add(e.id);
+                    }
+                    newCampaigns++;
+                    eventsCorrelated += cluster.length;
+                }
+            }
+            // --- Pattern Cluster detection ---
+            const unassigned = events.filter((e) => !assignedIds.has(e.id));
+            const byPattern = new Map();
+            for (const e of unassigned) {
+                const techniques = JSON.parse(e.mitre_techniques).sort().join(',');
+                const key = `${e.attack_type}|${techniques}`;
+                const list = byPattern.get(key) ?? [];
+                list.push(e);
+                byPattern.set(key, list);
+            }
+            for (const [pattern, patternEvents] of byPattern) {
+                const distinctIPs = new Set(patternEvents.map((e) => e.attack_source_ip));
+                if (distinctIPs.size < this.config.minIPsForPatternCampaign)
+                    continue;
+                const campaignId = this.generateCampaignId(patternEvents.map((e) => e.id));
+                const [attackType] = pattern.split('|');
+                const allTechniques = patternEvents.flatMap((e) => JSON.parse(e.mitre_techniques));
+                const techniques = [...new Set(allTechniques)];
+                const regions = [...new Set(patternEvents.map((e) => e.region))];
+                const timestamps = patternEvents.map((e) => e.timestamp).sort();
+                const maxSeverity = this.pickMaxSeverity(patternEvents.map((e) => e.severity));
+                this.upsertCampaign({
+                    campaignId,
+                    name: `Pattern: ${attackType} from ${distinctIPs.size} IPs`,
+                    campaignType: 'pattern_cluster',
+                    firstSeen: timestamps[0],
+                    lastSeen: timestamps[timestamps.length - 1],
+                    eventCount: patternEvents.length,
+                    uniqueIPs: distinctIPs.size,
+                    attackTypes: [attackType],
+                    mitreTechniques: techniques,
+                    regions,
+                    severity: maxSeverity,
+                });
+                for (const e of patternEvents) {
+                    updateCampaignId.run(campaignId, e.id);
+                }
+                newCampaigns++;
+                eventsCorrelated += patternEvents.length;
+            }
+        })();
+        return {
+            newCampaigns,
+            updatedCampaigns,
+            eventsCorrelated,
+            duration: Date.now() - startTime,
+        };
+    }
+    /** Get campaign by ID / 取得 campaign */
+    getCampaign(campaignId) {
+        const row = this.db.prepare('SELECT * FROM campaigns WHERE campaign_id = ?').get(campaignId);
+        return row ? rowToCampaign(row) : null;
+    }
+    /** List campaigns / 列表 campaigns */
+    listCampaigns(pagination, status) {
+        const where = status ? 'WHERE status = ?' : '';
+        const params = status ? [status] : [];
+        const safeLimit = Math.min(Math.max(1, pagination.limit), 1000);
+        const offset = (Math.max(1, pagination.page) - 1) * safeLimit;
+        const total = this.db.prepare(`SELECT COUNT(*) as count FROM campaigns ${where}`).get(...params).count;
+        const rows = this.db
+            .prepare(`SELECT * FROM campaigns ${where} ORDER BY last_seen DESC LIMIT ? OFFSET ?`)
+            .all(...params, safeLimit, offset);
+        return {
+            items: rows.map(rowToCampaign),
+            total,
+            page: pagination.page,
+            limit: safeLimit,
+            hasMore: offset + safeLimit < total,
+        };
+    }
+    /** Get campaign events / 取得 campaign 事件 */
+    getCampaignEvents(campaignId) {
+        const rows = this.db
+            .prepare('SELECT * FROM enriched_threats WHERE campaign_id = ? ORDER BY timestamp ASC')
+            .all(campaignId);
+        return rows.map((r) => ({
+            id: r['id'],
+            sourceType: r['source_type'],
+            attackSourceIP: r['attack_source_ip'],
+            attackType: r['attack_type'],
+            mitreTechniques: JSON.parse(r['mitre_techniques']),
+            sigmaRuleMatched: r['sigma_rule_matched'],
+            timestamp: r['timestamp'],
+            industry: r['industry'],
+            region: r['region'],
+            confidence: r['confidence'],
+            severity: r['severity'],
+            serviceType: r['service_type'],
+            skillLevel: r['skill_level'],
+            intent: r['intent'],
+            tools: r['tools'] ? JSON.parse(r['tools']) : undefined,
+            eventHash: r['event_hash'],
+            receivedAt: r['received_at'],
+            campaignId: r['campaign_id'],
+        }));
+    }
+    /** Get campaign statistics / 取得攻擊活動統計 */
+    getCampaignStats() {
+        const total = this.db.prepare('SELECT COUNT(*) as count FROM campaigns').get().count;
+        const active = this.db.prepare("SELECT COUNT(*) as count FROM campaigns WHERE status = 'active'").get().count;
+        const correlated = this.db
+            .prepare('SELECT COUNT(*) as count FROM enriched_threats WHERE campaign_id IS NOT NULL')
+            .get().count;
+        const topTypes = this.db
+            .prepare(`SELECT attack_type as type, COUNT(*) as count
+         FROM enriched_threats WHERE campaign_id IS NOT NULL
+         GROUP BY attack_type ORDER BY count DESC LIMIT 10`)
+            .all();
+        return {
+            totalCampaigns: total,
+            activeCampaigns: active,
+            totalCorrelatedEvents: correlated,
+            topAttackTypes: topTypes,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers / 私有輔助方法
+    // -------------------------------------------------------------------------
+    /** Cluster events by time window / 依時間窗口聚類事件 */
+    clusterByTimeWindow(events) {
+        if (events.length === 0)
+            return [];
+        const sorted = [...events].sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+        const windowMs = this.config.timeWindowMinutes * 60 * 1000;
+        const clusters = [[sorted[0]]];
+        for (let i = 1; i < sorted.length; i++) {
+            const current = new Date(sorted[i].timestamp).getTime();
+            const clusterStart = new Date(clusters[clusters.length - 1][0].timestamp).getTime();
+            if (current - clusterStart <= windowMs) {
+                clusters[clusters.length - 1].push(sorted[i]);
+            }
+            else {
+                clusters.push([sorted[i]]);
+            }
+        }
+        return clusters;
+    }
+    /** Generate deterministic campaign ID / 產生確定性 campaign ID */
+    generateCampaignId(eventIds) {
+        const sorted = [...eventIds].sort((a, b) => a - b);
+        const hash = createHash('sha256').update(sorted.join(',')).digest('hex').slice(0, 8);
+        const date = new Date().toISOString().slice(0, 10).replace(/-/g, '');
+        return `C-${date}-${hash}`;
+    }
+    /** Pick the maximum severity / 選擇最高嚴重度 */
+    pickMaxSeverity(severities) {
+        const order = ['critical', 'high', 'medium', 'low'];
+        for (const s of order) {
+            if (severities.includes(s))
+                return s;
+        }
+        return 'medium';
+    }
+    /** Upsert campaign / 新增或更新攻擊活動 */
+    upsertCampaign(c) {
+        this.db
+            .prepare(`INSERT INTO campaigns
+          (campaign_id, name, campaign_type, first_seen, last_seen, event_count, unique_ips,
+           attack_types, mitre_techniques, regions, severity)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(campaign_id) DO UPDATE SET
+          last_seen = excluded.last_seen,
+          event_count = excluded.event_count,
+          unique_ips = excluded.unique_ips,
+          attack_types = excluded.attack_types,
+          mitre_techniques = excluded.mitre_techniques,
+          regions = excluded.regions,
+          severity = excluded.severity,
+          updated_at = datetime('now')`)
+            .run(c.campaignId, c.name, c.campaignType, c.firstSeen, c.lastSeen, c.eventCount, c.uniqueIPs, JSON.stringify(c.attackTypes), JSON.stringify(c.mitreTechniques), JSON.stringify(c.regions), c.severity);
+    }
+}
+//# sourceMappingURL=correlation-engine.js.map