# How to Set Up the MITM Transparent Proxy in OmniRoute for CLI Tools

> Learn to set up the MITM transparent proxy in OmniRoute for CLI tools. Intercept and decrypt HTTPS traffic with kernel-level transparent sockets and dynamic CA installation.

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

---

**OmniRoute intercepts and decrypts HTTPS traffic from CLI tools that ignore proxy environment variables by leveraging TPROXY mode to create kernel-level transparent sockets, dynamically installing a per-SNI root CA, and rewriting iptables rules to redirect traffic through a local MITM server.**

OmniRoute’s **TPROXY capture mode** enables you to inspect traffic from command-line utilities and languages that do not respect standard `HTTP_PROXY` or `HTTPS_PROXY` variables. This functionality requires a Linux host with root privileges (or the `CAP_NET_ADMIN` capability) and a native N-API addon compiled from [`src/mitm/tproxy/native/transparent.c`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/native/transparent.c) to interface with the kernel’s transparent proxy mechanism.

## Prerequisites for TPROXY Mode

Before enabling the transparent proxy, ensure your environment meets the following requirements:

- **Linux kernel** with `IP_TRANSPARENT` socket option support (available in most modern distributions).
- **Root access** or the `CAP_NET_ADMIN` capability to modify iptables and create transparent sockets.
- **Build toolchain** including `gcc`, `make`, and `node-gyp` to compile the native addon.

## Step 1: Build the Native TPROXY Addon

The transparent proxy functionality relies on a native C addon that exposes low-level socket operations. Compile the addon using the provided build script:

```bash
npm run build:native:tproxy

```

This command compiles [`src/mitm/tproxy/native/transparent.c`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/native/transparent.c), which exports the `createTransparentListener`, `setSocketMark`, and `connectMarked` functions required for kernel-level traffic interception. The build logic is defined in `scripts/build/build-tproxy-native.mjs`.

## Step 2: Generate and Install the MITM Root CA

OmniRoute generates a unique root certificate authority (CA) for signing dynamic per-SNI certificates. Run the installer script to create the CA file and add it to the OS trust store:

```bash
node src/mitm/cert/install.ts

# Or via npm script:

npm run mitm:install-ca

```

By default, this stores the certificate as `omniroute-tproxy-ca.crt` and imports it into the system trust store. To skip automatic trust installation (useful for CI environments), set `OMNIROUTE_SKIP_SYSTEM_TRUST=1` before running the script.

## Step 3: Configure iptables for Traffic Redirection

The [`src/mitm/tproxy/commands.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/commands.ts) module constructs the necessary netfilter rules to redirect incoming traffic. You must create a rule that marks packets destined for your target port (e.g., 443) and redirects them to the local transparent proxy port:

```bash
sudo node -e "require('./src/mitm/tproxy/commands').addRule({
  dport: 443,
  onPort: 8443,
  mark: 0x1
})"

```

This `iptables` rule uses the `TPROXY` target to intercept packets without altering the destination IP, allowing the MITM server to see the original destination through `SO_ORIGINAL_DST`.

## Step 4: Enable TPROXY Capture via the Agent Bridge API

Activate the capture mode by sending a POST request to the Agent Bridge endpoint. The payload specifies the local port to listen on (`onPort`), the destination port to intercept (`dport`), and the packet mark used in iptables:

```bash
curl -X POST http://localhost:20128/api/tools/agent-bridge/tproxy \
  -H 'Content-Type: application/json' \
  -d '{"dport":443,"onPort":8443,"mark":1}'

```

This request is handled by [`src/app/api/v1/tools/agent-bridge/tproxy/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/tools/agent-bridge/tproxy/route.ts), which initializes the capture configuration in [`src/mitm/tproxy/captureMode.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/captureMode.ts).

## Step 5: Start the MITM Server and Verify Traffic

The MITM lifecycle is orchestrated by [`src/mitm/manager.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/manager.ts), which automatically starts when you run the OmniRoute development server:

```bash
npm run dev

```

Once running, the manager initializes a transparent listener through [`src/mitm/tproxy/transparentSocket.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/transparentSocket.ts). This loader resolves the native addon and provides high-level helpers like `createTransparentListenerFd`.

To verify the setup, use a CLI tool that explicitly ignores proxy settings:

```bash
curl -v https://ifconfig.me

```

The request should appear in the OmniRoute inspector under the `"tproxy"` source (as defined in [`src/shared/schemas/inspector.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/schemas/inspector.ts)), with TLS decrypted and HTTP payload visible.

## Step 6: Disable TPROXY and Clean Up

When finished testing, remove the iptables rules and stop the transparent listener by sending a DELETE request to the same endpoint:

```bash
curl -X DELETE http://localhost:20128/api/tools/agent-bridge/tproxy

```

This triggers the cleanup logic in [`src/mitm/tproxy/commands.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/commands.ts) to flush the netfilter rules and releases the transparent socket created by the native addon.

## Summary

Setting up the MITM transparent proxy in OmniRoute requires coordinating several system-level components:

- **Build** the native addon from [`src/mitm/tproxy/native/transparent.c`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/native/transparent.c) using `npm run build:native:tproxy`.
- **Install** the root CA via [`src/mitm/tproxy/cert/install.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/cert/install.ts) to enable TLS decryption.
- **Configure** iptables rules using the helpers in [`src/mitm/tproxy/commands.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/commands.ts) to redirect traffic.
- **Activate** capture mode via POST to `/api/tools/agent-bridge/tproxy` handled by [`src/app/api/v1/tools/agent-bridge/tproxy/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/tools/agent-bridge/tproxy/route.ts).
- **Verify** interception by making HTTPS requests without proxy environment variables set.
- **Clean up** by sending DELETE to the same API endpoint to remove firewall rules.

## Frequently Asked Questions

### Why do CLI tools require a transparent proxy instead of standard proxy settings?

Many command-line tools, programming language runtimes, and compiled binaries ignore the `HTTP_PROXY` and `HTTPS_PROXY` environment variables. The **TPROXY** mode operates at the kernel level by intercepting packets before they reach the application socket, ensuring all outbound TCP traffic is captured regardless of the tool’s proxy configuration.

### What specific privileges are required to run the TPROXY mode?

You must run OmniRoute as **root** or grant the process the `CAP_NET_ADMIN` capability. These permissions are necessary to execute iptables commands, set the `IP_TRANSPARENT` socket option, and bind to privileged ports. Without these capabilities, the call to `createTransparentListener` in the native addon will fail with `EACCES` or `EPERM` errors.

### How do I remove the OmniRoute CA from my system trust store?

The installation script in [`src/mitm/tproxy/cert/install.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/mitm/tproxy/cert/install.ts) typically adds the certificate to the OS-specific trust stores (e.g., `/usr/local/share/ca-certificates/` on Debian/Ubuntu or `/etc/pki/ca-trust/source/anchors/` on RHEL). To remove it, delete the `omniroute-tproxy-ca.crt` file from these directories and run your distribution’s trust update command (such as `sudo update-ca-certificates` or `sudo update-ca-trust`).

### Does the TPROXY capture mode work on macOS or Windows?

No. The TPROXY functionality is **Linux-specific** because it depends on the `IP_TRANSPARENT` socket option and netfilter/iptables, which are kernel features not available on macOS or Windows. Users on other operating systems should use OmniRoute’s standard HTTP/HTTPS proxy modes, which rely on environment variable injection and application-level proxy support.