Security Considerations for OmniRoute: 7 Critical Protection Layers Explained

OmniRoute implements seven distinct security layers—including route guard tiers, CORS policies, and pluggable guardrails—to prevent remote code execution, credential leakage, and upstream cascade failures when proxying requests to LLM providers.

OmniRoute acts as a critical middleware layer between client applications and dozens of LLM providers, handling sensitive authentication tokens and occasionally spawning subprocesses. Understanding the security considerations for OmniRoute is essential for production deployments, as the system enforces strict authentication boundaries, request validation pipelines, and fail-closed network policies across multiple subsystems. This guide examines the architectural protections implemented in the diegosouzapw/OmniRoute repository, referencing specific source files and configuration options available in release v3.8.51.

Authentication and Route Guard Tiers

OmniRoute classifies all management routes into three distinct tiers: LOCAL_ONLY, ALWAYS_PROTECTED, and MANAGEMENT. The first check occurs in src/server/authz/routeGuard.ts, where the isLocalOnlyPath function evaluates requests before any authentication logic executes.

This ordering guarantees that spawn-capable endpoints—such as /api/mcp/, /api/services/, /api/tunnels/*, and /api/vnc-session—cannot be reached via remote network traffic. The guard rejects any non-loopback request with a 403 LOCAL_ONLY response prior to JWT validation, effectively preventing the CVE class of "remote code execution via management API" regardless of token compromise.

The single exception to this rule applies to /api/mcp/ endpoints, which accept remote connections only when accompanied by a manage-scoped API key or the narrower mcp:connect scope. All other subprocess-capable routes remain strictly restricted to localhost origins.

CORS Policy and Origin Validation

OmniRoute adopts a fail-closed stance on cross-origin requests: no origin is permitted unless explicitly listed in the configuration. The implementation in src/server/cors/origins.ts resolves allowed origins through the setRuntimeAllowedOrigins function, merging static environment variables with runtime settings before applying headers via applyCorsHeaders.

While the environment variable CORS_ALLOW_ALL=true echoes any origin back for development convenience, it never includes the Access-Control-Allow-Credentials header, ensuring that credentialed sessions remain protected even in permissive modes.

# Production configuration (recommended)

CORS_ALLOWED_ORIGINS="https://app.example.com,https://admin.example.com"

# Development convenience - localhost only

CORS_ALLOWED_ORIGINS="http://localhost:3000,http://localhost:5173"

import { setRuntimeAllowedOrigins } from 'src/server/cors/origins';

// Runtime update example from Dashboard UI
setRuntimeAllowedOrigins('https://app.example.com,https://admin.example.com');

Guardrails Pipeline for Request and Response Sanitization

The guardrails system provides a pluggable pipeline that inspects both inbound payloads (preCall) and downstream responses (postCall). Registered in src/lib/guardrails/registry.ts via registerDefaultGuardrails(), these components operate at specific priority levels to enforce security policies without blocking legitimate traffic unnecessarily.

Core Guardrails and Priority Order

Priority	Guardrail	Stage(s)	Implementation 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

Guardrails default to fail-open: if a guardrail throws an exception, the error is logged and processing continues unless the guardrail explicitly returns block: true. This design prevents accidental denial-of-service from misconfigured security rules while allowing strict enforcement where required.

The credential-masker (priority 95) automatically strips API keys from logs and responses, while the pii-masker remains opt-in (default off) to avoid accidental data loss. Modality bridges safely convert images, audio, and video into text for non-vision models with configurable runtime settings.

Public Credential Handling

OmniRoute embeds public OAuth client IDs, Firebase Web keys, and similar non-secret values through resolvePublicCred() in src/shared/utils/publicCreds.ts. This function reads values from a generated .env file at startup, ensuring that these identifiers are never hard-coded in source code or exposed in version control.

This approach maintains a clear distinction between public configuration (client IDs) and secret credentials (API keys), with the latter stored in secure secret management systems rather than the codebase.

Error Sanitization and Stack Trace Prevention

All HTTP, SSE, and executor responses flow through buildErrorBody() or sanitizeErrorMessage() in src/open-sse/utils/error.ts before transmission to clients. These utilities guarantee that no stack traces, internal file paths, or implementation details leak to callers, preventing information disclosure that could aid attackers in mapping the system architecture.

Provider Resilience and Circuit Breakers

OmniRoute isolates upstream provider failures through a three-layer resilience model defined in src/shared/utils/circuitBreaker.ts and related authentication services:

• Provider Circuit Breaker: Trips after a configurable threshold of 5xx errors, temporarily blocking traffic to the entire provider to prevent cascade failures.
• Connection Cooldown: Applies per-account/key cooldowns for 429/403 rate-limit responses, implemented in src/open-sse/services/auth.ts.
• Model Lockout: Isolates failures affecting specific models while keeping other models on the same connection usable, managed via src/open-sse/services/accountFallback.ts.

These mechanisms protect the proxy infrastructure from abusive upstream failures and prevent resource exhaustion during provider outages.

Configuration Examples

Enabling PII Masking (Opt-In)

// Environment configuration
PII_RESPONSE_SANITIZATION=true

// Example request that triggers masking
await fetch('/v1/chat/completions', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}` },
  body: JSON.stringify({ 
    messages: [{ role: 'user', content: 'My SSN is 123-45-6789' }] 
  })
});

Accessing Local-Only Routes with Management Scope

# Generate key with manage scope

omniroute create-key --scopes manage

// Remote client accessing /api/mcp/ with manage-scoped key
await fetch('https://my-omniroute.example.com/api/mcp/status', {
  headers: { Authorization: `Bearer <manage-key>` }
});

Implementing a Custom Guardrail

// src/lib/guardrails/myCustomGuard.ts
import { Guardrail } from './base';

export class MyCustomGuard extends Guardrail {
  priority = 50;
  async preCall(ctx) {
    if (ctx.payload?.messages?.some(m => /forbidden/i.test(m.content))) {
      return { block: true, error: 'Forbidden content detected' };
    }
    return {};
  }
}

// Registration in src/lib/guardrails/registry.ts
registerGuardrail(new MyCustomGuard());

Summary

• Route Guard Tiers in src/server/authz/routeGuard.ts enforce LOCAL_ONLY restrictions before authentication, preventing remote code execution on spawn-capable endpoints.
• CORS Policy defaults to deny-all in src/server/cors/origins.ts, with explicit allowlists required for production and safe handling of CORS_ALLOW_ALL in development.
• Guardrails provide modular request/response inspection via src/lib/guardrails/registry.ts, with credential masking (priority 95) and optional PII masking (priority 10) available.
• Public Credentials resolve dynamically through src/shared/utils/publicCreds.ts to avoid hard-coding client IDs.
• Error Sanitization in src/open-sse/utils/error.ts ensures stack traces never reach client responses.
• Circuit Breakers in src/shared/utils/circuitBreaker.ts isolate failing upstream providers to maintain service stability.

Frequently Asked Questions

How does OmniRoute prevent remote code execution?

OmniRoute prevents remote code execution through route guard tiers that classify spawn-capable endpoints as LOCAL_ONLY. According to the source code in src/server/authz/routeGuard.ts, the isLocalOnlyPath check runs before JWT validation, rejecting any non-loopback request to routes like /api/services/ or /api/vnc-session. Only /api/mcp/ accepts remote connections, and solely when authenticated with a manage-scoped key or mcp:connect scope, mitigating the GHSA-fhh6-4qxv-rpqj vulnerability class.

Are OmniRoute guardrails fail-open or fail-closed?

OmniRoute guardrails default to fail-open. If a guardrail throws an exception during execution in src/lib/guardrails/registry.ts, the error is logged and request processing continues unless the guardrail explicitly returns { block: true }. This design prevents accidental denial-of-service from malformed guardrail logic while allowing operators to configure strict blocking behavior for specific security policies.

What is the difference between CORS_ALLOW_ALL and CORS_ALLOWED_ORIGINS?

CORS_ALLOWED_ORIGINS accepts a comma-separated list of specific origins that may access the API, providing strict production security. CORS_ALLOW_ALL=true relaxes origin checking for development but maintains safety by never including Access-Control-Allow-Credentials in responses, preventing credentialed cross-origin attacks. As implemented in src/server/cors/origins.ts, production deployments should always use explicit origin lists and omit CORS_ALLOW_ALL.

How does OmniRoute handle upstream provider failures securely?

OmniRoute implements provider resilience through three mechanisms in the source code: the circuit breaker in src/shared/utils/circuitBreaker.ts trips after consecutive 5xx errors; connection cooldowns in src/open-sse/services/auth.ts handle rate-limit responses per API key; and model lockout isolates failures to specific models without terminating entire connections. These layers prevent upstream outages from destabilizing the proxy service or exhausting local resources.

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