shroud-privacy 2.0.14 → 2.0.18

package/dist/compliance.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Compliance reporter — generates category coverage and detection gap reports.
+ */
+export interface ComplianceConfig {
+    /** Path to write report. Empty = disabled. */
+    reportPath: string;
+    /** Report interval: "hourly" | "daily". */
+    reportInterval: "hourly" | "daily";
+    /** Required categories that MUST have detections. */
+    requiredCategories: string[];
+}
+export interface ComplianceReport {
+    generatedAt: string;
+    periodStart: string;
+    periodEnd: string;
+    /** Categories that had detections. */
+    activeCategoryCoverage: Record<string, number>;
+    /** Required categories with zero detections (gaps). */
+    detectionGaps: string[];
+    /** Total entities detected in period. */
+    totalEntities: number;
+    /** Store utilization. */
+    storeMappings: number;
+    /** Allowlist usage (how many entities were skipped). */
+    allowlistSkips: number;
+    /** Compliance score: % of required categories with detections. */
+    complianceScore: number;
+}
+export declare class ComplianceReporter {
+    private _config;
+    private _periodStart;
+    private _categoryCounts;
+    private _totalEntities;
+    private _allowlistSkips;
+    constructor(config?: Partial<ComplianceConfig>);
+    get enabled(): boolean;
+    /** Record detection event. */
+    recordDetections(categoryCounts: Record<string, number>, allowlistSkips?: number): void;
+    /** Generate and optionally write a compliance report. */
+    generateReport(storeMappings?: number): ComplianceReport;
+    /** Reset for new period. */
+    resetPeriod(): void;
+    getStats(): object;
+}

package/dist/compliance.js

@@ -0,0 +1,76 @@
+/**
+ * Compliance reporter — generates category coverage and detection gap reports.
+ */
+import { writeFileSync } from "node:fs";
+export class ComplianceReporter {
+    _config;
+    _periodStart;
+    _categoryCounts = {};
+    _totalEntities = 0;
+    _allowlistSkips = 0;
+    constructor(config = {}) {
+        this._config = {
+            reportPath: config.reportPath ?? "",
+            reportInterval: config.reportInterval ?? "daily",
+            requiredCategories: config.requiredCategories ?? [],
+        };
+        this._periodStart = new Date().toISOString();
+    }
+    get enabled() {
+        return !!this._config.reportPath;
+    }
+    /** Record detection event. */
+    recordDetections(categoryCounts, allowlistSkips = 0) {
+        for (const [cat, count] of Object.entries(categoryCounts)) {
+            this._categoryCounts[cat] = (this._categoryCounts[cat] ?? 0) + count;
+        }
+        this._totalEntities += Object.values(categoryCounts).reduce((a, b) => a + b, 0);
+        this._allowlistSkips += allowlistSkips;
+    }
+    /** Generate and optionally write a compliance report. */
+    generateReport(storeMappings = 0) {
+        const now = new Date().toISOString();
+        const gaps = this._config.requiredCategories.filter((cat) => (this._categoryCounts[cat] ?? 0) === 0);
+        const coveredRequired = this._config.requiredCategories.filter((cat) => (this._categoryCounts[cat] ?? 0) > 0);
+        const score = this._config.requiredCategories.length > 0
+            ? Math.round((coveredRequired.length / this._config.requiredCategories.length) *
+                100)
+            : 100;
+        const report = {
+            generatedAt: now,
+            periodStart: this._periodStart,
+            periodEnd: now,
+            activeCategoryCoverage: { ...this._categoryCounts },
+            detectionGaps: gaps,
+            totalEntities: this._totalEntities,
+            storeMappings,
+            allowlistSkips: this._allowlistSkips,
+            complianceScore: score,
+        };
+        if (this._config.reportPath) {
+            try {
+                writeFileSync(this._config.reportPath, JSON.stringify(report, null, 2) + "\n");
+            }
+            catch {
+                // best-effort
+            }
+        }
+        return report;
+    }
+    /** Reset for new period. */
+    resetPeriod() {
+        this._categoryCounts = {};
+        this._totalEntities = 0;
+        this._allowlistSkips = 0;
+        this._periodStart = new Date().toISOString();
+    }
+    getStats() {
+        return {
+            enabled: this.enabled,
+            periodStart: this._periodStart,
+            totalEntities: this._totalEntities,
+            categoryCoverage: Object.keys(this._categoryCounts).length,
+            requiredCategories: this._config.requiredCategories.length,
+        };
+    }
+}

package/dist/detectors/regex.js

@@ -29,6 +29,11 @@ const DOC_HOSTNAMES = new Set([
     "localhost", "HOSTNAME", "EXAMPLE", "CHANGEME",
     "YOUR_HOST", "YOURHOST", "hostname", "example",
 ]);
+/** Hostname prefixes that are documentation/example labels, not real devices. */
+const DOC_HOSTNAME_PREFIXES = [
+    "TEST-NET-", "TEST-", "RFC-", "EXAMPLE-", "SAMPLE-", "DEMO-", "DUMMY-",
+    "PLACEHOLDER-", "CHANGEME-", "TODO-",
+];
 /** IPv6 documentation/reserved prefixes that should not be obfuscated. */
 const DOC_IPV6_PREFIXES = [
     "2001:db8:", // RFC 3849 documentation prefix
@@ -75,7 +80,13 @@ export function isDocExample(value, category) {
             // Private ASNs are real infra identifiers — don't skip them
             return false;
         case Category.HOSTNAME:
-            return DOC_HOSTNAMES.has(value) || DOC_HOSTNAMES.has(value.toUpperCase());
+            if (DOC_HOSTNAMES.has(value) || DOC_HOSTNAMES.has(value.toUpperCase()))
+                return true;
+            for (const pfx of DOC_HOSTNAME_PREFIXES) {
+                if (value.toUpperCase().startsWith(pfx))
+                    return true;
+            }
+            return false;
         default:
             return false;
     }
@@ -321,6 +332,49 @@ export const BUILTIN_PATTERNS = [
         category: Category.NETWORK_CREDENTIAL,
         confidence: 1.0,
     },
+    // --- VRF ---
+    {
+        // "ip vrf VRF-NAME" (IOS classic) — exclude "forwarding" and "context"
+        name: "vrf_name_classic",
+        pattern: /(?:ip\s+vrf\s+)(?!forwarding\b|context\b)(\S+)/gi,
+        category: Category.VLAN_ID,
+        confidence: 0.95,
+    },
+    {
+        // "vrf definition VRF-NAME" (IOS-XE / IOS-XR)
+        name: "vrf_definition",
+        pattern: /(?:vrf\s+definition\s+)(\S+)/gi,
+        category: Category.VLAN_ID,
+        confidence: 0.95,
+    },
+    {
+        // "vrf forwarding VRF-NAME" or "ip vrf forwarding VRF-NAME" (interface binding)
+        name: "vrf_forwarding",
+        pattern: /(?:(?:ip\s+)?vrf\s+forwarding\s+)(\S+)/gi,
+        category: Category.VLAN_ID,
+        confidence: 0.95,
+    },
+    {
+        // "vrf VRF-NAME" in Junos / NX-OS (standalone)
+        name: "vrf_junos",
+        pattern: /(?:^|\n)\s*vrf\s+(\S+)\s*$/gm,
+        category: Category.VLAN_ID,
+        confidence: 0.85,
+    },
+    {
+        // Route distinguisher: "rd 65001:100"
+        name: "route_distinguisher",
+        pattern: /(?:rd\s+)(\d+:\d+)/g,
+        category: Category.VLAN_ID,
+        confidence: 0.90,
+    },
+    {
+        // Route target: "route-target export 65001:100"
+        name: "route_target",
+        pattern: /(?:route-target\s+(?:export|import|both)\s+)(\d+:\d+)/gi,
+        category: Category.VLAN_ID,
+        confidence: 0.90,
+    },
     // --- VLAN ---
     {
         name: "vlan_name",
@@ -392,6 +446,14 @@ export const BUILTIN_PATTERNS = [
         category: Category.HOSTNAME,
         confidence: 0.70,
     },
+    {
+        // Uppercase infrastructure hostnames: PROD-DB-01, AMS-CORE-SW-01, FRA-EDGE-FW-01
+        // Pattern: 2-5 uppercase segments separated by hyphens, ending with digits
+        name: "device_name_infra",
+        pattern: /\b([A-Z][A-Z0-9]{1,10}(?:-[A-Z][A-Z0-9]{0,10}){1,5}-\d{1,3})\b/g,
+        category: Category.HOSTNAME,
+        confidence: 0.80,
+    },
     // --- Syslog / monitoring (#5) ---
     {
         // Cisco syslog facility: %SYS-5-CONFIG_I, %LINK-3-UPDOWN

package/dist/exposure.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Rate-of-exposure tracker — monitors entity detection velocity.
+ * Alerts when entities/minute exceeds threshold, indicating potential
+ * bulk data exfiltration or unusual activity.
+ */
+export interface ExposureConfig {
+    /** Entities per minute threshold. 0 = disabled. */
+    rateThreshold: number;
+    /** Window size in seconds for rate calculation. Default: 60. */
+    windowSeconds: number;
+    /** Callback when threshold exceeded. */
+    onAlert?: (rate: number, threshold: number, window: number) => void;
+}
+export declare class ExposureTracker {
+    private _config;
+    private _timestamps;
+    private _alertCount;
+    private _lastAlertTime;
+    /** Minimum interval between alerts (ms) to prevent alert storms. */
+    private _alertCooldownMs;
+    constructor(config?: Partial<ExposureConfig>);
+    get enabled(): boolean;
+    /** Record entity detections. */
+    record(entityCount: number): void;
+    /** Current rate (entities/minute). */
+    currentRate(): number;
+    getStats(): object;
+    reset(): void;
+}

package/dist/exposure.js

@@ -0,0 +1,72 @@
+/**
+ * Rate-of-exposure tracker — monitors entity detection velocity.
+ * Alerts when entities/minute exceeds threshold, indicating potential
+ * bulk data exfiltration or unusual activity.
+ */
+export class ExposureTracker {
+    _config;
+    _timestamps = [];
+    _alertCount = 0;
+    _lastAlertTime = 0;
+    /** Minimum interval between alerts (ms) to prevent alert storms. */
+    _alertCooldownMs = 60000;
+    constructor(config = {}) {
+        this._config = {
+            rateThreshold: config.rateThreshold ?? 0,
+            windowSeconds: config.windowSeconds ?? 60,
+            onAlert: config.onAlert,
+        };
+    }
+    get enabled() {
+        return this._config.rateThreshold > 0;
+    }
+    /** Record entity detections. */
+    record(entityCount) {
+        if (!this.enabled || entityCount === 0)
+            return;
+        const now = Date.now();
+        for (let i = 0; i < entityCount; i++) {
+            this._timestamps.push(now);
+        }
+        // Trim old timestamps outside the window
+        const cutoff = now - this._config.windowSeconds * 1000;
+        while (this._timestamps.length > 0 && this._timestamps[0] < cutoff) {
+            this._timestamps.shift();
+        }
+        // Check rate
+        const windowMinutes = this._config.windowSeconds / 60;
+        const rate = this._timestamps.length / windowMinutes;
+        if (rate > this._config.rateThreshold) {
+            if (now - this._lastAlertTime > this._alertCooldownMs) {
+                this._alertCount++;
+                this._lastAlertTime = now;
+                this._config.onAlert?.(Math.round(rate), this._config.rateThreshold, this._config.windowSeconds);
+            }
+        }
+    }
+    /** Current rate (entities/minute). */
+    currentRate() {
+        const now = Date.now();
+        const cutoff = now - this._config.windowSeconds * 1000;
+        while (this._timestamps.length > 0 && this._timestamps[0] < cutoff) {
+            this._timestamps.shift();
+        }
+        const windowMinutes = this._config.windowSeconds / 60;
+        return Math.round(this._timestamps.length / windowMinutes);
+    }
+    getStats() {
+        return {
+            enabled: this.enabled,
+            currentRate: this.currentRate(),
+            threshold: this._config.rateThreshold,
+            windowSeconds: this._config.windowSeconds,
+            alertCount: this._alertCount,
+            entitiesInWindow: this._timestamps.length,
+        };
+    }
+    reset() {
+        this._timestamps = [];
+        this._alertCount = 0;
+        this._lastAlertTime = 0;
+    }
+}

package/dist/generators/network.d.ts

@@ -45,6 +45,7 @@ export declare class SubnetMapper {
     reset(): void;
 }
 export declare const VLAN_NAMES: string[];
+export declare const VRF_NAMES: string[];
 export declare const INTERFACE_DESCS: string[];
 export declare const ROUTE_MAP_NAMES: string[];
 export declare const ACL_NAMES: string[];
@@ -73,7 +74,7 @@ export declare class NetworkGenerator implements BaseGenerator {
     _fakeNetworkCredential(seed: number, original: string): string;
     /** Generate a fake hostname preserving structure. */
     _fakeHostname(seed: number): string;
-    /** Fake VLAN ID/name. Preserves the keyword structure. */
+    /** Fake VLAN ID/name or VRF name. Preserves the keyword structure. */
     _fakeVlanId(seed: number, original: string): string;
     /** Fake interface description. */
     _fakeInterfaceDesc(seed: number, _original: string): string;

package/dist/generators/network.js

@@ -159,15 +159,19 @@ export class SubnetMapper {
         const existing = this.subnetFwd.get(key);
         if (existing !== undefined)
             return existing;
-        // Allocate a slot in CGNAT space, aligned to the subnet size
+        // Allocate in CGNAT space using a byte offset (not a slot counter).
+        // Each allocation advances the offset by the actual subnet size,
+        // aligned to the subnet boundary, to prevent overlapping subnets.
         const hostBits = 32 - prefixLen;
         const subnetSize = 1 << hostBits;
-        // Place fake networks sequentially in CGNAT space
-        let fakeNet = (CGNAT_BASE + this.subnetNextSlot * subnetSize) >>> 0;
-        this.subnetNextSlot += 1;
+        // Align the current offset up to the subnet boundary
+        const alignedOffset = (this.subnetNextSlot + subnetSize - 1) & ~(subnetSize - 1);
+        let fakeNet = (CGNAT_BASE + alignedOffset) >>> 0;
+        // Advance offset past this allocation
+        this.subnetNextSlot = alignedOffset + subnetSize;
         // Wrap around if we exceed CGNAT space
         if ((fakeNet + subnetSize) >>> 0 > (CGNAT_BASE + CGNAT_SIZE) >>> 0) {
-            this.subnetNextSlot = 0;
+            this.subnetNextSlot = subnetSize;
             fakeNet = CGNAT_BASE;
         }
         this.subnetFwd.set(key, fakeNet);
@@ -189,6 +193,12 @@ export const VLAN_NAMES = [
     "MGMT", "USERS", "SERVERS", "PRINTERS", "VOIP", "GUEST",
     "DMZ", "BACKUP", "IOT", "SECURITY", "WIRELESS", "STORAGE",
 ];
+export const VRF_NAMES = [
+    "VRF-TRANSIT", "VRF-SERVICES", "VRF-INTERNAL", "VRF-EXTERNAL",
+    "VRF-MGMT", "VRF-BACKUP", "VRF-GUEST", "VRF-DMZ",
+    "VRF-CORE", "VRF-EDGE", "VRF-INFRA", "VRF-MONITOR",
+    "VRF-VOICE", "VRF-DATA", "VRF-IOT", "VRF-SECURE",
+];
 export const INTERFACE_DESCS = [
     "Uplink to Core", "Server Farm Link", "WAN Circuit", "Management VLAN",
     "User Access Port", "Trunk to Distribution", "Backup Link", "DMZ Segment",
@@ -430,8 +440,18 @@ export class NetworkGenerator {
         const num = (seed % 99) + 1;
         return `${site}-${role}-${String(num).padStart(2, "0")}`;
     }
-    /** Fake VLAN ID/name. Preserves the keyword structure. */
+    /** Fake VLAN ID/name or VRF name. Preserves the keyword structure. */
     _fakeVlanId(seed, original) {
+        // VRF names: VRF-VOICE, VRF-EUROCAT_E, VRF_OPS_DATA, etc.
+        if (/^VRF[-_]/i.test(original) || /^[A-Z][A-Z_]{2,}$/i.test(original)) {
+            return VRF_NAMES[seed % VRF_NAMES.length];
+        }
+        // Route distinguisher / route target: 65001:100
+        if (/^\d+:\d+$/.test(original)) {
+            const asn = 64512 + (seed % 1023);
+            const id = 100 + (seed % 900);
+            return `${asn}:${id}`;
+        }
         // If the original is a "vlan <id>" or just a number in a vlan context,
         // the detector captures the full match. Preserve surrounding keywords.
         const nameMatch = original.match(/name\s+(.+)/i);

package/dist/hooks.js

@@ -179,6 +179,10 @@ export function registerHooks(api, obfuscator) {
             return;
         dumpStatsFile(obfuscator);
         api.logger?.info(`[shroud] before_prompt_build: obfuscated ${result.entities.length} entities`);
+        // NOTE: OpenClaw's hook API only supports prependContext (not prompt
+        // replacement). The raw user text still reaches the LLM alongside
+        // the obfuscated version. This is a known limitation tracked as a
+        // feature request for OpenClaw's before_prompt_build hook.
         return {
             prependContext: [
                 "--- SHROUD PRIVACY LAYER ---",

package/dist/obfuscator.d.ts

@@ -65,6 +65,15 @@ export declare class Obfuscator {
      * Subnet-aware reverse mapping for CGNAT IPs not in the store.
      */
     private _deobfuscateResidualCgnat;
+    /**
+     * Clean up CGNAT range descriptions that LLMs generate when summarizing
+     * fake networks. The LLM sees multiple 100.64.x.y addresses and writes
+     * summaries like "100.64.x.x/xx" or "within 100.64.x.x space".
+     *
+     * Strategy: find the most common real network prefix from the store
+     * mappings and replace CGNAT range descriptions with the real prefix.
+     */
+    private _deobfuscateCgnatRangeDescriptions;
     /**
      * Normalize-and-match deobfuscation for fd00::/8 ULA IPv6 addresses.
      */

package/dist/obfuscator.js

@@ -17,6 +17,20 @@ import { ContextDetector } from "./detectors/context.js";
 import { RedactionFormatter } from "./redaction.js";
 /** Regex to find CGNAT IPs (100.64.0.0/10) in text. */
 const CGNAT_IP_RE = /\b(100\.(?:6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.\d{1,3}\.\d{1,3})\b/g;
+/**
+ * Regex to find CGNAT range descriptions that LLMs generate when summarizing
+ * fake networks. Catches patterns like:
+ *   - "100.64.x.x/xx" or "100.64.0.x/24"
+ *   - "100.64.x.x space" or "within 100.64.x.x"
+ *   - "100.64.0.0/10" (the CGNAT range itself)
+ *   - "100.64.x.x" (wildcard notation)
+ */
+// Match CGNAT range descriptions including:
+// - Full IPs with wildcards: "100.64.x.x/xx", "100.64.9.x/32"
+// - Hyphenated ranges: "100.64.16-19.0/24", "100.64.0-3.0"
+// - Short 3-octet forms: "100.64.8-14", "100.64.9"
+// - Prose references: "100.64.x.x space", "100.64.8-11"
+const CGNAT_RANGE_DESC_RE = /\b100\.(?:6[4-9]|[7-9]\d|1[01]\d|12[0-7])(?:\.[\dx]+(?:-[\dx]+)?(?:\.[\dx]+(?:-[\dx]+)?)?)?(?:\/[\dx]+(?:-[\dx]+)?)?\b/gi;
 /** Regex to find fd00::/8 ULA IPv6 addresses (Shroud fake range) in text. */
 const ULA_IPV6_RE = /(?:^|(?<=[\s,;=(\[]))fd00(?::[0-9a-fA-F]{1,4}){0,7}(?:::(?:[0-9a-fA-F]{1,4}(?::[0-9a-fA-F]{1,4})*)?)?(?=$|[\s,;)\]\/])/gi;
 /**
@@ -405,6 +419,14 @@ export class Obfuscator {
             result = residualV6.text;
             totalReplacements += residualV6.count;
         }
+        // CGNAT range description cleanup: catch LLM-generated summaries like
+        // "100.64.x.x/xx" or "100.64.0.x/24" that indicate the LLM learned
+        // Shroud's fake range and is describing it generically.
+        const rangeCleanup = this._deobfuscateCgnatRangeDescriptions(result);
+        if (rangeCleanup.count > 0) {
+            result = rangeCleanup.text;
+            totalReplacements += rangeCleanup.count;
+        }
         // Audit log
         if (this._audit && totalReplacements > 0) {
             const elapsed = Date.now() - startTime;
@@ -468,6 +490,12 @@ export class Obfuscator {
             result = residualV6.text;
             replacementCount += residualV6.count;
         }
+        // CGNAT range description cleanup (same as in deobfuscate)
+        const rangeCleanup = this._deobfuscateCgnatRangeDescriptions(result);
+        if (rangeCleanup.count > 0) {
+            result = rangeCleanup.text;
+            replacementCount += rangeCleanup.count;
+        }
         if (this._audit && replacementCount > 0) {
             const elapsed = Date.now() - startTime;
             this._audit.logDeobfuscation(replacementCount, undefined, elapsed);
@@ -487,24 +515,42 @@ export class Obfuscator {
             if (knownFakes.has(match))
                 return match;
             try {
+                // Validate all octets are 0-255 before processing
+                const octets = match.split(".").map(s => parseInt(s, 10));
+                if (octets.some(o => o > 255 || o < 0 || isNaN(o)))
+                    return match;
                 const fakeInt = ipToInt(match);
                 // Check if this IP is in CGNAT range
                 if ((fakeInt & CGNAT_MASK_10) !== CGNAT_BASE)
                     return match;
-                // Try each known fake subnet to find which one this IP belongs to
+                // Try each known fake subnet — use longest-prefix match to avoid
+                // broader subnets incorrectly claiming IPs from narrower ones.
+                let bestMatch = null;
                 for (const [fakeNetInt, key] of mapper.subnetRev) {
                     const [realNetStr, prefixLenStr] = key.split(",");
                     const prefixLen = parseInt(prefixLenStr, 10);
                     const mask = prefixLen === 0 ? 0 : ((0xffffffff << (32 - prefixLen)) >>> 0);
                     // Check if this fake IP is in this fake subnet
                     if (((fakeInt & mask) >>> 0) === fakeNetInt) {
-                        const hostBits = (fakeInt & (~mask >>> 0)) >>> 0;
-                        const realNetInt = parseInt(realNetStr, 10);
-                        const realIp = intToIp((realNetInt | hostBits) >>> 0);
-                        count++;
-                        return realIp;
+                        if (!bestMatch || prefixLen > bestMatch.prefixLen) {
+                            const hostBits = (fakeInt & (~mask >>> 0)) >>> 0;
+                            const realNetInt = parseInt(realNetStr, 10);
+                            const combined = (realNetInt | hostBits) >>> 0;
+                            // Validate: all octets must be 0-255
+                            const o1 = (combined >>> 24) & 0xff;
+                            const o2 = (combined >>> 16) & 0xff;
+                            const o3 = (combined >>> 8) & 0xff;
+                            const o4 = combined & 0xff;
+                            if (o1 <= 255 && o2 <= 255 && o3 <= 255 && o4 <= 255) {
+                                bestMatch = { realIp: `${o1}.${o2}.${o3}.${o4}`, prefixLen };
+                            }
+                        }
                     }
                 }
+                if (bestMatch) {
+                    count++;
+                    return bestMatch.realIp;
+                }
             }
             catch {
                 // skip invalid
@@ -513,6 +559,106 @@ export class Obfuscator {
         });
         return { text: result, count };
     }
+    /**
+     * Clean up CGNAT range descriptions that LLMs generate when summarizing
+     * fake networks. The LLM sees multiple 100.64.x.y addresses and writes
+     * summaries like "100.64.x.x/xx" or "within 100.64.x.x space".
+     *
+     * Strategy: find the most common real network prefix from the store
+     * mappings and replace CGNAT range descriptions with the real prefix.
+     */
+    _deobfuscateCgnatRangeDescriptions(text) {
+        const mapper = this._subnetMapper;
+        if (mapper.subnetRev.size === 0)
+            return { text, count: 0 };
+        // Find the most common real network prefix to use as replacement
+        // Build a map of real network prefixes and their frequency
+        const realPrefixCounts = new Map();
+        for (const [, key] of mapper.subnetRev) {
+            const [realNetStr, prefixLenStr] = key.split(",");
+            const realNetInt = parseInt(realNetStr, 10);
+            const prefixLen = parseInt(prefixLenStr, 10);
+            const realIp = intToIp(realNetInt);
+            // Extract first two octets as the prefix
+            const prefix = realIp.split(".").slice(0, 2).join(".");
+            realPrefixCounts.set(prefix, (realPrefixCounts.get(prefix) ?? 0) + 1);
+        }
+        if (realPrefixCounts.size === 0)
+            return { text, count: 0 };
+        // Find the most common real prefix
+        let bestPrefix = "10.0";
+        let bestCount = 0;
+        for (const [prefix, count] of realPrefixCounts) {
+            if (count > bestCount) {
+                bestPrefix = prefix;
+                bestCount = count;
+            }
+        }
+        // Build mapping: full fake network IP → {realIp, prefixLen}
+        // Key on the full IP (not just 2 octets) to avoid collisions — all
+        // CGNAT subnets start with 100.64, so 2-octet keys overwrite each other.
+        const fakeToRealMap = new Map();
+        let mostCommonPrefixLen = 24;
+        const prefixLenCounts = new Map();
+        for (const [fakeNetInt, key] of mapper.subnetRev) {
+            const fakeIp = intToIp(fakeNetInt);
+            const [realNetStr, prefixLenStr] = key.split(",");
+            const realIp = intToIp(parseInt(realNetStr, 10));
+            const prefixLen = parseInt(prefixLenStr, 10);
+            fakeToRealMap.set(fakeIp, { realIp, prefixLen });
+            prefixLenCounts.set(prefixLen, (prefixLenCounts.get(prefixLen) ?? 0) + 1);
+        }
+        // Find most common prefix length
+        let bestPrefixLenCount = 0;
+        for (const [pLen, cnt] of prefixLenCounts) {
+            if (cnt > bestPrefixLenCount) {
+                mostCommonPrefixLen = pLen;
+                bestPrefixLenCount = cnt;
+            }
+        }
+        let count = 0;
+        const result = text.replace(CGNAT_RANGE_DESC_RE, (match) => {
+            // Skip bare IPs without CIDR/range notation ONLY if they were already
+            // handled by _deobfuscateResidualCgnat (i.e., no longer contain 100.64)
+            if (/^\d+\.\d+\.\d+\.\d+$/.test(match) && !match.startsWith("100."))
+                return match;
+            // For range descriptions, try to find the best real prefix.
+            // First try exact third-octet match, then fall back to best prefix.
+            const matchOctets = match.split(".");
+            const thirdOctet = parseInt(matchOctets[2], 10);
+            let realPrefix = bestPrefix;
+            let realPrefixLen = mostCommonPrefixLen;
+            if (!isNaN(thirdOctet)) {
+                // Try to find a fake subnet whose third octet matches
+                for (const [fakeIp, info] of fakeToRealMap) {
+                    const fakeOctets = fakeIp.split(".");
+                    if (parseInt(fakeOctets[2], 10) === thirdOctet) {
+                        realPrefix = info.realIp.split(".").slice(0, 2).join(".");
+                        realPrefixLen = info.prefixLen;
+                        break;
+                    }
+                }
+            }
+            count++;
+            // Replace CGNAT first two octets with real prefix
+            let replaced = match.replace(/^100\.(?:6[4-9]|[7-9]\d|1[01]\d|12[0-7])/, realPrefix);
+            // Fix CIDR suffix
+            replaced = replaced.replace(/\/10\b/, `/${realPrefixLen}`);
+            replaced = replaced.replace(/\/xx\b/, `/${realPrefixLen}`);
+            // Validate: check all numeric octets in result are 0-255
+            const numericOctets = replaced.match(/\b\d{1,3}\b/g);
+            if (numericOctets) {
+                for (let i = 0; i < Math.min(numericOctets.length, 4); i++) {
+                    if (parseInt(numericOctets[i], 10) > 255) {
+                        count--;
+                        return match;
+                    }
+                }
+            }
+            return replaced;
+        });
+        return { text: result, count };
+    }
     /**
      * Normalize-and-match deobfuscation for fd00::/8 ULA IPv6 addresses.
      */

package/dist/policy.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Policy-as-code enforcement — validate Shroud config against policy constraints.
+ * Policy files define required categories, minimum confidence levels, and mandatory denylist entries.
+ */
+import { ShroudConfig } from "./types.js";
+export interface PolicyDef {
+    /** Policy version. */
+    version: string;
+    /** Human-readable policy name. */
+    name: string;
+    /** Categories that MUST be enabled (not overridden to disabled). */
+    requiredCategories?: string[];
+    /** Minimum global confidence threshold. */
+    minConfidence?: number;
+    /** Maximum global confidence threshold (prevent over-filtering). */
+    maxConfidence?: number;
+    /** Values that MUST be in the denylist. */
+    mandatoryDenylist?: string[];
+    /** Values that MUST NOT be in the allowlist. */
+    prohibitedAllowlist?: string[];
+    /** Audit must be enabled. */
+    requireAudit?: boolean;
+    /** Canary must be enabled. */
+    requireCanary?: boolean;
+    /** Redaction level must be one of these. */
+    allowedRedactionLevels?: string[];
+    /** Custom rules. */
+    customRules?: Array<{
+        name: string;
+        check: string;
+        message: string;
+    }>;
+}
+export interface PolicyViolation {
+    rule: string;
+    severity: "error" | "warning";
+    message: string;
+}
+/**
+ * Load a policy from a JSON file.
+ */
+export declare function loadPolicy(filePath: string): PolicyDef | null;
+/**
+ * Validate a ShroudConfig against a policy.
+ * Returns an array of violations (empty = compliant).
+ */
+export declare function validatePolicy(config: ShroudConfig, policy: PolicyDef, detectorOverrides?: Record<string, {
+    enabled?: boolean;
+}>): PolicyViolation[];

package/dist/policy.js

@@ -0,0 +1,105 @@
+/**
+ * Policy-as-code enforcement — validate Shroud config against policy constraints.
+ * Policy files define required categories, minimum confidence levels, and mandatory denylist entries.
+ */
+import { readFileSync, existsSync } from "node:fs";
+/**
+ * Load a policy from a JSON file.
+ */
+export function loadPolicy(filePath) {
+    if (!filePath || !existsSync(filePath))
+        return null;
+    try {
+        const raw = readFileSync(filePath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        return null;
+    }
+}
+/**
+ * Validate a ShroudConfig against a policy.
+ * Returns an array of violations (empty = compliant).
+ */
+export function validatePolicy(config, policy, detectorOverrides) {
+    const violations = [];
+    // Required categories
+    if (policy.requiredCategories) {
+        const overrides = detectorOverrides ?? config.detectorOverrides ?? {};
+        for (const cat of policy.requiredCategories) {
+            // Check if any rule for this category is explicitly disabled
+            const disabledRules = Object.entries(overrides)
+                .filter(([, v]) => v.enabled === false)
+                .map(([k]) => k);
+            // This is a simplified check — in practice you'd need to map rules to categories
+            if (disabledRules.length > 0) {
+                // Log a warning, not an error, since we can't easily map rule→category here
+            }
+        }
+    }
+    // Minimum confidence
+    if (policy.minConfidence !== undefined && config.minConfidence < policy.minConfidence) {
+        violations.push({
+            rule: "minConfidence",
+            severity: "error",
+            message: `Global minConfidence (${config.minConfidence}) is below policy minimum (${policy.minConfidence})`,
+        });
+    }
+    // Maximum confidence
+    if (policy.maxConfidence !== undefined && config.minConfidence > policy.maxConfidence) {
+        violations.push({
+            rule: "maxConfidence",
+            severity: "warning",
+            message: `Global minConfidence (${config.minConfidence}) exceeds policy maximum (${policy.maxConfidence}) — may over-filter`,
+        });
+    }
+    // Mandatory denylist
+    if (policy.mandatoryDenylist) {
+        for (const entry of policy.mandatoryDenylist) {
+            if (!config.denylist.includes(entry)) {
+                violations.push({
+                    rule: "mandatoryDenylist",
+                    severity: "error",
+                    message: `Required denylist entry missing: "${entry}"`,
+                });
+            }
+        }
+    }
+    // Prohibited allowlist
+    if (policy.prohibitedAllowlist) {
+        for (const entry of policy.prohibitedAllowlist) {
+            if (config.allowlist.includes(entry)) {
+                violations.push({
+                    rule: "prohibitedAllowlist",
+                    severity: "error",
+                    message: `Prohibited allowlist entry found: "${entry}"`,
+                });
+            }
+        }
+    }
+    // Audit required
+    if (policy.requireAudit && !config.auditEnabled) {
+        violations.push({
+            rule: "requireAudit",
+            severity: "error",
+            message: "Policy requires audit logging to be enabled",
+        });
+    }
+    // Canary required
+    if (policy.requireCanary && !config.canaryEnabled) {
+        violations.push({
+            rule: "requireCanary",
+            severity: "warning",
+            message: "Policy recommends canary token injection",
+        });
+    }
+    // Allowed redaction levels
+    if (policy.allowedRedactionLevels && !policy.allowedRedactionLevels.includes(config.redactionLevel)) {
+        violations.push({
+            rule: "redactionLevel",
+            severity: "error",
+            message: `Redaction level "${config.redactionLevel}" is not allowed by policy. Allowed: ${policy.allowedRedactionLevels.join(", ")}`,
+        });
+    }
+    return violations;
+}

package/dist/siem.d.ts

@@ -0,0 +1,35 @@
+/**
+ * SIEM webhook forwarder — batch and async delivery of audit events.
+ * Does not block obfuscation pipeline.
+ */
+export interface SiemConfig {
+    /** Webhook URL to send audit events to. Empty = disabled. */
+    webhookUrl: string;
+    /** Custom headers (e.g., Authorization). */
+    headers: Record<string, string>;
+    /** Max events to batch before flushing. Default: 10. */
+    batchSize: number;
+    /** Max time (ms) to hold events before flushing. Default: 5000. */
+    flushIntervalMs: number;
+    /** Format: "json" (array of events) or "ndjson" (newline-delimited). */
+    format: "json" | "ndjson";
+}
+export declare const DEFAULT_SIEM_CONFIG: SiemConfig;
+export declare class SiemForwarder {
+    private _config;
+    private _buffer;
+    private _timer;
+    private _sendCount;
+    private _errorCount;
+    private _lastError;
+    constructor(config?: Partial<SiemConfig>);
+    get enabled(): boolean;
+    /** Queue an audit event for delivery. */
+    push(event: Record<string, unknown>): void;
+    /** Flush buffered events to the webhook. */
+    flush(): void;
+    /** Stop the forwarder and flush remaining events. */
+    stop(): void;
+    getStats(): object;
+    private _sendHttp;
+}

package/dist/siem.js

@@ -0,0 +1,91 @@
+/**
+ * SIEM webhook forwarder — batch and async delivery of audit events.
+ * Does not block obfuscation pipeline.
+ */
+export const DEFAULT_SIEM_CONFIG = {
+    webhookUrl: "",
+    headers: {},
+    batchSize: 10,
+    flushIntervalMs: 5000,
+    format: "json",
+};
+export class SiemForwarder {
+    _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();
+        }
+    }
+    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",
+        });
+        if (this._buffer.length >= this._config.batchSize) {
+            this.flush();
+        }
+    }
+    /** Flush buffered events to the webhook. */
+    flush() {
+        if (this._buffer.length === 0 || !this.enabled)
+            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);
+        });
+    }
+    /** Stop the forwarder and flush remaining events. */
+    stop() {
+        if (this._timer) {
+            clearInterval(this._timer);
+            this._timer = null;
+        }
+        this.flush();
+    }
+    getStats() {
+        return {
+            enabled: this.enabled,
+            buffered: this._buffer.length,
+            sent: this._sendCount,
+            errors: this._errorCount,
+            lastError: this._lastError,
+        };
+    }
+    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}`);
+        }
+        this._sendCount += 1;
+    }
+}

package/dist/store-file.d.ts

@@ -0,0 +1,26 @@
+/**
+ * File-backed mapping store — persists to JSON on disk.
+ * Wraps MemoryStore with periodic flush and load-on-startup.
+ */
+import { Category } from "./types.js";
+import { MappingStore } from "./store.js";
+export declare class FileBackedStore implements MappingStore {
+    private _inner;
+    private _filePath;
+    private _dirty;
+    private _flushTimer;
+    private _flushIntervalMs;
+    constructor(filePath: string, maxSize?: number, flushIntervalMs?: number);
+    put(real: string, fake: string, category: Category): void;
+    getFake(real: string): string | undefined;
+    getReal(fake: string): string | undefined;
+    getCategory(real: string): Category | undefined;
+    allMappings(): Map<string, string>;
+    size(): number;
+    clear(): void;
+    /** Flush dirty mappings to disk. */
+    flush(): void;
+    /** Stop the periodic flush timer. */
+    stop(): void;
+    private _loadFromDisk;
+}

package/dist/store-file.js

@@ -0,0 +1,79 @@
+/**
+ * File-backed mapping store — persists to JSON on disk.
+ * Wraps MemoryStore with periodic flush and load-on-startup.
+ */
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { MemoryStore } from "./store.js";
+export class FileBackedStore {
+    _inner;
+    _filePath;
+    _dirty = false;
+    _flushTimer = null;
+    _flushIntervalMs;
+    constructor(filePath, maxSize = 0, flushIntervalMs = 5000) {
+        this._inner = new MemoryStore(maxSize);
+        this._filePath = filePath;
+        this._flushIntervalMs = flushIntervalMs;
+        // Ensure directory exists
+        const dir = dirname(filePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        // Load existing data
+        this._loadFromDisk();
+        // Periodic flush
+        this._flushTimer = setInterval(() => this.flush(), this._flushIntervalMs);
+        if (this._flushTimer.unref)
+            this._flushTimer.unref();
+    }
+    put(real, fake, category) {
+        this._inner.put(real, fake, category);
+        this._dirty = true;
+    }
+    getFake(real) { return this._inner.getFake(real); }
+    getReal(fake) { return this._inner.getReal(fake); }
+    getCategory(real) { return this._inner.getCategory(real); }
+    allMappings() { return this._inner.allMappings(); }
+    size() { return this._inner.size(); }
+    clear() {
+        this._inner.clear();
+        this._dirty = true;
+        this.flush();
+    }
+    /** Flush dirty mappings to disk. */
+    flush() {
+        if (!this._dirty)
+            return;
+        try {
+            const data = this._inner.export("", undefined);
+            writeFileSync(this._filePath, JSON.stringify(data, null, 2) + "\n");
+            this._dirty = false;
+        }
+        catch (e) {
+            // best-effort — log but don't crash
+            process.stderr.write(`[shroud-store] Flush failed: ${e.message}\n`);
+        }
+    }
+    /** Stop the periodic flush timer. */
+    stop() {
+        if (this._flushTimer) {
+            clearInterval(this._flushTimer);
+            this._flushTimer = null;
+        }
+        this.flush(); // final flush
+    }
+    _loadFromDisk() {
+        if (!existsSync(this._filePath))
+            return;
+        try {
+            const raw = readFileSync(this._filePath, "utf-8");
+            const data = JSON.parse(raw);
+            this._inner.import(data);
+            process.stderr.write(`[shroud-store] Loaded ${data.mappings.length} mappings from ${this._filePath}\n`);
+        }
+        catch (e) {
+            process.stderr.write(`[shroud-store] Load failed: ${e.message}\n`);
+        }
+    }
+}

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "shroud-privacy",
   "name": "Shroud",
-  "version": "2.0.14",
+  "version": "2.0.18",
   "description": "Privacy obfuscation with deterministic fake values and deobfuscation — PII never reaches the LLM, tool calls still work",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shroud-privacy",
-  "version": "2.0.14",
+  "version": "2.0.18",
   "description": "Privacy obfuscation plugin for OpenClaw — detects sensitive data and replaces with deterministic fake values",
   "type": "module",
   "main": "dist/index.js",