OmniRoute TLS Stealth and Proxy Avoidance: How It Spoofs Browser Fingerprints and Bypasses Proxies

OmniRoute TLS stealth and proxy avoidance are dual security capabilities that spoof Chrome‑like TLS fingerprints to evade bot detection and optionally bypass configured egress proxies when direct connections are required.

The OmniRoute routing engine implements these features through opt‑in configuration flags, allowing operators to masquerade automated traffic as legitimate browser sessions while maintaining fallback pathways for proxy failures.

What Is TLS‑Fingerprint Stealth in OmniRoute?

The TLS‑fingerprint stealth capability hides the fact that traffic originates from a Node.js program rather than a real browser by substituting the default TLS client with one that emits a genuine Chrome handshake.

How the Spoofing Works

When ENABLE_TLS_FINGERPRINT is activated, the Open‑SSE executors (open-sse/executors/) instantiate HTTP/HTTPS clients via the wreq‑js library instead of Node.js native tls. This library reproduces the exact JA3/JA4 hash of Chrome 124, defeating fingerprint‑based bot detection used by Cloudflare, Akamai, and similar services.

Configuration Element	Location	Default
Feature flag definition	src/shared/constants/featureFlagDefinitions.ts	false
Runtime toggle	Database or env ENABLE_TLS_FINGERPRINT	false
Timeout control	TLS_CLIENT_TIMEOUT_MS in ENVIRONMENT.md	Mirrors FETCH_TIMEOUT_MS

The stealth client respects the same timeout semantics as standard fetches, ensuring performance parity while evading detection.

Why TLS Stealth Matters

• JA3/JA4 blocking — Services refuse generic Node.js TLS profiles.
• Credential binding — Some providers invalidate sessions when the TLS fingerprint changes mid‑session.
• Bot detection — Hosted automation is flagged via TLS signature analysis.

Proxy Avoidance: Direct‑Egress Fallbacks

OmniRoute normally routes outbound traffic through a control‑plane proxy for auditing and egress‑IP control. Two mechanisms allow proxy avoidance when the proxy is unreachable or when direct connections are mandated:

Mechanism 1: Health‑Check Fallback

The OMNIROUTE_CONTROL_PLANE_PROXY_DIRECT_FALLBACK flag enables automatic direct connections when proxy health checks fail.

# Enable fallback on proxy failure

OMNIROUTE_CONTROL_PLANE_PROXY_DIRECT_FALLBACK=true npm run start

This prevents total outage when the control‑plane proxy becomes unavailable.

Mechanism 2: Host‑Specific Bypass via NO_PROXY

The NO_PROXY environment variable accepts comma‑separated host patterns that skip proxy resolution entirely through the resolveProxyForRequest logic:

# Bypass proxy for OpenAI API calls

NO_PROXY=api.openai.com npm run start

Both mechanisms are fail‑closed by default. The proxy is never bypassed without explicit operator configuration, preventing accidental IP leakage.

Stealth Browser Pool for Web‑Cookie Providers

For providers requiring genuine browser sessions (Cloudflare‑protected flows), OmniRoute runs a shared stealth browser pool:

Component	Implementation	Location
Stealth launcher	puppeteer-extra-plugin-stealth	open-sse/services/browserPool.ts
Pool management	Context reuse and cookie extraction	open-sse/services/browserPool.ts
Status tooling	MCP tool browser_pool_status	open-sse/mcp-server/tools/poolTools.ts

The pool launches headless Chromium in stealth mode, solves challenges (CAPTCHAs, Cloudflare interstitials), and extracts fresh cookies for downstream requests. The stealthAvailable flag indicates whether the stealth launcher is operational.

Accessing the Browser Pool

import { getBrowserPool } from '@/open-sse/services/browserPool';

async function refreshGrokCookies() {
  const pool = await getBrowserPool();

  // Launches stealth Chromium, solves challenges, returns fresh cookies
  await pool.refreshCookiesViaBrowser('grok-web');
}

Check pool status via MCP:

omniroute mcp tool browser_pool_status

Enabling TLS Stealth and Proxy Avoidance

Complete Environment Configuration

# .env file — TLS fingerprint spoofing

ENABLE_TLS_FINGERPRINT=true
TLS_CLIENT_TIMEOUT_MS=60000

# Proxy fallback configuration

OMNIROUTE_CONTROL_PLANE_PROXY_DIRECT_FALLBACK=true
NO_PROXY=api.openai.com,auth.openai.com

npm run start

Runtime Feature Flag Toggle

The ENABLE_TLS_FINGERPRINT flag can be modified at runtime through the feature‑flag API by setting the database entry ENABLE_TLS_FINGERPRINT = true, enabling dynamic response to changing detection environments.

Key Source Files

• open-sse/executors/ — HTTP client instantiation with wreq-js substitution when stealth is enabled
• open-sse/services/browserPool.ts — Shared stealth Chromium pool with stealthAvailable flag
• open-sse/mcp-server/tools/poolTools.ts — MCP tooling for pool telemetry
• src/shared/constants/featureFlagDefinitions.ts — Internal definition of ENABLE_TLS_FINGERPRINT
• docs/security/STEALTH_GUIDE.md — Comprehensive TLS and CLI fingerprint documentation
• docs/reference/ENVIRONMENT.md — Environment variable specifications
• docs/reference/FEATURE_FLAGS.md — Feature flag reference

Summary

• OmniRoute TLS stealth spoofs Chrome 124 TLS fingerprints via wreq-js to defeat JA3/JA4 bot detection.
• The ENABLE_TLS_FINGERPRINT flag gates this capability, defaulting to false for fail‑closed security.
• Proxy avoidance provides two pathways: automatic fallback on proxy failure and host‑specific NO_PROXY bypass.
• The stealth browser pool complements TLS spoofing with genuine Chromium sessions for web‑cookie providers.
• All capabilities are opt‑in, preserving operational safety while enabling evasion when required.

Frequently Asked Questions

How does OmniRoute TLS stealth differ from a standard HTTPS proxy?

Standard HTTPS proxies forward encrypted traffic without modifying the TLS handshake. OmniRoute TLS stealth replaces the client hello entirely, emitting a fingerprint that matches real Chrome rather than Node.js. This occurs at the application layer before any proxy connection is established.

Can I enable TLS stealth without the stealth browser pool?

Yes. The ENABLE_TLS_FINGERPRINT flag operates independently of the browser pool. TLS stealth handles transport‑level fingerprinting for API calls, while the browser pool provides session‑level authenticity for web‑cookie flows. Enable either or both based on provider requirements.

What happens if wreq-js fails or the stealth browser pool is unavailable?

The executors fall back to standard Node.js TLS clients when wreq-js encounters errors. The browser pool's stealthAvailable flag surfaces availability through the browser_pool_status MCP tool, and providers requiring cookies will fail gracefully with clear error messages rather than hanging indefinitely.

Is proxy avoidance safe for production deployments?

Proxy avoidance is safe when configured deliberately. The OMNIROUTE_CONTROL_PLANE_PROXY_DIRECT_FALLBACK flag prevents outage cascades when proxies fail, while NO_PROXY enables precise exceptions for providers that reject proxied connections. Both require explicit opt‑in, maintaining the principle of least privilege.

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