agent-threat-rules 0.1.0

package/dist/engine.d.ts

@@ -0,0 +1,127 @@
+/**
+ * ATR Engine - Evaluates agent events against ATR rules
+ *
+ * Core detection engine that:
+ * 1. Loads ATR YAML rules from disk
+ * 2. Evaluates agent events (LLM I/O, tool calls, behaviors) against rules
+ * 3. Returns matched rules with confidence scores
+ * 4. Supports two condition formats:
+ *    - Array format: conditions is an array of {field, operator, value} objects
+ *    - Named format: conditions is an object map of named condition blocks
+ *
+ * @module agent-threat-rules/engine
+ */
+import type { ATRRule, ATRMatch, AgentEvent } from './types.js';
+import type { SessionTracker } from './session-tracker.js';
+export interface ATREngineConfig {
+    /** Directory containing ATR rule YAML files */
+    rulesDir?: string;
+    /** Pre-loaded rules (for testing or embedding) */
+    rules?: ATRRule[];
+    /** Enable hot-reload of rule files */
+    hotReload?: boolean;
+    /** Optional session tracker for behavioral detection across events */
+    sessionTracker?: SessionTracker;
+}
+export declare class ATREngine {
+    private readonly config;
+    private rules;
+    private readonly compiledPatterns;
+    constructor(config?: ATREngineConfig);
+    /**
+     * Load rules from configured directory and/or pre-loaded rules.
+     */
+    loadRules(): Promise<number>;
+    /**
+     * Load a single rule file and add it to the engine.
+     */
+    addRuleFile(filePath: string): void;
+    /**
+     * Add a pre-parsed rule to the engine.
+     */
+    addRule(rule: ATRRule): void;
+    /**
+     * Evaluate an agent event against all loaded ATR rules.
+     * Returns all matching rules with details.
+     */
+    evaluate(event: AgentEvent): ATRMatch[];
+    /**
+     * Evaluate a single rule against an event.
+     * Supports both array-format and named-map-format conditions.
+     */
+    private evaluateRule;
+    /**
+     * Evaluate array-format conditions: [{field, operator, value}, ...]
+     * with condition: "any" | "all"
+     */
+    private evaluateArrayConditions;
+    /**
+     * Evaluate a single array-format condition {field, operator, value}.
+     */
+    private evaluateArrayCondition;
+    /**
+     * Evaluate named-map-format conditions: {name: {field, patterns, match_type}, ...}
+     * with condition: "name1 AND name2" | "name1 OR name2" | "name1"
+     */
+    private evaluateNamedConditions;
+    /**
+     * Evaluate a single named condition against an event.
+     */
+    private evaluateNamedCondition;
+    /**
+     * Evaluate a pattern matching condition (named format with patterns array).
+     */
+    private evaluatePatternCondition;
+    /**
+     * Evaluate a behavioral threshold condition.
+     * When a session tracker is available and the event has a sessionId,
+     * supports session-derived metrics: call_frequency, pattern_frequency, event_count.
+     */
+    private evaluateBehavioralCondition;
+    /**
+     * Resolve a metric value from event metrics or session tracker.
+     * Session-derived metrics use the format: "call_frequency:toolName" or "pattern_frequency:pattern".
+     */
+    private resolveMetricValue;
+    /**
+     * Parse a window string (e.g. "5m", "1h", "30s") to milliseconds.
+     * Defaults to 5 minutes if not specified or unparseable.
+     */
+    private parseWindowMs;
+    /**
+     * Evaluate a sequence condition against the current event.
+     *
+     * Limitation (v0.1): This checks whether patterns from multiple steps
+     * co-occur in the current event's content. It does NOT track ordered
+     * execution across separate events or enforce time windows.
+     * Full session-aware sequence detection is planned for v0.2.
+     */
+    private evaluateSequenceCondition;
+    /**
+     * Resolve a field value from an agent event.
+     */
+    private resolveField;
+    /**
+     * Evaluate a boolean expression string against condition results.
+     * Supports AND, OR, NOT operators.
+     */
+    private evaluateExpression;
+    /**
+     * Split expression by operator, respecting parentheses.
+     */
+    private splitByOperator;
+    /**
+     * Pre-compile regex patterns for a rule (performance optimization).
+     * Supports both array-format and named-map-format conditions.
+     */
+    private compilePatterns;
+    /** Get loaded rule count */
+    getRuleCount(): number;
+    /** Get all loaded rules */
+    getRules(): readonly ATRRule[];
+    /** Get a rule by ID */
+    getRuleById(id: string): ATRRule | undefined;
+    /** Get rules by category */
+    getRulesByCategory(category: string): ATRRule[];
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EACR,UAAU,EAGX,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAsB3D,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,sCAAsC;IACtC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,sEAAsE;IACtE,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,qBAAa,SAAS;IAIR,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA4C;gBAEhD,MAAM,GAAE,eAAoB;IAEzD;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAyBlC;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAMnC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAK5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,QAAQ,EAAE;IAwCvC;;;OAGG;IACH,OAAO,CAAC,YAAY;IAapB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAuC/B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAoE9B;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAmC/B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAiC9B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAqEhC;;;;OAIG;IACH,OAAO,CAAC,2BAA2B;IAoBnC;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAgC1B;;;OAGG;IACH,OAAO,CAAC,aAAa;IAiBrB;;;;;;;OAOG;IACH,OAAO,CAAC,yBAAyB;IA8BjC;;OAEG;IACH,OAAO,CAAC,YAAY;IAgCpB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAsC1B;;OAEG;IACH,OAAO,CAAC,eAAe;IAgCvB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAkDvB,4BAA4B;IAC5B,YAAY,IAAI,MAAM;IAItB,2BAA2B;IAC3B,QAAQ,IAAI,SAAS,OAAO,EAAE;IAI9B,uBAAuB;IACvB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAI5C,4BAA4B;IAC5B,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,EAAE;CAGhD"}