shroud-privacy 2.2.9 → 2.2.11

package/dist/event-grader.js

@@ -0,0 +1,214 @@
+/**
+ * LLM-based security event grading.
+ *
+ * Accumulates flagged security events, batches them, and sends to an LLM
+ * via OpenClaw gateway session to classify as TRUE_POSITIVE, FALSE_POSITIVE,
+ * or NEEDS_REVIEW. Results are stored on the event for dashboard display.
+ *
+ * Self-whitelisting: grading sessions use a marker in the session key so
+ * Shroud's own scanner doesn't flag the grading prompt (which contains
+ * real injection examples by definition).
+ *
+ * Zero external dependencies — uses Node.js built-in child_process to call
+ * `openclaw gateway call sessions.create`.
+ */
+import { execFileSync } from "node:child_process";
+/** Marker prefix for grading session keys. */
+export const GRADING_SESSION_PREFIX = "shroud-grading-";
+/** The agent label that grading sessions will produce via extractLabel. */
+export const GRADING_AGENT_LABEL = "Security Event Grader";
+/** The grading system prompt. */
+const GRADING_PROMPT = `You are a security event grader for an AI agent firewall (Shroud).
+
+For each flagged event below, classify it as one of:
+- TRUE_POSITIVE: This is a genuine security concern (injection attempt, data exfiltration, etc.)
+- FALSE_POSITIVE: This is benign — the pattern triggered on normal content being discussed, not an actual attack
+- NEEDS_REVIEW: Ambiguous — a human should review this
+
+Consider:
+- Is the matched text being DISCUSSED/QUOTED (benign) or EXECUTED/INJECTED (malicious)?
+- Is this a normal part of the agent's role? (e.g. a security researcher discussing injection techniques is expected)
+- What is the agent's classification and context?
+
+Respond with ONLY a JSON array. Each element:
+{"index": N, "verdict": "TRUE_POSITIVE|FALSE_POSITIVE|NEEDS_REVIEW", "reasoning": "one sentence"}
+
+Do not include any other text outside the JSON array.`;
+export class EventGrader {
+    _pending = [];
+    _graded = new Map();
+    _batchLog = [];
+    _timer = null;
+    _threshold;
+    _intervalMs;
+    _gatewayUrl;
+    _openclawBin;
+    _running = false;
+    constructor(opts) {
+        this._threshold = opts.threshold;
+        this._intervalMs = opts.intervalSec * 1000;
+        this._gatewayUrl = opts.gatewayUrl;
+        // Find openclaw binary
+        this._openclawBin = process.env.OPENCLAW_BIN || "openclaw";
+        try {
+            const which = execFileSync("which", ["openclaw"], { encoding: "utf-8" }).trim();
+            if (which)
+                this._openclawBin = which;
+        }
+        catch { }
+    }
+    /** Start the grading timer. */
+    start() {
+        if (this._timer)
+            return;
+        this._timer = setInterval(() => this._tryGrade(), this._intervalMs);
+        if (this._timer.unref)
+            this._timer.unref();
+    }
+    /** Stop the grading timer. */
+    stop() {
+        if (this._timer) {
+            clearInterval(this._timer);
+            this._timer = null;
+        }
+    }
+    /** Add an event to the pending grading queue. */
+    addEvent(event) {
+        // Don't grade events from grading sessions (prevent recursion)
+        if (event.agentSessionId?.startsWith(GRADING_SESSION_PREFIX))
+            return;
+        // Don't re-grade
+        if (this._graded.has(event.timestamp))
+            return;
+        this._pending.push(event);
+        // Trigger immediately if threshold met
+        if (this._pending.length >= this._threshold) {
+            this._tryGrade("threshold");
+        }
+    }
+    /** Get the verdict for an event (by timestamp). */
+    getVerdict(eventTimestamp) {
+        return this._graded.get(eventTimestamp) ?? null;
+    }
+    /** Get all graded events. */
+    getAllGraded() {
+        return [...this._graded.values()];
+    }
+    /** Get grading stats. */
+    getStats() {
+        let tp = 0, fp = 0, nr = 0;
+        for (const g of this._graded.values()) {
+            if (g.verdict === "TRUE_POSITIVE")
+                tp++;
+            else if (g.verdict === "FALSE_POSITIVE")
+                fp++;
+            else if (g.verdict === "NEEDS_REVIEW")
+                nr++;
+        }
+        return { pending: this._pending.length, graded: this._graded.size, truePositive: tp, falsePositive: fp, needsReview: nr };
+    }
+    /** Get the grading batch log (last 50 batches). */
+    getBatchLog() {
+        return this._batchLog;
+    }
+    /** Attempt a grading batch. */
+    _tryGrade(trigger = "timer") {
+        if (this._running || this._pending.length === 0)
+            return;
+        this._running = true;
+        const batch = this._pending.splice(0, 20);
+        const startTime = Date.now();
+        const log = {
+            timestamp: startTime,
+            trigger,
+            eventCount: batch.length,
+            prompt: "",
+            rawResponse: "",
+            verdicts: [],
+            success: false,
+            error: "",
+            responseTimeMs: 0,
+        };
+        try {
+            const { verdicts, prompt, rawResponse } = this._callGateway(batch);
+            log.prompt = prompt;
+            log.rawResponse = rawResponse;
+            log.responseTimeMs = Date.now() - startTime;
+            log.success = true;
+            for (const v of verdicts) {
+                if (v.index >= 0 && v.index < batch.length) {
+                    const event = batch[v.index];
+                    const graded = {
+                        eventTimestamp: event.timestamp,
+                        signatureId: event.signatureId,
+                        agentLabel: event.agentLabel || "unknown",
+                        matchedText: event.matchedText?.slice(0, 100) || "",
+                        verdict: v.verdict,
+                        reasoning: v.reasoning || "",
+                        gradedAt: Date.now(),
+                    };
+                    this._graded.set(event.timestamp, graded);
+                    log.verdicts.push({
+                        signatureId: event.signatureId,
+                        agentLabel: event.agentLabel || "unknown",
+                        verdict: v.verdict,
+                        reasoning: v.reasoning || "",
+                    });
+                }
+            }
+        }
+        catch (err) {
+            log.error = err?.message || "Unknown error";
+            log.responseTimeMs = Date.now() - startTime;
+            this._pending.unshift(...batch);
+        }
+        this._batchLog.push(log);
+        if (this._batchLog.length > 50)
+            this._batchLog.shift();
+        this._running = false;
+    }
+    /** Call the OpenClaw gateway to grade a batch of events. */
+    _callGateway(batch) {
+        const eventsText = batch.map((e, i) => `[${i}] sig=${e.signatureId} sev=${e.severity} agent="${e.agentLabel || "?"}" ` +
+            `class=${e.threatClass} match="${(e.matchedText || "").slice(0, 150)}" ` +
+            `desc="${e.description || ""}"`).join("\n");
+        const message = `Grade these ${batch.length} security events:\n\n${eventsText}`;
+        const fullPrompt = `${GRADING_PROMPT}\n\n${message}`;
+        const sessionKey = `${GRADING_SESSION_PREFIX}${Date.now()}`;
+        try {
+            const result = execFileSync(this._openclawBin, [
+                "gateway", "call", "sessions.create",
+                "--expect-final",
+                "--timeout", "30000",
+                "--json",
+                "--params", JSON.stringify({
+                    key: sessionKey,
+                    message,
+                    systemPrompt: GRADING_PROMPT,
+                }),
+            ], {
+                timeout: 35_000,
+                encoding: "utf-8",
+                env: { ...process.env, NODE_TLS_REJECT_UNAUTHORIZED: "0" },
+            });
+            const jsonMatch = result.match(/\[[\s\S]*?\]/);
+            if (!jsonMatch)
+                return { verdicts: [], prompt: fullPrompt, rawResponse: result.slice(0, 2000) };
+            const parsed = JSON.parse(jsonMatch[0]);
+            if (!Array.isArray(parsed))
+                return { verdicts: [], prompt: fullPrompt, rawResponse: result.slice(0, 2000) };
+            const verdicts = parsed
+                .filter((v) => typeof v.index === "number" &&
+                ["TRUE_POSITIVE", "FALSE_POSITIVE", "NEEDS_REVIEW"].includes(v.verdict))
+                .map((v) => ({
+                index: v.index,
+                verdict: v.verdict,
+                reasoning: typeof v.reasoning === "string" ? v.reasoning.slice(0, 200) : "",
+            }));
+            return { verdicts, prompt: fullPrompt, rawResponse: result.slice(0, 2000) };
+        }
+        catch (err) {
+            throw new Error(err?.message?.slice(0, 200) || "Gateway call failed");
+        }
+    }
+}

package/dist/policy.d.ts

@@ -1,49 +1,99 @@
 /**
- * Policy-as-code enforcement — validate Shroud config against policy constraints.
- * Policy files define required categories, minimum confidence levels, and mandatory denylist entries.
+ * Per-agent firewall policy engine.
+ *
+ * Maps agent build IDs to security policy overrides.
+ * Supports hot-reload from a JSON policy file.
+ * Enables per-agent WAF rules — different agents get different
+ * injection detection thresholds, disabled signatures, and action modes.
+ *
+ * Policy file format (~/.shroud/policy.json):
+ * {
+ *   "default": {
+ *     "injectionDetection": "flag",
+ *     "injectionMinSeverity": "low",
+ *     "injectionDisabledSignatures": []
+ *   },
+ *   "agents": {
+ *     "a1b2c3d4e5f6g7h8": {
+ *       "label": "research-agent",
+ *       "injectionDetection": "flag",
+ *       "injectionMinSeverity": "medium",
+ *       "injectionDisabledSignatures": ["rs_jailbreak"],
+ *       "notes": "Research agent legitimately discusses injection patterns"
+ *     }
+ *   }
+ * }
  */
-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;
-    }>;
+/** Per-agent policy overrides. */
+export interface AgentPolicy {
+    label?: string;
+    injectionDetection?: "flag" | "block" | "off";
+    injectionMinSeverity?: "low" | "medium" | "high";
+    injectionDisabledSignatures?: string[];
+    injectionScanResponses?: boolean;
+    profilingMode?: "learning" | "active" | "strict";
+    notes?: string;
 }
-export interface PolicyViolation {
-    rule: string;
-    severity: "error" | "warning";
-    message: string;
+/** Full policy file structure. */
+export interface PolicyFile {
+    default: AgentPolicy;
+    agents: Record<string, AgentPolicy>;
+}
+/** A versioned policy commit. */
+export interface PolicyCommit {
+    version: number;
+    timestamp: string;
+    description: string;
+    policy: PolicyFile;
+}
+/** Policy history — stored alongside the policy file. */
+export interface PolicyHistory {
+    current: number;
+    commits: PolicyCommit[];
 }
 /**
- * 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).
+ * Policy engine with hot-reload support.
  */
-export declare function validatePolicy(config: ShroudConfig, policy: PolicyDef, detectorOverrides?: Record<string, {
-    enabled?: boolean;
-}>): PolicyViolation[];
+export declare class PolicyEngine {
+    private _policyPath;
+    private _historyPath;
+    private _policy;
+    private _history;
+    private _watching;
+    private _onReload;
+    constructor(policyPath: string);
+    /** Get the effective policy for an agent (merged with defaults). */
+    getPolicy(agentBuildId: string): AgentPolicy;
+    /** Get the full policy file. */
+    getFullPolicy(): PolicyFile;
+    /** Update policy for a specific agent. Saves to disk. */
+    setAgentPolicy(agentBuildId: string, policy: AgentPolicy): void;
+    /** Update the default policy. Saves to disk. */
+    setDefaultPolicy(policy: AgentPolicy): void;
+    /** Remove agent-specific policy (falls back to default). */
+    removeAgentPolicy(agentBuildId: string): void;
+    /**
+     * Commit the current policy state with a description.
+     * Creates a versioned snapshot that can be rolled back to.
+     */
+    commit(description: string): PolicyCommit;
+    /**
+     * Rollback to a specific version number.
+     * Returns the restored commit or null if version not found.
+     */
+    rollback(version: number): PolicyCommit | null;
+    /** Get the commit history. */
+    getHistory(): PolicyHistory;
+    /** Get the current version number. */
+    getCurrentVersion(): number;
+    /** Start watching the policy file for external changes (hot-reload). */
+    startWatching(): void;
+    /** Stop watching. */
+    stopWatching(): void;
+    /** Register a callback for policy reload events. */
+    onReload(callback: () => void): void;
+    private _loadOrDefault;
+    private _save;
+    private _loadHistory;
+    private _saveHistory;
+}

package/dist/policy.js

@@ -1,105 +1,212 @@
 /**
- * Policy-as-code enforcement — validate Shroud config against policy constraints.
- * Policy files define required categories, minimum confidence levels, and mandatory denylist entries.
+ * Per-agent firewall policy engine.
+ *
+ * Maps agent build IDs to security policy overrides.
+ * Supports hot-reload from a JSON policy file.
+ * Enables per-agent WAF rules — different agents get different
+ * injection detection thresholds, disabled signatures, and action modes.
+ *
+ * Policy file format (~/.shroud/policy.json):
+ * {
+ *   "default": {
+ *     "injectionDetection": "flag",
+ *     "injectionMinSeverity": "low",
+ *     "injectionDisabledSignatures": []
+ *   },
+ *   "agents": {
+ *     "a1b2c3d4e5f6g7h8": {
+ *       "label": "research-agent",
+ *       "injectionDetection": "flag",
+ *       "injectionMinSeverity": "medium",
+ *       "injectionDisabledSignatures": ["rs_jailbreak"],
+ *       "notes": "Research agent legitimately discusses injection patterns"
+ *     }
+ *   }
+ * }
  */
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, watchFile, unwatchFile, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 /**
- * Load a policy from a JSON file.
+ * Policy engine with hot-reload support.
  */
-export function loadPolicy(filePath) {
-    if (!filePath || !existsSync(filePath))
-        return null;
-    try {
-        const raw = readFileSync(filePath, "utf-8");
-        return JSON.parse(raw);
+export class PolicyEngine {
+    _policyPath;
+    _historyPath;
+    _policy;
+    _history;
+    _watching = false;
+    _onReload = [];
+    constructor(policyPath) {
+        this._policyPath = policyPath;
+        this._historyPath = policyPath.replace(/\.json$/, ".history.json");
+        this._policy = this._loadOrDefault();
+        this._history = this._loadHistory();
     }
-    catch (e) {
-        return null;
+    /** Get the effective policy for an agent (merged with defaults). */
+    getPolicy(agentBuildId) {
+        const agentOverride = this._policy.agents[agentBuildId];
+        if (!agentOverride)
+            return { ...this._policy.default };
+        return {
+            ...this._policy.default,
+            ...agentOverride,
+            // Merge disabled signatures (union of default + agent-specific)
+            injectionDisabledSignatures: [
+                ...(this._policy.default.injectionDisabledSignatures || []),
+                ...(agentOverride.injectionDisabledSignatures || []),
+            ],
+        };
     }
-}
-/**
- * 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
-            }
+    /** Get the full policy file. */
+    getFullPolicy() {
+        return this._policy;
+    }
+    /** Update policy for a specific agent. Saves to disk. */
+    setAgentPolicy(agentBuildId, policy) {
+        this._policy.agents[agentBuildId] = {
+            ...this._policy.agents[agentBuildId],
+            ...policy,
+        };
+        this._save();
+    }
+    /** Update the default policy. Saves to disk. */
+    setDefaultPolicy(policy) {
+        this._policy.default = { ...this._policy.default, ...policy };
+        this._save();
+    }
+    /** Remove agent-specific policy (falls back to default). */
+    removeAgentPolicy(agentBuildId) {
+        delete this._policy.agents[agentBuildId];
+        this._save();
+    }
+    /**
+     * Commit the current policy state with a description.
+     * Creates a versioned snapshot that can be rolled back to.
+     */
+    commit(description) {
+        const version = (this._history.commits.length > 0
+            ? this._history.commits[this._history.commits.length - 1].version
+            : 0) + 1;
+        const commit = {
+            version,
+            timestamp: new Date().toISOString(),
+            description,
+            policy: JSON.parse(JSON.stringify(this._policy)), // deep clone
+        };
+        this._history.commits.push(commit);
+        this._history.current = version;
+        // Keep last 50 commits max
+        if (this._history.commits.length > 50) {
+            this._history.commits = this._history.commits.slice(-50);
         }
+        this._saveHistory();
+        this._save();
+        return commit;
     }
-    // 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})`,
-        });
+    /**
+     * Rollback to a specific version number.
+     * Returns the restored commit or null if version not found.
+     */
+    rollback(version) {
+        const commit = this._history.commits.find(c => c.version === version);
+        if (!commit)
+            return null;
+        this._policy = JSON.parse(JSON.stringify(commit.policy)); // deep clone
+        this._history.current = version;
+        this._saveHistory();
+        this._save();
+        for (const cb of this._onReload)
+            cb();
+        return commit;
     }
-    // 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`,
-        });
+    /** Get the commit history. */
+    getHistory() {
+        return this._history;
     }
-    // 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}"`,
-                });
+    /** Get the current version number. */
+    getCurrentVersion() {
+        return this._history.current;
+    }
+    /** Start watching the policy file for external changes (hot-reload). */
+    startWatching() {
+        if (this._watching)
+            return;
+        this._watching = true;
+        watchFile(this._policyPath, { interval: 2000 }, () => {
+            try {
+                this._policy = this._loadOrDefault();
+                for (const cb of this._onReload)
+                    cb();
             }
-        }
+            catch {
+                // Corrupt file — keep current policy
+            }
+        });
+    }
+    /** Stop watching. */
+    stopWatching() {
+        if (!this._watching)
+            return;
+        this._watching = false;
+        unwatchFile(this._policyPath);
     }
-    // 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}"`,
-                });
+    /** Register a callback for policy reload events. */
+    onReload(callback) {
+        this._onReload.push(callback);
+    }
+    _loadOrDefault() {
+        if (existsSync(this._policyPath)) {
+            try {
+                const raw = readFileSync(this._policyPath, "utf-8");
+                const parsed = JSON.parse(raw);
+                return {
+                    default: parsed.default || {},
+                    agents: parsed.agents || {},
+                };
+            }
+            catch {
+                // Corrupt file
             }
         }
+        return {
+            default: {
+                injectionDetection: "flag",
+                injectionMinSeverity: "low",
+                injectionDisabledSignatures: [],
+            },
+            agents: {},
+        };
     }
-    // Audit required
-    if (policy.requireAudit && !config.auditEnabled) {
-        violations.push({
-            rule: "requireAudit",
-            severity: "error",
-            message: "Policy requires audit logging to be enabled",
-        });
+    _save() {
+        try {
+            mkdirSync(dirname(this._policyPath), { recursive: true });
+            writeFileSync(this._policyPath, JSON.stringify(this._policy, null, 2) + "\n", "utf-8");
+        }
+        catch {
+            // Best-effort — don't crash if path is unwritable
+        }
     }
-    // Canary required
-    if (policy.requireCanary && !config.canaryEnabled) {
-        violations.push({
-            rule: "requireCanary",
-            severity: "warning",
-            message: "Policy recommends canary token injection",
-        });
+    _loadHistory() {
+        if (existsSync(this._historyPath)) {
+            try {
+                const raw = readFileSync(this._historyPath, "utf-8");
+                const parsed = JSON.parse(raw);
+                return {
+                    current: parsed.current || 0,
+                    commits: parsed.commits || [],
+                };
+            }
+            catch { /* corrupt file */ }
+        }
+        return { current: 0, commits: [] };
     }
-    // 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(", ")}`,
-        });
+    _saveHistory() {
+        try {
+            mkdirSync(dirname(this._historyPath), { recursive: true });
+            writeFileSync(this._historyPath, JSON.stringify(this._history, null, 2) + "\n", "utf-8");
+        }
+        catch {
+            // Best-effort
+        }
     }
-    return violations;
 }