Security Guardrails in OmniRoute: Architecture, Configuration, and Implementation

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, 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
6	Audio Bridge	preCall	src/lib/guardrails/audioBridge.ts
7	Video Bridge	preCall	src/lib/guardrails/videoBridge.ts
10	PII Masker	pre + post	src/lib/guardrails/piiMasker.ts
20	Prompt Injection	preCall	src/lib/guardrails/promptInjection.ts
95	Credential Masker	pre + post	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): Detects image payloads destined for non-vision models. Using helper functions in src/lib/guardrails/visionBridgeHelpers.ts, it extracts image parts and retrieves configuration from 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): Handles audio payload transformation and rerouting using logic parallel to the Vision Bridge implementation.

• Video Bridge (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) 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) 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) 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. 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 accepts a priority parameter to position the custom logic within the execution chain.

// 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.

// 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.

// 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 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) 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, 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. 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. 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 and enforced by 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).

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