# OmniRoute MITM TPROXY Transparent Proxy: Deep Dive into Linux HTTPS Interception

> Learn about the OmniRoute MITM TPROXY transparent proxy. This Linux tool intercepts HTTPS traffic at the kernel level for deep inspection without altering proxy settings.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: deep-dive
- Published: 2026-08-24

---

**The OmniRoute MITM TPROXY transparent proxy is a Linux-only capture mode that intercepts outbound HTTPS traffic at the kernel level using policy routing and transparent sockets, decrypting and inspecting traffic without modifying system proxy settings or `/etc/hosts`.**

The OmniRoute MITM TPROXY transparent proxy represents the fifth capture mode in the Traffic Inspector/AgentBridge stack, designed specifically for scenarios where applications ignore traditional proxy configurations. Implemented in the `diegosouzapw/OmniRoute` repository, this mode leverages the Linux kernel's TPROXY feature to perform true man-in-the-middle interception of TLS-encrypted traffic. Unlike standard proxy configurations, this approach requires no modifications to `/etc/hosts` entries, OS-wide proxy settings, or client environment variables.

## How the OmniRoute MITM TPROXY Transparent Proxy Works

The system operates as a **privileged, opt-in interception framework** that captures outbound HTTPS connections transparently. When enabled via the loopback-only API endpoint at [`src/app/api/tools/agent-bridge/tproxy/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/tools/agent-bridge/tproxy/route.ts), the mode installs `iptables` rules in the `mangle OUTPUT` chain to mark new TCP connections to the target port—typically **443**—with a specific firewall mark (`MITM_DEFAULT_MARK`).

An `ip rule` then directs these marked packets to a local routing table, which routes them back to the loopback interface. The native N-API addon at [`src/mitm/tproxy/native/transparent.c`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/native/transparent.c) creates a kernel-transparent socket using the `IP_TRANSPARENT` option, allowing the process to receive packets destined for foreign addresses. This transparent listener binds to the designated intercept port and accepts the redirected traffic before handing it off for TLS termination.

## The Six-Stage Interception Pipeline

### Stage 1: Outbound Connection Marking

The pipeline begins when the [`captureManager.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/captureManager.ts) initializes the TPROXY mode. The system executes `iptables` commands to mark outbound TCP SYN packets destined for the target port with a unique firewall mark. This mark serves as a selector for the policy routing system, identifying which connections require interception versus which should proceed normally.

### Stage 2: Policy Routing Redirection

Once marked, packets hit the routing subsystem. A specific `ip rule` directs all traffic bearing the interception mark to a dedicated routing table—specified by the `routeTable` parameter (default **233**). This table routes the packets back to the loopback interface (`lo`), effectively redirecting the outbound connection to the local OmniRoute instance while preserving the original destination metadata in the socket options.

### Stage 3: Transparent Socket Listener

The native addon exposes `createTransparentListener` through the N-API layer loaded by [`src/mitm/tproxy/transparentSocket.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/transparentSocket.ts). This creates a socket with `IP_TRANSPARENT` enabled, bound to the intercept port (default **8443** via `onPort`). The kernel delivers the redirected packets to this socket, which appears to the client as the legitimate destination endpoint. The `TPROXY` target in the `mangle PREROUTING` chain facilitates this redirection without network address translation.

### Stage 4: Dynamic TLS Termination

Upon accepting a connection, the system must present a valid certificate for the original destination's Server Name Indication (SNI). The `DynamicCertStore` class in [`src/mitm/tproxy/dynamicCert.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/dynamicCert.ts) generates **per-SNI leaf certificates** on-the-fly, signed by a dedicated dynamic CA. The `createSNICallback` method provides the `SNICallback` for the Node.js TLS server, selecting or generating the appropriate certificate based on the client's SNI header. This allows OmniRoute to decrypt the HTTPS payload while presenting a trusted certificate to the client.

### Stage 5: HTTP Capture and Sanitization

With the TLS session terminated, the decrypted HTTP request arrives at the internal HTTP server. The system sanitizes headers and masks secrets before storing the traffic in the global buffer. This capture phase operates entirely in user space, with the plaintext request available for inspection, logging, or modification according to the Traffic Inspector's configuration.

### Stage 6: Re-encryption with Anti-Loop Protection

To complete the proxy chain, OmniRoute must forward the request to the original upstream server. The `connectMarked` function in [`transparentSocket.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/transparentSocket.ts) opens a new socket to the original destination but applies a **bypass mark** via `SO_MARK` (typically **0x539**). The `iptables` rules explicitly exclude packets bearing this bypass mark from interception, preventing infinite proxy loops. The response follows the reverse path: decrypted by OmniRoute, re-encrypted with the per-SNI certificate, and delivered to the client application.

## Implementation Architecture and Key Files

The implementation spans TypeScript orchestration layers and C++ native modules for kernel interaction:

- **[`src/mitm/manager.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/manager.ts)** – Orchestrates the MITM lifecycle, handling process start/stop, PID management, and configuration persistence across sessions.
- **[`src/mitm/tproxy/transparentSocket.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/transparentSocket.ts)** – Loads the native addon and exposes `connectMarked` for upstream connections, managing socket marks through `setSocketMark`.
- **[`src/mitm/tproxy/native/transparent.c`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/native/transparent.c)** – N-API addon providing `createTransparentListener`, `setSocketMark`, and `connectMarked` syscalls.
- **[`src/mitm/tproxy/dynamicCert.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/dynamicCert.ts)** – Implements the `DynamicCertStore` class for runtime certificate generation and TLS context caching.
- **[`src/mitm/tproxy/caTrust.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/caTrust.ts)** – Manages installation and removal of `omniroute-tproxy-ca.crt` from the OS trust store using dedicated slots to avoid conflicts.
- **[`src/mitm/tproxy/captureManager.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/captureManager.ts)** – Singleton API controlling the TPROXY mode lifecycle, exposing start, stop, and status methods.

## Starting the Capture Mode via API

The TPROXY mode is accessible exclusively through the loopback-only API endpoint at [`src/app/api/tools/agent-bridge/tproxy/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/tools/agent-bridge/tproxy/route.ts). Clients initiate interception by calling `startTproxyCaptureMode` with a configuration object specifying ports, marks, and routing tables.

```typescript
import { startTproxyCaptureMode } from "@/lib/inspector/tproxyCaptureApi";

await startTproxyCaptureMode({
  dport: 443,               // Target port to intercept (HTTPS)
  mark: 0x2333,             // Firewall mark for interception
  onPort: 8443,             // Local transparent listener port
  routeTable: 233,          // Policy routing table ID
  bypassMark: 0x539,        // Anti-loop SO_MARK for upstream
});

```

The `dport` parameter specifies which destination port to intercept, while `mark` defines the netfilter mark used for routing decisions. The `onPort` value represents where the transparent listener binds, and `bypassMark` ensures upstream connections escape re-interception.

To establish the TLS termination server with dynamic certificates:

```typescript
import { DynamicCertStore } from "@/mitm/tproxy/dynamicCert";
import * as tls from "tls";

const certStore = new DynamicCertStore();
const httpsServer = tls.createServer(
  { SNICallback: certStore.createSNICallback() },
  (tlsSocket) => {
    // tlsSocket carries plaintext HTTP after decryption
    httpServer.emit("connection", tlsSocket);
  }
);
httpsServer.listen(8443);

```

For connecting to upstream servers with loop prevention:

```typescript
import { connectMarked } from "@/mitm/tproxy/transparentSocket";

const upstream = connectMarked(originalHost, originalPort, 0x539);

```

## Security Model and Certificate Authority

The OmniRoute MITM TPROXY transparent proxy operates under a **strict security model** requiring root privileges for netfilter manipulation and raw socket creation. Upon activation, [`caTrust.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/caTrust.ts) automatically installs the `omniroute-tproxy-ca.crt` certificate into the host's trust store. The corresponding private key never leaves the machine and is removed automatically when the mode is stopped.

This design ensures that only local processes with sufficient privileges can initiate interception, and the dedicated CA prevents systemic trust store pollution. The mode is **opt-in** and **Linux-only**, with the API restricted to loopback interfaces to prevent remote exploitation. Full security considerations are documented in [`docs/security/MITM-TPROXY-DECRYPT.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/security/MITM-TPROXY-DECRYPT.md) and usage guidelines in [`docs/security/STEALTH_GUIDE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/security/STEALTH_GUIDE.md).

## Summary

- The OmniRoute MITM TPROXY transparent proxy intercepts HTTPS traffic using Linux kernel TPROXY and policy routing, requiring no changes to `/etc/hosts` or client proxy settings.
- Traffic flows through a six-stage pipeline: packet marking, routing redirection, transparent socket acceptance, dynamic TLS termination, HTTP capture, and re-encryption with bypass marks.
- The architecture relies on [`src/mitm/tproxy/native/transparent.c`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/native/transparent.c) for kernel-level socket operations and [`src/mitm/tproxy/dynamicCert.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/dynamicCert.ts) for per-SNI certificate generation.
- Configuration occurs via `startTproxyCaptureMode` with parameters for firewall marks, ports, and routing tables, exposed through a loopback-only API.
- Anti-loop protection uses `SO_MARK` with a bypass mark (e.g., **0x539**) to prevent recursive interception of upstream connections.
- The system automatically manages a dedicated CA certificate (`omniroute-tproxy-ca.crt`) for the interception session, removing it upon shutdown.

## Frequently Asked Questions

### What makes the OmniRoute MITM TPROXY transparent proxy different from standard HTTP_PROXY interception?

Standard proxy interception requires applications to honor `HTTP_PROXY` or `HTTPS_PROXY` environment variables, which many modern applications ignore or strip for security reasons. The TPROXY mode operates at the kernel level using netfilter marks and policy routing, capturing traffic regardless of application configuration. According to the OmniRoute source code, this approach intercepts connections "without modifying `/etc/hosts` entries, changing the OS-wide proxy configuration, or requiring the client to honor `HTTP_PROXY`/`HTTPS_PROXY`."

### Is the OmniRoute MITM TPROXY transparent proxy safe to use?

The implementation includes several safety mechanisms. It is **opt-in** and restricted to root users, with the API endpoint bound exclusively to loopback interfaces to prevent remote access. The dynamic CA certificate (`omniroute-tproxy-ca.crt`) is installed only during active sessions and removed immediately upon stopping the capture mode. Additionally, the CA key remains on the local machine and is never transmitted. However, as noted in [`docs/security/MITM-TPROXY-DECRYPT.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/security/MITM-TPROXY-DECRYPT.md), users should understand that this tool decrypts HTTPS traffic, creating a genuine man-in-the-middle position that requires trusted handling of the signing keys.

### Why does this mode require root privileges?

Root access is mandatory for three kernel-level operations: modifying `iptables` rules in the `mangle` table, manipulating the routing policy database with `ip rule`, and creating transparent sockets with `IP_TRANSPARENT`. The native addon at [`src/mitm/tproxy/native/transparent.c`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/native/transparent.c) requires `CAP_NET_ADMIN` capabilities to bind to arbitrary addresses and use the `TPROXY` target. Without elevated privileges, the process cannot install the packet marking rules or bind the transparent listener to foreign addresses required for interception.

### Can I use the OmniRoute MITM TPROXY transparent proxy on macOS or Windows?

No. The OmniRoute MITM TPROXY transparent proxy is **Linux-only** due to its dependency on specific kernel features. The implementation relies on the Linux netfilter framework (`iptables`/`nftables`), the `TPROXY` module, and policy routing (`ip rule`/`ip route`) which have no direct equivalents on macOS or Windows. The native C++ addon at [`src/mitm/tproxy/native/transparent.c`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/native/transparent.c) is compiled specifically against Linux kernel headers and socket APIs. Users on other platforms must use alternative capture modes in the OmniRoute stack that rely on traditional proxy configuration or DNS redirection.