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

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, 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 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 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. 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 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 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 – Orchestrates the MITM lifecycle, handling process start/stop, PID management, and configuration persistence across sessions.
• 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 – N-API addon providing createTransparentListener, setSocketMark, and connectMarked syscalls.
• src/mitm/tproxy/dynamicCert.ts – Implements the DynamicCertStore class for runtime certificate generation and TLS context caching.
• 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 – 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. Clients initiate interception by calling startTproxyCaptureMode with a configuration object specifying ports, marks, and routing tables.

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:

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:

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 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 and usage guidelines in 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 for kernel-level socket operations and 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, 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 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 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.

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