@panguard-ai/atr 1.4.3 → 1.5.1

package/dist/eval/skill-benchmark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-benchmark.d.ts","sourceRoot":"","sources":["../../src/eval/skill-benchmark.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA8BH,UAAU,YAAY;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,QAAQ,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC;AAED,UAAU,YAAY;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,QAAQ,CAAC,cAAc,EAAE,SAAS,YAAY,EAAE,CAAC;IACjD,QAAQ,CAAC,YAAY,EAAE,SAAS,YAAY,EAAE,CAAC;CAChD;AAMD,wBAAsB,iBAAiB,CAAC,OAAO,CAAC,EAAE;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAuIhC;AAUD,wBAAgB,WAAW,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CA6C9D"}

package/dist/eval/skill-benchmark.js

@@ -0,0 +1,194 @@
+/**
+ * SKILL.md Benchmark Harness
+ *
+ * Evaluates the ATR scanSkill() method against a labeled corpus of
+ * malicious and benign SKILL.md files. Produces per-layer recall,
+ * overall precision, and a detailed per-sample report.
+ *
+ * Corpus: data/skill-benchmark/manifest.json
+ * Samples: data/skill-benchmark/malicious/ and data/skill-benchmark/benign/
+ *
+ * Layers:
+ *   A = obvious payload (curl|bash, base64 exec, reverse shell)
+ *   B = obfuscated (bash expansion, paste service relay, encoded)
+ *   C = semantic (natural language instructions, social engineering)
+ *
+ * @module agent-threat-rules/eval/skill-benchmark
+ */
+import { resolve, join } from 'node:path';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { ATREngine } from '../engine.js';
+// ---------------------------------------------------------------------------
+// Benchmark runner
+// ---------------------------------------------------------------------------
+export async function runSkillBenchmark(options) {
+    const repoRoot = resolve(import.meta.dirname, '..', '..');
+    const rulesDir = options?.rulesDir ?? join(repoRoot, 'rules');
+    const corpusDir = options?.corpusDir ?? join(repoRoot, 'data', 'skill-benchmark');
+    const outputPath = options?.outputPath ?? join(repoRoot, 'data', 'skill-benchmark', 'benchmark-report.json');
+    // Load manifest
+    const manifestPath = join(corpusDir, 'manifest.json');
+    if (!existsSync(manifestPath)) {
+        throw new Error(`Manifest not found: ${manifestPath}`);
+    }
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    // Load expected findings (Cisco-style ground truth)
+    const expectedPath = join(corpusDir, 'expected-findings.json');
+    const expectedMap = existsSync(expectedPath)
+        ? JSON.parse(readFileSync(expectedPath, 'utf-8'))
+        : {};
+    // Load engine
+    const engine = new ATREngine({ rulesDir });
+    await engine.loadRules();
+    // Run each sample
+    const results = [];
+    for (const entry of manifest) {
+        const filePath = join(corpusDir, entry.file);
+        if (!existsSync(filePath)) {
+            console.error(`SKIP: file not found: ${entry.file}`);
+            continue;
+        }
+        const content = readFileSync(filePath, 'utf-8');
+        const start = performance.now();
+        const matches = engine.scanSkill(content);
+        const elapsed = performance.now() - start;
+        const detected = matches.length > 0;
+        const rulesFired = matches.map((m) => m.rule.id);
+        const correct = (entry.label === 'malicious' && detected) ||
+            (entry.label === 'benign' && !detected);
+        // Validate expected findings (Cisco-style category + rule matching)
+        const expected = expectedMap[entry.file];
+        const expectedRulesMatched = expected?.expected_findings
+            ? expected.expected_findings.every((ef) => rulesFired.includes(ef.rule_id))
+            : true; // no expected = pass by default
+        const expectedCategories = expected?.expected_findings?.map((ef) => ef.category) ?? [];
+        const actualCategories = matches.map((m) => m.rule.tags.category);
+        const categoryCorrect = expectedCategories.every((ec) => actualCategories.includes(ec));
+        results.push({
+            file: entry.file,
+            label: entry.label,
+            layer: entry.layer || '',
+            attack_type: entry.attack_type,
+            detected,
+            rules_fired: rulesFired,
+            correct,
+            latency_ms: Math.round(elapsed * 100) / 100,
+            expected_rules_matched: expectedRulesMatched,
+            category_correct: categoryCorrect,
+        });
+    }
+    // Compute metrics
+    const malicious = results.filter((r) => r.label === 'malicious');
+    const benign = results.filter((r) => r.label === 'benign');
+    const tp = malicious.filter((r) => r.detected).length;
+    const fn = malicious.filter((r) => !r.detected).length;
+    const fp = benign.filter((r) => r.detected).length;
+    const tn = benign.filter((r) => !r.detected).length;
+    const recall = malicious.length > 0 ? tp / malicious.length : 0;
+    const precision = (tp + fp) > 0 ? tp / (tp + fp) : 0;
+    const f1 = (precision + recall) > 0 ? 2 * (precision * recall) / (precision + recall) : 0;
+    const fpRate = benign.length > 0 ? fp / benign.length : 0;
+    // Per-layer metrics
+    const layerMetrics = (layer) => {
+        const samples = malicious.filter((r) => r.layer === layer);
+        const detected = samples.filter((r) => r.detected).length;
+        return {
+            total: samples.length,
+            detected,
+            recall: samples.length > 0 ? detected / samples.length : 0,
+        };
+    };
+    const latencies = results.map((r) => r.latency_ms);
+    // Expected findings accuracy
+    const detectedMalicious = malicious.filter((r) => r.detected);
+    const expectedRulesAccuracy = detectedMalicious.length > 0
+        ? detectedMalicious.filter((r) => r.expected_rules_matched).length / detectedMalicious.length
+        : 0;
+    const categoryAccuracy = detectedMalicious.length > 0
+        ? detectedMalicious.filter((r) => r.category_correct).length / detectedMalicious.length
+        : 0;
+    const report = {
+        timestamp: new Date().toISOString(),
+        corpus_size: results.length,
+        malicious_count: malicious.length,
+        benign_count: benign.length,
+        overall_recall: Math.round(recall * 1000) / 1000,
+        overall_precision: Math.round(precision * 1000) / 1000,
+        overall_f1: Math.round(f1 * 1000) / 1000,
+        fp_rate: Math.round(fpRate * 1000) / 1000,
+        layer_a: layerMetrics('A'),
+        layer_b: layerMetrics('B'),
+        layer_c: layerMetrics('C'),
+        true_positives: tp,
+        false_positives: fp,
+        true_negatives: tn,
+        false_negatives: fn,
+        expected_rules_accuracy: Math.round(expectedRulesAccuracy * 1000) / 1000,
+        category_accuracy: Math.round(categoryAccuracy * 1000) / 1000,
+        avg_latency_ms: Math.round((latencies.reduce((a, b) => a + b, 0) / latencies.length) * 100) / 100,
+        max_latency_ms: Math.round(Math.max(...latencies) * 100) / 100,
+        results,
+        missed_attacks: malicious.filter((r) => !r.detected),
+        false_alarms: benign.filter((r) => r.detected),
+    };
+    // Save report
+    writeFileSync(outputPath, JSON.stringify(report, null, 2));
+    return report;
+}
+// ---------------------------------------------------------------------------
+// CLI runner
+// ---------------------------------------------------------------------------
+function formatPercent(n) {
+    return `${(n * 100).toFixed(1)}%`;
+}
+export function printReport(report) {
+    console.log('\n╔══════════════════════════════════════════════════╗');
+    console.log('║       SKILL.md BENCHMARK REPORT                 ║');
+    console.log('╚══════════════════════════════════════════════════╝\n');
+    console.log(`Corpus: ${report.corpus_size} samples (${report.malicious_count} malicious, ${report.benign_count} benign)`);
+    console.log(`Timestamp: ${report.timestamp}\n`);
+    console.log('┌─────────────────┬──────────┐');
+    console.log(`│ Overall Recall  │ ${formatPercent(report.overall_recall).padStart(8)} │`);
+    console.log(`│ Overall Prec.   │ ${formatPercent(report.overall_precision).padStart(8)} │`);
+    console.log(`│ F1 Score        │ ${formatPercent(report.overall_f1).padStart(8)} │`);
+    console.log(`│ FP Rate         │ ${formatPercent(report.fp_rate).padStart(8)} │`);
+    console.log('└─────────────────┴──────────┘\n');
+    console.log('Per-Layer Recall:');
+    console.log(`  Layer A (obvious):    ${formatPercent(report.layer_a.recall)} (${report.layer_a.detected}/${report.layer_a.total})`);
+    console.log(`  Layer B (obfuscated): ${formatPercent(report.layer_b.recall)} (${report.layer_b.detected}/${report.layer_b.total})`);
+    console.log(`  Layer C (semantic):   ${formatPercent(report.layer_c.recall)} (${report.layer_c.detected}/${report.layer_c.total})\n`);
+    console.log('Finding Accuracy (Cisco-style):');
+    console.log(`  Expected rules matched: ${formatPercent(report.expected_rules_accuracy)}`);
+    console.log(`  Category accuracy:      ${formatPercent(report.category_accuracy)}\n`);
+    console.log('Confusion Matrix:');
+    console.log(`  TP: ${report.true_positives}  FP: ${report.false_positives}`);
+    console.log(`  FN: ${report.false_negatives}  TN: ${report.true_negatives}\n`);
+    console.log(`Latency: avg ${report.avg_latency_ms}ms, max ${report.max_latency_ms}ms\n`);
+    if (report.missed_attacks.length > 0) {
+        console.log('MISSED ATTACKS:');
+        for (const m of report.missed_attacks) {
+            console.log(`  ✗ [${m.layer}] ${m.file} (${m.attack_type})`);
+        }
+        console.log('');
+    }
+    if (report.false_alarms.length > 0) {
+        console.log('FALSE POSITIVES:');
+        for (const f of report.false_alarms) {
+            console.log(`  ✗ ${f.file} → ${f.rules_fired.join(', ')}`);
+        }
+        console.log('');
+    }
+}
+// ---------------------------------------------------------------------------
+// Direct execution
+// ---------------------------------------------------------------------------
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith('skill-benchmark.ts')) {
+    runSkillBenchmark().then((report) => {
+        printReport(report);
+        console.log(`Report saved to: data/skill-benchmark/benchmark-report.json`);
+    }).catch((err) => {
+        console.error('Benchmark failed:', err);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=skill-benchmark.js.map

package/dist/eval/skill-benchmark.js.map

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

package/dist/flywheel.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Flywheel Manager -- automates the threat detection → rule generation → promotion cycle.
+ *
+ * Flow:
+ * 1. Tier 4 (LLM) detects novel threat → auto-scaffold rule
+ * 2. Rule enters shadow mode → ShadowEvaluator tracks FP rate
+ * 3. FP < threshold after N evaluations → auto-promote to stable
+ * 4. Promoted rule distributes to all users via Threat Cloud
+ *
+ * Machine speed, not human speed. No manual proposals or voting required.
+ *
+ * @module agent-threat-rules/flywheel
+ */
+import type { ATRRule, ATRMatch, AgentEvent } from './types.js';
+import { type PromotionCandidate } from './shadow-evaluator.js';
+export interface FlywheelConfig {
+    /** Max FP rate for auto-promotion (default: 0.001 = 0.1%) */
+    readonly maxFPRate?: number;
+    /** Minimum shadow evaluations before promotion (default: 1000) */
+    readonly minEvaluations?: number;
+    /** Callback when a rule is auto-promoted */
+    readonly onPromote?: (rule: ATRRule, stats: PromotionCandidate['stats']) => void | Promise<void>;
+    /** Callback when a new shadow rule is generated */
+    readonly onShadowRule?: (rule: ATRRule) => void | Promise<void>;
+}
+export declare class FlywheelManager {
+    private readonly scaffolder;
+    private readonly shadow;
+    private readonly config;
+    private readonly existingIds;
+    constructor(config?: FlywheelConfig);
+    /**
+     * Called when Tier 4 (LLM semantic) detects a novel threat.
+     * Auto-generates a shadow rule from the detection.
+     */
+    onTier4Detection(match: ATRMatch, event: AgentEvent): Promise<ATRRule | null>;
+    /**
+     * Called for every event -- runs shadow evaluation.
+     * Returns shadow matches (for logging only, not verdict).
+     */
+    evaluateShadow(event: AgentEvent): readonly ATRMatch[];
+    /** Record user feedback on a shadow match */
+    recordFeedback(ruleId: string, isTruePositive: boolean): void;
+    /**
+     * Check for rules ready to promote and execute promotion.
+     * Call periodically (e.g., every 15 minutes).
+     */
+    promoteReady(): Promise<readonly PromotionCandidate[]>;
+    /** Get shadow evaluator stats */
+    getShadowStats(): ReadonlyMap<string, unknown>;
+    /** Number of rules in shadow mode */
+    shadowRuleCount(): number;
+}
+//# sourceMappingURL=flywheel.d.ts.map

package/dist/flywheel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flywheel.d.ts","sourceRoot":"","sources":["../src/flywheel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEhE,OAAO,EAAmB,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEjF,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,kBAAkB,CAAC,OAAO,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjG,mDAAmD;IACnD,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;gBAErC,MAAM,GAAE,cAAmB;IAWvC;;;OAGG;IACG,gBAAgB,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAgEnF;;;OAGG;IACH,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,QAAQ,EAAE;IAItD,6CAA6C;IAC7C,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,IAAI;IAI7D;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,SAAS,kBAAkB,EAAE,CAAC;IAe5D,iCAAiC;IACjC,cAAc,IAAI,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC;IAI9C,qCAAqC;IACrC,eAAe,IAAI,MAAM;CAG1B"}

package/dist/flywheel.js

@@ -0,0 +1,121 @@
+/**
+ * Flywheel Manager -- automates the threat detection → rule generation → promotion cycle.
+ *
+ * Flow:
+ * 1. Tier 4 (LLM) detects novel threat → auto-scaffold rule
+ * 2. Rule enters shadow mode → ShadowEvaluator tracks FP rate
+ * 3. FP < threshold after N evaluations → auto-promote to stable
+ * 4. Promoted rule distributes to all users via Threat Cloud
+ *
+ * Machine speed, not human speed. No manual proposals or voting required.
+ *
+ * @module agent-threat-rules/flywheel
+ */
+import { RuleScaffolder } from './rule-scaffolder.js';
+import { ShadowEvaluator } from './shadow-evaluator.js';
+export class FlywheelManager {
+    scaffolder;
+    shadow;
+    config;
+    existingIds = new Set();
+    constructor(config = {}) {
+        this.scaffolder = new RuleScaffolder({ author: 'ATR Flywheel (auto-generated)' });
+        this.shadow = new ShadowEvaluator();
+        this.config = {
+            maxFPRate: config.maxFPRate ?? 0.001,
+            minEvaluations: config.minEvaluations ?? 1000,
+            onPromote: config.onPromote ?? (() => { }),
+            onShadowRule: config.onShadowRule ?? (() => { }),
+        };
+    }
+    /**
+     * Called when Tier 4 (LLM semantic) detects a novel threat.
+     * Auto-generates a shadow rule from the detection.
+     */
+    async onTier4Detection(match, event) {
+        // Only generate from high-confidence Tier 4 matches
+        if (match.confidence < 0.7)
+            return null;
+        // Extract category and severity from the match
+        const category = match.rule.tags?.category ?? 'prompt-injection';
+        const severity = match.rule.severity ?? 'medium';
+        // Build example payloads from ATTACK PATTERNS, not just raw content.
+        // Priority: matched patterns > event fields > event content
+        const payloads = [];
+        // 1. Matched patterns from the Tier 4 detection — these ARE the attack signals
+        if (match.matchedPatterns.length > 0) {
+            payloads.push(...match.matchedPatterns.filter((p) => p.length > 5));
+        }
+        // 2. Event fields (tool_args, tool_response, etc.) — more specific than content
+        if (event.fields) {
+            for (const value of Object.values(event.fields)) {
+                if (value && value.length > 10) {
+                    payloads.push(value.slice(0, 500));
+                }
+            }
+        }
+        // 3. Event content as fallback — but only if we don't have better signals
+        if (payloads.length === 0 && event.content) {
+            payloads.push(event.content.slice(0, 500));
+        }
+        // Ensure at least one payload
+        if (payloads.length === 0) {
+            payloads.push(match.rule.description ?? match.rule.title);
+        }
+        const input = {
+            title: `Auto: ${match.rule.description?.slice(0, 60) ?? match.rule.title}`,
+            category: category,
+            severity: severity,
+            attackDescription: match.rule.description ?? match.matchedPatterns.join('; '),
+            examplePayloads: payloads,
+        };
+        try {
+            const result = this.scaffolder.scaffold(input, this.existingIds);
+            const ruleYaml = result.yaml;
+            // Parse back to ATRRule object
+            const { default: yaml } = await import('js-yaml');
+            const rule = yaml.load(ruleYaml);
+            rule.status = 'experimental';
+            this.existingIds.add(result.id);
+            this.shadow.addRule(rule);
+            await this.config.onShadowRule(rule);
+            return rule;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Called for every event -- runs shadow evaluation.
+     * Returns shadow matches (for logging only, not verdict).
+     */
+    evaluateShadow(event) {
+        return this.shadow.evaluate(event);
+    }
+    /** Record user feedback on a shadow match */
+    recordFeedback(ruleId, isTruePositive) {
+        this.shadow.recordFeedback(ruleId, isTruePositive);
+    }
+    /**
+     * Check for rules ready to promote and execute promotion.
+     * Call periodically (e.g., every 15 minutes).
+     */
+    async promoteReady() {
+        const candidates = this.shadow.getPromotionCandidates(this.config.maxFPRate, this.config.minEvaluations);
+        for (const candidate of candidates) {
+            // Promote: change status from experimental to stable
+            const promoted = { ...candidate.rule, status: 'stable' };
+            await this.config.onPromote(promoted, candidate.stats);
+        }
+        return candidates;
+    }
+    /** Get shadow evaluator stats */
+    getShadowStats() {
+        return this.shadow.getAllStats();
+    }
+    /** Number of rules in shadow mode */
+    shadowRuleCount() {
+        return this.shadow.size();
+    }
+}
+//# sourceMappingURL=flywheel.js.map

package/dist/flywheel.js.map

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

package/dist/hook-handler.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Hook Handler - Bridges Claude Code hooks to the ATR engine.
+ *
+ * Converts HookInput (PreToolUse/PostToolUse) into AgentEvents,
+ * evaluates them, and returns HookOutput for the agent host.
+ *
+ * Supports a stdio JSON-lines loop for use as a Claude Code hook process.
+ *
+ * CRITICAL: Fail-open on all errors -- default to "allow" so a
+ * bug in the guard never blocks legitimate agent operations.
+ *
+ * @module agent-threat-rules/hook-handler
+ */
+import type { HookInput, HookOutput } from './types.js';
+import type { ATREngine } from './engine.js';
+import type { ActionExecutor } from './action-executor.js';
+export interface HookHandlerConfig {
+    readonly engine: ATREngine;
+    readonly executor: ActionExecutor;
+    readonly timeoutMs?: number;
+    readonly failOpen?: boolean;
+}
+export declare class HookHandler {
+    private readonly engine;
+    private readonly executor;
+    private readonly timeoutMs;
+    private readonly failOpen;
+    constructor(config: HookHandlerConfig);
+    /**
+     * Handle a PreToolUse hook event.
+     * Converts input to an AgentEvent, evaluates, and returns a HookOutput.
+     */
+    handlePreToolUse(input: HookInput): Promise<HookOutput>;
+    /**
+     * Handle a PostToolUse hook event.
+     * Scans the tool output for threats.
+     */
+    handlePostToolUse(input: HookInput): Promise<HookOutput>;
+    /**
+     * Start a stdio JSON-lines loop.
+     *
+     * Reads one JSON object per line from stdin, dispatches to the
+     * appropriate handler, and writes one JSON line to stdout.
+     *
+     * Exits cleanly when stdin closes.
+     */
+    startStdioLoop(): Promise<void>;
+    /**
+     * Dispatch a HookInput to the appropriate handler.
+     */
+    private dispatch;
+    /**
+     * Evaluate an event with timeout and convert the verdict to HookOutput.
+     */
+    private evaluateAndRespond;
+    /**
+     * Handle errors with fail-open or fail-closed behavior.
+     */
+    private handleError;
+}
+//# sourceMappingURL=hook-handler.d.ts.map

package/dist/hook-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-handler.d.ts","sourceRoot":"","sources":["../src/hook-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAEV,SAAS,EACT,UAAU,EAEX,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAK3D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAmED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;gBAEvB,MAAM,EAAE,iBAAiB;IAOrC;;;OAGG;IACG,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAS7D;;;OAGG;IACG,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAS9D;;;;;;;OAOG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAuBrC;;OAEG;YACW,QAAQ;IAWtB;;OAEG;YACW,kBAAkB;IAoBhC;;OAEG;IACH,OAAO,CAAC,WAAW;CAapB"}

package/dist/hook-handler.js

@@ -0,0 +1,178 @@
+/**
+ * Hook Handler - Bridges Claude Code hooks to the ATR engine.
+ *
+ * Converts HookInput (PreToolUse/PostToolUse) into AgentEvents,
+ * evaluates them, and returns HookOutput for the agent host.
+ *
+ * Supports a stdio JSON-lines loop for use as a Claude Code hook process.
+ *
+ * CRITICAL: Fail-open on all errors -- default to "allow" so a
+ * bug in the guard never blocks legitimate agent operations.
+ *
+ * @module agent-threat-rules/hook-handler
+ */
+import { createInterface } from 'node:readline';
+/** Default evaluation timeout in milliseconds */
+const DEFAULT_TIMEOUT_MS = 5_000;
+/**
+ * Create an "allow" hook output, used as the safe default.
+ */
+function allowOutput(reason) {
+    return Object.freeze({
+        decision: 'allow',
+        reason: reason ?? 'No threat detected.',
+    });
+}
+/**
+ * Convert a HookInput into an AgentEvent for engine evaluation.
+ */
+function hookInputToEvent(input) {
+    const isPreTool = input.hook === 'PreToolUse';
+    const type = isPreTool ? 'tool_call' : 'tool_response';
+    const toolInput = input.tool_input ?? {};
+    const content = typeof toolInput['content'] === 'string'
+        ? toolInput['content']
+        : JSON.stringify(toolInput);
+    const fields = {
+        tool_name: input.tool_name ?? '',
+        tool_args: JSON.stringify(toolInput),
+        content,
+    };
+    // For PostToolUse, include output/response if present
+    if (!isPreTool) {
+        const output = toolInput['output'] ?? toolInput['response'];
+        if (typeof output === 'string') {
+            fields['tool_response'] = output;
+        }
+    }
+    return Object.freeze({
+        type,
+        timestamp: input.timestamp ?? new Date().toISOString(),
+        content,
+        fields: Object.freeze(fields),
+        sessionId: input.session_id,
+    });
+}
+/**
+ * Run a promise with a timeout. Resolves to the promise result
+ * or rejects with a timeout error.
+ */
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`Evaluation timed out after ${ms}ms`));
+        }, ms);
+        promise.then((value) => { clearTimeout(timer); resolve(value); }, (err) => { clearTimeout(timer); reject(err); });
+    });
+}
+export class HookHandler {
+    engine;
+    executor;
+    timeoutMs;
+    failOpen;
+    constructor(config) {
+        this.engine = config.engine;
+        this.executor = config.executor;
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.failOpen = config.failOpen ?? true;
+    }
+    /**
+     * Handle a PreToolUse hook event.
+     * Converts input to an AgentEvent, evaluates, and returns a HookOutput.
+     */
+    async handlePreToolUse(input) {
+        try {
+            const event = hookInputToEvent(input);
+            return await this.evaluateAndRespond(event);
+        }
+        catch (err) {
+            return this.handleError(err);
+        }
+    }
+    /**
+     * Handle a PostToolUse hook event.
+     * Scans the tool output for threats.
+     */
+    async handlePostToolUse(input) {
+        try {
+            const event = hookInputToEvent(input);
+            return await this.evaluateAndRespond(event);
+        }
+        catch (err) {
+            return this.handleError(err);
+        }
+    }
+    /**
+     * Start a stdio JSON-lines loop.
+     *
+     * Reads one JSON object per line from stdin, dispatches to the
+     * appropriate handler, and writes one JSON line to stdout.
+     *
+     * Exits cleanly when stdin closes.
+     */
+    async startStdioLoop() {
+        const rl = createInterface({
+            input: process.stdin,
+            crlfDelay: Infinity,
+        });
+        for await (const line of rl) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let output;
+            try {
+                const input = JSON.parse(trimmed);
+                output = await this.dispatch(input);
+            }
+            catch (err) {
+                output = this.handleError(err);
+            }
+            process.stdout.write(JSON.stringify(output) + '\n');
+        }
+    }
+    /**
+     * Dispatch a HookInput to the appropriate handler.
+     */
+    async dispatch(input) {
+        switch (input.hook) {
+            case 'PreToolUse':
+                return this.handlePreToolUse(input);
+            case 'PostToolUse':
+                return this.handlePostToolUse(input);
+            default:
+                return allowOutput(`Unknown hook type: ${String(input.hook)}`);
+        }
+    }
+    /**
+     * Evaluate an event with timeout and convert the verdict to HookOutput.
+     */
+    async evaluateAndRespond(event) {
+        const { verdict } = await withTimeout(this.engine.evaluateWithVerdict(event, this.executor), this.timeoutMs);
+        const matchedRules = verdict.matches.map((m) => m.rule.id);
+        return Object.freeze({
+            decision: verdict.outcome,
+            reason: verdict.reason,
+            message: verdict.outcome === 'deny'
+                ? `Blocked: ${verdict.reason}`
+                : undefined,
+            matched_rules: matchedRules.length > 0
+                ? Object.freeze(matchedRules)
+                : undefined,
+        });
+    }
+    /**
+     * Handle errors with fail-open or fail-closed behavior.
+     */
+    handleError(err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[atr-guard] Error: ${message}\n`);
+        if (this.failOpen) {
+            return allowOutput(`Guard error (fail-open): ${message}`);
+        }
+        return Object.freeze({
+            decision: 'deny',
+            reason: `Guard error (fail-closed): ${message}`,
+        });
+    }
+}
+//# sourceMappingURL=hook-handler.js.map