palaryn 0.1.0 → 0.3.2

package/src/dlp/text-normalizer.ts

@@ -0,0 +1,225 @@
+/**
+ * Text normalizer for bypass-resistant prompt injection detection.
+ *
+ * Applies a series of transformations to collapse evasion techniques
+ * (zero-width chars, HTML entities, homoglyphs, leetspeak, etc.)
+ * into canonical ASCII text before pattern matching.
+ */
+
+// ---------------------------------------------------------------------------
+// Zero-width character stripping
+// ---------------------------------------------------------------------------
+
+/** Regex matching zero-width and invisible Unicode characters. */
+export const ZERO_WIDTH_REGEX = /[\u200B\u200C\u200D\u00AD\uFEFF\u200E\u200F\u2060\u2061\u2062\u2063\u2064\u180E]/g;
+
+// ---------------------------------------------------------------------------
+// Homoglyph map (visually similar characters -> ASCII equivalents)
+// ---------------------------------------------------------------------------
+
+/** Map of Unicode homoglyphs to their ASCII equivalents. */
+export const HOMOGLYPH_MAP: Record<string, string> = {
+  // Cyrillic -> Latin
+  '\u0430': 'a', // а
+  '\u0435': 'e', // е
+  '\u043E': 'o', // о
+  '\u0440': 'p', // р
+  '\u0441': 'c', // с
+  '\u0443': 'y', // у
+  '\u0445': 'x', // х
+  '\u0456': 'i', // і
+  '\u0458': 'j', // ј
+  '\u04BB': 'h', // һ
+  '\u0410': 'A', // А
+  '\u0412': 'B', // В
+  '\u0415': 'E', // Е
+  '\u041A': 'K', // К
+  '\u041C': 'M', // М
+  '\u041D': 'H', // Н
+  '\u041E': 'O', // О
+  '\u0420': 'P', // Р
+  '\u0421': 'C', // С
+  '\u0422': 'T', // Т
+  '\u0425': 'X', // Х
+  // Greek -> Latin
+  '\u03B1': 'a', // α
+  '\u03BF': 'o', // ο
+  '\u03C1': 'p', // ρ
+  '\u0391': 'A', // Α
+  '\u0392': 'B', // Β
+  '\u0395': 'E', // Ε
+  '\u0397': 'H', // Η
+  '\u0399': 'I', // Ι
+  '\u039A': 'K', // Κ
+  '\u039C': 'M', // Μ
+  '\u039D': 'N', // Ν
+  '\u039F': 'O', // Ο
+  '\u03A1': 'P', // Ρ
+  '\u03A4': 'T', // Τ
+  '\u03A7': 'X', // Χ
+  '\u03A5': 'Y', // Υ
+  '\u0396': 'Z', // Ζ
+  // Fullwidth -> ASCII (supplemental to NFKC — belt and suspenders)
+  '\uFF41': 'a',
+  '\uFF42': 'b',
+  '\uFF43': 'c',
+  '\uFF49': 'i',
+  '\uFF4E': 'n',
+  '\uFF4F': 'o',
+  '\uFF50': 'p',
+  '\uFF52': 'r',
+  '\uFF53': 's',
+  '\uFF54': 't',
+  '\uFF55': 'u',
+  // Common lookalikes
+  '\u0131': 'i', // ı (dotless i)
+  '\u0237': 'j', // ȷ (dotless j)
+  '\u01C0': 'l', // ǀ (dental click -> l)
+};
+
+// Build reverse lookup for efficiency
+const homoglyphRegex = new RegExp(
+  '[' + Object.keys(HOMOGLYPH_MAP).join('') + ']',
+  'g',
+);
+
+// ---------------------------------------------------------------------------
+// Leetspeak map
+// ---------------------------------------------------------------------------
+
+/** Map of common leetspeak substitutions to their letter equivalents. */
+export const LEETSPEAK_MAP: Record<string, string> = {
+  '0': 'o',
+  '1': 'i',
+  '3': 'e',
+  '4': 'a',
+  '5': 's',
+  '7': 't',
+  '@': 'a',
+  '$': 's',
+  '!': 'i',
+};
+
+const leetspeakRegex = /[013457@$!]/g;
+
+// ---------------------------------------------------------------------------
+// HTML entity decoding
+// ---------------------------------------------------------------------------
+
+/** Named HTML entities most commonly used for evasion. */
+const NAMED_ENTITIES: Record<string, string> = {
+  '&lt;': '<',
+  '&gt;': '>',
+  '&amp;': '&',
+  '&quot;': '"',
+  '&apos;': "'",
+  '&nbsp;': ' ',
+  '&tab;': '\t',
+};
+
+/** Decode HTML entities (named + numeric decimal + numeric hex). */
+function decodeHTMLEntities(input: string): string {
+  // Named entities
+  let result = input;
+  for (const [entity, char] of Object.entries(NAMED_ENTITIES)) {
+    // Case-insensitive replacement for named entities
+    const re = new RegExp(entity.replace(/[&;]/g, (c) => '\\' + c), 'gi');
+    result = result.replace(re, char);
+  }
+
+  // Decimal numeric entities: &#105; -> 'i'
+  result = result.replace(/&#(\d+);/g, (_match, digits) => {
+    const code = parseInt(digits, 10);
+    if (code > 0 && code <= 0x10FFFF) {
+      return String.fromCodePoint(code);
+    }
+    return _match;
+  });
+
+  // Hex numeric entities: &#x69; -> 'i'
+  result = result.replace(/&#x([0-9a-fA-F]+);/g, (_match, hex) => {
+    const code = parseInt(hex, 16);
+    if (code > 0 && code <= 0x10FFFF) {
+      return String.fromCodePoint(code);
+    }
+    return _match;
+  });
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// URL decoding
+// ---------------------------------------------------------------------------
+
+/** Decode percent-encoded sequences (%69 -> 'i'). */
+function decodeURLEncoding(input: string): string {
+  try {
+    return decodeURIComponent(input);
+  } catch {
+    // If decoding fails (malformed sequences), apply partial decoding
+    return input.replace(/%([0-9a-fA-F]{2})/g, (_match, hex) => {
+      return String.fromCharCode(parseInt(hex, 16));
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main normalizer
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize text for bypass-resistant pattern matching.
+ *
+ * Applies transformations in order:
+ * 1. Strip zero-width / invisible Unicode characters
+ * 2. Unicode NFKC normalization (collapses fullwidth, ligatures, etc.)
+ * 3. Decode HTML entities (named + numeric)
+ * 4. Decode URL percent-encoding
+ * 5. Collapse homoglyphs (Cyrillic/Greek lookalikes -> ASCII)
+ * 6. Collapse repeated whitespace to single space
+ *
+ * @param input - The raw text to normalize.
+ * @returns The normalized text suitable for pattern matching.
+ */
+export function normalizeText(input: string): string {
+  // Early exit for very short strings
+  if (input.length === 0) return input;
+
+  let text = input;
+
+  // 1. Strip zero-width characters
+  text = text.replace(ZERO_WIDTH_REGEX, '');
+
+  // 2. NFKC normalization (fullwidth -> ASCII, ligatures -> components, etc.)
+  text = text.normalize('NFKC');
+
+  // 3. Decode HTML entities
+  text = decodeHTMLEntities(text);
+
+  // 4. Decode URL percent-encoding
+  text = decodeURLEncoding(text);
+
+  // 5. Collapse homoglyphs
+  text = text.replace(homoglyphRegex, (ch) => HOMOGLYPH_MAP[ch] || ch);
+
+  // 6. Collapse whitespace (spaces, tabs, newlines) to single space and trim
+  text = text.replace(/\s+/g, ' ').trim();
+
+  return text;
+}
+
+/**
+ * Apply leetspeak normalization on top of standard normalization.
+ *
+ * Returns the leet-decoded version of the text. Callers should match
+ * patterns against BOTH the standard-normalized and leet-normalized text
+ * to catch leet evasions without causing false positives on normal text
+ * containing digits.
+ *
+ * @param normalizedInput - Text already passed through normalizeText().
+ * @returns The leet-decoded text.
+ */
+export function normalizeLeetspeak(normalizedInput: string): string {
+  return normalizedInput.replace(leetspeakRegex, (ch) => LEETSPEAK_MAP[ch] || ch);
+}

package/src/dlp/tool-patterns.ts

@@ -0,0 +1,35 @@
+import { DLPPattern } from './patterns';
+
+// Shell injection patterns
+export const SHELL_INJECTION_PATTERNS: DLPPattern[] = [
+  { name: 'shell_pipe', pattern: /\|/g, severity: 'medium' },
+  { name: 'shell_subshell', pattern: /\$\(|\`/g, severity: 'high' },
+  { name: 'shell_redirect', pattern: /[><]{1,2}/g, severity: 'medium' },
+  { name: 'shell_semicolon', pattern: /;\s*\w/g, severity: 'high' },
+  { name: 'shell_background', pattern: /&\s*$/g, severity: 'medium' },
+  { name: 'shell_env_expansion', pattern: /\$\{[^}]+\}/g, severity: 'medium' },
+];
+
+// Path traversal patterns
+export const PATH_TRAVERSAL_PATTERNS: DLPPattern[] = [
+  { name: 'path_traversal', pattern: /\.\.\//g, severity: 'high' },
+  { name: 'path_traversal_encoded', pattern: /%2e%2e%2f/gi, severity: 'high' },
+  { name: 'path_null_byte', pattern: /%00/g, severity: 'high' },
+  { name: 'path_absolute_unix', pattern: /^\/(?:etc|proc|sys|dev|root|var\/log)\//g, severity: 'high' },
+];
+
+// SQL injection patterns
+export const SQL_INJECTION_PATTERNS: DLPPattern[] = [
+  { name: 'sql_union_select', pattern: /UNION\s+(?:ALL\s+)?SELECT/gi, severity: 'high' },
+  { name: 'sql_stacked_query', pattern: /;\s*(?:SELECT|INSERT|UPDATE|DELETE|DROP|ALTER|CREATE)\b/gi, severity: 'high' },
+  { name: 'sql_comment_injection', pattern: /(?:--|#|\/\*)/g, severity: 'medium' },
+  { name: 'sql_sleep_benchmark', pattern: /(?:SLEEP|BENCHMARK|WAITFOR\s+DELAY)\s*\(/gi, severity: 'high' },
+  { name: 'sql_info_schema', pattern: /INFORMATION_SCHEMA/gi, severity: 'high' },
+];
+
+/** All tool-specific DLP patterns combined */
+export const TOOL_DLP_PATTERNS: DLPPattern[] = [
+  ...SHELL_INJECTION_PATTERNS,
+  ...PATH_TRAVERSAL_PATTERNS,
+  ...SQL_INJECTION_PATTERNS,
+];

package/src/dlp/trufflehog-backend.ts

@@ -0,0 +1,190 @@
+import { execFileSync } from 'child_process';
+import { writeFileSync, unlinkSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+import { DLPSeverity } from '../types/tool-result';
+import { DLPBackend, DLPDetection } from './interfaces';
+
+/**
+ * Configuration for the TruffleHog DLP backend.
+ */
+export interface TruffleHogConfig {
+  /** Path to the trufflehog binary. Defaults to 'trufflehog' (resolved via PATH). */
+  binaryPath?: string;
+  /** Execution timeout in milliseconds. Defaults to 10000 (10s). */
+  timeout?: number;
+}
+
+/**
+ * Raw JSON output from a single trufflehog finding.
+ *
+ * TruffleHog emits one JSON object per line when run with --json.
+ */
+interface TruffleHogFinding {
+  DetectorName?: string;
+  DetectorType?: number;
+  Verified?: boolean;
+  Raw?: string;
+  RawV2?: string;
+  SourceMetadata?: unknown;
+  ExtraData?: Record<string, unknown>;
+}
+
+/**
+ * DLP backend that delegates secret scanning to the TruffleHog binary.
+ *
+ * TruffleHog is a comprehensive secret scanner that supports 700+ detector
+ * types including verified credential checks against live services.
+ *
+ * This backend writes the input string to a temporary file, runs
+ * `trufflehog filesystem --json --no-update <tmpfile>`, and parses the
+ * line-delimited JSON output into DLPDetection objects.
+ *
+ * Graceful degradation: if the trufflehog binary is not installed or the
+ * process fails for any reason, the backend logs a warning and returns an
+ * empty array (no detections). This allows it to be safely composed with
+ * other backends without breaking the pipeline.
+ */
+export class TruffleHogBackend implements DLPBackend {
+  readonly name = 'trufflehog';
+
+  private readonly binaryPath: string;
+  private readonly timeout: number;
+
+  constructor(config?: TruffleHogConfig) {
+    this.binaryPath = config?.binaryPath ?? 'trufflehog';
+    this.timeout = config?.timeout ?? 10_000;
+  }
+
+  /**
+   * Scan a string for secrets using trufflehog.
+   *
+   * 1. Writes the value to a temp file
+   * 2. Runs trufflehog filesystem in JSON mode
+   * 3. Parses each JSON line into a DLPDetection
+   * 4. Cleans up the temp file
+   *
+   * Returns an empty array if trufflehog is not available or fails.
+   */
+  scanString(value: string): DLPDetection[] {
+    const tmpFile = join(tmpdir(), `palaryn-dlp-${randomUUID()}.tmp`);
+
+    try {
+      // Write input to temp file for trufflehog to scan
+      writeFileSync(tmpFile, value, 'utf-8');
+
+      // Execute trufflehog
+      const stdout = execFileSync(
+        this.binaryPath,
+        ['filesystem', '--json', '--no-update', tmpFile],
+        {
+          timeout: this.timeout,
+          encoding: 'utf-8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        },
+      );
+
+      return this.parseOutput(stdout, value);
+    } catch (err: unknown) {
+      // Graceful degradation: log and return empty
+      const message = err instanceof Error ? err.message : String(err);
+      // Only log if it's not a "no findings" exit (trufflehog exits 0 with no output when clean)
+      if (!this.isNoFindingsError(message)) {
+        console.warn(`[TruffleHogBackend] scan failed: ${message}`);
+      }
+      return [];
+    } finally {
+      // Always clean up the temp file
+      try {
+        unlinkSync(tmpFile);
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  }
+
+  /**
+   * Parse trufflehog JSON output (one JSON object per line) into DLPDetection[].
+   *
+   * Each line is an independent JSON object representing a single finding.
+   */
+  private parseOutput(stdout: string, originalValue: string): DLPDetection[] {
+    if (!stdout || !stdout.trim()) {
+      return [];
+    }
+
+    const detections: DLPDetection[] = [];
+    const lines = stdout.trim().split('\n');
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+
+      try {
+        const finding: TruffleHogFinding = JSON.parse(trimmed);
+        const detection = this.findingToDetection(finding, originalValue);
+        if (detection) {
+          detections.push(detection);
+        }
+      } catch {
+        // Skip malformed JSON lines
+        continue;
+      }
+    }
+
+    return detections;
+  }
+
+  /**
+   * Convert a single trufflehog finding to a DLPDetection.
+   *
+   * Severity mapping:
+   *   - Verified findings -> 'high' (credential confirmed active)
+   *   - Unverified findings -> 'medium' (potential secret)
+   */
+  private findingToDetection(finding: TruffleHogFinding, originalValue: string): DLPDetection | null {
+    const detectorName = finding.DetectorName;
+    if (!detectorName) {
+      return null;
+    }
+
+    const raw = finding.Raw || finding.RawV2 || '';
+    const severity: DLPSeverity = finding.Verified ? 'high' : 'medium';
+
+    // Locate the raw finding within the original string
+    let start = 0;
+    let end = 0;
+    if (raw) {
+      const idx = originalValue.indexOf(raw);
+      if (idx !== -1) {
+        start = idx;
+        end = idx + raw.length;
+      } else {
+        // If we can't locate the raw match, use the full string range
+        start = 0;
+        end = originalValue.length;
+      }
+    }
+
+    return {
+      pattern_name: `trufflehog:${detectorName}`,
+      severity,
+      match: raw || originalValue,
+      start,
+      end,
+    };
+  }
+
+  /**
+   * Check if the error is simply a "no findings" situation rather than a real failure.
+   *
+   * TruffleHog may exit with code 0 and empty output, or in some versions
+   * it may produce an error-like message when there are no findings.
+   */
+  private isNoFindingsError(message: string): boolean {
+    // execFileSync throws if the process exits with non-zero or produces no output
+    // for an empty scan. Check for common benign patterns.
+    return message.includes('ENOENT') === false && message.includes('ETIMEDOUT') === false;
+  }
+}

package/src/executor/filesystem-executor.ts

@@ -0,0 +1,196 @@
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { ToolCall } from '../types/tool-call';
+import { ToolOutput } from '../types/tool-result';
+import { ToolExecutor } from './interfaces';
+import { FilesystemExecutorConfig } from '../types/config';
+
+/**
+ * Filesystem executor for sandboxed file operations.
+ * Handles tool calls with tool name `file.*` (e.g., file.read, file.write).
+ * All paths are resolved relative to and contained within base_dir.
+ */
+export class FilesystemExecutor implements ToolExecutor {
+  private config: FilesystemExecutorConfig;
+  private resolvedBaseDir: string;
+
+  constructor(config: FilesystemExecutorConfig) {
+    this.config = config;
+    this.resolvedBaseDir = path.resolve(config.base_dir);
+  }
+
+  async execute(toolCall: ToolCall): Promise<ToolOutput> {
+    const action = this.resolveAction(toolCall);
+
+    switch (action) {
+      case 'read':
+        return this.read(toolCall);
+      case 'write':
+        return this.write(toolCall);
+      case 'delete':
+        return this.delete(toolCall);
+      case 'list':
+        return this.list(toolCall);
+      case 'stat':
+        return this.stat(toolCall);
+      default:
+        throw new Error(`Unsupported filesystem action: ${action}`);
+    }
+  }
+
+  private resolveAction(toolCall: ToolCall): string {
+    if (toolCall.args.action && typeof toolCall.args.action === 'string') {
+      return toolCall.args.action;
+    }
+
+    const toolName = toolCall.tool.name;
+    const dotIndex = toolName.indexOf('.');
+    if (dotIndex !== -1) {
+      return toolName.substring(dotIndex + 1);
+    }
+
+    throw new Error(`Unsupported filesystem action: ${toolName}`);
+  }
+
+  /**
+   * Resolve and validate a path, ensuring it stays within base_dir.
+   * Prevents path traversal attacks.
+   */
+  private resolveSafePath(filePath: string): string {
+    const resolved = path.resolve(this.resolvedBaseDir, filePath);
+    if (!resolved.startsWith(this.resolvedBaseDir + path.sep) && resolved !== this.resolvedBaseDir) {
+      throw new Error(`Path traversal denied: "${filePath}" resolves outside base directory`);
+    }
+    return resolved;
+  }
+
+  private checkExtension(filePath: string): void {
+    const allowed = this.config.allowed_extensions;
+    if (allowed && allowed.length > 0) {
+      const ext = path.extname(filePath).toLowerCase();
+      if (!allowed.includes(ext)) {
+        throw new Error(`File extension "${ext}" is not allowed. Allowed: ${allowed.join(', ')}`);
+      }
+    }
+  }
+
+  private async read(toolCall: ToolCall): Promise<ToolOutput> {
+    const { path: filePath, encoding } = toolCall.args;
+
+    if (!filePath || typeof filePath !== 'string') {
+      throw new Error('Missing or invalid "path" argument for file.read');
+    }
+
+    const resolved = this.resolveSafePath(filePath);
+    this.checkExtension(resolved);
+
+    const stat = await fs.stat(resolved);
+    if (stat.size > this.config.max_file_size_bytes) {
+      throw new Error(`File size ${stat.size} exceeds max allowed ${this.config.max_file_size_bytes} bytes`);
+    }
+
+    const content = await fs.readFile(resolved, {
+      encoding: (encoding as BufferEncoding) || 'utf-8',
+    });
+
+    return { body: content, paths: [filePath] };
+  }
+
+  private async write(toolCall: ToolCall): Promise<ToolOutput> {
+    const { path: filePath, content, encoding, append } = toolCall.args;
+
+    if (!filePath || typeof filePath !== 'string') {
+      throw new Error('Missing or invalid "path" argument for file.write');
+    }
+    if (content === undefined || content === null) {
+      throw new Error('Missing "content" argument for file.write');
+    }
+
+    const resolved = this.resolveSafePath(filePath);
+    this.checkExtension(resolved);
+
+    const data = typeof content === 'string' ? content : JSON.stringify(content);
+
+    if (Buffer.byteLength(data) > this.config.max_file_size_bytes) {
+      throw new Error(`Content size exceeds max allowed ${this.config.max_file_size_bytes} bytes`);
+    }
+
+    // Ensure parent directory exists
+    await fs.mkdir(path.dirname(resolved), { recursive: true });
+
+    if (append) {
+      await fs.appendFile(resolved, data, {
+        encoding: (encoding as BufferEncoding) || 'utf-8',
+      });
+    } else {
+      await fs.writeFile(resolved, data, {
+        encoding: (encoding as BufferEncoding) || 'utf-8',
+      });
+    }
+
+    return { body: { written: true }, paths: [filePath] };
+  }
+
+  private async delete(toolCall: ToolCall): Promise<ToolOutput> {
+    const { path: filePath, recursive } = toolCall.args;
+
+    if (!filePath || typeof filePath !== 'string') {
+      throw new Error('Missing or invalid "path" argument for file.delete');
+    }
+
+    const resolved = this.resolveSafePath(filePath);
+
+    const stat = await fs.stat(resolved);
+    if (stat.isDirectory()) {
+      await fs.rm(resolved, { recursive: !!recursive });
+    } else {
+      await fs.unlink(resolved);
+    }
+
+    return { body: { deleted: true }, paths: [filePath] };
+  }
+
+  private async list(toolCall: ToolCall): Promise<ToolOutput> {
+    const { path: dirPath, pattern } = toolCall.args;
+
+    const targetPath = (dirPath && typeof dirPath === 'string') ? dirPath : '.';
+    const resolved = this.resolveSafePath(targetPath);
+
+    const entries = await fs.readdir(resolved, { withFileTypes: true });
+
+    let items = entries.map(entry => ({
+      name: entry.name,
+      type: entry.isDirectory() ? 'directory' : 'file',
+    }));
+
+    if (pattern && typeof pattern === 'string') {
+      const regex = new RegExp(pattern);
+      items = items.filter(item => regex.test(item.name));
+    }
+
+    return { body: items, paths: [targetPath] };
+  }
+
+  private async stat(toolCall: ToolCall): Promise<ToolOutput> {
+    const { path: filePath } = toolCall.args;
+
+    if (!filePath || typeof filePath !== 'string') {
+      throw new Error('Missing or invalid "path" argument for file.stat');
+    }
+
+    const resolved = this.resolveSafePath(filePath);
+    const stat = await fs.stat(resolved);
+
+    return {
+      body: {
+        size: stat.size,
+        is_file: stat.isFile(),
+        is_directory: stat.isDirectory(),
+        created: stat.birthtime.toISOString(),
+        modified: stat.mtime.toISOString(),
+        permissions: stat.mode.toString(8),
+      },
+      paths: [filePath],
+    };
+  }
+}