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

> Configure MITM TPROXY in OmniRoute to decrypt CLI traffic. Learn to intercept HTTPS traffic without proxy variables by enabling MITM and starting the proxy via API endpoints.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-05

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/manager.ts) | Spawns the server process, creates the root CA, installs it to the OS trust store, and writes [`targets.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/targets.json)/[`bypass.json`](https://github.com/diegosouzapw/OmniRoute/blob/main/bypass.json) |
| **TPROXY native addon** | [`src/mitm/tproxy/transparentSocket.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/transparentSocket.ts) | Loads the N‑API addon for `IP_TRANSPARENT` socket operations |
| **TPROXY rule engine** | [`src/mitm/tproxy/commands.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/commands.ts) | Generates iptables/ip‑rule commands for packet marking and routing |
| **TPROXY capture manager** | [`src/mitm/tproxy/captureManager.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

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

```

The [`manager.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/cert/install.ts), which executes:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/native/transparent.c). Check availability programmatically via `isTransparentSocketAvailable()` in [`transparentSocket.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/transparentSocket.ts), or ensure your build completed successfully with `scripts/build/mitm-stub-flag.mjs`.

### Apply TPROXY Rules

Enable transparent capture through the API:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/setup.ts), which executes the four commands generated by [`commands.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

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

```

The inspector client at [`src/lib/inspector/tproxyCaptureApi.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/inspector/tproxyCaptureApi.ts) implements this endpoint, returning applied rule IDs and certificate metadata documented in [`docs/security/MITM-TPROXY-DECRYPT.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/security/MITM-TPROXY-DECRYPT.md).

## Stop and Clean Up

### Stop TPROXY Capture

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

```

The [`setup.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/setup.ts) layer runs inverse iptables commands from [`commands.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/commands.ts) and unloads the transparent socket through idempotent `removeTproxyRules` logic.

### Stop the MITM Proxy

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/mitm-stop-dns-before-kill-1809.test.ts).

## Complete Configuration Example

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/cert/install.ts) |
| Privileged system command execution | [`src/mitm/systemCommands.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/API_REFERENCE.md) covering `/api/cli-tools/antigravity-mitm` and `/api/mitm/tproxy/*`. Operational guidance appears in [`docs/security/STEALTH_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/security/STEALTH_GUIDE.md) (MITM proxy) and [`docs/security/MITM-TPROXY-DECRYPT.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/security/MITM-TPROXY-DECRYPT.md) (transparent capture). Environment variable references are fully documented in [`docs/reference/ENVIRONMENT.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/reference/ENVIRONMENT.md).