@panguard-ai/panguard-guard 0.1.0

package/dist/agent/detect-agent.js

@@ -0,0 +1,214 @@
+/**
+ * Detect Agent - Event detection through rules, threat intelligence, and correlation
+ * 偵測代理 - 透過規則、威脅情報和事件關聯進行事件偵測
+ *
+ * First stage of the multi-agent pipeline. Receives raw SecurityEvents,
+ * runs them through the Sigma rule engine and threat intelligence feeds,
+ * correlates events within a sliding time window to detect attack chains,
+ * and emits DetectionResults for events that match.
+ *
+ * @module @panguard-ai/panguard-guard/agent/detect-agent
+ */
+import { createLogger, checkThreatIntel } from '@panguard-ai/core';
+const logger = createLogger('panguard-guard:detect-agent');
+/** Correlation window in ms (5 minutes) */
+const CORRELATION_WINDOW_MS = 5 * 60 * 1000;
+/** Max correlated events to keep in memory */
+const MAX_CORRELATION_BUFFER = 1000;
+/** Deduplication window in ms (60 seconds) */
+const DEDUP_WINDOW_MS = 60 * 1000;
+/** Max dedup entries to track */
+const MAX_DEDUP_ENTRIES = 500;
+/** Minimum events from same source to flag as attack chain */
+const ATTACK_CHAIN_THRESHOLD = 3;
+/**
+ * Detect Agent processes security events through rule matching,
+ * threat intelligence, event correlation, and deduplication.
+ */
+export class DetectAgent {
+    ruleEngine;
+    detectionCount = 0;
+    /** Sliding window for event correlation */
+    correlationBuffer = [];
+    /** Deduplication tracker: key → last detection timestamp */
+    dedupMap = new Map();
+    constructor(ruleEngine) {
+        this.ruleEngine = ruleEngine;
+    }
+    /**
+     * Process a security event and detect threats
+     *
+     * Steps:
+     * 1. Match the event against loaded Sigma rules
+     * 2. Check threat intelligence for network events (IP lookup, IPv4 + IPv6)
+     * 3. Deduplicate: skip if same source+rule fired within dedup window
+     * 4. Correlate: check sliding window for attack chain patterns
+     * 5. If any matches found, return a DetectionResult; otherwise null
+     */
+    detect(event) {
+        logger.info(`Processing event: ${event.id} [${event.source}]`);
+        // Step 1: Match against Sigma rules
+        const ruleMatches = this.ruleEngine.match(event);
+        // Step 2: Check threat intelligence (supports multiple IP fields)
+        let threatIntelMatch;
+        if (event.source === 'network' || event.source === 'suricata') {
+            const ip = this.extractIP(event);
+            if (ip) {
+                const threatEntry = checkThreatIntel(ip);
+                if (threatEntry) {
+                    threatIntelMatch = { ip, threat: `${threatEntry.type} (${threatEntry.source})` };
+                }
+            }
+        }
+        // If no matches found, return null (normal event)
+        if (ruleMatches.length === 0 && !threatIntelMatch) {
+            return null;
+        }
+        // Step 3: Deduplication — skip if identical detection within window
+        const dedupKey = this.buildDedupKey(event, ruleMatches);
+        if (this.isDuplicate(dedupKey)) {
+            logger.info(`Dedup: skipping duplicate detection for event ${event.id}`);
+            return null;
+        }
+        this.recordDedup(dedupKey);
+        // Step 4: Correlation — check for attack chain
+        const sourceIP = this.extractIP(event);
+        const ruleIds = ruleMatches.map((m) => m.rule.id);
+        const attackChain = this.correlate(event, ruleIds, sourceIP);
+        this.detectionCount++;
+        const result = {
+            event,
+            ruleMatches: ruleMatches.map((m) => ({
+                ruleId: m.rule.id,
+                ruleName: m.rule.title,
+                severity: (m.rule.level ?? 'medium'),
+            })),
+            threatIntelMatch,
+            timestamp: new Date().toISOString(),
+            // Attach correlation metadata if attack chain detected
+            ...(attackChain ? { attackChain } : {}),
+        };
+        logger.info(`Threat detected for event ${event.id}: ${ruleMatches.length} rule matches, ` +
+            `threat intel: ${threatIntelMatch ? 'yes' : 'no'}, ` +
+            `attack chain: ${attackChain ? `${attackChain.eventCount} events` : 'no'}`);
+        return result;
+    }
+    /**
+     * Extract IP address from event metadata (IPv4 + IPv6 support)
+     */
+    extractIP(event) {
+        const meta = event.metadata;
+        if (!meta)
+            return undefined;
+        // Check multiple possible IP fields
+        const candidates = [
+            meta['remoteAddress'],
+            meta['sourceIP'],
+            meta['src_ip'],
+            meta['destinationIP'],
+            meta['dst_ip'],
+            meta['clientIP'],
+            meta['peerAddress'],
+        ];
+        for (const candidate of candidates) {
+            if (typeof candidate === 'string' && candidate.length > 0) {
+                return candidate;
+            }
+        }
+        return undefined;
+    }
+    // ---------------------------------------------------------------------------
+    // Deduplication
+    // ---------------------------------------------------------------------------
+    /** Build a dedup key from event source + matched rule IDs */
+    buildDedupKey(event, matches) {
+        const ip = this.extractIP(event) ?? 'no-ip';
+        const rules = matches
+            .map((m) => m.rule.id)
+            .sort()
+            .join(',');
+        return `${event.source}:${ip}:${rules}`;
+    }
+    /** Check if this key was seen within the dedup window */
+    isDuplicate(key) {
+        const lastSeen = this.dedupMap.get(key);
+        if (!lastSeen)
+            return false;
+        return Date.now() - lastSeen < DEDUP_WINDOW_MS;
+    }
+    /** Record a dedup entry and evict old entries if over limit */
+    recordDedup(key) {
+        this.dedupMap.set(key, Date.now());
+        // Evict expired entries periodically
+        if (this.dedupMap.size > MAX_DEDUP_ENTRIES) {
+            const now = Date.now();
+            for (const [k, ts] of this.dedupMap) {
+                if (now - ts > DEDUP_WINDOW_MS) {
+                    this.dedupMap.delete(k);
+                }
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Event Correlation (Attack Chain Detection)
+    // ---------------------------------------------------------------------------
+    /**
+     * Correlate events within a sliding time window.
+     * Returns attack chain metadata if multiple events from same source detected.
+     */
+    correlate(event, ruleIds, sourceIP) {
+        const now = Date.now();
+        // Add current event to correlation buffer
+        this.correlationBuffer.push({
+            event,
+            ruleIds,
+            sourceIP,
+            timestamp: now,
+        });
+        // Evict events outside the correlation window
+        while (this.correlationBuffer.length > 0 &&
+            now - this.correlationBuffer[0].timestamp > CORRELATION_WINDOW_MS) {
+            this.correlationBuffer.shift();
+        }
+        // Trim buffer if too large
+        while (this.correlationBuffer.length > MAX_CORRELATION_BUFFER) {
+            this.correlationBuffer.shift();
+        }
+        // Only correlate if we have a source IP
+        if (!sourceIP)
+            return undefined;
+        // Find all events from this source IP within the window
+        const relatedEvents = this.correlationBuffer.filter((e) => e.sourceIP === sourceIP && now - e.timestamp <= CORRELATION_WINDOW_MS);
+        if (relatedEvents.length >= ATTACK_CHAIN_THRESHOLD) {
+            // Collect all unique rule IDs across the chain
+            const allRuleIds = new Set();
+            for (const re of relatedEvents) {
+                for (const rid of re.ruleIds) {
+                    allRuleIds.add(rid);
+                }
+            }
+            logger.warn(`Attack chain detected from ${sourceIP}: ${relatedEvents.length} events, ` +
+                `${allRuleIds.size} unique rules in ${CORRELATION_WINDOW_MS / 1000}s window`);
+            return {
+                sourceIP,
+                eventCount: relatedEvents.length,
+                ruleIds: [...allRuleIds],
+                windowMs: CORRELATION_WINDOW_MS,
+            };
+        }
+        return undefined;
+    }
+    /** Get total number of detections */
+    getDetectionCount() {
+        return this.detectionCount;
+    }
+    /** Get current correlation buffer size (for monitoring) */
+    getCorrelationBufferSize() {
+        return this.correlationBuffer.length;
+    }
+    /** Get current dedup map size (for monitoring) */
+    getDedupMapSize() {
+        return this.dedupMap.size;
+    }
+}
+//# sourceMappingURL=detect-agent.js.map

package/dist/agent/detect-agent.js.map

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

package/dist/agent/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Multi-Agent Pipeline
+ * 多代理管線
+ *
+ * Exports the four-agent pipeline: Detect -> Analyze -> Respond -> Report.
+ * 匯出四代理管線：偵測 -> 分析 -> 回應 -> 報告。
+ *
+ * @module @panguard-ai/panguard-guard/agent
+ */
+export { DetectAgent } from './detect-agent.js';
+export { AnalyzeAgent } from './analyze-agent.js';
+export { RespondAgent } from './respond-agent.js';
+export { ReportAgent } from './report-agent.js';
+export type { ReportRecord } from './report-agent.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/agent/index.js

@@ -0,0 +1,14 @@
+/**
+ * Multi-Agent Pipeline
+ * 多代理管線
+ *
+ * Exports the four-agent pipeline: Detect -> Analyze -> Respond -> Report.
+ * 匯出四代理管線：偵測 -> 分析 -> 回應 -> 報告。
+ *
+ * @module @panguard-ai/panguard-guard/agent
+ */
+export { DetectAgent } from './detect-agent.js';
+export { AnalyzeAgent } from './analyze-agent.js';
+export { RespondAgent } from './respond-agent.js';
+export { ReportAgent } from './report-agent.js';
+//# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/agent/report-agent.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Report Agent - Event logging with rotation, streaming reads, and retention policy
+ * 報告代理 - 事件記錄，支援 log rotation、串流讀取和資料保留策略
+ *
+ * Fourth stage of the multi-agent pipeline. Logs all events to JSONL with
+ * automatic rotation, updates the baseline during learning mode, and
+ * generates anonymized threat data for collective intelligence.
+ *
+ * @module @panguard-ai/panguard-guard/agent/report-agent
+ */
+import type { SecurityEvent } from '@panguard-ai/core';
+import type { ThreatVerdict, ResponseResult, EnvironmentBaseline, AnonymizedThreatData, GuardMode } from '../types.js';
+/** Full report record written to JSONL */
+export interface ReportRecord {
+    event: SecurityEvent;
+    verdict: ThreatVerdict;
+    response: ResponseResult;
+    timestamp: string;
+}
+/** Daily/weekly summary structure */
+export interface ReportSummary {
+    period: {
+        start: string;
+        end: string;
+    };
+    totalEvents: number;
+    threatsBlocked: number;
+    suspiciousEvents: number;
+    benignEvents: number;
+    topAttackSources: Array<{
+        ip: string;
+        count: number;
+    }>;
+    actionsTaken: Array<{
+        action: string;
+        count: number;
+    }>;
+    verdictBreakdown: {
+        benign: number;
+        suspicious: number;
+        malicious: number;
+    };
+}
+/** Log rotation configuration */
+interface RotationConfig {
+    /** Max log file size before rotation (default 50MB) */
+    maxFileSizeBytes: number;
+    /** Max number of rotated log files to keep (default 10) */
+    maxRotatedFiles: number;
+    /** Retention period in days (default 90) */
+    retentionDays: number;
+}
+/**
+ * Report Agent logs events with rotation, updates baselines, and generates anonymized data.
+ */
+export declare class ReportAgent {
+    private readonly logPath;
+    private mode;
+    private reportCount;
+    private readonly rotation;
+    constructor(logPath: string, mode: GuardMode, rotation?: Partial<RotationConfig>);
+    /** Update operating mode */
+    setMode(mode: GuardMode): void;
+    /**
+     * Process a complete pipeline result: log, update baseline, generate anonymized data.
+     * Automatically rotates log file when size limit is reached.
+     */
+    report(event: SecurityEvent, verdict: ThreatVerdict, response: ResponseResult, baseline: EnvironmentBaseline): {
+        updatedBaseline: EnvironmentBaseline;
+        anonymizedData?: AnonymizedThreatData;
+    };
+    /**
+     * Rotate log file if it exceeds the size limit.
+     * Naming: events.jsonl -> events.jsonl.1 -> events.jsonl.2 -> ...
+     * Oldest files beyond maxRotatedFiles are deleted.
+     */
+    private rotateIfNeeded;
+    /**
+     * Delete rotated log files beyond maxRotatedFiles and older than retentionDays
+     */
+    private enforceRetention;
+    private appendLog;
+    /**
+     * Read log records from JSONL using streaming (line-by-line).
+     * Only loads records after the cutoff date into memory.
+     * This replaces the previous readFileSync approach that loaded entire files.
+     */
+    readLogRecordsStreaming(after: Date): Promise<ReportRecord[]>;
+    /**
+     * Get all log files (current + rotated) sorted newest first
+     */
+    private getLogFiles;
+    /**
+     * Stream a single JSONL file, returning records after the cutoff
+     */
+    private streamFile;
+    /**
+     * Generate a summary for the given time period.
+     * Uses streaming reader for memory efficiency.
+     */
+    generateSummary(hoursBack: number): Promise<ReportSummary>;
+    /** Generate daily summary (last 24 hours) */
+    generateDailySummary(): Promise<ReportSummary>;
+    /** Generate weekly summary (last 7 days) */
+    generateWeeklySummary(): Promise<ReportSummary>;
+    /**
+     * Synchronous summary for backwards compatibility (reads current file only).
+     * Prefer async generateSummary() for production use.
+     */
+    generateSummarySync(hoursBack: number): ReportSummary;
+    /** Synchronous read of current log file only */
+    private readLogRecordsSync;
+    private generateAnonymizedData;
+    /** Get total report count */
+    getReportCount(): number;
+    /** Get current log file size in bytes */
+    getLogSizeBytes(): number;
+    /** Get number of rotated log files */
+    getRotatedFileCount(): number;
+}
+export {};
+//# sourceMappingURL=report-agent.d.ts.map

package/dist/agent/report-agent.d.ts.map

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