shroud-privacy 2.2.9 → 2.2.11

package/dist/siem.js

@@ -1,91 +1,113 @@
 /**
- * SIEM webhook forwarder — batch and async delivery of audit events.
- * Does not block obfuscation pipeline.
+ * SIEM integration — ships security events to external systems.
+ *
+ * Two output modes:
+ * 1. Webhook POST: sends events as JSON to a configured URL (Splunk HEC, Grafana Loki, custom)
+ * 2. JSONL file: appends events as newline-delimited JSON to a local file
+ *
+ * Both are async fire-and-forget — never blocks the request pipeline.
+ * Zero runtime dependencies.
  */
-export const DEFAULT_SIEM_CONFIG = {
-    webhookUrl: "",
-    headers: {},
-    batchSize: 10,
-    flushIntervalMs: 5000,
-    format: "json",
-};
-export class SiemForwarder {
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+/**
+ * SIEM event shipper. Subscribes to SecurityEventBus and ships events
+ * to configured destinations.
+ */
+export class SiemShipper {
     _config;
     _buffer = [];
-    _timer = null;
-    _sendCount = 0;
-    _errorCount = 0;
-    _lastError = null;
-    constructor(config = {}) {
-        this._config = { ...DEFAULT_SIEM_CONFIG, ...config };
-        if (this._config.webhookUrl) {
-            this._timer = setInterval(() => this.flush(), this._config.flushIntervalMs);
-            if (this._timer.unref)
-                this._timer.unref();
+    _flushTimer = null;
+    _stats = { shipped: 0, webhookErrors: 0, fileErrors: 0 };
+    constructor(config) {
+        this._config = config;
+        // Start flush timer if batching
+        if (config.batchSize > 1 && config.flushIntervalMs > 0) {
+            this._flushTimer = setInterval(() => this.flush(), config.flushIntervalMs);
+        }
+        // Ensure JSONL directory exists
+        if (config.jsonlPath) {
+            try {
+                mkdirSync(dirname(config.jsonlPath), { recursive: true });
+            }
+            catch { }
         }
     }
-    get enabled() {
-        return !!this._config.webhookUrl;
-    }
-    /** Queue an audit event for delivery. */
-    push(event) {
-        if (!this.enabled)
-            return;
-        this._buffer.push({
-            ...event,
-            _ts: new Date().toISOString(),
-            _source: "shroud",
-        });
+    /** Called for each security event. Buffers and flushes. */
+    onEvent(event) {
+        this._buffer.push(event);
         if (this._buffer.length >= this._config.batchSize) {
             this.flush();
         }
     }
-    /** Flush buffered events to the webhook. */
+    /** Flush buffered events to all configured destinations. */
     flush() {
-        if (this._buffer.length === 0 || !this.enabled)
+        if (this._buffer.length === 0)
             return;
         const events = this._buffer.splice(0);
-        const body = this._config.format === "ndjson"
-            ? events.map((e) => JSON.stringify(e)).join("\n") + "\n"
-            : JSON.stringify(events);
-        this._sendHttp(body).catch((err) => {
-            this._errorCount++;
-            this._lastError = String(err);
-        });
+        // JSONL file output
+        if (this._config.jsonlPath) {
+            try {
+                const lines = events.map(e => JSON.stringify(e)).join("\n") + "\n";
+                appendFileSync(this._config.jsonlPath, lines);
+                this._stats.shipped += events.length;
+            }
+            catch {
+                this._stats.fileErrors++;
+            }
+        }
+        // Webhook POST
+        if (this._config.webhookUrl) {
+            this._postWebhook(events);
+        }
     }
-    /** Stop the forwarder and flush remaining events. */
+    /** Stop the flush timer and flush remaining events. */
     stop() {
-        if (this._timer) {
-            clearInterval(this._timer);
-            this._timer = null;
+        if (this._flushTimer) {
+            clearInterval(this._flushTimer);
+            this._flushTimer = null;
         }
         this.flush();
     }
+    /** Get shipping stats. */
     getStats() {
-        return {
-            enabled: this.enabled,
-            buffered: this._buffer.length,
-            sent: this._sendCount,
-            errors: this._errorCount,
-            lastError: this._lastError,
-        };
+        return { ...this._stats, buffered: this._buffer.length };
     }
-    async _sendHttp(body) {
-        const contentType = this._config.format === "ndjson"
-            ? "application/x-ndjson"
-            : "application/json";
-        const resp = await fetch(this._config.webhookUrl, {
-            method: "POST",
-            headers: {
-                "Content-Type": contentType,
-                "User-Agent": "shroud-siem/1.0",
-                ...this._config.headers,
-            },
-            body,
-        });
-        if (!resp.ok) {
-            throw new Error(`SIEM webhook returned ${resp.status}`);
+    _postWebhook(events) {
+        try {
+            const url = new URL(this._config.webhookUrl);
+            const isHttps = url.protocol === "https:";
+            const reqFn = isHttps ? httpsRequest : httpRequest;
+            const body = JSON.stringify({ events, count: events.length, timestamp: new Date().toISOString() });
+            const options = {
+                hostname: url.hostname,
+                port: url.port || (isHttps ? 443 : 80),
+                path: url.pathname + url.search,
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Content-Length": Buffer.byteLength(body),
+                    ...(this._config.webhookAuth ? { Authorization: this._config.webhookAuth } : {}),
+                },
+            };
+            const req = reqFn(options, (res) => {
+                // Drain response
+                res.resume();
+                if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+                    this._stats.shipped += events.length;
+                }
+                else {
+                    this._stats.webhookErrors++;
+                }
+            });
+            req.on("error", () => { this._stats.webhookErrors++; });
+            req.write(body);
+            req.end();
+        }
+        catch {
+            this._stats.webhookErrors++;
         }
-        this._sendCount += 1;
     }
 }

package/dist/signature-loader.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Hot-refresh signature loader.
+ *
+ * Fetches external signature definitions from a URL or local file,
+ * merges them with built-in signatures at runtime. Supports periodic
+ * polling with atomic swap — no restart needed.
+ *
+ * Zero runtime dependencies — uses Node.js built-in http/https + fs.
+ *
+ * Signature JSON schema:
+ * {
+ *   "version": "1.0",
+ *   "updated": "2026-03-30T12:00:00Z",
+ *   "injectionSignatures": [
+ *     { "id": "custom_sig_1", "threatClass": "instruction_override",
+ *       "pattern": "ignore all safety", "flags": "gi",
+ *       "severity": "high", "description": "...", "direction": "request" }
+ *   ],
+ *   "toolGuardPatterns": [
+ *     { "id": "custom_tg_1", "paramPattern": "kubectl delete ns",
+ *       "flags": "gi", "severity": "high", "description": "...",
+ *       "block": true, "toolName": null }
+ *   ]
+ * }
+ */
+/** External signature definition (JSON-friendly — pattern is a string, not RegExp). */
+export interface ExternalSignature {
+    id: string;
+    threatClass: string;
+    pattern: string;
+    flags?: string;
+    severity: "low" | "medium" | "high";
+    description: string;
+    direction: "request" | "response" | "both";
+}
+/** External tool guard pattern (JSON-friendly). */
+export interface ExternalToolGuard {
+    id: string;
+    toolName: string | null;
+    paramPattern: string;
+    flags?: string;
+    severity: "low" | "medium" | "high";
+    description: string;
+    block: boolean;
+}
+/** The full signature feed payload. */
+export interface SignatureFeed {
+    version: string;
+    updated: string;
+    injectionSignatures?: ExternalSignature[];
+    toolGuardPatterns?: ExternalToolGuard[];
+}
+/** Compiled signatures ready for the scanner. */
+export interface CompiledSignatures {
+    injection: Array<{
+        id: string;
+        threatClass: string;
+        pattern: RegExp;
+        severity: "low" | "medium" | "high";
+        description: string;
+        direction: "request" | "response" | "both";
+    }>;
+    toolGuard: Array<{
+        id: string;
+        toolName: string | null;
+        paramPattern: RegExp;
+        severity: "low" | "medium" | "high";
+        description: string;
+        block: boolean;
+    }>;
+    feedVersion: string;
+    feedUpdated: string;
+    loadedAt: number;
+}
+/**
+ * Signature loader with hot-refresh support.
+ */
+export declare class SignatureLoader {
+    private _url;
+    private _filePath;
+    private _refreshMs;
+    private _timer;
+    private _current;
+    private _onUpdate;
+    private _cacheDir;
+    constructor(opts: {
+        url?: string | null;
+        filePath?: string | null;
+        refreshSec?: number;
+        cacheDir?: string;
+    });
+    /** Register a callback for when signatures are refreshed. */
+    onUpdate(cb: (sigs: CompiledSignatures) => void): void;
+    /** Get the currently loaded external signatures (null if none loaded). */
+    getCurrent(): CompiledSignatures | null;
+    /** Start polling. Does an immediate load, then polls on interval. */
+    start(): Promise<void>;
+    /** Stop polling. */
+    stop(): void;
+    /** Force a manual refresh. */
+    refresh(): Promise<CompiledSignatures | null>;
+    private _refresh;
+    /** Compile JSON signature definitions into RegExp objects with safety validation. */
+    private _compile;
+    /** Validate an injection signature before compilation. */
+    private _validateSig;
+    /** Validate a tool guard pattern before compilation. */
+    private _validateToolGuard;
+    /** Sanitize regex flags — only allow safe flags. */
+    private _sanitizeFlags;
+    /** Fetch a URL using Node.js built-in http/https. Zero dependencies. */
+    private _fetchUrl;
+}

package/dist/signature-loader.js

@@ -0,0 +1,255 @@
+/**
+ * Hot-refresh signature loader.
+ *
+ * Fetches external signature definitions from a URL or local file,
+ * merges them with built-in signatures at runtime. Supports periodic
+ * polling with atomic swap — no restart needed.
+ *
+ * Zero runtime dependencies — uses Node.js built-in http/https + fs.
+ *
+ * Signature JSON schema:
+ * {
+ *   "version": "1.0",
+ *   "updated": "2026-03-30T12:00:00Z",
+ *   "injectionSignatures": [
+ *     { "id": "custom_sig_1", "threatClass": "instruction_override",
+ *       "pattern": "ignore all safety", "flags": "gi",
+ *       "severity": "high", "description": "...", "direction": "request" }
+ *   ],
+ *   "toolGuardPatterns": [
+ *     { "id": "custom_tg_1", "paramPattern": "kubectl delete ns",
+ *       "flags": "gi", "severity": "high", "description": "...",
+ *       "block": true, "toolName": null }
+ *   ]
+ * }
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import * as nodeHttps from "node:https";
+import * as nodeHttp from "node:http";
+/**
+ * Signature loader with hot-refresh support.
+ */
+export class SignatureLoader {
+    _url;
+    _filePath;
+    _refreshMs;
+    _timer = null;
+    _current = null;
+    _onUpdate = null;
+    _cacheDir;
+    constructor(opts) {
+        this._url = opts.url || null;
+        this._filePath = opts.filePath || null;
+        this._refreshMs = (opts.refreshSec || 3600) * 1000;
+        this._cacheDir = opts.cacheDir || "/tmp/shroud-signatures";
+    }
+    /** Register a callback for when signatures are refreshed. */
+    onUpdate(cb) {
+        this._onUpdate = cb;
+    }
+    /** Get the currently loaded external signatures (null if none loaded). */
+    getCurrent() {
+        return this._current;
+    }
+    /** Start polling. Does an immediate load, then polls on interval. */
+    async start() {
+        if (!this._url && !this._filePath)
+            return;
+        // Immediate load
+        await this._refresh();
+        // Periodic poll
+        if (this._refreshMs > 0) {
+            this._timer = setInterval(() => this._refresh(), this._refreshMs);
+            // Don't keep the process alive for the timer
+            if (this._timer.unref)
+                this._timer.unref();
+        }
+    }
+    /** Stop polling. */
+    stop() {
+        if (this._timer) {
+            clearInterval(this._timer);
+            this._timer = null;
+        }
+    }
+    /** Force a manual refresh. */
+    async refresh() {
+        await this._refresh();
+        return this._current;
+    }
+    async _refresh() {
+        try {
+            let json = null;
+            // Try URL first
+            if (this._url) {
+                json = await this._fetchUrl(this._url);
+                // Cache to local file for offline resilience
+                if (json) {
+                    try {
+                        mkdirSync(this._cacheDir, { recursive: true });
+                        writeFileSync(join(this._cacheDir, "signatures-cache.json"), json, "utf-8");
+                    }
+                    catch { }
+                }
+            }
+            // Fall back to local file
+            if (!json && this._filePath) {
+                try {
+                    json = readFileSync(this._filePath, "utf-8");
+                }
+                catch { }
+            }
+            // Fall back to cached copy
+            if (!json) {
+                const cachePath = join(this._cacheDir, "signatures-cache.json");
+                if (existsSync(cachePath)) {
+                    try {
+                        json = readFileSync(cachePath, "utf-8");
+                    }
+                    catch { }
+                }
+            }
+            if (!json)
+                return;
+            // Max feed size: 500KB — reject bloated/malicious payloads
+            if (json.length > 512_000)
+                return;
+            const feed = JSON.parse(json);
+            // Max 500 signatures per feed — prevent resource exhaustion
+            if ((feed.injectionSignatures?.length || 0) > 500)
+                return;
+            if ((feed.toolGuardPatterns?.length || 0) > 500)
+                return;
+            const compiled = this._compile(feed);
+            // Only update if version changed or first load
+            if (!this._current || compiled.feedVersion !== this._current.feedVersion ||
+                compiled.feedUpdated !== this._current.feedUpdated) {
+                this._current = compiled;
+                if (this._onUpdate)
+                    this._onUpdate(compiled);
+            }
+        }
+        catch {
+            // Non-fatal — keep using existing signatures
+        }
+    }
+    /** Compile JSON signature definitions into RegExp objects with safety validation. */
+    _compile(feed) {
+        const injection = (feed.injectionSignatures || [])
+            .filter(sig => this._validateSig(sig))
+            .map(sig => ({
+            id: sig.id,
+            threatClass: sig.threatClass,
+            pattern: new RegExp(sig.pattern, this._sanitizeFlags(sig.flags)),
+            severity: sig.severity,
+            description: sig.description,
+            direction: sig.direction,
+        }));
+        const toolGuard = (feed.toolGuardPatterns || [])
+            .filter(tg => this._validateToolGuard(tg))
+            .map(tg => ({
+            id: tg.id,
+            toolName: tg.toolName,
+            paramPattern: new RegExp(tg.paramPattern, this._sanitizeFlags(tg.flags)),
+            severity: tg.severity,
+            description: tg.description,
+            block: tg.block,
+        }));
+        return {
+            injection,
+            toolGuard,
+            feedVersion: feed.version || "unknown",
+            feedUpdated: feed.updated || new Date().toISOString(),
+            loadedAt: Date.now(),
+        };
+    }
+    /** Validate an injection signature before compilation. */
+    _validateSig(sig) {
+        // Must have required fields
+        if (!sig.id || !sig.pattern || !sig.severity || !sig.direction)
+            return false;
+        // ID must be prefixed with ext_ (external signatures can't impersonate built-ins)
+        if (!sig.id.startsWith("ext_"))
+            return false;
+        // Severity must be valid
+        if (!["low", "medium", "high"].includes(sig.severity))
+            return false;
+        // Direction must be valid
+        if (!["request", "response", "both"].includes(sig.direction))
+            return false;
+        // Pattern length cap — prevents ReDoS via catastrophic backtracking
+        if (sig.pattern.length > 500)
+            return false;
+        // Block nested quantifiers (ReDoS: (a+)+ or (a*)*b)
+        if (/\([^)]*[+*][^)]*\)[+*]/.test(sig.pattern))
+            return false;
+        // Test compile — reject if regex is invalid
+        try {
+            new RegExp(sig.pattern);
+        }
+        catch {
+            return false;
+        }
+        // Description length cap
+        if ((sig.description || "").length > 300)
+            return false;
+        return true;
+    }
+    /** Validate a tool guard pattern before compilation. */
+    _validateToolGuard(tg) {
+        if (!tg.id || !tg.paramPattern || !tg.severity)
+            return false;
+        if (!tg.id.startsWith("ext_"))
+            return false;
+        if (!["low", "medium", "high"].includes(tg.severity))
+            return false;
+        if (tg.paramPattern.length > 500)
+            return false;
+        if (/\([^)]*[+*][^)]*\)[+*]/.test(tg.paramPattern))
+            return false;
+        try {
+            new RegExp(tg.paramPattern);
+        }
+        catch {
+            return false;
+        }
+        if ((tg.description || "").length > 300)
+            return false;
+        return true;
+    }
+    /** Sanitize regex flags — only allow safe flags. */
+    _sanitizeFlags(flags) {
+        if (!flags)
+            return "gi";
+        return flags.replace(/[^gimsuy]/g, "") || "gi";
+    }
+    /** Fetch a URL using Node.js built-in http/https. Zero dependencies. */
+    _fetchUrl(url) {
+        return new Promise((resolve) => {
+            try {
+                const mod = url.startsWith("https") ? nodeHttps : nodeHttp;
+                const req = mod.get(url, { timeout: 10_000 }, (res) => {
+                    // Follow redirects (1 level)
+                    if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+                        this._fetchUrl(res.headers.location).then(resolve);
+                        return;
+                    }
+                    if (res.statusCode !== 200) {
+                        resolve(null);
+                        return;
+                    }
+                    const chunks = [];
+                    res.on("data", (c) => chunks.push(c));
+                    res.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+                    res.on("error", () => resolve(null));
+                });
+                req.on("error", () => resolve(null));
+                req.on("timeout", () => { req.destroy(); resolve(null); });
+            }
+            catch {
+                resolve(null);
+            }
+        });
+    }
+}