How to Configure Guardrails for PII Redaction and Credential Masking in OmniRoute

Enable PII redaction and credential masking in OmniRoute by setting feature flags via environment variables or persistent database overrides, with request-side masking controlled by PII_REDACTION_ENABLED and response-side sanitization controlled by PII_RESPONSE_SANITIZATION.

OmniRoute provides built-in guardrails that let you control personal-identifiable-information (PII) redaction and credential masking at runtime. These security features are driven by feature flags defined in src/shared/constants/featureFlagDefinitions.ts and can be configured per-tenant without code changes. This guide walks through configuring guardrails for PII redaction and credential masking using the exact implementation details from the OmniRoute source code.

Understanding the Guardrail Architecture

OmniRoute implements guardrails across two primary domains:

Guardrail	Purpose	Implementation File
Request-side PII masking	Redacts PII in incoming requests before they reach the LLM	src/lib/guardrails/piiMasker.ts
Response-side PII sanitization	Redacts PII in LLM responses, including SSE streams	src/lib/piiSanitizer.ts
Feature-flag resolution	Reads database overrides or falls back to environment variables	src/lib/db/featureFlags.ts

Both guardrails default to opt-in behavior—they are disabled unless explicitly enabled. This design prevents unexpected data transformation in production environments.

Enabling Request-Side PII Redaction

Step 1: Set Environment Variables for Quick Testing

For immediate validation, export the feature flag before starting OmniRoute:

export PII_REDACTION_ENABLED=true

The PIIMaskerGuardrail class in src/lib/guardrails/piiMasker.ts reads this value through the feature-flag resolution layer. The class exposes an isEnabled() method for runtime verification:

import { PIIMaskerGuardrail } from '@/lib/guardrails/piiMasker';

const guardrail = new PIIMaskerGuardrail();
console.log('Request-side PII guard enabled:', guardrail.isEnabled());

Step 2: Persist Configuration in the Database

For production deployments, use the OmniRoute CLI to write overrides to the feature_flags table:

omniroute feature-flag set PII_REDACTION_ENABLED true

The resolution logic in src/lib/db/featureFlags.ts prefers database values over environment variables. This ensures configuration survives restarts and can be updated without redeployment.

Configuring Response-Side PII Sanitization

Response-side guardrails require two settings: enablement and mode selection.

Enable Response Sanitization

export PII_RESPONSE_SANITIZATION=true

Or persist via CLI:

omniroute feature-flag set PII_RESPONSE_SANITIZATION true

Choose the Sanitization Mode

Set PII_RESPONSE_SANITIZATION_MODE to control behavior when PII is detected:

Mode	Behavior	Use Case
redact	Removes detected PII from the response	Production traffic where partial responses are acceptable
block	Aborts the request with an error	High-security environments requiring zero PII exposure

export PII_RESPONSE_SANITIZATION_MODE=redact  # or "block"

The default is redact when the variable is unset or invalid. The implementation in src/lib/piiSanitizer.ts handles both standard responses and SSE streams.

Implementing Credential Masking and Log Redaction

Automatic Log Redaction with the no_log Flag

The PIIMaskerGuardrail class sanitizes log payloads when requests include no_log: true. To enforce this globally, set:

export DEFAULT_NO_LOG=true

When enabled, the request handler automatically injects no_log: true, triggering PII redaction before any persistence to logs. This behavior is validated in tests/unit/t07-no-log-key-config.test.ts.

HTTP Header Sanitization

OmniRoute protects credentials in HTTP headers through an allowlist defined in src/shared/constants/upstreamHeaders.ts. Only headers explicitly listed are forwarded to upstream services; all others are dropped or redacted.

To extend the allowlist:

1. Edit src/shared/constants/upstreamHeaders.ts
2. Add your custom header to the Zod schema
3. Run npm run typecheck:core to validate type safety

Complete Configuration Example

A production-ready .env configuration:

# PII Redaction Configuration

PII_REDACTION_ENABLED=true
PII_RESPONSE_SANITIZATION=true
PII_RESPONSE_SANITIZATION_MODE=redact

# Credential Masking

DEFAULT_NO_LOG=true

Validating Your Configuration

OmniRoute includes comprehensive unit tests to verify guardrail behavior. Run the relevant test suites to confirm your configuration works correctly:

# Request-side PII masking tests

npm run test:unit tests/unit/piiSanitizer.test.ts

# Response-side PII sanitization tests (IPv6-aware)

npm run test:unit tests/unit/piiSanitizerIpv6.test.ts

# Feature-flag opt-in default tests

npm run test:unit tests/unit/pii-opt-in-default.test.ts

These tests assert that guardrails respect both environment variables and database overrides as implemented in src/lib/db/featureFlags.ts.

Summary

• Enable request-side PII redaction with PII_REDACTION_ENABLED to mask PII before it reaches the LLM
• Enable response-side PII sanitization with PII_RESPONSE_SANITIZATION, choosing redact or block mode via PII_RESPONSE_SANITIZATION_MODE
• Use database overrides through omniroute feature-flag set for persistent, restart-safe configuration
• Leverage no_log: true (or DEFAULT_NO_LOG=true) for automatic credential masking in logs
• Maintain header security by editing src/shared/constants/upstreamHeaders.ts when adding custom upstream headers

Frequently Asked Questions

What is the default behavior for PII redaction in OmniRoute?

Both PII_REDACTION_ENABLED and PII_RESPONSE_SANITIZATION default to "false". This opt-in design prevents accidental data transformation. You must explicitly enable these features via environment variables or database overrides in src/lib/db/featureFlags.ts.

How does OmniRoute handle PII in streaming (SSE) responses?

The PIISanitizer in src/lib/piiSanitizer.ts processes SSE streams chunk-by-chunk, applying the same redaction logic used for standard HTTP responses. This ensures consistent PII protection regardless of response format.

Can I use both environment variables and database overrides simultaneously?

Yes, but database overrides take precedence. The resolution logic in src/lib/db/featureFlags.ts checks the feature_flags table first, then falls back to environment variables, then to hardcoded defaults. This hierarchy allows emergency overrides without code changes.

What's the difference between "redact" and "block" modes?

redact removes detected PII and returns the sanitized content—use this when partial responses are acceptable. block aborts the entire request with an error when PII is detected—use this for environments requiring zero tolerance for PII exposure.

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