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

> Secure your data in OmniRoute. Learn to configure PII redaction and credential masking using environment variables or database overrides for robust data protection.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-11

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/piiMasker.ts) |
| **Response-side PII sanitization** | Redacts PII in LLM responses, including SSE streams | [`src/lib/piiSanitizer.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/piiSanitizer.ts) |
| **Feature-flag resolution** | Reads database overrides or falls back to environment variables | [`src/lib/db/featureFlags.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
export PII_REDACTION_ENABLED=true

```

The `PIIMaskerGuardrail` class in [`src/lib/guardrails/piiMasker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/piiMasker.ts) reads this value through the feature-flag resolution layer. The class exposes an `isEnabled()` method for runtime verification:

```typescript
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:

```bash
omniroute feature-flag set PII_REDACTION_ENABLED true

```

The resolution logic in [`src/lib/db/featureFlags.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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

```bash
export PII_RESPONSE_SANITIZATION=true

```

Or persist via CLI:

```bash
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 |

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```dotenv

# 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:

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/featureFlags.ts).

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

The `PIISanitizer` in [`src/lib/piiSanitizer.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.