How to Configure Guardrails in OmniRoute for PII Redaction and Prompt Injection Detection

OmniRoute provides built-in PII redaction and prompt injection detection guardrails that activate automatically via environment variables and can be bypassed per-request using headers or JSON fields.

The OmniRoute repository (diegosouzapw/OmniRoute) ships with a modular guardrail framework that executes on every request and response. Two critical built-in guardrails handle sensitive data protection and security: the PII Masker for redacting personal identifiable information, and the Prompt Injection Guardrail for blocking malicious prompt manipulation attempts.

Understanding OmniRoute's Guardrail Architecture

OmniRoute implements a registry-based guardrail system defined in src/lib/guardrails/registry.ts. When the server initializes via src/server-init.ts, the registerDefaultGuardrails() function automatically instantiates and registers the security guardrails:

// src/lib/guardrails/registry.ts
export function registerDefaultGuardrails() {
  if (defaultGuardrailsRegistered) return guardrailRegistry;

  guardrailRegistry.register(new VisionBridgeGuardrail());
  guardrailRegistry.register(new PIIMaskerGuardrail());          // PII protection
  guardrailRegistry.register(new PromptInjectionGuardrail());    // Security filter
  defaultGuardrailsRegistered = true;
  return guardrailRegistry;
}

This registration occurs at server startup (line 16 of src/server-init.ts), ensuring all guardrails are active before traffic hits the API.

Configuring PII Redaction Guardrails

The PII Masker guardrail (src/lib/guardrails/piiMasker.ts) operates in two phases: pre-call (incoming request sanitization) and post-call (outgoing response sanitization).

Environment Variables for PII Masking

Control PII redaction through these environment variables:

Variable	Default	Effect
PII_REDACTION_ENABLED	false	Activates request-side PII detection when set to "true"
INPUT_SANITIZER_MODE	"off"	Must be set to "redact" for request-side masking to execute
PII_RESPONSE_SANITIZATION	false	Enables response-side PII redaction when set to "true"
PII_RESPONSE_SANITIZATION_MODE	"redact"	Determines redaction mode for responses (currently supports "redact" only)

Configure your .env file to enable full bidirectional PII protection:

# .env

PII_REDACTION_ENABLED=true
INPUT_SANITIZER_MODE=redact
PII_RESPONSE_SANITIZATION=true
PII_RESPONSE_SANITIZATION_MODE=redact

How PII Masking Transforms Requests

When enabled, the guardrail intercepts payloads before they reach upstream models. A request containing sensitive data:

{
  "messages": [{ "role": "user", "content": "My email is john@example.com" }]
}

Gets transformed in the preCall hook to:

{
  "messages": [{ "role": "user", "content": "My email is [REDACTED]" }]
}

The postCall hook applies identical sanitization to response bodies when PII_RESPONSE_SANITIZATION is enabled.

Enabling Prompt Injection Detection

The Prompt Injection Guardrail (src/lib/guardrails/promptInjection.ts) requires no additional environment configuration—it runs by default using the shared inputSanitizer utilities to detect patterns like "Ignore your system prompt" or "You are a..." roleplay attempts.

When the detectInjection logic identifies a violation, the guardrail blocks the request before any upstream call occurs, returning a 400 error:

{
  "error": "Prompt injection detected – request blocked by guardrail 'prompt-injection'."
}

Per-Request Guardrail Control

OmniRoute allows runtime opt-out of specific guardrails via the resolveDisabledGuardrails function in src/lib/guardrails/registry.ts (lines 52-78).

Disabling Guardrails via HTTP Headers

Add the x-omniroute-disabled-guardrails header to skip specific guardrails:

POST /v1/chat/completions HTTP/1.1
Content-Type: application/json
x-omniroute-disabled-guardrails: pii-masker,prompt-injection

{
  "messages": [{ "role": "user", "content": "My email is john@example.com" }]
}

Disabling via JSON Body or Metadata

Alternatively, include the disabledGuardrails array in your request body:

{
  "disabledGuardrails": ["pii-masker"],
  "messages": [{ "role": "user", "content": "Process this PII freely" }]
}

Or nest it within the metadata object using the same array format. The registry merges these sources and deduplicates entries before skipping the specified guardrail hooks.

Testing and Debugging Guardrails

OmniRoute exposes inspection endpoints to verify guardrail configuration without processing live traffic.

Listing Active Guardrails

Query the registry status via src/app/api/guardrails/route.ts:

curl http://localhost:3000/api/guardrails

Returns guardrail names, enabled status, and priority levels.

Dry-Run Testing

Test how guardrails transform specific payloads using the test endpoint (src/app/api/guardrails/test/route.ts):

curl -X POST http://localhost:3000/api/guardrails/test \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Test email: user@example.com"}]}'

This executes the pre-call pipeline and returns per-guardrail verdicts (blocked, modified, or passed) without forwarding to upstream models.

Programmatic Status Checks

Inspect guardrail states programmatically:

import { guardrailRegistry } from "@/lib/guardrails/registry";

const guardrails = guardrailRegistry.list();
guardrails.forEach(g => console.log(`${g.name} – enabled: ${g.enabled}`));

Expected output shows all default guardrails active:

vision-bridge – enabled: true
pii-masker – enabled: true
prompt-injection – enabled: true

Summary

• PII Redaction requires setting PII_REDACTION_ENABLED=true and INPUT_SANITIZER_MODE=redact for requests, plus PII_RESPONSE_SANITIZATION=true for responses.
• Prompt Injection Detection runs automatically via src/lib/guardrails/promptInjection.ts with no environment variables needed.
• Disable guardrails per-request using the x-omniroute-disabled-guardrails header or disabledGuardrails JSON field.
• Test configurations using the /api/guardrails and /api/guardrails/test endpoints before deploying to production.

Frequently Asked Questions

How do I completely disable PII redaction in OmniRoute?

Set PII_REDACTION_ENABLED=false and PII_RESPONSE_SANITIZATION=false in your environment file, then restart the server. Alternatively, keep the global settings enabled but pass x-omniroute-disabled-guardrails: pii-masker on specific requests that require unfiltered data processing.

Can I customize the prompt injection detection patterns?

The current implementation in src/lib/guardrails/promptInjection.ts uses the shared detectInjection logic from the input sanitizer utilities. To modify detection patterns, you would need to fork and edit the detectInjection function or implement a custom guardrail that extends the base guardrail interface and registers it alongside the defaults.

What happens if multiple guardrails conflict on a single request?

OmniRoute processes guardrails sequentially according to their registration priority in src/lib/guardrails/registry.ts. Each guardrail can modify the payload or block the request entirely. If the Prompt Injection Guardrail blocks a request, execution stops immediately and no upstream call occurs, regardless of PII masking status.

Is there a performance penalty for enabling these guardrails?

The PII Masker runs regex-based detection on request and response bodies, adding minimal latency proportional to payload size. The Prompt Injection Guardrail performs pattern matching in the preCall phase only. Both operate synchronously before network calls, so they add compute overhead but do not affect upstream API latency.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}