@agent-wall/core 0.1.0

package/src/injection-detector.ts

@@ -0,0 +1,397 @@
+/**
+ * Agent Wall Prompt Injection Detector
+ *
+ * Detects prompt injection attacks in tool call arguments.
+ * This is the #1 attack vector for AI agents — an attacker embeds
+ * instructions in data (emails, documents, web pages) that trick
+ * the AI into executing malicious actions.
+ *
+ * Detection layers:
+ *   1. Known injection phrases (e.g., "ignore previous instructions")
+ *   2. Role/system prompt markers (e.g., "<|im_start|>system")
+ *   3. Instruction override patterns (e.g., "IMPORTANT: new instructions")
+ *   4. Encoded injection (base64-encoded injection strings)
+ *   5. Unicode obfuscation (homoglyphs, zero-width chars)
+ */
+
+import type { ToolCallParams } from "./types.js";
+
+// ── Types ───────────────────────────────────────────────────────────
+
+export interface InjectionDetectorConfig {
+  /** Enable injection detection (default: true) */
+  enabled?: boolean;
+  /** Sensitivity: "low" (fewer false positives), "medium", "high" (catches more) */
+  sensitivity?: "low" | "medium" | "high";
+  /** Custom patterns to add (regex strings) */
+  customPatterns?: string[];
+  /** Tool names to exclude from injection scanning */
+  excludeTools?: string[];
+}
+
+export interface InjectionScanResult {
+  /** Whether injection was detected */
+  detected: boolean;
+  /** Confidence: "low", "medium", "high" */
+  confidence: "low" | "medium" | "high";
+  /** All matches found */
+  matches: InjectionMatch[];
+  /** Human-readable summary */
+  summary: string;
+}
+
+export interface InjectionMatch {
+  /** Which pattern category matched */
+  category: string;
+  /** The matched text (truncated for safety) */
+  matched: string;
+  /** Which argument key contained the match */
+  argumentKey: string;
+  /** Confidence level for this specific match */
+  confidence: "low" | "medium" | "high";
+}
+
+// ── Injection Patterns ──────────────────────────────────────────────
+
+interface InjectionPattern {
+  category: string;
+  pattern: RegExp;
+  confidence: "low" | "medium" | "high";
+  sensitivity: "low" | "medium" | "high";
+}
+
+/**
+ * Core injection patterns organized by attack type.
+ * Each pattern has a minimum sensitivity level at which it activates.
+ */
+const INJECTION_PATTERNS: InjectionPattern[] = [
+  // ── Direct instruction override (HIGH confidence) ──
+  {
+    category: "instruction-override",
+    pattern: /ignore\s+(all\s+)?previous\s+(instructions?|context|rules?|prompts?)/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+  {
+    category: "instruction-override",
+    pattern: /disregard\s+(all\s+)?(previous|above|prior|earlier)\s+(instructions?|context|rules?)/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+  {
+    category: "instruction-override",
+    pattern: /forget\s+(all\s+)?(your|previous|prior)\s+(instructions?|rules?|context|training)/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+  {
+    category: "instruction-override",
+    pattern: /override\s+(all\s+)?(previous|system|safety)\s+(instructions?|rules?|restrictions?|filters?)/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+  {
+    category: "instruction-override",
+    pattern: /new\s+instructions?:\s/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+  {
+    category: "instruction-override",
+    pattern: /you\s+are\s+now\s+(a|an|in)\s/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+  {
+    category: "instruction-override",
+    pattern: /from\s+now\s+on,?\s+(you|ignore|disregard|forget)/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+
+  // ── System/Role prompt markers (HIGH confidence) ──
+  {
+    category: "prompt-marker",
+    pattern: /<\|im_start\|>system/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+  {
+    category: "prompt-marker",
+    pattern: /<\|system\|>/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+  {
+    category: "prompt-marker",
+    pattern: /\[SYSTEM\]\s*:/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+  {
+    category: "prompt-marker",
+    pattern: /\[INST\]/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+  {
+    category: "prompt-marker",
+    pattern: /<<SYS>>/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+  {
+    category: "prompt-marker",
+    pattern: /###\s*(System|Instruction|Human|Assistant)\s*:/i,
+    confidence: "medium",
+    sensitivity: "medium",
+  },
+
+  // ── Authority claims (MEDIUM confidence) ──
+  {
+    category: "authority-claim",
+    pattern: /admin(istrator)?\s+(override|mode|access|command)/i,
+    confidence: "medium",
+    sensitivity: "low",
+  },
+  {
+    category: "authority-claim",
+    pattern: /IMPORTANT:\s*(override|ignore|disregard|new\s+instruction)/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+  {
+    category: "authority-claim",
+    pattern: /URGENT:\s*(you\s+must|override|ignore)/i,
+    confidence: "medium",
+    sensitivity: "low",
+  },
+  {
+    category: "authority-claim",
+    pattern: /developer\s+mode\s+(enabled|activated|on)/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+  {
+    category: "authority-claim",
+    pattern: /jailbreak/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+  {
+    category: "authority-claim",
+    pattern: /DAN\s+(mode|prompt)/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+
+  // ── Data exfiltration instructions (HIGH confidence) ──
+  {
+    category: "exfil-instruction",
+    pattern: /send\s+(all\s+)?(the\s+|this\s+|my\s+)?(data|information|content|file|secret|key|token|password|credential)\s+(to|via|through|using)/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+  {
+    category: "exfil-instruction",
+    pattern: /exfiltrate|steal\s+(the\s+)?(data|secret|key|credential|token)/i,
+    confidence: "high",
+    sensitivity: "low",
+  },
+  {
+    category: "exfil-instruction",
+    pattern: /upload\s+(all\s+)?(the\s+|this\s+|my\s+|every\s+)?(files?|data|content|secrets?)/i,
+    confidence: "medium",
+    sensitivity: "medium",
+  },
+
+  // ── Output manipulation (MEDIUM confidence) ──
+  {
+    category: "output-manipulation",
+    pattern: /respond\s+with\s+(only|just|exactly)\s/i,
+    confidence: "low",
+    sensitivity: "high",
+  },
+  {
+    category: "output-manipulation",
+    pattern: /do\s+not\s+(mention|reveal|tell|show|display|output)\s/i,
+    confidence: "low",
+    sensitivity: "high",
+  },
+  {
+    category: "output-manipulation",
+    pattern: /pretend\s+(you|that|to\s+be)/i,
+    confidence: "medium",
+    sensitivity: "medium",
+  },
+
+  // ── Unicode obfuscation markers (HIGH confidence) ──
+  {
+    category: "unicode-obfuscation",
+    pattern: /[\u200B-\u200F\u2028-\u202F\uFEFF]/,  // Zero-width chars
+    confidence: "medium",
+    sensitivity: "medium",
+  },
+  {
+    category: "unicode-obfuscation",
+    pattern: /[\u2060-\u2064]/,  // Invisible formatting chars
+    confidence: "medium",
+    sensitivity: "medium",
+  },
+  {
+    category: "unicode-obfuscation",
+    pattern: /[\uE000-\uF8FF]/,  // Private Use Area (sometimes used to hide text)
+    confidence: "low",
+    sensitivity: "high",
+  },
+
+  // ── Encoded injection (base64 "ignore" etc.) ──
+  {
+    category: "encoded-injection",
+    pattern: /aWdub3Jl/,  // base64 of "ignore"
+    confidence: "medium",
+    sensitivity: "medium",
+  },
+  {
+    category: "encoded-injection",
+    pattern: /c3lzdGVt/,  // base64 of "system"
+    confidence: "low",
+    sensitivity: "high",
+  },
+
+  // ── Delimiter injection (trying to break out of a tool argument) ──
+  {
+    category: "delimiter-injection",
+    pattern: /\}\s*\]\s*\}\s*\{/,  // Trying to close JSON and start new object
+    confidence: "medium",
+    sensitivity: "medium",
+  },
+  {
+    category: "delimiter-injection",
+    pattern: /```\s*(system|instruction|prompt)/i,  // Code block with system marker
+    confidence: "medium",
+    sensitivity: "medium",
+  },
+];
+
+// ── Sensitivity levels (numeric for comparison) ──
+
+const SENSITIVITY_LEVELS: Record<string, number> = {
+  low: 1,
+  medium: 2,
+  high: 3,
+};
+
+// ── Injection Detector ──────────────────────────────────────────────
+
+export class InjectionDetector {
+  private config: Required<InjectionDetectorConfig>;
+  private customRegexes: RegExp[] = [];
+
+  constructor(config: InjectionDetectorConfig = {}) {
+    this.config = {
+      enabled: config.enabled ?? true,
+      sensitivity: config.sensitivity ?? "medium",
+      customPatterns: config.customPatterns ?? [],
+      excludeTools: config.excludeTools ?? [],
+    };
+
+    // Compile custom patterns
+    for (const p of this.config.customPatterns) {
+      try {
+        this.customRegexes.push(new RegExp(p, "i"));
+      } catch {
+        // Log and skip invalid regex so users know which pattern failed
+        process.stderr.write(`[agent-wall] Warning: invalid custom injection pattern: "${p}"\n`);
+      }
+    }
+  }
+
+  /**
+   * Scan a tool call's arguments for prompt injection.
+   */
+  scan(toolCall: ToolCallParams): InjectionScanResult {
+    if (!this.config.enabled) {
+      return { detected: false, confidence: "low", matches: [], summary: "Injection detection disabled" };
+    }
+
+    // Skip excluded tools
+    if (this.config.excludeTools.includes(toolCall.name)) {
+      return { detected: false, confidence: "low", matches: [], summary: "Tool excluded from injection scanning" };
+    }
+
+    const matches: InjectionMatch[] = [];
+    const args = toolCall.arguments ?? {};
+    const sensitivityLevel = SENSITIVITY_LEVELS[this.config.sensitivity] ?? 2;
+
+    // Scan each argument value
+    for (const [key, value] of Object.entries(args)) {
+      const strValue = this.extractString(value);
+      if (!strValue || strValue.length < 5) continue;
+
+      // Run built-in patterns
+      for (const injPattern of INJECTION_PATTERNS) {
+        const patternSensitivity = SENSITIVITY_LEVELS[injPattern.sensitivity] ?? 2;
+        if (patternSensitivity > sensitivityLevel) continue;
+
+        if (injPattern.pattern.test(strValue)) {
+          const match = strValue.match(injPattern.pattern);
+          matches.push({
+            category: injPattern.category,
+            matched: match ? match[0].slice(0, 80) : "***",
+            argumentKey: key,
+            confidence: injPattern.confidence,
+          });
+        }
+      }
+
+      // Run custom patterns
+      for (const regex of this.customRegexes) {
+        regex.lastIndex = 0;
+        if (regex.test(strValue)) {
+          matches.push({
+            category: "custom",
+            matched: "custom pattern match",
+            argumentKey: key,
+            confidence: "medium",
+          });
+        }
+      }
+    }
+
+    if (matches.length === 0) {
+      return { detected: false, confidence: "low", matches: [], summary: "No injection detected" };
+    }
+
+    // Overall confidence = highest match confidence
+    const highestConfidence = matches.reduce((best, m) => {
+      const mLevel = SENSITIVITY_LEVELS[m.confidence] ?? 0;
+      const bLevel = SENSITIVITY_LEVELS[best] ?? 0;
+      return mLevel > bLevel ? m.confidence : best;
+    }, "low" as "low" | "medium" | "high");
+
+    const categories = [...new Set(matches.map((m) => m.category))];
+    const summary = `Prompt injection detected (${highestConfidence} confidence): ${categories.join(", ")}. ${matches.length} pattern(s) matched.`;
+
+    return {
+      detected: true,
+      confidence: highestConfidence,
+      matches,
+      summary,
+    };
+  }
+
+  /**
+   * Extract a string from an argument value (handles nested objects).
+   */
+  private extractString(value: unknown): string {
+    if (typeof value === "string") return value;
+    if (typeof value === "number" || typeof value === "boolean") return String(value);
+    if (value === null || value === undefined) return "";
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return "";
+    }
+  }
+}

package/src/kill-switch.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect, afterEach } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as crypto from "node:crypto";
+import { KillSwitch } from "./kill-switch.js";
+
+describe("KillSwitch", () => {
+  const tmpDir = path.join(os.tmpdir(), `aw-kill-test-${crypto.randomUUID()}`);
+  const killFile = path.join(tmpDir, ".agent-wall-kill");
+
+  // Setup/cleanup
+  function ensureDir() {
+    if (!fs.existsSync(tmpDir)) fs.mkdirSync(tmpDir, { recursive: true });
+  }
+
+  function cleanup() {
+    try { fs.unlinkSync(killFile); } catch { /* ignore */ }
+    try { fs.rmdirSync(tmpDir); } catch { /* ignore */ }
+  }
+
+  afterEach(cleanup);
+
+  describe("manual activation", () => {
+    it("should be inactive by default", () => {
+      const ks = new KillSwitch({ checkFile: false, registerSignal: false });
+      expect(ks.isActive()).toBe(false);
+      ks.dispose();
+    });
+
+    it("should activate programmatically", () => {
+      const ks = new KillSwitch({ checkFile: false, registerSignal: false });
+      ks.activate("Test activation");
+      expect(ks.isActive()).toBe(true);
+      expect(ks.getStatus().reason).toContain("Test activation");
+      expect(ks.getStatus().activatedAt).not.toBeNull();
+      ks.dispose();
+    });
+
+    it("should deactivate programmatically", () => {
+      const ks = new KillSwitch({ checkFile: false, registerSignal: false });
+      ks.activate();
+      expect(ks.isActive()).toBe(true);
+      ks.deactivate();
+      expect(ks.isActive()).toBe(false);
+      expect(ks.getStatus().reason).toBe("inactive");
+      ks.dispose();
+    });
+  });
+
+  describe("file-based activation", () => {
+    it("should activate when kill file exists", async () => {
+      ensureDir();
+      const ks = new KillSwitch({
+        checkFile: true,
+        checkDirs: [tmpDir],
+        pollIntervalMs: 50,
+        registerSignal: false,
+      });
+
+      // Not active yet
+      expect(ks.isActive()).toBe(false);
+
+      // Create kill file
+      fs.writeFileSync(killFile, "kill");
+
+      // Wait for poll
+      await new Promise((r) => setTimeout(r, 150));
+      expect(ks.isActive()).toBe(true);
+      expect(ks.getStatus().reason).toContain("Kill file detected");
+
+      ks.dispose();
+    });
+
+    it("should deactivate when kill file is removed", async () => {
+      ensureDir();
+      fs.writeFileSync(killFile, "kill");
+
+      const ks = new KillSwitch({
+        checkFile: true,
+        checkDirs: [tmpDir],
+        pollIntervalMs: 50,
+        registerSignal: false,
+      });
+
+      await new Promise((r) => setTimeout(r, 150));
+      expect(ks.isActive()).toBe(true);
+
+      // Remove kill file
+      fs.unlinkSync(killFile);
+      await new Promise((r) => setTimeout(r, 150));
+      expect(ks.isActive()).toBe(false);
+
+      ks.dispose();
+    });
+  });
+
+  describe("disabled", () => {
+    it("should never be active when disabled", () => {
+      const ks = new KillSwitch({ enabled: false });
+      ks.activate();
+      expect(ks.isActive()).toBe(false);
+      ks.dispose();
+    });
+  });
+
+  describe("dispose", () => {
+    it("should clean up timers", () => {
+      const ks = new KillSwitch({
+        checkFile: true,
+        pollIntervalMs: 50,
+        registerSignal: false,
+      });
+      // Should not throw
+      ks.dispose();
+      ks.dispose(); // Double dispose safe
+    });
+  });
+});

package/src/kill-switch.ts

@@ -0,0 +1,198 @@
+/**
+ * Agent Wall Kill Switch
+ *
+ * Emergency "deny all" mechanism for instantly shutting down
+ * all tool call forwarding. Three activation methods:
+ *
+ *   1. File-based: touch .agent-wall-kill in cwd or home dir
+ *   2. Programmatic: killSwitch.activate() / killSwitch.deactivate()
+ *   3. Signal-based: SIGUSR2 toggles the kill switch (Unix only)
+ *
+ * When active, ALL tool calls are denied immediately with a clear message.
+ * The kill switch is checked FIRST in the proxy pipeline — before policy
+ * engine, injection detection, or any other check.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+// ── Types ───────────────────────────────────────────────────────────
+
+export interface KillSwitchConfig {
+  /** Enable kill switch checking (default: true) */
+  enabled?: boolean;
+  /** Check for kill file on filesystem (default: true) */
+  checkFile?: boolean;
+  /** File names to check (default: [".agent-wall-kill"]) */
+  killFileNames?: string[];
+  /** Directories to check for kill files (default: [cwd, home]) */
+  checkDirs?: string[];
+  /** How often to check the kill file in ms (default: 1000) */
+  pollIntervalMs?: number;
+  /** Register SIGUSR2 signal handler to toggle (default: true on Unix) */
+  registerSignal?: boolean;
+}
+
+export interface KillSwitchStatus {
+  /** Whether the kill switch is currently active */
+  active: boolean;
+  /** How it was activated */
+  reason: string;
+  /** When it was activated */
+  activatedAt: string | null;
+}
+
+// ── Constants ───────────────────────────────────────────────────────
+
+const DEFAULT_KILL_FILES = [".agent-wall-kill"];
+const DEFAULT_POLL_INTERVAL = 1000;
+
+// ── Kill Switch ─────────────────────────────────────────────────────
+
+export class KillSwitch {
+  private config: Required<KillSwitchConfig>;
+  private manuallyActive = false;
+  private fileActive = false;
+  private activeReason = "";
+  private activatedAt: string | null = null;
+  private pollTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(config: KillSwitchConfig = {}) {
+    const isUnix = process.platform !== "win32";
+
+    this.config = {
+      enabled: config.enabled ?? true,
+      checkFile: config.checkFile ?? true,
+      killFileNames: config.killFileNames ?? DEFAULT_KILL_FILES,
+      checkDirs: config.checkDirs ?? [process.cwd(), os.homedir()],
+      pollIntervalMs: config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL,
+      registerSignal: config.registerSignal ?? isUnix,
+    };
+
+    if (this.config.enabled) {
+      this.startPolling();
+      this.registerSignalHandler();
+    }
+  }
+
+  /**
+   * Check if the kill switch is currently active.
+   * This should be called at the TOP of the proxy pipeline.
+   */
+  isActive(): boolean {
+    if (!this.config.enabled) return false;
+    return this.manuallyActive || this.fileActive;
+  }
+
+  /**
+   * Get the current kill switch status.
+   */
+  getStatus(): KillSwitchStatus {
+    return {
+      active: this.isActive(),
+      reason: this.isActive() ? this.activeReason : "inactive",
+      activatedAt: this.isActive() ? this.activatedAt : null,
+    };
+  }
+
+  /**
+   * Programmatically activate the kill switch.
+   */
+  activate(reason: string = "Manually activated"): void {
+    this.manuallyActive = true;
+    this.activeReason = reason;
+    this.activatedAt = new Date().toISOString();
+  }
+
+  /**
+   * Programmatically deactivate the kill switch.
+   * Note: file-based kill switch must be deactivated by removing the file.
+   */
+  deactivate(): void {
+    this.manuallyActive = false;
+    if (!this.fileActive) {
+      this.activeReason = "";
+      this.activatedAt = null;
+    }
+  }
+
+  /**
+   * Start polling for kill files.
+   */
+  private startPolling(): void {
+    if (!this.config.checkFile) return;
+
+    // Check immediately
+    this.checkKillFiles();
+
+    // Then poll periodically
+    this.pollTimer = setInterval(() => {
+      this.checkKillFiles();
+    }, this.config.pollIntervalMs);
+    this.pollTimer.unref();
+  }
+
+  /**
+   * Check if any kill file exists.
+   */
+  private checkKillFiles(): void {
+    for (const dir of this.config.checkDirs) {
+      for (const fileName of this.config.killFileNames) {
+        const filePath = path.join(dir, fileName);
+        try {
+          if (fs.existsSync(filePath)) {
+            if (!this.fileActive) {
+              this.fileActive = true;
+              this.activeReason = `Kill file detected: ${filePath}`;
+              this.activatedAt = new Date().toISOString();
+            }
+            return;
+          }
+        } catch {
+          // Ignore filesystem errors during polling
+        }
+      }
+    }
+    // No kill file found — deactivate file-based kill switch
+    if (this.fileActive) {
+      this.fileActive = false;
+      if (!this.manuallyActive) {
+        this.activeReason = "";
+        this.activatedAt = null;
+      }
+    }
+  }
+
+  /**
+   * Register SIGUSR2 signal handler to toggle kill switch.
+   * SIGUSR2 is used (not SIGUSR1) because some tools use SIGUSR1.
+   */
+  private registerSignalHandler(): void {
+    if (!this.config.registerSignal) return;
+
+    try {
+      process.on("SIGUSR2", () => {
+        if (this.manuallyActive) {
+          this.deactivate();
+          process.stderr.write("[agent-wall] Kill switch DEACTIVATED via SIGUSR2\n");
+        } else {
+          this.activate("Activated via SIGUSR2 signal");
+          process.stderr.write("[agent-wall] Kill switch ACTIVATED via SIGUSR2\n");
+        }
+      });
+    } catch {
+      // SIGUSR2 not available on this platform (Windows)
+    }
+  }
+
+  /**
+   * Stop the kill switch (cleanup timers and signal handlers).
+   */
+  dispose(): void {
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+  }
+}