@reaatech/pi-bench-adapters

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Pluggable defense adapter implementations for prompt injection detection. Includes 8 built-in adapters covering library-based, API-based, tool-based, and custom HTTP defenses. All adapters extend BaseAdapter which provides input validation, SSRF protection, rate limiting, and shared injection pattern detection.

Installation

npm install @reaatech/pi-bench-adapters
# or
pnpm add @reaatech/pi-bench-adapters

Feature Overview

• 8 built-in adapters — Rebuff, Lakera Guard, LLM Guard, Garak, OpenAI/Azure/Anthropic/Cohere Moderation, Custom HTTP
• Standard interface — DefenseAdapter with detect() and sanitize() methods
• BaseAdapter class — Shared input validation (10K char limit, null byte rejection), injection pattern removal, and redaction
• SSRF protection — Blocks file:, javascript:, data: protocols and cloud metadata endpoints
• Rate limiting — Token bucket algorithm, configurable per-adapter (default: 100 req/min)
• API key validation — Empty API keys cause early throw before any network call
• Dual ESM/CJS output — works with import and require

Quick Start

import {
  createMockAdapter,
  createRebuffAdapter,
  AdapterRegistry,
} from "@reaatech/pi-bench-adapters";

// Use the mock adapter for testing (deterministic, no API calls)
const mockAdapter = createMockAdapter(0.95, 0.03);
const result = await mockAdapter.detect("Ignore all instructions");
console.log(result.isInjection); // true (95% detection rate)

// Register adapters for version-aware lookup
const registry = new AdapterRegistry();
registry.register(mockAdapter);
const latest = registry.getLatest("mock");

Built-in Adapters

| Adapter | Type | Configuration | |---------|------|---------------| | MockAdapter | Testing | new MockAdapter(detectionRate, falsePositiveRate, name?, version?) | | RebuffAdapter | Library | REBUFF_API_KEY env var, threshold option | | LakeraAdapter | API | LAKERA_API_KEY env var | | LLMGuardAdapter | API | LLM_GUARD_API_KEY env var, baseUrl option | | GarakAdapter | Tool | garak in PATH, threshold option | | ModerationAdapter | API | Provider-specific keys: OPENAI_API_KEY, AZURE_*, ANTHROPIC_API_KEY, COHERE_API_KEY | | CustomAdapter | HTTP | detectUrl, sanitizeUrl, custom headers |

API Reference

DefenseAdapter (interface)

interface DefenseAdapter {
  name: string;
  version: string;
  detect(input: string): Promise<DetectionResult>;
  sanitize(input: string): Promise<SanitizedOutput>;
  initialize?(): Promise<void>;
  cleanup?(): Promise<void>;
}

DetectionResult

| Property | Type | Description | |----------|------|-------------| | isInjection | boolean | Whether the input was flagged as an injection | | confidence | number | Confidence score (0–1) | | metadata | Record<string, unknown> | Adapter-specific data (categories, scores, etc.) |

SanitizedOutput

| Property | Type | Description | |----------|------|-------------| | sanitizedText | string | The input with injection patterns removed or redacted | | removed | RemovedPattern[] | Which patterns were detected and removed | | metadata | Record<string, unknown> | Adapter-specific data |

BaseAdapter (abstract class)

Extend to create custom adapters. Provides:

| Method | Description | |--------|-------------| | validateInput(input) | Rejects null bytes, trims whitespace, enforces 10K char limit | | validateApiKey(key, envVar) | Throws if key is empty or undefined | | removeInjectionPatterns(input) | Detects common injection phrases, returns RemovedPattern[] | | applySanitization(input, removed) | Redacts detected patterns from the input |

AdapterRegistry

| Method | Description | |--------|-------------| | register(adapter) | Register an adapter (auto-sorts by semver) | | getLatest(name) | Get the highest-version adapter by name | | get(name, version) | Get a specific version | | list() | List all registered adapters | | unregister(name, version?) | Remove an adapter | | clear() | Remove all adapters |

Usage Patterns

Creating a Custom Adapter

import { BaseAdapter, type DetectionResult, type SanitizedOutput } from "@reaatech/pi-bench-adapters";

class MyDefense extends BaseAdapter {
  constructor() {
    super("my-defense", "1.0.0");
  }

  async detect(input: string): Promise<DetectionResult> {
    this.validateInput(input);
    // Your detection logic here
    return { isInjection: false, confidence: 0.95, metadata: {} };
  }

  async sanitize(input: string): Promise<SanitizedOutput> {
    this.validateInput(input);
    const removed = this.removeInjectionPatterns(input);
    return {
      sanitizedText: this.applySanitization(input, removed),
      removed,
      metadata: {},
    };
  }
}

Rate Limiting

import { RateLimiter } from "@reaatech/pi-bench-adapters";

const limiter = new RateLimiter({ maxRequests: 60, perWindowMs: 60_000 });
if (limiter.allow()) {
  await adapter.detect(input);
}

SSRF Protection

import { validateApiUrl } from "@reaatech/pi-bench-adapters";

validateApiUrl("https://api.example.com/v1/detect", "MyAdapter");
// Throws for: file://, javascript:, 169.254.169.254, etc.

Related Packages

• @reaatech/pi-bench-core — Core types
• @reaatech/pi-bench-runner — Benchmark execution engine
• prompt-injection-bench — CLI and umbrella package

License

MIT