agent-threat-rules 0.1.0 → 0.2.0

package/dist/rule-scaffolder.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ATR Rule Scaffolder - Generates ATR rule YAML scaffolds from structured input
+ * @module agent-threat-rules/rule-scaffolder
+ */
+import type { ATRCategory, ATRSeverity, ATRSourceType } from './types.js';
+export interface ScaffoldInput {
+    title: string;
+    category: ATRCategory;
+    severity?: ATRSeverity;
+    attackDescription: string;
+    examplePayloads: string[];
+    agentSourceType?: ATRSourceType;
+    owaspRefs?: string[];
+    mitreRefs?: string[];
+}
+export interface ScaffoldResult {
+    yaml: string;
+    id: string;
+    warnings: string[];
+}
+export interface ScaffoldOptions {
+    author?: string;
+    schemaVersion?: string;
+}
+export declare class RuleScaffolder {
+    private readonly options;
+    constructor(options?: ScaffoldOptions);
+    /**
+     * Generate a complete ATR YAML rule from structured input.
+     * Returns a ScaffoldResult with the YAML string, generated ID, and any warnings.
+     */
+    scaffold(input: ScaffoldInput): ScaffoldResult;
+    /**
+     * Validate scaffold input, throwing on invalid required fields
+     * and returning warnings for non-critical issues.
+     */
+    private validateInput;
+}
+//# sourceMappingURL=rule-scaffolder.d.ts.map

package/dist/rule-scaffolder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-scaffolder.d.ts","sourceRoot":"","sources":["../src/rule-scaffolder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,aAAa,EAGd,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,CAAC,EAAE,aAAa,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAmED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;gBAExC,OAAO,GAAE,eAAoB;IAOzC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc;IAwF9C;;;OAGG;IACH,OAAO,CAAC,aAAa;CAwBtB"}

package/dist/rule-scaffolder.js

@@ -0,0 +1,173 @@
+/**
+ * ATR Rule Scaffolder - Generates ATR rule YAML scaffolds from structured input
+ * @module agent-threat-rules/rule-scaffolder
+ */
+import yaml from 'js-yaml';
+const CATEGORY_TO_SOURCE_TYPE = {
+    'prompt-injection': 'llm_io',
+    'tool-poisoning': 'tool_call',
+    'context-exfiltration': 'context_window',
+    'agent-manipulation': 'multi_agent_comm',
+    'privilege-escalation': 'agent_behavior',
+    'excessive-autonomy': 'agent_behavior',
+    'data-poisoning': 'llm_io',
+    'model-abuse': 'llm_io',
+    'skill-compromise': 'skill_lifecycle',
+};
+const CATEGORY_TO_FIELD = {
+    'prompt-injection': 'user_input',
+    'tool-poisoning': 'tool_response',
+    'context-exfiltration': 'agent_output',
+    'agent-manipulation': 'agent_message',
+    'privilege-escalation': 'agent_action',
+    'excessive-autonomy': 'agent_action',
+    'data-poisoning': 'training_input',
+    'model-abuse': 'user_input',
+    'skill-compromise': 'skill_manifest',
+};
+const SEVERITY_TO_ACTIONS = {
+    critical: ['block_input', 'alert', 'escalate'],
+    high: ['block_input', 'alert'],
+    medium: ['alert', 'snapshot'],
+    low: ['alert'],
+    informational: ['alert'],
+};
+const REGEX_SPECIAL_CHARS = /[.*+?^${}()|[\]\\]/g;
+function escapeRegex(str) {
+    return str.replace(REGEX_SPECIAL_CHARS, '\\$&');
+}
+/**
+ * Build a case-insensitive regex pattern from a payload string.
+ * Extracts significant keywords (length > 3) and creates lookahead assertions,
+ * falling back to a simple escaped match for short payloads.
+ */
+function buildRegexPattern(payload) {
+    const trimmed = payload.trim();
+    const words = trimmed.split(/\s+/).filter((w) => w.length > 3);
+    if (words.length === 0) {
+        return `(?i).*${escapeRegex(trimmed)}.*`;
+    }
+    const keywords = words.slice(0, 4);
+    return `(?i)${keywords.map((k) => `(?=.*${escapeRegex(k)})`).join('')}`;
+}
+function generateId() {
+    const year = new Date().getFullYear();
+    const seq = String(Math.floor(Math.random() * 900) + 100);
+    return `ATR-${year}-${seq}`;
+}
+function getCurrentDate() {
+    return new Date().toISOString().split('T')[0];
+}
+export class RuleScaffolder {
+    options;
+    constructor(options = {}) {
+        this.options = {
+            author: options.author ?? 'ATR Community (auto-scaffolded)',
+            schemaVersion: options.schemaVersion ?? '0.1',
+        };
+    }
+    /**
+     * Generate a complete ATR YAML rule from structured input.
+     * Returns a ScaffoldResult with the YAML string, generated ID, and any warnings.
+     */
+    scaffold(input) {
+        const warnings = this.validateInput(input);
+        const severity = input.severity ?? 'medium';
+        const sourceType = input.agentSourceType ?? CATEGORY_TO_SOURCE_TYPE[input.category];
+        const field = CATEGORY_TO_FIELD[input.category];
+        const id = generateId();
+        const date = getCurrentDate();
+        const conditions = input.examplePayloads.map((payload, idx) => ({
+            field,
+            operator: 'regex',
+            value: buildRegexPattern(payload),
+            description: `Pattern ${idx + 1}: detects "${payload.trim()}"`,
+        }));
+        const truePositives = input.examplePayloads.map((payload) => ({
+            input: payload.trim(),
+            expected: 'trigger',
+        }));
+        const trueNegatives = [
+            {
+                input: 'TODO: Add benign input that should not trigger this rule',
+                expected: 'no_trigger',
+            },
+        ];
+        const references = {};
+        if (input.owaspRefs && input.owaspRefs.length > 0) {
+            references.owasp_llm = [...input.owaspRefs];
+        }
+        if (input.mitreRefs && input.mitreRefs.length > 0) {
+            references.mitre_atlas = [...input.mitreRefs];
+        }
+        const conditionExpr = conditions.length > 1 ? 'any' : 'all';
+        const rule = {
+            title: input.title,
+            id,
+            schema_version: this.options.schemaVersion,
+            status: 'draft',
+            description: input.attackDescription,
+            author: this.options.author,
+            date,
+            severity,
+            detection_tier: 'pattern',
+            maturity: 'draft',
+            ...(Object.keys(references).length > 0 ? { references } : {}),
+            tags: {
+                category: input.category,
+                confidence: severity === 'critical' || severity === 'high' ? 'high' : 'medium',
+            },
+            agent_source: {
+                type: sourceType,
+            },
+            detection: {
+                conditions,
+                condition: conditionExpr,
+                false_positives: [
+                    'TODO: Document known false positive scenarios',
+                ],
+            },
+            response: {
+                actions: [...SEVERITY_TO_ACTIONS[severity]],
+                message_template: `Potential ${input.category} detected: {{matched_patterns}}`,
+            },
+            test_cases: {
+                true_positives: truePositives,
+                true_negatives: trueNegatives,
+            },
+        };
+        const yamlStr = yaml.dump(rule, {
+            indent: 2,
+            lineWidth: 120,
+            noRefs: true,
+            sortKeys: false,
+            quotingType: '"',
+            forceQuotes: false,
+        });
+        return { yaml: yamlStr, id, warnings };
+    }
+    /**
+     * Validate scaffold input, throwing on invalid required fields
+     * and returning warnings for non-critical issues.
+     */
+    validateInput(input) {
+        const warnings = [];
+        if (!input.title || input.title.trim().length === 0) {
+            throw new Error('ScaffoldInput.title is required and must be non-empty');
+        }
+        if (!input.category) {
+            throw new Error('ScaffoldInput.category is required');
+        }
+        if (!input.attackDescription || input.attackDescription.trim().length === 0) {
+            throw new Error('ScaffoldInput.attackDescription is required and must be non-empty');
+        }
+        if (!input.examplePayloads || input.examplePayloads.length === 0) {
+            throw new Error('ScaffoldInput.examplePayloads must contain at least one payload');
+        }
+        if (input.examplePayloads.length < 3) {
+            warnings.push('Fewer than 3 example payloads - consider adding more for better pattern coverage.');
+        }
+        return warnings;
+    }
+}
+//# sourceMappingURL=rule-scaffolder.js.map

package/dist/rule-scaffolder.js.map

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

package/dist/skill-fingerprint.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Skill Behavioral Fingerprint
+ * Skill 行為指紋追蹤器
+ *
+ * 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
+ *
+ * 追蹤每個 skill 的「正常行為」，然後在行為偏移時偵測：
+ * - 前 N 次呼叫：建立指紋
+ * - 指紋穩定後：任何偏離都標記為異常
+ *
+ * @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.
+     *
+     * 記錄 skill 呼叫並偵測行為異常。
+     * 如果指紋已穩定且出現新能力，回傳異常列表。
+     */
+    recordInvocation(skillName: string, event: AgentEvent): readonly BehaviorAnomaly[];
+    /**
+     * Get an immutable fingerprint snapshot for a skill.
+     * 取得某 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).
+     * 重置 skill 指紋（例如合法更新後）。
+     */
+    resetFingerprint(skillName: string): void;
+    /**
+     * Evict fingerprints not seen since cutoffMs ago.
+     * 清除超過 cutoffMs 未活動的指紋。
+     */
+    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;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM7C,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;AAqGD,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;;;;;;OAMG;IACH,gBAAgB,CACd,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,UAAU,GAChB,SAAS,eAAe,EAAE;IA8H7B;;;OAGG;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;;;OAGG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIzC;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAgBjC,OAAO,CAAC,WAAW;IAkCnB,OAAO,CAAC,qBAAqB;CAU9B"}

package/dist/skill-fingerprint.js

@@ -0,0 +1,337 @@
+/**
+ * Skill Behavioral Fingerprint
+ * Skill 行為指紋追蹤器
+ *
+ * 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
+ *
+ * 追蹤每個 skill 的「正常行為」，然後在行為偏移時偵測：
+ * - 前 N 次呼叫：建立指紋
+ * - 指紋穩定後：任何偏離都標記為異常
+ *
+ * @module agent-threat-rules/skill-fingerprint
+ */
+import { createHash } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Pattern detectors (regex-based, no LLM needed)
+// ---------------------------------------------------------------------------
+const FS_WRITE_PATTERN = /(?:write(?:File)?|appendFile|fs\.write|truncate|mkdir|rmdir|unlink|rm\s+-)/i;
+const FS_READ_PATTERN = /(?:read(?:File)?|readdir|stat|access|exists|glob|find\s)/i;
+const FS_DELETE_PATTERN = /(?:unlink|rm\s+-rf|delete(?:File)?|removeDir|rmdir)/i;
+const NETWORK_PATTERN = /(?:https?:\/\/|fetch|curl|wget|axios|http\.request|net\.connect|socket)[\s('"]*([a-zA-Z0-9.-]+(?:\.[a-zA-Z]{2,}))/i;
+const ENV_PATTERN = /(?:process\.env|os\.environ|getenv|System\.getenv)\[?['"(]?([A-Z_][A-Z0-9_]*)/i;
+const ENV_INLINE_PATTERN = /\$\{?([A-Z_][A-Z0-9_]{2,})\}?/g;
+const EXEC_PATTERN = /(?:child_process|spawn|exec(?:File)?|system\(|popen|subprocess|shell_exec|os\.system)\s*\(\s*['"(]?([^\s'")\]]{1,80})/i;
+const EXFIL_PATTERN = /(?:base64|btoa|encode|compress|deflate|gzip).*(?:http|fetch|curl|send|post|upload)/i;
+const REDIRECT_PATTERN = /(?:redirect|forward|proxy|tunnel)\s+(?:to\s+)?(?:https?:\/\/)/i;
+/** Classify a text content into behavioral capabilities */
+function extractCapabilities(text) {
+    const result = {
+        filesystemOps: [],
+        networkTargets: [],
+        envAccesses: [],
+        processExecs: [],
+        outputPatterns: [],
+    };
+    if (!text || text.length === 0)
+        return result;
+    // Limit analysis to first 10KB to prevent ReDoS
+    const safeText = text.slice(0, 10_240);
+    // Filesystem
+    if (FS_WRITE_PATTERN.test(safeText))
+        result.filesystemOps.push('write');
+    if (FS_READ_PATTERN.test(safeText))
+        result.filesystemOps.push('read');
+    if (FS_DELETE_PATTERN.test(safeText))
+        result.filesystemOps.push('delete');
+    // Network targets
+    const netMatch = safeText.match(NETWORK_PATTERN);
+    if (netMatch?.[1])
+        result.networkTargets.push(netMatch[1]);
+    // Environment variable accesses
+    const envMatch = safeText.match(ENV_PATTERN);
+    if (envMatch?.[1])
+        result.envAccesses.push(envMatch[1]);
+    // Also check inline env vars like $HOME, ${API_KEY}
+    for (const m of safeText.matchAll(ENV_INLINE_PATTERN)) {
+        if (m[1] && !result.envAccesses.includes(m[1])) {
+            result.envAccesses.push(m[1]);
+        }
+    }
+    // Process executions
+    const execMatch = safeText.match(EXEC_PATTERN);
+    if (execMatch?.[1])
+        result.processExecs.push(execMatch[1]);
+    // Output patterns
+    if (EXFIL_PATTERN.test(safeText))
+        result.outputPatterns.push('exfiltration');
+    if (REDIRECT_PATTERN.test(safeText))
+        result.outputPatterns.push('redirect');
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Fingerprint Store
+// ---------------------------------------------------------------------------
+/** Default invocations needed before fingerprint is considered stable */
+const DEFAULT_STABILITY_THRESHOLD = 10;
+/** Consecutive invocations with no new capabilities to mark stable */
+const DEFAULT_STABLE_STREAK = 5;
+/** Maximum number of skills to track */
+const MAX_SKILLS = 5_000;
+export class SkillFingerprintStore {
+    fingerprints = new Map();
+    stabilityThreshold;
+    stableStreak;
+    constructor(config) {
+        this.stabilityThreshold = config?.stabilityThreshold ?? DEFAULT_STABILITY_THRESHOLD;
+        this.stableStreak = config?.stableStreak ?? DEFAULT_STABLE_STREAK;
+    }
+    /**
+     * Record a skill invocation and detect behavioral anomalies.
+     * Returns anomalies if the fingerprint was stable and new capabilities appeared.
+     *
+     * 記錄 skill 呼叫並偵測行為異常。
+     * 如果指紋已穩定且出現新能力，回傳異常列表。
+     */
+    recordInvocation(skillName, event) {
+        const now = Date.now();
+        const fp = this.getOrCreate(skillName, now);
+        fp.invocationCount++;
+        fp.lastSeen = now;
+        // Extract capabilities from event content + fields
+        const content = [
+            event.content ?? '',
+            event.fields?.['tool_args'] ?? '',
+            event.fields?.['tool_response'] ?? '',
+        ].join('\n');
+        const caps = extractCapabilities(content);
+        // Check for anomalies (only if fingerprint is stable)
+        const anomalies = [];
+        const isStable = fp.stableHash !== null;
+        if (isStable) {
+            // Detect NEW capabilities not in the stable fingerprint
+            for (const op of caps.filesystemOps) {
+                if (!fp.filesystemOps.has(op)) {
+                    anomalies.push({
+                        skillName,
+                        anomalyType: 'new_filesystem_op',
+                        description: `Skill "${skillName}" performing new filesystem operation: ${op} (not in baseline)`,
+                        severity: op === 'delete' ? 'critical' : op === 'write' ? 'high' : 'medium',
+                        newValue: op,
+                        timestamp: now,
+                    });
+                }
+            }
+            for (const target of caps.networkTargets) {
+                if (!fp.networkTargets.has(target)) {
+                    anomalies.push({
+                        skillName,
+                        anomalyType: 'new_network_target',
+                        description: `Skill "${skillName}" contacting new network target: ${target}`,
+                        severity: 'high',
+                        newValue: target,
+                        timestamp: now,
+                    });
+                }
+            }
+            for (const env of caps.envAccesses) {
+                if (!fp.envAccesses.has(env)) {
+                    const isSensitive = /(?:KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL)/i.test(env);
+                    anomalies.push({
+                        skillName,
+                        anomalyType: 'new_env_access',
+                        description: `Skill "${skillName}" accessing new env var: ${env}`,
+                        severity: isSensitive ? 'critical' : 'medium',
+                        newValue: env,
+                        timestamp: now,
+                    });
+                }
+            }
+            for (const proc of caps.processExecs) {
+                if (!fp.processExecs.has(proc)) {
+                    anomalies.push({
+                        skillName,
+                        anomalyType: 'new_process_exec',
+                        description: `Skill "${skillName}" executing new process: ${proc}`,
+                        severity: 'critical',
+                        newValue: proc,
+                        timestamp: now,
+                    });
+                }
+            }
+            for (const pat of caps.outputPatterns) {
+                if (!fp.outputPatterns.has(pat)) {
+                    anomalies.push({
+                        skillName,
+                        anomalyType: 'new_output_pattern',
+                        description: `Skill "${skillName}" exhibiting new pattern: ${pat}`,
+                        severity: pat === 'exfiltration' ? 'critical' : 'high',
+                        newValue: pat,
+                        timestamp: now,
+                    });
+                }
+            }
+        }
+        // Update fingerprint with observed capabilities
+        let newCapsSeen = false;
+        for (const op of caps.filesystemOps) {
+            if (!fp.filesystemOps.has(op)) {
+                fp.filesystemOps.add(op);
+                newCapsSeen = true;
+            }
+        }
+        for (const t of caps.networkTargets) {
+            if (!fp.networkTargets.has(t)) {
+                fp.networkTargets.add(t);
+                newCapsSeen = true;
+            }
+        }
+        for (const e of caps.envAccesses) {
+            if (!fp.envAccesses.has(e)) {
+                fp.envAccesses.add(e);
+                newCapsSeen = true;
+            }
+        }
+        for (const p of caps.processExecs) {
+            if (!fp.processExecs.has(p)) {
+                fp.processExecs.add(p);
+                newCapsSeen = true;
+            }
+        }
+        for (const o of caps.outputPatterns) {
+            if (!fp.outputPatterns.has(o)) {
+                fp.outputPatterns.add(o);
+                newCapsSeen = true;
+            }
+        }
+        // Track stability
+        if (!isStable) {
+            if (newCapsSeen) {
+                fp.stableStreak = 0;
+            }
+            else {
+                fp.stableStreak++;
+            }
+            // Mark stable when threshold met
+            if (fp.invocationCount >= this.stabilityThreshold &&
+                fp.stableStreak >= this.stableStreak) {
+                fp.stableHash = this.computeCapabilityHash(fp);
+            }
+        }
+        return anomalies;
+    }
+    /**
+     * Get an immutable fingerprint snapshot for a skill.
+     * 取得某 skill 的不可變指紋快照。
+     */
+    getFingerprint(skillName) {
+        const fp = this.fingerprints.get(skillName);
+        if (!fp)
+            return undefined;
+        return {
+            skillName: fp.skillName,
+            invocationCount: fp.invocationCount,
+            firstSeen: fp.firstSeen,
+            lastSeen: fp.lastSeen,
+            isStable: fp.stableHash !== null,
+            capabilities: {
+                filesystemOps: new Set(fp.filesystemOps),
+                networkTargets: new Set(fp.networkTargets),
+                envAccesses: new Set(fp.envAccesses),
+                processExecs: new Set(fp.processExecs),
+                outputPatterns: new Set(fp.outputPatterns),
+            },
+            capabilityHash: fp.stableHash ?? this.computeCapabilityHash(fp),
+        };
+    }
+    /** Get all tracked skill names */
+    getTrackedSkills() {
+        return [...this.fingerprints.keys()];
+    }
+    /** Get count of stable fingerprints */
+    getStableCount() {
+        let count = 0;
+        for (const fp of this.fingerprints.values()) {
+            if (fp.stableHash !== null)
+                count++;
+        }
+        return count;
+    }
+    /** Get total tracked skills */
+    getTrackedCount() {
+        return this.fingerprints.size;
+    }
+    /**
+     * Reset a skill's fingerprint (e.g., after a legitimate update).
+     * 重置 skill 指紋（例如合法更新後）。
+     */
+    resetFingerprint(skillName) {
+        this.fingerprints.delete(skillName);
+    }
+    /**
+     * Evict fingerprints not seen since cutoffMs ago.
+     * 清除超過 cutoffMs 未活動的指紋。
+     */
+    cleanup(cutoffMs) {
+        const cutoff = Date.now() - cutoffMs;
+        let evicted = 0;
+        for (const [name, fp] of this.fingerprints) {
+            if (fp.lastSeen < cutoff) {
+                this.fingerprints.delete(name);
+                evicted++;
+            }
+        }
+        return evicted;
+    }
+    // -----------------------------------------------------------------------
+    // Private
+    // -----------------------------------------------------------------------
+    getOrCreate(skillName, now) {
+        const existing = this.fingerprints.get(skillName);
+        if (existing)
+            return existing;
+        // Evict oldest if at capacity
+        if (this.fingerprints.size >= MAX_SKILLS) {
+            let oldestName;
+            let oldestTime = Infinity;
+            for (const [name, fp] of this.fingerprints) {
+                if (fp.lastSeen < oldestTime) {
+                    oldestTime = fp.lastSeen;
+                    oldestName = name;
+                }
+            }
+            if (oldestName)
+                this.fingerprints.delete(oldestName);
+        }
+        const fp = {
+            skillName,
+            invocationCount: 0,
+            firstSeen: now,
+            lastSeen: now,
+            filesystemOps: new Set(),
+            networkTargets: new Set(),
+            envAccesses: new Set(),
+            processExecs: new Set(),
+            outputPatterns: new Set(),
+            stableHash: null,
+            stableStreak: 0,
+        };
+        this.fingerprints.set(skillName, fp);
+        return fp;
+    }
+    computeCapabilityHash(fp) {
+        const parts = [
+            [...fp.filesystemOps].sort().join(','),
+            [...fp.networkTargets].sort().join(','),
+            [...fp.envAccesses].sort().join(','),
+            [...fp.processExecs].sort().join(','),
+            [...fp.outputPatterns].sort().join(','),
+        ];
+        return createHash('sha256').update(parts.join('|')).digest('hex').slice(0, 16);
+    }
+}
+//# sourceMappingURL=skill-fingerprint.js.map