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

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 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:

npm run build:native:tproxy

This command compiles 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:

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 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:

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:

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, which initializes the capture configuration in src/mitm/tproxy/captureMode.ts.

Step 5: Start the MITM Server and Verify Traffic

The MITM lifecycle is orchestrated by src/mitm/manager.ts, which automatically starts when you run the OmniRoute development server:

npm run dev

Once running, the manager initializes a transparent listener through 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:

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), 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:

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

This triggers the cleanup logic in 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 using npm run build:native:tproxy.
• Install the root CA via src/mitm/tproxy/cert/install.ts to enable TLS decryption.
• Configure iptables rules using the helpers in 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.
• 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 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.

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