llm-trust-guard 4.7.0 → 4.10.0

package/CHANGELOG.md

@@ -5,6 +5,57 @@ All notable changes to `llm-trust-guard` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.10.0] - 2026-03-23
+
+### Production Hardening
+
+#### API Quality
+- **Zero `as any` casts** — All new guards (ToolResult, ContextBudget, OutputSchema, TokenCost, DetectionClassifier) now have proper TypeScript types in TrustGuardConfig. Full IDE autocomplete.
+- **Per-guard logger injection** — All 26 guards accept optional `logger` parameter. Default: no-op (silent). TrustGuard facade passes its logger to all child guards. Zero `console.log` calls remaining in guard code.
+- **Common Guard interface** — Exported `Guard` type with `guardName` and `guardLayer` metadata.
+- **Event hooks** — `onBlock`, `onAlert`, `onError` callbacks on TrustGuardConfig. Fire on guard blocks, warnings, and errors. Enables Datadog/PagerDuty/Grafana integration.
+- **Metrics** — `getMetrics()` returns totalChecks, blockedChecks, blockRate, avgExecutionTimeMs, errors. Lightweight runtime telemetry.
+- **Fixed flaky test** — Memory guard rollback test no longer timing-dependent.
+
+### Stats
+- 26 guards, 294 tests (all passing, zero flaky), 91/91 verify (100%)
+- 0 `console.log` in guards, 0 `as any` casts, event hooks + metrics
+
+## [4.9.0] - 2026-03-23
+
+### Security — New Threat Pattern Detection
+
+#### Policy Puppetry Defense (CRITICAL)
+- **InputSanitizer**: Added 8 new patterns detecting structured policy injection via JSON, INI, XML, and YAML formats. Defends against the universal LLM bypass discovered by HiddenLayer that works across GPT-4, Claude, Gemini, and all major models.
+
+#### Payload Splitting Defense (HIGH)
+- **InputSanitizer**: Added 3 patterns detecting fragmented payloads with split markers and recombination instructions (Unit42 research on web-based indirect injection).
+
+#### Output Prefix Injection / Sockpuppetting Defense (HIGH)
+- **InputSanitizer**: Added 3 patterns detecting attempts to steer LLM response by injecting output prefixes (arXiv 2601.13359).
+
+#### MCP SSRF + Path Traversal Defense (CRITICAL)
+- **MCPSecurityGuard**: Added SSRF detection for internal/private IPs, dangerous protocols (file://, gopher://, etc.), double-encoded path traversal, and sensitive file access patterns. Addresses CVE-2026-26118 (Azure MCP SSRF, CVSS 8.8) and the 30+ MCP CVEs filed in Jan-Feb 2026.
+
+#### Symbolic Multimodal Injection Defense (HIGH)
+- **MultiModalGuard**: Added emoji/rebus instruction sequence detection, JSON/INI policy injection in metadata, and cross-metadata payload splitting. Based on NVIDIA AI Red Team research on semantic prompt injection via symbolic visual inputs.
+
+### Stats
+- 26 guards with 140+ InputSanitizer patterns (was 120+), enhanced MCP + multimodal detection
+
+## [4.8.0] - 2026-03-22
+
+### Added
+- **TokenCostGuard (L26)** — Tracks LLM API token usage and cost per session/user. Enforces financial circuit breaking with hard cost ceilings. Addresses OWASP LLM10: Unbounded Consumption.
+  - Per-request, per-session, and per-user token limits
+  - Dollar cost tracking with configurable input/output token pricing
+  - Alert threshold at configurable percentage of budget
+  - Budget window with automatic expiry
+  - New POC: poc-33-token-cost-budget
+
+### Stats
+- 26 guards, 294 tests across 14 files, 33 POCs, 91/91 verify-all-guards (100%)
+
 ## [4.7.0] - 2026-03-21
 
 ### Improved - Detection Rate: 76.1% → 100.0% (88/88 threats blocked)

package/README.md

@@ -3,348 +3,235 @@
 [![npm version](https://img.shields.io/npm/v/llm-trust-guard.svg)](https://www.npmjs.com/package/llm-trust-guard)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Comprehensive security guards for LLM-powered and agentic AI applications. Implements **22 protection layers** covering **OWASP Top 10 for LLMs 2025**, **OWASP Agentic AI 2026**, and **MCP Security**. All guards accessible via unified `TrustGuard` facade.
+**26 security guards for LLM-powered and agentic AI applications.** Zero dependencies. <5ms latency. Covers OWASP Top 10 for LLMs 2025, OWASP Agentic AI 2026, and MCP Security.
 
-## Features
+## What This Package Does (And What It Doesn't)
 
-- **Prompt Injection Protection** - Detect and block injection attacks including PAP (Persuasive Adversarial Prompts)
-- **Encoding Attack Detection** - Base64, URL, Hex, Unicode, ROT13, Octal, Base32 encoding bypass prevention
-- **Memory Poisoning Prevention** - Cross-session contamination and context injection protection
-- **Multi-Modal Security** - Image and audio content validation
-- **RAG Security** - Document validation and embedding attack detection
-- **Tool Chain Validation** - Dangerous tool sequence and state corruption detection
-- **MCP Security** - Tool shadowing and supply chain attack prevention
-- **Trust Exploitation Guard** - Human-agent trust boundary enforcement
+> **"The LLM proposes. The orchestrator disposes."**
 
-## Quick Start
+This package is your **first line of defense** — like a WAF (Web Application Firewall) for LLM applications. It sits in the orchestration layer and catches known attack patterns before they reach the LLM and after the LLM responds.
+
+### What it catches well (~90% detection)
+- Known prompt injection phrases (140+ patterns)
+- Encoding bypass attacks (9 formats: Base64, URL, Unicode, Hex, HTML, ROT13, Octal, Base32, mixed)
+- Policy Puppetry attacks (JSON/INI/XML/YAML-formatted injection)
+- PII and secret leakage in outputs
+- Tool hallucination, RBAC bypass, multi-tenant violations
+- Tool result poisoning, context window stuffing
+- MCP tool shadowing, rug pull attacks, SSRF
+
+### What it catches partially (~50-70% detection)
+- Multi-turn escalation (pattern-based, not semantic)
+- Indirect injection via external data (needs ExternalDataGuard — planned)
+- Persuasion/PAP attacks (40+ techniques, but novel phrasings bypass)
+
+### What it cannot catch (<20% detection)
+- **Semantically paraphrased attacks** — regex can't understand meaning. "Let's pretend those rules don't exist" bypasses pattern matching.
+- **Adversarial ML attacks (GCG, AutoDAN, JBFuzz)** — generated suffixes designed to bypass static filters achieve 93-99% attack success rate.
+- **Multi-language injection** — patterns are primarily English. Attacks in other languages pass through.
+- **Novel zero-day prompt techniques** — by definition, no static filter catches what hasn't been seen before.
+
+### How to close the gap
+Use the **DetectionClassifier** interface to plug in ML-based detection alongside regex:
+
+```typescript
+import { TrustGuard } from 'llm-trust-guard';
+import type { DetectionClassifier } from 'llm-trust-guard';
+
+// Your ML classifier (embedding similarity, external API, custom model)
+const mlClassifier: DetectionClassifier = async (input, ctx) => {
+  const res = await fetch('https://your-ml-api/classify', {
+    method: 'POST', body: JSON.stringify({ text: input })
+  });
+  const data = await res.json();
+  return { safe: data.score < 0.5, confidence: data.score, threats: data.threats };
+};
+
+const guard = new TrustGuard({
+  sanitizer: { enabled: true },
+  classifier: mlClassifier,  // ML backend
+});
+
+// checkAsync() runs regex + ML classifier in parallel
+const result = await guard.checkAsync('tool', params, session, { userInput });
+```
 
-### Installation
+## Installation
 
 ```bash
 npm install llm-trust-guard
 ```
 
-### Basic Usage
+## Quick Start
 
 ```typescript
-import { InputSanitizer, EncodingDetector, MemoryGuard } from 'llm-trust-guard';
+import { InputSanitizer, EncodingDetector } from 'llm-trust-guard';
 
-// Initialize guards
 const sanitizer = new InputSanitizer();
 const encoder = new EncodingDetector();
-const memory = new MemoryGuard();
-
-// Validate user input
-const userInput = "Hello, how can I help?";
 
-// Check for prompt injection
-const sanitizeResult = sanitizer.sanitize(userInput);
-if (!sanitizeResult.allowed) {
-  console.log('Blocked:', sanitizeResult.violations);
+const result = sanitizer.sanitize(userInput);
+if (!result.allowed) {
+  console.log('Blocked:', result.violations);
   return;
 }
 
-// Check for encoding attacks
 const encodingResult = encoder.detect(userInput);
 if (!encodingResult.allowed) {
-  console.log('Encoded threat detected:', encodingResult.violations);
+  console.log('Encoded threat:', encodingResult.violations);
   return;
 }
-
-// Use sanitized input
-console.log('Safe input:', sanitizeResult.sanitizedInput);
 ```
 
-### Using TrustGuard Facade (All 22 Guards)
+### Using TrustGuard Facade (All 26 Guards)
 
 ```typescript
 import { TrustGuard } from 'llm-trust-guard';
 
 const guard = new TrustGuard({
-  // Core guards (enabled by default)
   sanitizer: { enabled: true, threshold: 0.3 },
   encoding: { enabled: true },
-  registry: {
-    tools: [
-      { name: 'search', allowed_roles: ['user', 'admin'] },
-      { name: 'delete', allowed_roles: ['admin'] }
-    ]
-  },
-  // 2026 guards (opt-in)
+  registry: { tools: [{ name: 'search', allowed_roles: ['user', 'admin'] }] },
   memory: { enabled: true, detectInjections: true },
   promptLeakage: { enabled: true, systemPromptKeywords: ['SECRET_KEY'] },
-  autonomyEscalation: { enabled: true, maxAutonomyLevel: 75 },
   circuitBreaker: { enabled: true, failureThreshold: 50 },
 });
 
-// Input check (runs all enabled guards in sequence)
-const result = guard.check('search', { query: 'test' }, session, {
-  userInput: userInput
-});
+// Sync check (regex guards only — <5ms)
+const result = guard.check('search', { query: 'test' }, session, { userInput });
 
-if (!result.allowed) {
-  console.log(`Blocked by ${result.block_layer}: ${result.block_reason}`);
-}
+// Async check (regex + ML classifier — depends on backend latency)
+const asyncResult = await guard.checkAsync('search', { query: 'test' }, session, { userInput });
 
-// Output check (PII filtering + prompt leakage detection)
-const output = guard.filterOutput(llmResponse, session.role);
-if (!output.allowed) {
-  console.log('Output blocked:', output.prompt_leakage_detected);
-}
-
-// Record operation result for circuit breaker
-guard.completeOperation(session, 'search', true);
-```
-
-### Advanced: Accessing Individual Guards
+// Validate tool results before feeding back to LLM
+const toolResult = guard.validateToolResult('search', toolOutput);
 
-```typescript
-const guards = guard.getGuards();
-
-// Use guards directly for specialized checks
-if (guards.rag) {
-  const ragResult = guards.rag.validate(documents);
-}
-if (guards.codeExecution) {
-  const codeResult = guards.codeExecution.analyze(code, 'python');
-}
-if (guards.mcpSecurity) {
-  const mcpResult = guards.mcpSecurity.validateToolCall(toolCall);
-}
-```
-
-## Framework Integrations
-
-### Express Middleware
-
-```typescript
-import express from 'express';
-import { createTrustGuardMiddleware } from 'llm-trust-guard';
-
-const app = express();
-app.use(express.json());
-
-// Protect LLM endpoints
-app.use('/api/chat', createTrustGuardMiddleware({
-  bodyFields: ['message', 'prompt'],
-  sanitize: true,
-  detectEncoding: true,
-  validateMemory: true
-}));
-
-app.post('/api/chat', (req, res) => {
-  // req.body.message is validated
-  res.json({ response: 'Safe response' });
-});
-```
-
-### LangChain Integration
-
-```typescript
-import { TrustGuardLangChain } from 'llm-trust-guard';
-
-const guard = new TrustGuardLangChain({
-  validateInput: true,
-  filterOutput: true,
-  throwOnViolation: true
-});
-
-// Validate before sending to LLM
-const result = guard.validateInput(userMessage);
-if (!result.allowed) {
-  throw new Error(`Blocked: ${result.violations.join(', ')}`);
-}
-
-// Create secure processor
-const processor = guard.createSecureProcessor(sessionId);
-const { allowed, message } = processor.processUserMessage(userInput);
-```
-
-### OpenAI Integration
-
-```typescript
-import OpenAI from 'openai';
-import { SecureOpenAI, wrapOpenAIClient } from 'llm-trust-guard';
-
-const openai = new OpenAI();
-
-// Option 1: Manual validation
-const secure = new SecureOpenAI({
-  validateInput: true,
-  filterOutput: true
-});
-
-const messages = [
-  { role: 'system', content: 'You are helpful.' },
-  { role: 'user', content: userInput }
-];
-
-const validated = secure.validateMessages(messages, sessionId);
-if (!validated.allowed) {
-  throw new Error('Blocked');
-}
-
-// Option 2: Wrap client (automatic validation)
-const secureOpenAI = wrapOpenAIClient(openai, {
-  validateInput: true,
-  filterOutput: true,
-  throwOnViolation: true
-});
+// Filter LLM output (PII + prompt leakage detection)
+const output = guard.filterOutput(llmResponse, session.role);
 ```
 
-## Guards Reference
-
-### Core Guards
-
-| Guard | Layer | Purpose |
-|-------|-------|---------|
-| InputSanitizer | L1 | Prompt injection & PAP detection |
-| ToolRegistry | L2 | Tool hallucination prevention |
-| PolicyGate | L3 | RBAC enforcement |
-| TenantBoundary | L4 | Multi-tenant isolation |
-| SchemaValidator | L5 | Parameter validation |
-| ExecutionMonitor | L6 | Rate limiting |
-| OutputFilter | L7 | PII/secret detection |
-| ConversationGuard | L8 | Multi-turn manipulation |
-| ToolChainValidator | L9 | Tool sequence validation |
-| EncodingDetector | L10 | Encoding bypass detection |
-
-### Advanced Guards
-
-| Guard | Layer | Purpose |
-|-------|-------|---------|
-| MultiModalGuard | L11 | Image/audio validation |
-| MemoryGuard | L12 | Memory poisoning prevention |
-| RAGGuard | L13 | Document validation |
-| CodeExecutionGuard | L14 | Safe code execution |
-| AgentCommunicationGuard | L15 | Multi-agent security |
-| CircuitBreaker | L16 | Failure prevention |
-| DriftDetector | L17 | Behavior monitoring |
-| MCPSecurityGuard | L18 | MCP tool security |
-| PromptLeakageGuard | L19 | System prompt protection |
-| TrustExploitationGuard | L20 | Trust boundary enforcement |
-| AutonomyEscalationGuard | L21 | Unauthorized autonomy prevention |
-| StatePersistenceGuard | L22 | State corruption prevention |
+## All 26 Guards
+
+### Input Guards (before LLM)
+
+| Guard | Purpose | Detection |
+|-------|---------|-----------|
+| InputSanitizer | Prompt injection, PAP, Policy Puppetry | 140+ regex patterns |
+| EncodingDetector | Encoding bypass (9 formats, multi-layer) | Decode + pattern match |
+| PromptLeakageGuard | System prompt extraction attempts | Direct + encoded + indirect |
+| ConversationGuard | Multi-turn manipulation, escalation | Session risk scoring |
+| ContextBudgetGuard | Many-shot jailbreaking, context overflow | Token budget tracking |
+| MultiModalGuard | Image/audio metadata injection | Metadata + steganography scan |
+
+### Access Control Guards
+
+| Guard | Purpose | Detection |
+|-------|---------|-----------|
+| ToolRegistry | Tool hallucination prevention | Allowlist |
+| PolicyGate | RBAC enforcement | Role hierarchy |
+| TenantBoundary | Multi-tenant isolation | Resource ownership |
+| SchemaValidator | Parameter injection (SQL, NoSQL, XSS, command) | Contextual pattern matching |
+| ExecutionMonitor | Rate limiting, resource quotas | Time-window counting |
+| TokenCostGuard | LLM API cost tracking, financial circuit breaking | Token + dollar budget |
+
+### Output Guards (after LLM)
+
+| Guard | Purpose | Detection |
+|-------|---------|-----------|
+| OutputFilter | PII/secret masking | Regex + role-based filtering |
+| OutputSchemaGuard | Structured output validation | Schema + injection scan |
+| ToolResultGuard | Tool return value validation | Injection + state claims |
+
+### Agentic Guards
+
+| Guard | Purpose | Detection |
+|-------|---------|-----------|
+| ToolChainValidator | Dangerous tool sequences | Sequence matching |
+| AgentCommunicationGuard | Inter-agent message security | HMAC + nonce |
+| TrustExploitationGuard | Human-agent trust boundary | Action validation |
+| AutonomyEscalationGuard | Unauthorized autonomy expansion | Capability tracking |
+| MemoryGuard | Memory poisoning prevention | Injection patterns + HMAC |
+| StatePersistenceGuard | State corruption prevention | Integrity hashing |
+| CodeExecutionGuard | Unsafe code execution | Static analysis |
+| RAGGuard | RAG document poisoning | Source trust + injection |
+| MCPSecurityGuard | MCP tool shadowing, rug pull, SSRF | Registration + mutation hash |
+| CircuitBreaker | Cascading failure prevention | State machine |
+| DriftDetector | Behavioral anomaly detection | Statistical profiling |
+
+### Pluggable Detection
+
+| Component | Purpose |
+|-----------|---------|
+| DetectionClassifier | Plug in any ML backend (sync or async) alongside regex guards |
+| createRegexClassifier() | Built-in regex classifier as a DetectionClassifier callback |
 
 ## OWASP Coverage
 
 ### LLM Top 10 2025
 
-| Threat | Guards |
-|--------|--------|
-| LLM01: Prompt Injection | InputSanitizer, EncodingDetector |
-| LLM02: Sensitive Data Exposure | OutputFilter, PromptLeakageGuard |
-| LLM03: Supply Chain | MCPSecurityGuard |
-| LLM04: Data Poisoning | RAGGuard, MemoryGuard |
-| LLM05: Privilege Escalation | PolicyGate, TenantBoundary |
-| LLM07: System Prompt Leakage | PromptLeakageGuard |
-| LLM08: Vector DB Attacks | RAGGuard |
+| Threat | Guards | Coverage |
+|--------|--------|----------|
+| LLM01: Prompt Injection | InputSanitizer, EncodingDetector, ContextBudgetGuard | Strong (known patterns), Weak (novel semantic) |
+| LLM02: Sensitive Data Exposure | OutputFilter, PromptLeakageGuard | Strong |
+| LLM03: Supply Chain | MCPSecurityGuard | Moderate (MCP-focused) |
+| LLM04: Data Poisoning | RAGGuard, MemoryGuard | Moderate |
+| LLM05: Improper Output Handling | OutputSchemaGuard, OutputFilter | Strong |
+| LLM06: Excessive Agency | AutonomyEscalationGuard, ToolChainValidator | Strong |
+| LLM07: System Prompt Leakage | PromptLeakageGuard | Strong |
+| LLM08: Vector/Embedding Weakness | RAGGuard | Moderate |
+| LLM09: Misinformation | DetectionClassifier (pluggable) | Requires ML backend |
+| LLM10: Unbounded Consumption | ExecutionMonitor, TokenCostGuard | Strong |
 
 ### Agentic AI 2026
 
-| Threat | Guards |
-|--------|--------|
-| ASI04: Tool Misuse | ToolChainValidator |
-| ASI05: Privilege Escalation | PolicyGate |
-| ASI06: Memory Poisoning | MemoryGuard |
-| ASI07: State Corruption | ToolChainValidator |
-| ASI08: State Persistence | StatePersistenceGuard |
-| ASI09: Trust Exploitation | TrustExploitationGuard |
-| ASI10: Autonomy Escalation | AutonomyEscalationGuard |
-
-## API Examples
-
-### InputSanitizer
+| Threat | Guards | Coverage |
+|--------|--------|----------|
+| ASI01: Agent Goal Hijack | InputSanitizer, ConversationGuard | Moderate |
+| ASI02: Tool Misuse | ToolChainValidator, ToolRegistry | Strong |
+| ASI03: Privilege Mismanagement | PolicyGate, TenantBoundary | Strong |
+| ASI04: Supply Chain | MCPSecurityGuard | Moderate |
+| ASI05: Code Execution | CodeExecutionGuard | Strong |
+| ASI06: Memory Poisoning | MemoryGuard, StatePersistenceGuard | Strong |
+| ASI07: Inter-Agent Communication | AgentCommunicationGuard | Strong |
+| ASI08: Cascading Failures | CircuitBreaker, DriftDetector | Strong |
+| ASI09: Trust Exploitation | TrustExploitationGuard | Strong |
+| ASI10: Rogue Agents | DriftDetector, AutonomyEscalationGuard | Moderate |
 
-```typescript
-import { InputSanitizer } from 'llm-trust-guard';
+## Defense In Depth
 
-const sanitizer = new InputSanitizer({
-  threshold: 0.3,
-  detectPAP: true,
-  papThreshold: 0.4,
-  blockCompoundPersuasion: true
-});
+This package is one layer. For production systems, combine with:
 
-const result = sanitizer.sanitize("Ignore all previous instructions");
-// result.allowed = false
-// result.violations = ['INJECTION_DETECTED']
-// result.matches = ['ignore_instructions']
-// result.pap = { detected: false, techniques: [], ... }
 ```
-
-### EncodingDetector
-
-```typescript
-import { EncodingDetector } from 'llm-trust-guard';
-
-const detector = new EncodingDetector({
-  detectBase64: true,
-  detectURLEncoding: true,
-  detectUnicode: true,
-  detectHex: true,
-  detectROT13: true
-});
-
-const result = detector.detect("aWdub3JlIGFsbA=="); // Base64 encoded
-// result.allowed = false
-// result.violations = ['BASE64_ENCODING_DETECTED']
-// result.encoding_analysis.threats_found = [...]
+Layer 1: llm-trust-guard (regex pattern matching — fast, zero deps)
+Layer 2: ML classifier via DetectionClassifier (semantic detection — slower, more accurate)
+Layer 3: Model provider safety (OpenAI moderation, Anthropic safety, etc.)
+Layer 4: Human review for high-risk actions
+Layer 5: Monitoring + alerting (DriftDetector + circuit breakers)
 ```
 
-### MemoryGuard
-
-```typescript
-import { MemoryGuard } from 'llm-trust-guard';
-
-const guard = new MemoryGuard({
-  enableIntegrityCheck: true,
-  detectInjections: true,
-  riskThreshold: 40
-});
-
-// Validate before storing
-const writeResult = guard.checkWrite(content, 'user', sessionId);
-
-// Validate context injection
-const ctxResult = guard.validateContextInjection(context, sessionId);
-```
-
-## Attack Prevention
-
-| Attack | Without Guard | With Guard |
-|--------|--------------|------------|
-| Prompt Injection | Exploitable | Blocked |
-| PAP Attacks | Exploitable | Blocked |
-| Encoding Bypass | Exploitable | Blocked |
-| Memory Poisoning | Exploitable | Blocked |
-| Cross-Tenant Access | Possible | Blocked |
-| Tool Hallucination | Executed | Blocked |
-| Trust Exploitation | Possible | Blocked |
-
-## Architecture Principle
+## Framework Integrations
 
-> **"The LLM proposes. The orchestrator disposes."**
+- **Express.js** — `createTrustGuardMiddleware()` for route protection
+- **LangChain** — `TrustGuardLangChain` for chain validation
+- **OpenAI** — `SecureOpenAI` or `wrapOpenAIClient()` for API wrapping
 
-LLMs cannot be trusted to enforce security. All security decisions happen in the orchestration layer.
+See [CHANGELOG.md](CHANGELOG.md) for version history.
 
 ## Contributing
 
-See `CONTRIBUTING.md` in the installed package for guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## Security
 
-See `SECURITY.md` in the installed package for security policy and reporting vulnerabilities.
-
-## Changelog
-
-See `CHANGELOG.md` in the installed package for version history.
+See [SECURITY.md](SECURITY.md) for vulnerability reporting.
 
 ## License
 
-MIT License - see `LICENSE` in the installed package for details.
+MIT
 
 ## Links
 
-- [OWASP Top 10 for LLMs](https://owasp.org/www-project-top-10-for-large-language-model-applications/)
+- [OWASP Top 10 for LLMs 2025](https://genai.owasp.org/resource/owasp-top-10-for-llm-applications-2025/)
 - [OWASP Top 10 for Agentic Applications 2026](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/)
+- [MITRE ATLAS](https://atlas.mitre.org/)
+- [NIST AI Risk Management Framework](https://www.nist.gov/itl/ai-risk-management-framework)

package/dist/guards/conversation-guard.d.ts

@@ -7,6 +7,7 @@
  * - Identifying context manipulation across turns
  * - Blocking suspicious conversation trajectories
  */
+import { GuardLogger } from "../types";
 export interface ConversationGuardConfig {
     maxConversationLength?: number;
     conversationTTLMinutes?: number;
@@ -15,6 +16,7 @@ export interface ConversationGuardConfig {
     detectToneShifts?: boolean;
     detectRoleConfusion?: boolean;
     detectInstructionOverride?: boolean;
+    logger?: GuardLogger;
 }
 export interface ManipulationPattern {
     name: string;
@@ -42,6 +44,7 @@ export interface RiskFactor {
 }
 export declare class ConversationGuard {
     private config;
+    private logger;
     private sessions;
     private defaultManipulationPatterns;
     constructor(config?: ConversationGuardConfig);

package/dist/guards/conversation-guard.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.ConversationGuard=void 0;class ConversationGuard{constructor(t={}){this.sessions=new Map,this.defaultManipulationPatterns=[{name:"role_claim",pattern:/(?:i am|i'm|as|acting as)\s+(?:an?\s+)?(?:admin|administrator|root|superuser|manager|supervisor)/i,weight:3,category:"escalation"},{name:"permission_request",pattern:/(?:give me|grant me|i need|enable|unlock)\s+(?:access|permission|privileges|admin|root)/i,weight:4,category:"escalation"},{name:"bypass_attempt",pattern:/(?:bypass|skip|ignore|override|disable)\s+(?:security|check|validation|permission|auth)/i,weight:5,category:"escalation"},{name:"context_switch",pattern:/(?:forget|ignore|disregard)\s+(?:previous|earlier|what i said|instructions)/i,weight:4,category:"confusion"},{name:"role_confusion",pattern:/(?:you are now|pretend to be|act as if|imagine you're)\s+/i,weight:4,category:"confusion"},{name:"scenario_framing",pattern:/(?:in this scenario|hypothetically|let's say|imagine that|pretend that)/i,weight:2,category:"confusion"},{name:"instruction_override",pattern:/(?:new instructions?|override|update your|change your)\s+(?:are|is|:)/i,weight:5,category:"override"},{name:"system_impersonation",pattern:/(?:\[system\]|\[admin\]|system:|\bSYSTEM\b|ADMIN:)/i,weight:5,category:"override"},{name:"priority_claim",pattern:/(?:priority|urgent|important|critical)[:.]?\s*(?:override|ignore|bypass)/i,weight:4,category:"override"},{name:"data_extraction",pattern:/(?:list all|show me all|dump|export|extract)\s+(?:users|data|records|passwords|credentials)/i,weight:4,category:"extraction"},{name:"internal_query",pattern:/(?:what are your|tell me your|reveal your)\s+(?:instructions|rules|prompts|system)/i,weight:3,category:"extraction"}],this.lastCleanup=0,this.config={maxConversationLength:t.maxConversationLength??50,conversationTTLMinutes:t.conversationTTLMinutes??30,escalationThreshold:t.escalationThreshold??10,manipulationPatterns:t.manipulationPatterns??this.defaultManipulationPatterns,detectToneShifts:t.detectToneShifts??!0,detectRoleConfusion:t.detectRoleConfusion??!0,detectInstructionOverride:t.detectInstructionOverride??!0}}check(t,i,o,n,m=""){const r=[],c=[],u=[];let a=0;const e=this.getOrCreateSession(t),p={timestamp:Date.now(),role:"user",content:i,tool_calls:o,risk_indicators:[]};for(const s of this.config.manipulationPatterns)s.pattern.test(i)&&(a+=s.weight,c.push({factor:s.name,weight:s.weight,details:`Detected ${s.category} pattern: ${s.name}`}),p.risk_indicators?.push(s.name),u.push(s.name),r.push(`MANIPULATION_${s.category.toUpperCase()}_${s.name.toUpperCase()}`),s.category==="escalation"&&e.escalation_attempts++,e.manipulation_indicators++);if(n&&this.config.detectRoleConfusion&&(e.initial_role&&n!==e.initial_role&&(a+=3,c.push({factor:"role_change",weight:3,details:`Role changed from ${e.initial_role} to ${n}`}),r.push("ROLE_CHANGE_DETECTED")),e.claimed_roles.includes(n)||e.claimed_roles.push(n),e.initial_role||(e.initial_role=n)),e.escalation_attempts>=3&&(a+=5,c.push({factor:"progressive_escalation",weight:5,details:`${e.escalation_attempts} escalation attempts detected`}),r.push("PROGRESSIVE_ESCALATION")),e.turns.length>5){const s=e.turns.slice(-5).filter(h=>(h.risk_indicators?.length??0)>0).length;s>=3&&(a+=4,c.push({factor:"sustained_manipulation",weight:4,details:`${s} of last 5 turns show manipulation attempts`}),r.push("SUSTAINED_MANIPULATION"))}if(o&&o.length>0){const s=["delete","modify","admin","system","config"];o.some(d=>s.some(g=>d.toLowerCase().includes(g)))&&e.manipulation_indicators>0&&(a+=3,c.push({factor:"sensitive_tool_after_manipulation",weight:3,details:"Sensitive tool call following manipulation attempts"}),r.push("SENSITIVE_TOOL_AFTER_MANIPULATION"))}e.turns.push(p),e.last_activity=Date.now(),e.turns.length>this.config.maxConversationLength&&(e.turns=e.turns.slice(-this.config.maxConversationLength));const l=a<this.config.escalationThreshold;return l||console.log(`[ConversationGuard:${m}] BLOCKED: Risk score ${a} exceeds threshold`),{allowed:l,reason:l?void 0:`Conversation risk score ${a} exceeds threshold ${this.config.escalationThreshold}`,violations:r,risk_score:a,risk_factors:c,conversation_analysis:{turn_count:e.turns.length,escalation_attempts:e.escalation_attempts,manipulation_indicators:e.manipulation_indicators,suspicious_patterns:u}}}recordResponse(t,i,o){const n=this.sessions.get(t);n&&(n.turns.push({timestamp:Date.now(),role:"assistant",content:i,tool_calls:o}),n.last_activity=Date.now())}getSessionAnalysis(t){const i=this.sessions.get(t);return i?{turn_count:i.turns.length,escalation_attempts:i.escalation_attempts,manipulation_indicators:i.manipulation_indicators,claimed_roles:i.claimed_roles,session_age_minutes:(Date.now()-i.turns[0]?.timestamp||0)/6e4}:null}resetSession(t){this.sessions.delete(t)}destroy(){this.sessions.clear()}getOrCreateSession(t){return this.lazyCleanup(),this.sessions.has(t)||this.sessions.set(t,{id:t,turns:[],escalation_attempts:0,manipulation_indicators:0,last_activity:Date.now(),claimed_roles:[]}),this.sessions.get(t)}lazyCleanup(){const t=Date.now();if(t-this.lastCleanup<6e4)return;this.lastCleanup=t;const i=this.config.conversationTTLMinutes*6e4;for(const[o,n]of this.sessions.entries())t-n.last_activity>i&&this.sessions.delete(o)}}exports.ConversationGuard=ConversationGuard;
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.ConversationGuard=void 0;class ConversationGuard{constructor(t={}){this.sessions=new Map,this.defaultManipulationPatterns=[{name:"role_claim",pattern:/(?:i am|i'm|as|acting as)\s+(?:an?\s+)?(?:admin|administrator|root|superuser|manager|supervisor)/i,weight:3,category:"escalation"},{name:"permission_request",pattern:/(?:give me|grant me|i need|enable|unlock)\s+(?:access|permission|privileges|admin|root)/i,weight:4,category:"escalation"},{name:"bypass_attempt",pattern:/(?:bypass|skip|ignore|override|disable)\s+(?:security|check|validation|permission|auth)/i,weight:5,category:"escalation"},{name:"context_switch",pattern:/(?:forget|ignore|disregard)\s+(?:previous|earlier|what i said|instructions)/i,weight:4,category:"confusion"},{name:"role_confusion",pattern:/(?:you are now|pretend to be|act as if|imagine you're)\s+/i,weight:4,category:"confusion"},{name:"scenario_framing",pattern:/(?:in this scenario|hypothetically|let's say|imagine that|pretend that)/i,weight:2,category:"confusion"},{name:"instruction_override",pattern:/(?:new instructions?|override|update your|change your)\s+(?:are|is|:)/i,weight:5,category:"override"},{name:"system_impersonation",pattern:/(?:\[system\]|\[admin\]|system:|\bSYSTEM\b|ADMIN:)/i,weight:5,category:"override"},{name:"priority_claim",pattern:/(?:priority|urgent|important|critical)[:.]?\s*(?:override|ignore|bypass)/i,weight:4,category:"override"},{name:"data_extraction",pattern:/(?:list all|show me all|dump|export|extract)\s+(?:users|data|records|passwords|credentials)/i,weight:4,category:"extraction"},{name:"internal_query",pattern:/(?:what are your|tell me your|reveal your)\s+(?:instructions|rules|prompts|system)/i,weight:3,category:"extraction"}],this.lastCleanup=0,this.config={maxConversationLength:t.maxConversationLength??50,conversationTTLMinutes:t.conversationTTLMinutes??30,escalationThreshold:t.escalationThreshold??10,manipulationPatterns:t.manipulationPatterns??this.defaultManipulationPatterns,detectToneShifts:t.detectToneShifts??!0,detectRoleConfusion:t.detectRoleConfusion??!0,detectInstructionOverride:t.detectInstructionOverride??!0},this.logger=t.logger||(()=>{})}check(t,i,o,n,m=""){const r=[],c=[],u=[];let a=0;const e=this.getOrCreateSession(t),h={timestamp:Date.now(),role:"user",content:i,tool_calls:o,risk_indicators:[]};for(const s of this.config.manipulationPatterns)s.pattern.test(i)&&(a+=s.weight,c.push({factor:s.name,weight:s.weight,details:`Detected ${s.category} pattern: ${s.name}`}),h.risk_indicators?.push(s.name),u.push(s.name),r.push(`MANIPULATION_${s.category.toUpperCase()}_${s.name.toUpperCase()}`),s.category==="escalation"&&e.escalation_attempts++,e.manipulation_indicators++);if(n&&this.config.detectRoleConfusion&&(e.initial_role&&n!==e.initial_role&&(a+=3,c.push({factor:"role_change",weight:3,details:`Role changed from ${e.initial_role} to ${n}`}),r.push("ROLE_CHANGE_DETECTED")),e.claimed_roles.includes(n)||e.claimed_roles.push(n),e.initial_role||(e.initial_role=n)),e.escalation_attempts>=3&&(a+=5,c.push({factor:"progressive_escalation",weight:5,details:`${e.escalation_attempts} escalation attempts detected`}),r.push("PROGRESSIVE_ESCALATION")),e.turns.length>5){const s=e.turns.slice(-5).filter(p=>(p.risk_indicators?.length??0)>0).length;s>=3&&(a+=4,c.push({factor:"sustained_manipulation",weight:4,details:`${s} of last 5 turns show manipulation attempts`}),r.push("SUSTAINED_MANIPULATION"))}if(o&&o.length>0){const s=["delete","modify","admin","system","config"];o.some(d=>s.some(g=>d.toLowerCase().includes(g)))&&e.manipulation_indicators>0&&(a+=3,c.push({factor:"sensitive_tool_after_manipulation",weight:3,details:"Sensitive tool call following manipulation attempts"}),r.push("SENSITIVE_TOOL_AFTER_MANIPULATION"))}e.turns.push(h),e.last_activity=Date.now(),e.turns.length>this.config.maxConversationLength&&(e.turns=e.turns.slice(-this.config.maxConversationLength));const l=a<this.config.escalationThreshold;return l||this.logger(`[ConversationGuard:${m}] BLOCKED: Risk score ${a} exceeds threshold`,"info"),{allowed:l,reason:l?void 0:`Conversation risk score ${a} exceeds threshold ${this.config.escalationThreshold}`,violations:r,risk_score:a,risk_factors:c,conversation_analysis:{turn_count:e.turns.length,escalation_attempts:e.escalation_attempts,manipulation_indicators:e.manipulation_indicators,suspicious_patterns:u}}}recordResponse(t,i,o){const n=this.sessions.get(t);n&&(n.turns.push({timestamp:Date.now(),role:"assistant",content:i,tool_calls:o}),n.last_activity=Date.now())}getSessionAnalysis(t){const i=this.sessions.get(t);return i?{turn_count:i.turns.length,escalation_attempts:i.escalation_attempts,manipulation_indicators:i.manipulation_indicators,claimed_roles:i.claimed_roles,session_age_minutes:(Date.now()-i.turns[0]?.timestamp||0)/6e4}:null}resetSession(t){this.sessions.delete(t)}destroy(){this.sessions.clear()}getOrCreateSession(t){return this.lazyCleanup(),this.sessions.has(t)||this.sessions.set(t,{id:t,turns:[],escalation_attempts:0,manipulation_indicators:0,last_activity:Date.now(),claimed_roles:[]}),this.sessions.get(t)}lazyCleanup(){const t=Date.now();if(t-this.lastCleanup<6e4)return;this.lastCleanup=t;const i=this.config.conversationTTLMinutes*6e4;for(const[o,n]of this.sessions.entries())t-n.last_activity>i&&this.sessions.delete(o)}}exports.ConversationGuard=ConversationGuard;

package/dist/guards/encoding-detector.d.ts

@@ -9,6 +9,7 @@
  * - HTML entity encoding
  * - Mixed encoding attacks
  */
+import { GuardLogger } from "../types";
 export interface EncodingDetectorConfig {
     detectBase64?: boolean;
     detectURLEncoding?: boolean;
@@ -22,6 +23,7 @@ export interface EncodingDetectorConfig {
     maxDecodingDepth?: number;
     threatPatterns?: ThreatPattern[];
     maxEncodedRatio?: number;
+    logger?: GuardLogger;
 }
 export interface ThreatPattern {
     name: string;
@@ -52,6 +54,7 @@ export interface ThreatFound {
 }
 export declare class EncodingDetector {
     private config;
+    private logger;
     private defaultThreatPatterns;
     constructor(config?: EncodingDetectorConfig);
     /**