@panguard-ai/atr 1.4.3 → 1.5.1

package/dist/session-tracker.js

@@ -0,0 +1,176 @@
+/**
+ * SessionTracker - Tracks per-session state for behavioral detection operators.
+ *
+ * Enables multi-turn injection detection, call frequency tracking,
+ * and pattern repetition counting. All state is internal; public methods
+ * return copies to preserve immutability.
+ *
+ * @module agent-threat-rules/session-tracker
+ */
+/** Maximum number of events stored per session */
+const MAX_EVENTS_PER_SESSION = 1000;
+/** Maximum number of tracked sessions */
+const MAX_SESSIONS = 10_000;
+export class SessionTracker {
+    sessions = new Map();
+    /**
+     * Record an agent event for the given session.
+     * Extracts tool name and patterns from event fields/content.
+     */
+    recordEvent(sessionId, event, patterns = []) {
+        this.ensureCapacity();
+        const state = this.getOrCreateSession(sessionId);
+        const toolName = this.extractToolName(event);
+        const now = Date.now();
+        const tracked = {
+            event: Object.freeze({ ...event }),
+            recordedAt: now,
+            toolName,
+            patterns,
+        };
+        // Evict oldest if at capacity
+        if (state.events.length >= MAX_EVENTS_PER_SESSION) {
+            state.events = state.events.slice(1);
+        }
+        state.events = [...state.events, tracked];
+        state.lastActivityAt = now;
+        // Update call counts
+        if (toolName) {
+            const prev = state.callCounts.get(toolName) ?? 0;
+            state.callCounts.set(toolName, prev + 1);
+        }
+        // Update pattern counts
+        for (const p of patterns) {
+            const prev = state.patternCounts.get(p) ?? 0;
+            state.patternCounts.set(p, prev + 1);
+        }
+    }
+    /**
+     * Get the number of calls to a specific tool within a time window.
+     */
+    getCallFrequency(sessionId, toolName, windowMs) {
+        const state = this.sessions.get(sessionId);
+        if (!state)
+            return 0;
+        const cutoff = Date.now() - windowMs;
+        let count = 0;
+        for (const tracked of state.events) {
+            if (tracked.recordedAt >= cutoff && tracked.toolName === toolName) {
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Get the number of times a pattern has been observed within a time window.
+     */
+    getPatternFrequency(sessionId, pattern, windowMs) {
+        const state = this.sessions.get(sessionId);
+        if (!state)
+            return 0;
+        const cutoff = Date.now() - windowMs;
+        let count = 0;
+        for (const tracked of state.events) {
+            if (tracked.recordedAt >= cutoff && tracked.patterns.includes(pattern)) {
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Get total event count for a session, optionally within a time window.
+     */
+    getEventCount(sessionId, windowMs) {
+        const state = this.sessions.get(sessionId);
+        if (!state)
+            return 0;
+        if (windowMs === undefined) {
+            return state.events.length;
+        }
+        const cutoff = Date.now() - windowMs;
+        let count = 0;
+        for (const tracked of state.events) {
+            if (tracked.recordedAt >= cutoff) {
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Get an immutable snapshot of session state. Returns undefined if session does not exist.
+     */
+    getSessionSnapshot(sessionId) {
+        const state = this.sessions.get(sessionId);
+        if (!state)
+            return undefined;
+        const oldest = state.events.length > 0 ? state.events[0].recordedAt : undefined;
+        const newest = state.events.length > 0 ? state.events[state.events.length - 1].recordedAt : undefined;
+        return Object.freeze({
+            sessionId,
+            eventCount: state.events.length,
+            oldestEventTimestamp: oldest,
+            newestEventTimestamp: newest,
+            events: Object.freeze(state.events.map((e) => e.event)),
+        });
+    }
+    /**
+     * Evict sessions that have been inactive longer than maxAgeMs.
+     * Returns the number of sessions evicted.
+     */
+    cleanup(maxAgeMs) {
+        const cutoff = Date.now() - maxAgeMs;
+        let evicted = 0;
+        for (const [id, state] of this.sessions) {
+            if (state.lastActivityAt < cutoff) {
+                this.sessions.delete(id);
+                evicted++;
+            }
+        }
+        return evicted;
+    }
+    /** Get the number of tracked sessions */
+    getSessionCount() {
+        return this.sessions.size;
+    }
+    /**
+     * Ensure we don't exceed the maximum session count.
+     * Evicts the oldest session if at capacity.
+     */
+    ensureCapacity() {
+        if (this.sessions.size < MAX_SESSIONS)
+            return;
+        let oldestId;
+        let oldestTime = Infinity;
+        for (const [id, state] of this.sessions) {
+            if (state.lastActivityAt < oldestTime) {
+                oldestTime = state.lastActivityAt;
+                oldestId = id;
+            }
+        }
+        if (oldestId) {
+            this.sessions.delete(oldestId);
+        }
+    }
+    getOrCreateSession(sessionId) {
+        const existing = this.sessions.get(sessionId);
+        if (existing)
+            return existing;
+        const now = Date.now();
+        const state = {
+            events: [],
+            callCounts: new Map(),
+            patternCounts: new Map(),
+            createdAt: now,
+            lastActivityAt: now,
+        };
+        this.sessions.set(sessionId, state);
+        return state;
+    }
+    extractToolName(event) {
+        if (event.type === 'tool_call' || event.type === 'tool_response') {
+            return event.fields?.['tool_name'] ?? event.content;
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=session-tracker.js.map

package/dist/session-tracker.js.map

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

package/dist/shadow-evaluator.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Shadow Evaluator -- runs experimental rules without affecting verdict.
+ *
+ * Experimental rules evaluate against every event but don't influence
+ * the real verdict. Their match/no-match results are tracked to measure
+ * false positive rates. Rules with FP < threshold get promoted.
+ *
+ * @module agent-threat-rules/shadow-evaluator
+ */
+import type { ATRRule, ATRMatch, AgentEvent } from './types.js';
+interface ShadowRuleStats {
+    readonly ruleId: string;
+    totalEvaluations: number;
+    totalMatches: number;
+    confirmedTruePositives: number;
+    confirmedFalsePositives: number;
+    firstSeen: number;
+    lastSeen: number;
+}
+export interface PromotionCandidate {
+    readonly rule: ATRRule;
+    readonly stats: Readonly<ShadowRuleStats>;
+    readonly fpRate: number;
+}
+export declare class ShadowEvaluator {
+    private readonly rules;
+    private readonly stats;
+    private readonly compiledPatterns;
+    /** Add an experimental rule for shadow evaluation */
+    addRule(rule: ATRRule): void;
+    /** Evaluate all shadow rules against an event (does NOT affect verdict) */
+    evaluate(event: AgentEvent): readonly ATRMatch[];
+    /** Record user feedback on a shadow match */
+    recordFeedback(ruleId: string, isTruePositive: boolean): void;
+    /**
+     * Get rules ready for promotion.
+     * Criteria: FP rate < maxFPRate AND minimum evaluations reached.
+     */
+    getPromotionCandidates(maxFPRate?: number, minEvaluations?: number): readonly PromotionCandidate[];
+    /** Get stats for a specific rule */
+    getStats(ruleId: string): Readonly<ShadowRuleStats> | undefined;
+    /** Get all shadow rule stats */
+    getAllStats(): ReadonlyMap<string, Readonly<ShadowRuleStats>>;
+    /** Number of shadow rules */
+    size(): number;
+}
+export {};
+//# sourceMappingURL=shadow-evaluator.d.ts.map

package/dist/shadow-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow-evaluator.d.ts","sourceRoot":"","sources":["../src/shadow-evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEhE,UAAU,eAAe;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,uBAAuB,EAAE,MAAM,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsC;IAC5D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA6B;IAE9D,qDAAqD;IACrD,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAc5B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,QAAQ,EAAE;IAuDhD,6CAA6C;IAC7C,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,IAAI;IAU7D;;;OAGG;IACH,sBAAsB,CACpB,SAAS,GAAE,MAAc,EACzB,cAAc,GAAE,MAAa,GAC5B,SAAS,kBAAkB,EAAE;IAuBhC,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC,eAAe,CAAC,GAAG,SAAS;IAK/D,gCAAgC;IAChC,WAAW,IAAI,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;IAI7D,6BAA6B;IAC7B,IAAI,IAAI,MAAM;CAGf"}

package/dist/shadow-evaluator.js

@@ -0,0 +1,129 @@
+/**
+ * Shadow Evaluator -- runs experimental rules without affecting verdict.
+ *
+ * Experimental rules evaluate against every event but don't influence
+ * the real verdict. Their match/no-match results are tracked to measure
+ * false positive rates. Rules with FP < threshold get promoted.
+ *
+ * @module agent-threat-rules/shadow-evaluator
+ */
+export class ShadowEvaluator {
+    rules = [];
+    stats = new Map();
+    compiledPatterns = new Map();
+    /** Add an experimental rule for shadow evaluation */
+    addRule(rule) {
+        if (this.rules.some((r) => r.id === rule.id))
+            return; // dedup
+        this.rules.push(rule);
+        this.stats.set(rule.id, {
+            ruleId: rule.id,
+            totalEvaluations: 0,
+            totalMatches: 0,
+            confirmedTruePositives: 0,
+            confirmedFalsePositives: 0,
+            firstSeen: Date.now(),
+            lastSeen: Date.now(),
+        });
+    }
+    /** Evaluate all shadow rules against an event (does NOT affect verdict) */
+    evaluate(event) {
+        const matches = [];
+        for (const rule of this.rules) {
+            const stat = this.stats.get(rule.id);
+            if (!stat)
+                continue;
+            stat.totalEvaluations++;
+            stat.lastSeen = Date.now();
+            // Simple regex evaluation for shadow rules
+            const detection = rule.detection;
+            const conditions = Array.isArray(detection.conditions)
+                ? detection.conditions
+                : Object.values(detection.conditions);
+            let matched = false;
+            for (const cond of conditions) {
+                const c = cond;
+                const value = c['value'];
+                const field = c['field'];
+                if (!value || !field)
+                    continue;
+                const text = event.fields?.[field] ?? event.content ?? '';
+                try {
+                    let regex = this.compiledPatterns.get(value);
+                    if (!regex) {
+                        regex = new RegExp(value, 'i');
+                        this.compiledPatterns.set(value, regex);
+                    }
+                    if (regex.test(text)) {
+                        matched = true;
+                        break;
+                    }
+                }
+                catch {
+                    // Invalid regex
+                }
+            }
+            if (matched) {
+                stat.totalMatches++;
+                matches.push({
+                    rule,
+                    matchedConditions: ['shadow'],
+                    matchedPatterns: ['shadow-match'],
+                    confidence: 0.5, // Shadow matches have reduced confidence
+                    timestamp: new Date().toISOString(),
+                    scan_context: 'native',
+                });
+            }
+        }
+        return matches;
+    }
+    /** Record user feedback on a shadow match */
+    recordFeedback(ruleId, isTruePositive) {
+        const stat = this.stats.get(ruleId);
+        if (!stat)
+            return;
+        if (isTruePositive) {
+            stat.confirmedTruePositives++;
+        }
+        else {
+            stat.confirmedFalsePositives++;
+        }
+    }
+    /**
+     * Get rules ready for promotion.
+     * Criteria: FP rate < maxFPRate AND minimum evaluations reached.
+     */
+    getPromotionCandidates(maxFPRate = 0.001, minEvaluations = 1000) {
+        const candidates = [];
+        for (const rule of this.rules) {
+            const stat = this.stats.get(rule.id);
+            if (!stat || stat.totalEvaluations < minEvaluations)
+                continue;
+            const fpRate = stat.totalMatches > 0
+                ? stat.confirmedFalsePositives / stat.totalMatches
+                : 0;
+            // Only promote if:
+            // 1. Has been evaluated enough times
+            // 2. FP rate is below threshold
+            // 3. Has at least some matches (not a dead rule)
+            if (fpRate <= maxFPRate && stat.totalMatches > 0) {
+                candidates.push({ rule, stats: { ...stat }, fpRate });
+            }
+        }
+        return candidates;
+    }
+    /** Get stats for a specific rule */
+    getStats(ruleId) {
+        const stat = this.stats.get(ruleId);
+        return stat ? { ...stat } : undefined;
+    }
+    /** Get all shadow rule stats */
+    getAllStats() {
+        return new Map(Array.from(this.stats.entries()).map(([k, v]) => [k, { ...v }]));
+    }
+    /** Number of shadow rules */
+    size() {
+        return this.rules.length;
+    }
+}
+//# sourceMappingURL=shadow-evaluator.js.map

package/dist/shadow-evaluator.js.map

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

package/dist/skill-fingerprint.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Skill Behavioral Fingerprint
+ *
+ * Tracks what each skill "normally does" across invocations, then detects
+ * behavioral drift when a previously-trusted skill starts acting differently.
+ *
+ * Solves the "installed then turns malicious" scenario:
+ * - First N invocations: build fingerprint (what APIs, what patterns, what scope)
+ * - After fingerprint stabilizes: flag any deviation as anomaly
+ *
+ * @module agent-threat-rules/skill-fingerprint
+ */
+import type { AgentEvent } from './types.js';
+/** Behavioral capabilities observed for a skill */
+interface SkillCapabilities {
+    /** Seen filesystem operations (read/write/delete) */
+    readonly filesystemOps: ReadonlySet<string>;
+    /** Seen network destinations (hostnames) */
+    readonly networkTargets: ReadonlySet<string>;
+    /** Seen environment variable accesses */
+    readonly envAccesses: ReadonlySet<string>;
+    /** Seen child process executions */
+    readonly processExecs: ReadonlySet<string>;
+    /** Seen output patterns (categories: data, error, redirect, exfiltration) */
+    readonly outputPatterns: ReadonlySet<string>;
+}
+/** Immutable fingerprint snapshot */
+export interface SkillFingerprint {
+    readonly skillName: string;
+    readonly invocationCount: number;
+    readonly firstSeen: number;
+    readonly lastSeen: number;
+    readonly isStable: boolean;
+    readonly capabilities: SkillCapabilities;
+    /** Hash of capabilities for quick comparison */
+    readonly capabilityHash: string;
+}
+/** Anomaly when behavior deviates from fingerprint */
+export interface BehaviorAnomaly {
+    readonly skillName: string;
+    readonly anomalyType: 'new_filesystem_op' | 'new_network_target' | 'new_env_access' | 'new_process_exec' | 'new_output_pattern' | 'capability_expansion';
+    readonly description: string;
+    readonly severity: 'low' | 'medium' | 'high' | 'critical';
+    readonly newValue: string;
+    readonly timestamp: number;
+}
+export interface SkillFingerprintConfig {
+    /** Minimum invocations before fingerprint can stabilize (default: 10) */
+    stabilityThreshold?: number;
+    /** Consecutive clean invocations to mark stable (default: 5) */
+    stableStreak?: number;
+}
+export declare class SkillFingerprintStore {
+    private readonly fingerprints;
+    private readonly stabilityThreshold;
+    private readonly stableStreak;
+    constructor(config?: SkillFingerprintConfig);
+    /**
+     * Record a skill invocation and detect behavioral anomalies.
+     * Returns anomalies if the fingerprint was stable and new capabilities appeared.
+     */
+    recordInvocation(skillName: string, event: AgentEvent): readonly BehaviorAnomaly[];
+    /**
+     * Get an immutable fingerprint snapshot for a skill.
+     */
+    getFingerprint(skillName: string): SkillFingerprint | undefined;
+    /** Get all tracked skill names */
+    getTrackedSkills(): string[];
+    /** Get count of stable fingerprints */
+    getStableCount(): number;
+    /** Get total tracked skills */
+    getTrackedCount(): number;
+    /**
+     * Reset a skill's fingerprint (e.g., after a legitimate update).
+     */
+    resetFingerprint(skillName: string): void;
+    /**
+     * Evict fingerprints not seen since cutoffMs ago.
+     */
+    cleanup(cutoffMs: number): number;
+    private getOrCreate;
+    private computeCapabilityHash;
+}
+export {};
+//# sourceMappingURL=skill-fingerprint.d.ts.map

package/dist/skill-fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-fingerprint.d.ts","sourceRoot":"","sources":["../src/skill-fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAU7C,mDAAmD;AACnD,UAAU,iBAAiB;IACzB,qDAAqD;IACrD,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5C,4CAA4C;IAC5C,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7C,yCAAyC;IACzC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,oCAAoC;IACpC,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3C,6EAA6E;IAC7E,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC9C;AAED,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAAC;IACzC,gDAAgD;IAChD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAChB,mBAAmB,GACnB,oBAAoB,GACpB,gBAAgB,GAChB,kBAAkB,GAClB,oBAAoB,GACpB,sBAAsB,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAsDD,MAAM,WAAW,sBAAsB;IACrC,yEAAyE;IACzE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyC;IACtE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,MAAM,CAAC,EAAE,sBAAsB;IAK3C;;;OAGG;IACH,gBAAgB,CACd,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,UAAU,GAChB,SAAS,eAAe,EAAE;IA8H7B;;OAEG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAqB/D,kCAAkC;IAClC,gBAAgB,IAAI,MAAM,EAAE;IAI5B,uCAAuC;IACvC,cAAc,IAAI,MAAM;IAQxB,+BAA+B;IAC/B,eAAe,IAAI,MAAM;IAIzB;;OAEG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIzC;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAgBjC,OAAO,CAAC,WAAW;IAkCnB,OAAO,CAAC,qBAAqB;CAU9B"}