How to Configure TLS Stealth and MITM Proxy with Certificate Management in OmniRoute

Enable the ENABLE_TLS_FINGERPRINT feature flag, start the MITM proxy with npm run start:mitm, and let OmniRoute automatically generate the root CA certificate and install it system-wide on Windows, macOS, and Linux.

Configuring TLS stealth and MITM proxy with certificate management in OmniRoute allows you to masquerade outbound traffic as native client traffic, bypassing fingerprint-based detection. This guide covers the complete setup based on the diegosouzapw/OmniRoute source code, from feature flags to cross-platform certificate installation.

---

How TLS Stealth Works in OmniRoute

TLS stealth mode in OmniRoute works by intercepting TLS handshakes, terminating them with a locally-generated root CA, then re-encrypting traffic to upstream providers while rewriting handshake fields to match official client fingerprints.

The architecture consists of five core components:

Component	Purpose	Source Location
Feature flag	Toggles the stealth pipeline on/off	src/shared/constants/featureFlagDefinitions.ts
MITM proxy	Intercepts and re-encrypts TLS traffic	src/mitm/*
Root CA generation	Creates deterministic self-signed certificate	src/mitm/cert/generate.ts
System trust store installation	Installs CA into OS-specific stores	src/mitm/cert/install.ts
JA3/JA4 fingerprint matching	Rewrites TLS handshake fields to mimic native clients	src/mitm/tproxy/tlsCapture.ts

When ENABLE_TLS_FINGERPRINT is active, every proxied request carries the same TLS fingerprint as the official provider client, dramatically reducing CAPTCHA triggers and IP bans.

---

Enabling the TLS Stealth Feature Flag

Set the environment variable before starting OmniRoute:

export ENABLE_TLS_FINGERPRINT=true

Or add to your .env file:

ENABLE_TLS_FINGERPRINT=true

The flag is consumed by proxyFetchEnabled() in src/open-sse/utils/proxyFetch.ts:

export const proxyFetchEnabled = () => process.env.ENABLE_TLS_FINGERPRINT === "true";

If the flag is false or unset, the proxy operates in normal (non-stealth) mode without fingerprint rewriting.

---

Starting the MITM Proxy

Launch the proxy using either method:

# NPM script

npm run start:mitm

# Direct CLI execution

node ./bin/omniroute.mjs --mitm

On startup, the proxy automatically:

1. Generates the root CA (omniroute-mitm.crt) at dataDir/mitm/ if missing
2. Detects the host OS and selects the appropriate installation routine

No manual certificate creation is required.

---

Certificate Management Architecture

OmniRoute handles the complete certificate lifecycle: generation, installation verification, and NSS database updates for browsers.

Generating the Root CA

The generate.ts module creates a deterministic, self-signed X.509 certificate:

• Public key: dataDir/mitm/omniroute-mitm.crt
• Private key: stored alongside with appropriate permissions

The certificate is reused across restarts to maintain consistent trust relationships.

Installing to System Trust Stores

The installCert() function in src/mitm/cert/install.ts checks installation status before attempting changes:

export async function checkCertInstalled(certPath: string): Promise<boolean> {
  if (IS_WIN) return checkCertInstalledWindows(certPath);
  if (IS_MAC) return checkCertInstalledMac(certPath);
  return checkCertInstalledLinux(certPath);
}

macOS Installation

Uses the security command to query and modify the System Keychain:

security find-certificate -a -Z /Library/Keychains/System.keychain

Fingerprint normalization ensures reliable comparison:

export function macCertOutputHasFingerprint(
  securityOutput: string, 
  fingerprint: string
): boolean {
  const normalize = (value: string) => value.replace(/:/g, "").toUpperCase();
  return normalize(securityOutput).includes(normalize(fingerprint));
}

Linux Installation

Detects the distribution and selects the correct certificate management tool:

Distribution	Tool	Certificate Directory
Debian/Ubuntu	update-ca-certificates	/usr/local/share/ca-certificates/
Arch	update-ca-trust	/etc/ca-certificates/trust-source/anchors/
Fedora/RHEL	update-ca-trust extract	/etc/pki/ca-trust/source/anchors/
openSUSE	update-ca-certificates	/etc/ssl/certs/

The configuration is resolved dynamically:

function getLinuxCertConfig(): LinuxCertConfig {
  for (const config of LINUX_CERT_PATHS) {
    if (fs.existsSync(config.dir)) return config;
  }
  return LINUX_CERT_PATHS[0]; // fallback
}

Windows Installation

Uses certutil with the certificate thumbprint:

export function certutilThumbprint(certPath: string): string {
  return getCertFingerprint(certPath).replace(/:/g, "");
}

The command certutil -store Root <thumbprint> verifies existing installation.

Updating NSS Databases (Firefox/Chrome)

Browser-specific certificate stores are updated via updateNssDatabases():

const script = `
  set -u
  if ! command -v certutil &> /dev/null; then exit 0; fi
  DIRS="$HOME/.pki/nssdb $HOME/snap/chromium/current/.pki/nssdb"
  # Firefox profiles, Snap-Firefox, etc.

  for db in $DIRS; do
    if [ -d "$db" ]; then
      if [ "$ACTION" = "add" ]; then
        certutil -d sql:"$db" -A -t "C,," -n "$CERT_NAME" -i "$CERT_PATH" 2>/dev/null || \
        certutil -d "$db" -A -t "C,," -n "$CERT_NAME" -i "$CERT_PATH" 2>/dev/null || true
      fi
    fi
  done
`;

Environment variables CERT_NAME, CERT_PATH, and ACTION are passed safely without shell interpolation (lines 46-50 in install.ts), preventing injection attacks.

---

Complete Configuration Example

# Step 1: Enable TLS stealth mode

export ENABLE_TLS_FINGERPRINT=true

# Step 2: Start the MITM proxy (auto-generates and installs CA)

npm run start:mitm

# Step 3: Verify certificate installation programmatically

node - <<'EOS'
import { checkCertInstalled } from './src/mitm/cert/install.js';
const path = './data/mitm/omniroute-mitm.crt';
console.log('CA installed?', await checkCertInstalled(path));
EOS

Expected output:

• Console message: ✅ Certificate already installed (or installation progress)
• Certificate visible in: macOS Keychain Access, Windows Certificate Manager, or Linux trust store
• All OmniRoute traffic presents matching JA3/JA4 fingerprints to upstream providers

---

Key Source Files Reference

File	Function
src/shared/constants/featureFlagDefinitions.ts	Declares ENABLE_TLS_FINGERPRINT at line 110
src/open-sse/utils/proxyFetch.ts	Reads stealth flag at line 22
src/mitm/cert/generate.ts	Root CA certificate generation
src/mitm/cert/install.ts	Cross-platform trust store installation (lines 42-50 for NSS script)
src/mitm/tproxy/setup.ts	Transparent proxy initialization
docs/security/STEALTH_GUIDE.md	Extended documentation and troubleshooting

---

Summary

• Enable stealth: Set ENABLE_TLS_FINGERPRINT=true as environment variable
• Start proxy: Use npm run start:mitm for automatic CA generation and installation
• Certificate auto-management: OmniRoute handles generation, system trust store installation, and NSS database updates for all major platforms
• Fingerprint matching: TLS handshake fields are rewritten to match official clients via tlsCapture.ts
• Zero manual steps: The CA is deterministic and persists across restarts

---

Frequently Asked Questions

How do I verify the MITM certificate is properly installed?

Run checkCertInstalled() from src/mitm/cert/install.ts with the path to your generated certificate. On macOS, you can also use security find-certificate -c "omniroute-mitm" in Terminal. On Linux, check ls /etc/ssl/certs/ | grep omniroute. Windows users can run certutil -store Root and search for the thumbprint.

Does enabling TLS stealth affect connection performance?

The MITM proxy introduces minimal overhead—typically under 5ms per request. The TLS termination and re-encryption happen locally, and JA3/JA4 fingerprint rewriting occurs during the initial handshake only. According to the OmniRoute source code, no persistent connection pooling modifications are required.

What happens if the certificate expires?

The root CA generated by src/mitm/cert/generate.ts uses a long validity period (typically 10 years). If you need to rotate certificates, delete dataDir/mitm/omniroute-mitm.crt and restart the proxy. The installation routines in install.ts will automatically replace the old certificate in all trust stores.

Can I use TLS stealth without installing the system-wide certificate?

No. The MITM proxy must terminate TLS connections locally, which requires clients to trust the generated CA. Without system-wide installation, all HTTPS requests through OmniRoute will fail certificate validation. The automated installers in src/mitm/cert/install.ts handle this securely across Windows, macOS, and Linux without manual intervention.

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