How to Configure MITM/TPROXY in OmniRoute to Decrypt CLI Traffic

Configure MITM/TPROXY in OmniRoute by setting MITM_ROOT_CA_ENABLED=true, starting the MITM proxy via the /api/cli-tools/antigravity-mitm endpoint, and on Linux optionally enabling transparent capture with /api/mitm/tproxy/start to intercept HTTPS traffic without proxy environment variables.

OmniRoute provides a MITM (Man‑in‑the‑Middle) proxy architecture that decrypts outbound HTTPS traffic from CLI tools. When running on Linux, you can upgrade to TPROXY transparent‑socket capture mode to intercept traffic without requiring clients to respect HTTPS_PROXY settings. This guide covers the complete configuration based on the OmniRoute diegosouzapw/OmniRoute source code at release v3.8.50.

Architecture Overview

The MITM/TPROXY system consists of four coordinated layers defined in src/mitm/:

Layer	Key File	Purpose
MITM manager	src/mitm/manager.ts	Spawns the server process, creates the root CA, installs it to the OS trust store, and writes targets.json/bypass.json
TPROXY native addon	src/mitm/tproxy/transparentSocket.ts	Loads the N‑API addon for IP_TRANSPARENT socket operations
TPROXY rule engine	src/mitm/tproxy/commands.ts	Generates iptables/ip‑rule commands for packet marking and routing
TPROXY capture manager	src/mitm/tproxy/captureManager.ts	Orchestrates apply/revert steps and wires captured streams to the MITM server

Enable the MITM Proxy

Set Required Environment Variables

Configure these variables before starting OmniRoute:

export MITM_LOCAL_PORT=443              # MITM server bind port (default: 443)

export MITM_ROOT_CA_ENABLED=true        # Required for TPROXY; enables dynamic root CA

export OMNIROUTE_NO_SUDO=0              # Set to 1 for Docker/rootless deployments

Full documentation appears in docs/reference/ENVIRONMENT.md. The MITM_ROOT_CA_ENABLED=true flag is mandatory for TPROXY mode—the transparent capture requires the dynamic certificate authority model rather than legacy static leaf certificates.

Start the MITM Server

Authenticate with your router API key and call the CLI‑tools endpoint:

curl -X POST https://<omniroute-host>/api/cli-tools/antigravity-mitm \
     -H "Authorization: Bearer <ROUTER_API_KEY>" \
     -d '{"port":443}'

The manager.ts implementation performs three operations: spawns the Node.js server process at src/mitm/server.cjs, generates a fresh root CA, and writes the JSON configuration files the server consumes.

Install the Root CA

The manager automatically runs installCaCert from src/mitm/cert/install.ts, which executes:

sudo cp <ca-file> /usr/local/share/ca-certificates/omniroute-mitm-ca.crt
sudo update-ca-certificates

When OMNIROUTE_NO_SUDO=1 is set, this step is skipped and you must manually trust the certificate—typically via NODE_EXTRA_CA_CERTS or your OS certificate UI.

Upgrade to TPROXY Transparent Capture (Linux Only)

TPROXY intercepts traffic without client‑side proxy configuration. This captures HTTPS from CLI tools that ignore HTTPS_PROXY environment variables.

Verify the Native Addon

The transparent socket capability depends on a N‑API addon compiled from src/mitm/tproxy/native/transparent.c. Check availability programmatically via isTransparentSocketAvailable() in transparentSocket.ts, or ensure your build completed successfully with scripts/build/mitm-stub-flag.mjs.

Apply TPROXY Rules

Enable transparent capture through the API:

curl -X POST https://<omniroute-host>/api/mitm/tproxy/start \
     -H "Authorization: Bearer <ROUTER_API_KEY>"

This invokes applyTproxyRules() in src/mitm/tproxy/setup.ts, which executes the four commands generated by commands.ts:

1. OUTPUT mark — tags outbound packets from the OmniRoute process
2. PREROUTING TPROXY rule — redirects marked packets to the transparent listener
3. ip rule — selects the custom routing table for marked packets
4. ip route — routes marked packets locally to the capture socket

Open the Transparent Listener

The capture manager calls startTproxyCapture() from src/mitm/tproxy/captureMode.ts, which:

• Creates a socket via the addon's setSocketMark(fd) function with IP_TRANSPARENT enabled
• Binds to the original destination address retrieved from the kernel
• Pipes decrypted traffic to the MITM server for TLS termination

Verify TPROXY Status

Confirm active rules and CA thumbprint:

curl https://<omniroute-host>/api/mitm/tproxy/status \
     -H "Authorization: Bearer <ROUTER_API_KEY>"

The inspector client at src/lib/inspector/tproxyCaptureApi.ts implements this endpoint, returning applied rule IDs and certificate metadata documented in docs/security/MITM-TPROXY-DECRYPT.md.

Stop and Clean Up

Stop TPROXY Capture

curl -X POST https://<omniroute-host>/api/mitm/tproxy/stop \
     -H "Authorization: Bearer <ROUTER_API_KEY>"

The setup.ts layer runs inverse iptables commands from commands.ts and unloads the transparent socket through idempotent removeTproxyRules logic.

Stop the MITM Proxy

curl -X DELETE https://<omniroute-host>/api/cli-tools/antigravity-mitm \
     -H "Authorization: Bearer <ROUTER_API_KEY>"

The manager removes DNS spoof entries before terminating the child process—preventing a race condition where the OS still resolves hosts to 127.0.0.1. This sequencing is validated by mitm-stop-dns-before-kill-1809.test.ts.

Complete Configuration Example

# 1. Environment setup

export MITM_LOCAL_PORT=443
export MITM_ROOT_CA_ENABLED=true
export OMNIROUTE_NO_SUDO=0

# 2. Start MITM proxy

curl -X POST https://omniroute.local/api/cli-tools/antigravity-mitm \
     -H "Authorization: Bearer $ROUTER_API_KEY"

# 3. Enable TPROXY transparent capture (Linux)

curl -X POST https://omniroute.local/api/mitm/tproxy/start \
     -H "Authorization: Bearer $ROUTER_API_KEY"

# 4. Use CLI tools normally—traffic is intercepted and decrypted

# 5. Stop TPROXY

curl -X POST https://omniroute.local/api/mitm/tproxy/stop \
     -H "Authorization: Bearer $ROUTER_API_KEY"

# 6. Stop MITM

curl -X DELETE https://omniroute.local/api/cli-tools/antigravity-mitmitm \
     -H "Authorization: Bearer $ROUTER_API_KEY"

Key Implementation Details

Concern	Implementation Location
CA generation and trust installation	src/mitm/cert/install.ts
Privileged system command execution	src/mitm/systemCommands.ts
Server process lifecycle	src/mitm/manager.ts:start() / stop()
TPROXY command generation	src/mitm/tproxy/commands.ts:getApplyCommands() / getRevertCommands()
Transactional rule apply/revert	src/mitm/tproxy/setup.ts:applyTproxyRules() / revertTproxyRules()
Transparent socket operations	src/mitm/tproxy/transparentSocket.ts:setSocketMark(), connectMarked()

Summary

• MITM proxy requires MITM_ROOT_CA_ENABLED=true and starts via /api/cli-tools/antigravity-mitm
• TPROXY mode works only on Linux with the native addon loaded, activated via /api/mitm/tproxy/start
• Root CA trust happens automatically with sudo, or manually when OMNIROUTE_NO_SUDO=1
• Cleanup order matters: stop TPROXY before MITM to avoid routing loops; the manager handles DNS removal before process termination
• Source authority: All paths reference diegosouzapw/OmniRoute release v3.8.50, specifically src/mitm/manager.ts and the src/mitm/tproxy/ module

Frequently Asked Questions

What is the difference between MITM proxy mode and TPROXY mode in OmniRoute?

Standard MITM proxy mode requires CLI tools to respect HTTPS_PROXY environment variables to route traffic through the OmniRoute decryptor. TPROXY mode uses Linux's IP_TRANSPARENT socket option and iptables rules to intercept outbound connections transparently—clients need no proxy configuration. TPROXY requires the native addon built from src/mitm/tproxy/native/transparent.c and only functions on Linux hosts.

Why does TPROXY require MITM_ROOT_CA_ENABLED=true?

TPROXY captures traffic destined for arbitrary remote hosts, so the MITM server must generate certificates for those hosts on‑demand. The dynamic root‑CA model (MITM_ROOT_CA_ENABLED=true) allows runtime certificate generation signed by a trusted CA. Static leaf certificates cannot satisfy this requirement because they are pre‑generated for specific domains. The manager.ts implementation enforces this dependency when initializing transparent capture.

How do I run MITM/TPROXY in a container without sudo privileges?

Set OMNIROUTE_NO_SUDO=1 to skip automatic CA installation commands. Manually trust the generated certificate through NODE_EXTRA_CA_CERTS=/path/to/ca.crt or your container orchestration's secret mechanism. The install.ts module detects this flag and emits the certificate path without executing privileged system commands. You must still run the container with NET_ADMIN capability for TPROXY iptables modifications, or apply rules on the host outside the container.

Where can I find the official API documentation for MITM endpoints?

The OpenAPI definitions reside in docs/reference/API_REFERENCE.md covering /api/cli-tools/antigravity-mitm and /api/mitm/tproxy/*. Operational guidance appears in docs/security/STEALTH_GUIDE.md (MITM proxy) and docs/security/MITM-TPROXY-DECRYPT.md (transparent capture). Environment variable references are fully documented in docs/reference/ENVIRONMENT.md.

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