shroud-privacy 2.2.11 → 2.2.13

package/dist/event-grader.js

@@ -1,214 +0,0 @@
-/**
- * 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/exposure.d.ts

@@ -1,29 +0,0 @@
-/**
- * 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

@@ -1,72 +0,0 @@
-/**
- * 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/policy.d.ts

@@ -1,99 +0,0 @@
-/**
- * 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"
- *     }
- *   }
- * }
- */
-/** 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;
-}
-/** 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[];
-}
-/**
- * Policy engine with hot-reload support.
- */
-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,212 +0,0 @@
-/**
- * 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, writeFileSync, existsSync, watchFile, unwatchFile, mkdirSync } from "node:fs";
-import { dirname } from "node:path";
-/**
- * Policy engine with hot-reload support.
- */
-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();
-    }
-    /** 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 || []),
-            ],
-        };
-    }
-    /** 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;
-    }
-    /**
-     * 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;
-    }
-    /** Get the commit history. */
-    getHistory() {
-        return this._history;
-    }
-    /** 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);
-    }
-    /** 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: {},
-        };
-    }
-    _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
-        }
-    }
-    _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: [] };
-    }
-    _saveHistory() {
-        try {
-            mkdirSync(dirname(this._historyPath), { recursive: true });
-            writeFileSync(this._historyPath, JSON.stringify(this._history, null, 2) + "\n", "utf-8");
-        }
-        catch {
-            // Best-effort
-        }
-    }
-}

package/dist/profiler-analysis.d.ts

@@ -1,35 +0,0 @@
-/**
- * Statistical analysis utilities for behavioural profiling.
- *
- * Welford's online algorithm for incremental mean/stddev,
- * Z-score computation, and multi-feature anomaly scoring.
- * All synchronous, zero dependencies.
- */
-import { AnomalyAlert, BaselineFeatureStats, FeatureVector, RunningStats } from "./profiler-types.js";
-/** Create a fresh running stats accumulator. */
-export declare function emptyStats(): RunningStats;
-/**
- * Update running stats with a new observation.
- * Uses Welford's algorithm for numerically stable incremental mean/variance.
- */
-export declare function updateStats(stats: RunningStats, x: number): RunningStats;
-/** Compute standard deviation from running stats. */
-export declare function stddev(stats: RunningStats): number;
-/** Compute Z-score. Returns 0 if stddev is 0 and value equals mean. */
-export declare function zScore(observed: number, mean: number, sd: number): number;
-/**
- * Detect anomalies by comparing a feature vector against the baseline.
- *
- * @param features - Current turn's feature vector
- * @param baseline - Accumulated baseline feature statistics
- * @param sigma - Z-score threshold (default 3.0)
- * @param knownTools - Set of tool names seen in baseline sessions
- * @param knownCategories - Set of entity categories seen in baseline sessions
- */
-export declare function detectAnomalies(features: FeatureVector, baseline: BaselineFeatureStats, sigma: number, knownTools: Set<string>, knownCategories: Set<string>): AnomalyAlert[];
-/**
- * Update the baseline with feature values from a completed turn.
- */
-export declare function updateBaseline(baseline: BaselineFeatureStats, features: FeatureVector): BaselineFeatureStats;
-/** Get the list of tracked numeric feature names. */
-export declare function getTrackedFeatureNames(): string[];