@panguard-ai/panguard-guard 0.1.0

package/dist/response/file-quarantine.js

@@ -0,0 +1,137 @@
+/**
+ * File Quarantine - Isolate suspicious files with metadata and restore
+ * 檔案隔離 - 隔離可疑檔案（含中繼資料與還原功能）
+ *
+ * Features:
+ * - Move files to quarantine directory with restricted permissions
+ * - SHA-256 hash recording for evidence
+ * - Quarantine manifest (JSON) for tracking
+ * - Restore functionality to return files to original location
+ *
+ * @module @panguard-ai/panguard-guard/response/file-quarantine
+ */
+import { createHash } from 'node:crypto';
+import { readFile, rename, mkdir, chmod, writeFile, readdir, stat } from 'node:fs/promises';
+import { join, basename, resolve, normalize } from 'node:path';
+import { homedir, platform } from 'node:os';
+import { createLogger } from '@panguard-ai/core';
+const logger = createLogger('panguard-guard:file-quarantine');
+/**
+ * Manages file quarantine with metadata tracking and restore
+ * 管理檔案隔離（含中繼資料追蹤與還原功能）
+ */
+export class FileQuarantine {
+    quarantineDir;
+    manifestPath;
+    manifest = { version: 1, records: [] };
+    constructor(quarantineDir) {
+        this.quarantineDir = quarantineDir ?? join(homedir(), '.panguard', 'quarantine');
+        this.manifestPath = join(this.quarantineDir, 'manifest.json');
+    }
+    /** Initialize quarantine directory / 初始化隔離目錄 */
+    async initialize() {
+        await mkdir(this.quarantineDir, { recursive: true, mode: 0o700 });
+        try {
+            const data = await readFile(this.manifestPath, 'utf-8');
+            this.manifest = JSON.parse(data);
+        }
+        catch {
+            // No existing manifest
+            this.manifest = { version: 1, records: [] };
+        }
+    }
+    /**
+     * Quarantine a file
+     * 隔離檔案
+     */
+    async quarantine(filePath, reason) {
+        await this.initialize();
+        const absPath = resolve(normalize(filePath));
+        // Prevent quarantining files inside the quarantine directory
+        if (absPath.startsWith(this.quarantineDir)) {
+            throw new Error('Cannot quarantine a file already in quarantine directory');
+        }
+        // Read file and compute hash before moving
+        const fileBuffer = await readFile(absPath);
+        const sha256 = createHash('sha256').update(fileBuffer).digest('hex');
+        const fileStat = await stat(absPath);
+        // Generate unique quarantine name
+        const id = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const quarantineName = `${id}_${basename(absPath)}`;
+        const quarantinePath = join(this.quarantineDir, quarantineName);
+        // Move file to quarantine
+        await rename(absPath, quarantinePath);
+        // Restrict permissions (not on Windows)
+        if (platform() !== 'win32') {
+            await chmod(quarantinePath, 0o000);
+        }
+        const record = {
+            id,
+            originalPath: absPath,
+            quarantinePath,
+            sha256,
+            fileSize: fileStat.size,
+            reason,
+            quarantinedAt: new Date().toISOString(),
+        };
+        this.manifest.records.push(record);
+        await this.saveManifest();
+        logger.info(`Quarantined: ${absPath} -> ${quarantinePath} (SHA-256: ${sha256.slice(0, 16)}...)`);
+        return record;
+    }
+    /**
+     * Restore a quarantined file to its original location
+     * 還原隔離檔案到原始位置
+     */
+    async restore(id) {
+        await this.initialize();
+        const record = this.manifest.records.find((r) => r.id === id);
+        if (!record) {
+            return { success: false, message: `Quarantine record not found: ${id}` };
+        }
+        if (record.restoredAt) {
+            return { success: false, message: `File already restored at ${record.restoredAt}` };
+        }
+        try {
+            // Restore permissions before moving
+            if (platform() !== 'win32') {
+                await chmod(record.quarantinePath, 0o644);
+            }
+            await rename(record.quarantinePath, record.originalPath);
+            record.restoredAt = new Date().toISOString();
+            await this.saveManifest();
+            logger.info(`Restored: ${record.quarantinePath} -> ${record.originalPath}`);
+            return { success: true, message: `File restored to ${record.originalPath}` };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { success: false, message: `Restore failed: ${msg}` };
+        }
+    }
+    /** Get all quarantine records / 取得所有隔離紀錄 */
+    getRecords() {
+        return [...this.manifest.records];
+    }
+    /** Get active (not restored) quarantine records / 取得未還原的隔離紀錄 */
+    getActiveRecords() {
+        return this.manifest.records.filter((r) => !r.restoredAt);
+    }
+    /** Find record by ID / 以 ID 搜尋紀錄 */
+    findRecord(id) {
+        return this.manifest.records.find((r) => r.id === id);
+    }
+    /** Count files in quarantine / 隔離區檔案數量 */
+    async getQuarantineCount() {
+        try {
+            const files = await readdir(this.quarantineDir);
+            return files.filter((f) => f !== 'manifest.json').length;
+        }
+        catch {
+            return 0;
+        }
+    }
+    async saveManifest() {
+        await writeFile(this.manifestPath, JSON.stringify(this.manifest, null, 2), 'utf-8');
+    }
+}
+//# sourceMappingURL=file-quarantine.js.map

package/dist/response/file-quarantine.js.map

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

package/dist/response/index.d.ts

@@ -0,0 +1,4 @@
+export { IPBlocker, type BlockRecord, type IPBlockerConfig } from './ip-blocker.js';
+export { FileQuarantine, type QuarantineRecord, type QuarantineManifest, } from './file-quarantine.js';
+export { ProcessKiller, type KillResult } from './process-killer.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/response/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACpF,OAAO,EACL,cAAc,EACd,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/response/index.js

@@ -0,0 +1,4 @@
+export { IPBlocker } from './ip-blocker.js';
+export { FileQuarantine, } from './file-quarantine.js';
+export { ProcessKiller } from './process-killer.js';
+//# sourceMappingURL=index.js.map

package/dist/response/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/response/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAA0C,MAAM,iBAAiB,CAAC;AACpF,OAAO,EACL,cAAc,GAGf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAmB,MAAM,qBAAqB,CAAC"}

package/dist/response/ip-blocker.d.ts

@@ -0,0 +1,69 @@
+/**
+ * IP Blocker - Cross-platform firewall rule management with auto-unblock
+ * IP 封鎖器 - 跨平台防火牆規則管理與自動解封
+ *
+ * Features:
+ * - Platform-aware blocking (pfctl / iptables / netsh)
+ * - Auto-unblock timer (default 24h)
+ * - Persistent whitelist
+ * - Block manifest tracking
+ *
+ * @module @panguard-ai/panguard-guard/response/ip-blocker
+ */
+/** Record of a blocked IP / 封鎖 IP 紀錄 */
+export interface BlockRecord {
+    ip: string;
+    blockedAt: string;
+    expiresAt: string;
+    reason: string;
+    autoUnblock: boolean;
+}
+/** IP Blocker configuration / IP 封鎖器設定 */
+export interface IPBlockerConfig {
+    /** Default block duration in ms (default 24h) / 預設封鎖時長 */
+    defaultBlockDurationMs: number;
+    /** IPs that can never be blocked / 永不封鎖的 IP */
+    whitelist: string[];
+    /** Enable auto-unblock timer / 啟用自動解封 */
+    autoUnblockEnabled: boolean;
+}
+/**
+ * Manages IP blocking with auto-unblock timers
+ * 管理 IP 封鎖與自動解封計時器
+ */
+export declare class IPBlocker {
+    private readonly config;
+    private readonly blocked;
+    private readonly whitelist;
+    private unblockTimers;
+    constructor(config?: Partial<IPBlockerConfig>);
+    /** Check if IP is whitelisted / 檢查 IP 是否在白名單 */
+    isWhitelisted(ip: string): boolean;
+    /** Check if IP is currently blocked / 檢查 IP 是否已封鎖 */
+    isBlocked(ip: string): boolean;
+    /** Get all currently blocked IPs / 取得所有已封鎖的 IP */
+    getBlockedIPs(): BlockRecord[];
+    /**
+     * Block an IP address
+     * 封鎖 IP 位址
+     */
+    block(ip: string, reason: string, durationMs?: number): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Unblock an IP address
+     * 解封 IP 位址
+     */
+    unblock(ip: string, reason: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /** Add whitelist entry / 新增白名單條目 */
+    addToWhitelist(ip: string): void;
+    /** Clean up all timers / 清理所有計時器 */
+    destroy(): void;
+    private addFirewallRule;
+    private removeFirewallRule;
+}
+//# sourceMappingURL=ip-blocker.d.ts.map

package/dist/response/ip-blocker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ip-blocker.d.ts","sourceRoot":"","sources":["../../src/response/ip-blocker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,wCAAwC;AACxC,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,sBAAsB,EAAE,MAAM,CAAC;IAC/B,+CAA+C;IAC/C,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,yCAAyC;IACzC,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAQD;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,aAAa,CAAyD;gBAElE,MAAM,GAAE,OAAO,CAAC,eAAe,CAAM;IAKjD,gDAAgD;IAChD,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIlC,qDAAqD;IACrD,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI9B,kDAAkD;IAClD,aAAa,IAAI,WAAW,EAAE;IAI9B;;;OAGG;IACG,KAAK,CACT,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAsDjD;;;OAGG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IA0BzF,oCAAoC;IACpC,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIhC,oCAAoC;IACpC,OAAO,IAAI,IAAI;YASD,eAAe;YAoBf,kBAAkB;CAgBjC"}

package/dist/response/ip-blocker.js

@@ -0,0 +1,191 @@
+/**
+ * IP Blocker - Cross-platform firewall rule management with auto-unblock
+ * IP 封鎖器 - 跨平台防火牆規則管理與自動解封
+ *
+ * Features:
+ * - Platform-aware blocking (pfctl / iptables / netsh)
+ * - Auto-unblock timer (default 24h)
+ * - Persistent whitelist
+ * - Block manifest tracking
+ *
+ * @module @panguard-ai/panguard-guard/response/ip-blocker
+ */
+import { execFile } from 'node:child_process';
+import { platform } from 'node:os';
+import { createLogger } from '@panguard-ai/core';
+const logger = createLogger('panguard-guard:ip-blocker');
+const DEFAULT_CONFIG = {
+    defaultBlockDurationMs: 24 * 60 * 60 * 1000, // 24h
+    whitelist: ['127.0.0.1', '::1', '0.0.0.0', 'localhost'],
+    autoUnblockEnabled: true,
+};
+/**
+ * Manages IP blocking with auto-unblock timers
+ * 管理 IP 封鎖與自動解封計時器
+ */
+export class IPBlocker {
+    config;
+    blocked = new Map();
+    whitelist;
+    unblockTimers = new Map();
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.whitelist = new Set([...DEFAULT_CONFIG.whitelist, ...(config.whitelist ?? [])]);
+    }
+    /** Check if IP is whitelisted / 檢查 IP 是否在白名單 */
+    isWhitelisted(ip) {
+        return this.whitelist.has(ip);
+    }
+    /** Check if IP is currently blocked / 檢查 IP 是否已封鎖 */
+    isBlocked(ip) {
+        return this.blocked.has(ip);
+    }
+    /** Get all currently blocked IPs / 取得所有已封鎖的 IP */
+    getBlockedIPs() {
+        return Array.from(this.blocked.values());
+    }
+    /**
+     * Block an IP address
+     * 封鎖 IP 位址
+     */
+    async block(ip, reason, durationMs) {
+        // Whitelist check
+        if (this.whitelist.has(ip)) {
+            logger.warn(`Refusing to block whitelisted IP: ${ip}`);
+            return { success: false, message: `IP ${ip} is whitelisted` };
+        }
+        // Already blocked check
+        if (this.blocked.has(ip)) {
+            return { success: true, message: `IP ${ip} is already blocked` };
+        }
+        // Validate IP format
+        if (!isValidIP(ip)) {
+            return { success: false, message: `Invalid IP format: ${ip}` };
+        }
+        const duration = durationMs ?? this.config.defaultBlockDurationMs;
+        const now = new Date();
+        const expiresAt = new Date(now.getTime() + duration);
+        // Execute platform firewall command
+        try {
+            await this.addFirewallRule(ip);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.error(`Failed to block IP ${ip}: ${msg}`);
+            return { success: false, message: `Firewall error: ${msg}` };
+        }
+        // Record block
+        const record = {
+            ip,
+            blockedAt: now.toISOString(),
+            expiresAt: expiresAt.toISOString(),
+            reason,
+            autoUnblock: this.config.autoUnblockEnabled,
+        };
+        this.blocked.set(ip, record);
+        // Set auto-unblock timer
+        if (this.config.autoUnblockEnabled) {
+            const timer = setTimeout(() => {
+                void this.unblock(ip, 'auto-unblock: duration expired');
+            }, duration);
+            // Don't prevent process exit
+            if (timer.unref)
+                timer.unref();
+            this.unblockTimers.set(ip, timer);
+        }
+        logger.info(`Blocked IP ${ip} for ${Math.round(duration / 60000)} minutes. Reason: ${reason}`);
+        return { success: true, message: `IP ${ip} blocked until ${expiresAt.toISOString()}` };
+    }
+    /**
+     * Unblock an IP address
+     * 解封 IP 位址
+     */
+    async unblock(ip, reason) {
+        if (!this.blocked.has(ip)) {
+            return { success: true, message: `IP ${ip} is not blocked` };
+        }
+        try {
+            await this.removeFirewallRule(ip);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.error(`Failed to unblock IP ${ip}: ${msg}`);
+            return { success: false, message: `Firewall error: ${msg}` };
+        }
+        this.blocked.delete(ip);
+        // Clear timer
+        const timer = this.unblockTimers.get(ip);
+        if (timer) {
+            clearTimeout(timer);
+            this.unblockTimers.delete(ip);
+        }
+        logger.info(`Unblocked IP ${ip}. Reason: ${reason}`);
+        return { success: true, message: `IP ${ip} unblocked` };
+    }
+    /** Add whitelist entry / 新增白名單條目 */
+    addToWhitelist(ip) {
+        this.whitelist.add(ip);
+    }
+    /** Clean up all timers / 清理所有計時器 */
+    destroy() {
+        for (const timer of this.unblockTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.unblockTimers.clear();
+    }
+    // -- Platform firewall commands --
+    async addFirewallRule(ip) {
+        const os = platform();
+        if (os === 'darwin') {
+            await execFilePromise('/sbin/pfctl', ['-t', 'panguard_blocked', '-T', 'add', ip]);
+        }
+        else if (os === 'linux') {
+            await execFilePromise('/sbin/iptables', ['-A', 'INPUT', '-s', ip, '-j', 'DROP']);
+        }
+        else if (os === 'win32') {
+            await execFilePromise('netsh', [
+                'advfirewall',
+                'firewall',
+                'add',
+                'rule',
+                `name=Panguard_Block_${ip}`,
+                'dir=in',
+                'action=block',
+                `remoteip=${ip}`,
+            ]);
+        }
+    }
+    async removeFirewallRule(ip) {
+        const os = platform();
+        if (os === 'darwin') {
+            await execFilePromise('/sbin/pfctl', ['-t', 'panguard_blocked', '-T', 'delete', ip]);
+        }
+        else if (os === 'linux') {
+            await execFilePromise('/sbin/iptables', ['-D', 'INPUT', '-s', ip, '-j', 'DROP']);
+        }
+        else if (os === 'win32') {
+            await execFilePromise('netsh', [
+                'advfirewall',
+                'firewall',
+                'delete',
+                'rule',
+                `name=Panguard_Block_${ip}`,
+            ]);
+        }
+    }
+}
+/** Validate IPv4 or IPv6 format / 驗證 IPv4 或 IPv6 格式 */
+function isValidIP(ip) {
+    return /^[\d.]+$/.test(ip) || /^[a-fA-F\d:]+$/.test(ip);
+}
+function execFilePromise(command, args) {
+    return new Promise((resolve, reject) => {
+        execFile(command, args, { timeout: 10000 }, (error, stdout) => {
+            if (error)
+                reject(error);
+            else
+                resolve(stdout);
+        });
+    });
+}
+//# sourceMappingURL=ip-blocker.js.map

package/dist/response/ip-blocker.js.map

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

package/dist/response/process-killer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Process Killer - Terminate processes with child cleanup and safety checks
+ * 程序終止器 - 終止程序（含子程序清理與安全檢查）
+ *
+ * Features:
+ * - Kill process and all child processes (process tree)
+ * - Protected process list (never kill system-critical processes)
+ * - SIGTERM first, SIGKILL after timeout
+ * - Cross-platform support
+ *
+ * @module @panguard-ai/panguard-guard/response/process-killer
+ */
+/** Process kill result / 程序終止結果 */
+export interface KillResult {
+    pid: number;
+    processName?: string;
+    success: boolean;
+    message: string;
+    childrenKilled: number;
+}
+/**
+ * Process Killer with safety checks and tree killing
+ * 程序終止器（含安全檢查與程序樹終止）
+ */
+export declare class ProcessKiller {
+    private readonly additionalProtected;
+    constructor(additionalProtectedProcesses?: string[]);
+    /** Check if process name is protected / 檢查程序名稱是否受保護 */
+    isProtected(nameOrPid: string | number): boolean;
+    /**
+     * Kill a process and optionally its children
+     * 終止程序（可選終止子程序）
+     */
+    kill(pid: number, options?: {
+        processName?: string;
+        killChildren?: boolean;
+        gracePeriodMs?: number;
+    }): Promise<KillResult>;
+    /**
+     * Get child PIDs of a process / 取得程序的子 PID
+     */
+    private getChildPIDs;
+    /**
+     * Wait for process to exit, return true if still alive
+     * 等待程序退出，如果仍存活則回傳 true
+     */
+    private waitForExit;
+}
+//# sourceMappingURL=process-killer.d.ts.map

package/dist/response/process-killer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-killer.d.ts","sourceRoot":"","sources":["../../src/response/process-killer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,mCAAmC;AACnC,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;CACxB;AA6CD;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAc;gBAEtC,4BAA4B,GAAE,MAAM,EAAO;IAIvD,uDAAuD;IACvD,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO;IAOhD;;;OAGG;IACG,IAAI,CACR,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAO,GACrF,OAAO,CAAC,UAAU,CAAC;IA6FtB;;OAEG;YACW,YAAY;IA4B1B;;;OAGG;IACH,OAAO,CAAC,WAAW;CAkBpB"}