# Security Guardrails in OmniRoute: Architecture, Configuration, and Implementation

> Discover OmniRoute's security guardrails: learn how its modular system enforces rules at preCall, pre, and post stages with a fail open philosophy. Secure your routes now.

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

---

**OmniRoute enforces safety, policy, and content-transformation rules through a modular guardrail system that intercepts requests at `preCall`, `pre`, and `post` stages, following a fail-open philosophy where guardrails log errors and continue processing unless explicitly configured to block.**

OmniRoute acts as a secure routing layer between applications and upstream LLM providers, implementing **security guardrails in OmniRoute** to enforce data privacy, content safety, and modality compliance. These guardrails live under `src/lib/guardrails/` and are automatically loaded by a central registry that orchestrates execution based on configurable priority levels and processing stages.

## How the Guardrail Registry Orchestrates Security

The guardrail system centers on [`src/lib/guardrails/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/registry.ts), which auto-loads default implementations and manages execution order. The registry processes guardrails sequentially by **priority** (lower numbers execute first) across three pipeline stages: **`preCall`**, **`pre`**, and **`post`**.

The architecture follows a **fail-open** philosophy: if a guardrail throws an error, the registry logs the failure and proceeds to the next guardrail rather than aborting the request. A request is blocked only when a guardrail explicitly returns `block: true` in its result object.

## Built-in Security Guardrails and Execution Order

OmniRoute ships with six production-ready guardrails that handle multimodal content, data privacy, and prompt security. The following table lists their priority values and execution stages:

| Priority | Guardrail | Stage(s) | Source File |
|----------|-----------|----------|-------------|
| 5 | Vision Bridge | `preCall` | [`src/lib/guardrails/visionBridge.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/visionBridge.ts) |
| 6 | Audio Bridge | `preCall` | [`src/lib/guardrails/audioBridge.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/audioBridge.ts) |
| 7 | Video Bridge | `preCall` | [`src/lib/guardrails/videoBridge.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/videoBridge.ts) |
| 10 | PII Masker | `pre` + `post` | [`src/lib/guardrails/piiMasker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/piiMasker.ts) |
| 20 | Prompt Injection | `preCall` | [`src/lib/guardrails/promptInjection.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/promptInjection.ts) |
| 95 | Credential Masker | `pre` + `post` | [`src/lib/guardrails/credentialMasker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/credentialMasker.ts) |

### Modality Bridges (Vision, Audio, Video)

The **Vision Bridge**, **Audio Bridge**, and **Video Bridge** guardrails (priorities 5, 6, and 7 respectively) intercept multimodal payloads during the `preCall` stage to ensure compatibility with downstream models.

- **Vision Bridge** ([`src/lib/guardrails/visionBridge.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/visionBridge.ts)): Detects image payloads destined for non-vision models. Using helper functions in [`src/lib/guardrails/visionBridgeHelpers.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/visionBridgeHelpers.ts), it extracts image parts and retrieves configuration from [`src/shared/constants/modalityBridgeDefaults.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/modalityBridgeDefaults.ts). The guardrail either reroutes the request to a vision-capable model or converts images to text descriptions using the format `[Image N]: <description>`.

- **Audio Bridge** ([`src/lib/guardrails/audioBridge.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/audioBridge.ts)): Handles audio payload transformation and rerouting using logic parallel to the Vision Bridge implementation.

- **Video Bridge** ([`src/lib/guardrails/videoBridge.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/videoBridge.ts)): Provides transcript provenance for video content, enabling downstream text models to safely process video inputs without requiring native video capabilities.

### PII Masker

Running at priority 10 across both **`pre`** and **`post`** stages, the **PII Masker** ([`src/lib/guardrails/piiMasker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/piiMasker.ts)) strips personally identifiable information from request bodies before they reach the provider and from response bodies before they return to the client, ensuring end-to-end privacy protection.

### Prompt Injection Detection

At priority 20 during the `preCall` stage, the **Prompt Injection** guardrail ([`src/lib/guardrails/promptInjection.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/promptInjection.ts)) analyzes prompts for attack patterns such as "ignore previous instructions." When violations are detected, it can immediately block the request by returning `block: true` in the result object.

### Credential Masker

Operating at priority 95 across **`pre`** and **`post`** stages, the **Credential Masker** ([`src/lib/guardrails/credentialMasker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/credentialMasker.ts)) specifically targets credential leaks, ensuring API keys, passwords, and secrets never exit the system or enter LLM responses.

## Configuring Guardrails with Zod Validation and Feature Flags

All guardrail settings are enforced through **Zod-validated** schemas defined in [`src/shared/validation/settingsSchemas.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/settingsSchemas.ts). Administrators toggle specific guardrails via feature flags such as `modalityBridgeVisionEnabled`, `piiMaskerEnabled`, and `modalityBridgeVisionMode`.

### Implementing Custom Security Guardrails

Developers can extend the security perimeter by registering custom guardrails at runtime. The `registerGuardrail` function from [`src/lib/guardrails/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/registry.ts) accepts a priority parameter to position the custom logic within the execution chain.

```typescript
// Example: Registering a custom guardrail at runtime
import { registerGuardrail } from "@/src/lib/guardrails/registry.ts";

class MyCustomGuardrail extends BaseGuardrail {
  async preCall(payload: any, ctx: GuardrailContext) {
    // reject any request containing the word "forbidden"
    if (payload?.messages?.some(m => m.content?.includes("forbidden"))) {
      return { block: true, error: "Forbidden content detected" };
    }
    return { payload };
  }
}

// Insert with priority 15 (runs after Vision Bridge but before PII Masker)
registerGuardrail(new MyCustomGuardrail(), { priority: 15 });

```

## Monitoring Guardrail Performance and Statistics

OmniRoute exposes runtime statistics for guardrail activity. Vision Bridge metrics are accessible via the `GET /api/modality-bridge/stats` endpoint and appended to HTTP responses with the header `x-omniroute-modality-bridge`.

```typescript
// Example: Reading guardrail statistics from the API
import fetch from "node-fetch";

async function getBridgeStats() {
  const resp = await fetch("http://localhost:20128/api/modality-bridge/stats", {
    headers: { Authorization: `Bearer ${process.env.API_KEY}` },
  });
  const stats = await resp.json();
  console.log("Vision bridge stats:", stats.vision);
}

```

## Manually Invoking Guardrails for Testing

For unit tests or custom pipelines, instantiate guardrails directly with optional configuration overrides. The `preCall`, `pre`, and `post` methods return a result object containing `modifiedPayload`, `block` status, and processing metadata.

```typescript
// Example: Manually invoking a guardrail (used in tests or custom pipelines)
import { VisionBridgeGuardrail } from "@/src/lib/guardrails/visionBridge.ts";

async function runVisionGuardrail(payload: any, ctx: GuardrailContext) {
  const guardrail = new VisionBridgeGuardrail({
    // optional overrides – otherwise defaults are read from the settings DB
    visionMode: "auto",
    maxImages: 5,
  });
  const result = await guardrail.preCall(payload, ctx);
  // `result.modifiedPayload` contains the possibly-rewritten request
  // `result.meta` holds stats such as imagesProcessed, processingTimeMs, etc.
  return result;
}

```

## Summary

- **Security guardrails in OmniRoute** reside in `src/lib/guardrails/` and are auto-loaded by [`src/lib/guardrails/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/registry.ts) according to priority levels ranging from 5 (Vision Bridge) to 95 (Credential Masker).
- The system employs a **fail-open** philosophy, continuing processing when individual guardrails error and only blocking when `block: true` is explicitly returned.
- **Six built-in guardrails** handle multimodal bridging (Vision, Audio, Video), PII masking, credential masking, and prompt injection detection across `preCall`, `pre`, and `post` stages.
- Configuration is managed via **Zod-validated** schemas ([`src/shared/validation/settingsSchemas.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/settingsSchemas.ts)) and feature flags like `modalityBridgeVisionEnabled`.
- Runtime statistics for monitoring are available through the `/api/modality-bridge/stats` endpoint and the `x-omniroute-modality-bridge` response header.
- Developers can register **custom guardrails** using `registerGuardrail()` with specific priority values to insert logic into the processing pipeline.

## Frequently Asked Questions

### What happens if a security guardrail throws an error in OmniRoute?

According to the fail-open philosophy implemented in [`src/lib/guardrails/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/registry.ts), the registry catches the error, logs the failure, and continues executing the remaining guardrails in the priority chain. The request is only aborted if a guardrail explicitly returns `block: true` in its result object.

### How do I disable specific security guardrails in OmniRoute?

Toggle individual guardrails using feature flags defined in the Zod-validated settings schema at [`src/shared/validation/settingsSchemas.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/settingsSchemas.ts). Set boolean flags such as `piiMaskerEnabled` or `modalityBridgeVisionEnabled` to `false` in your configuration to disable the respective guardrail without modifying source code.

### Can I add my own custom security logic to OmniRoute guardrails?

Yes. Extend the `BaseGuardrail` class, implement the desired stage methods (`preCall`, `pre`, or `post`), and register your implementation using `registerGuardrail()` from [`src/lib/guardrails/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/registry.ts). Specify a priority value between 1 and 100 to control where your guardrail executes relative to the built-in components.

### Where can I find the priority order for built-in OmniRoute guardrails?

The priority order is documented in [`docs/security/GUARDRAILS.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/security/GUARDRAILS.md) and enforced by [`src/lib/guardrails/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/guardrails/registry.ts). Lower priority numbers execute first: Vision Bridge (5), Audio Bridge (6), Video Bridge (7), PII Masker (10), Prompt Injection (20), and Credential Masker (95).