How OmniRoute's Traffic Inspector Captures and Replays HTTP/TLS Traffic Using a MITM Proxy

OmniRoute's Traffic Inspector intercepts HTTP and HTTPS traffic through a MITM proxy, buffers requests in memory, persists them to SQLite, and enables replay via HAR export and WebSocket streaming.

OmniRoute (diegosouzapw/OmniRoute) includes a sophisticated Traffic Inspector that acts as a MITM (Man-in-the-Middle) proxy to capture, analyze, and replay HTTP/TLS traffic. This system transparently intercepts requests between your application and upstream providers, storing them in a ring buffer while enabling real-time inspection and post-capture replay through standard HAR formats.

MITM Proxy Architecture and Capture Modes

The Traffic Inspector supports two distinct capture modes that feed into a unified processing pipeline. Both modes terminate TLS when necessary and forward decrypted traffic to the inspector's internal ingestion endpoint.

TPROXY Transparent Mode

src/mitm/tproxy/tlsCapture.ts implements the TPROXY capture mechanism. When TLS decryption is enabled, this module creates a transparent listener that receives raw socket connections, performs TLS termination using dynamically generated per-SNI certificates, and forwards the decrypted HTTP stream to the inspector with the source label "tproxy".

src/mitm/tproxy/captureMode.ts orchestrates the complete workflow by building a dynamic Certificate Authority for each Server Name Indication (SNI), installing it into the system trust store, and starting the transparent listener. This file also defines the capture-state flags used by the inspector to label traffic as either tproxy or http-proxy depending on the interception method.

HTTP Proxy Mode

src/mitm/manager.ts serves as the central coordinator. It starts the MITM server, configures the HTTP-forwarding proxy, and manages system-proxy settings. Crucially, the manager injects an inspector ingest token into the proxy configuration, ensuring that all captured traffic is securely forwarded to the inspector's internal ingestion endpoint at /api/tools/traffic-inspector/internal/ingest.

The HTTP Proxy Capture Hook

At the heart of the capture mechanism lies src/mitm/inspector/httpProxyServer.ts. This module implements the core interception logic that sits between client applications and upstream providers.

When a request arrives, the proxy:

1. Forwards the request to the upstream provider using fetch()
2. Captures request metadata including method, URL, headers, and body
3. Captures response metadata including status code, headers, and body
4. Packages the complete exchange as an InterceptedRequest object
5. Hands the object to the inspector buffer for processing

src/mitm/inspector/diagnostics.ts provides complementary functionality by capturing diagnostic information when connections fail—such as missing CA certificates or DNS misconfigurations—storing this troubleshooting data alongside the captured request for later analysis.

Traffic Buffering and Session Management

Once captured, traffic flows through a sophisticated buffering system that balances real-time performance with persistent storage.

In-Memory Ring Buffer

src/mitm/inspector/buffer.ts implements the TrafficBuffer class—a ring buffer that holds up to INSPECTOR_BUFFER_SIZE entries (default 1000). The buffer processes each InterceptedRequest through four stages:

• Kind detection (detectKind): Identifies whether the traffic represents an LLM API call, custom host communication, or other protocol types
• Context-key fingerprinting (computeContextKey): Generates deterministic identifiers for the request's logical context to group related transactions
• Body truncation: Enforces INSPECTOR_MAX_BODY_KB limits to prevent excessive memory consumption
• Event broadcasting: Emits a new event to all WebSocket subscribers, enabling the dashboard UI to update in real time

src/mitm/inspector/types.ts defines the InterceptedRequest interface, specifying fields such as method, host, status, detectedKind, source, and optional sessionId for request grouping.

Persistent SQLite Storage

src/lib/db/inspectorSessions.ts persists each captured request in the SQLite inspector_sessions table. Sessions receive unique UUID identifiers and support full CRUD operations through the API, allowing users to query, filter, or delete historical capture data.

src/lib/db/inspectorCustomHosts.ts manages DNS spoofing entries that enable the proxy to intercept traffic destined for non-public endpoints, a prerequisite for capturing requests to internal development servers or custom API gateways.

Real-Time Streaming and API Endpoints

The Traffic Inspector exposes a comprehensive REST and WebSocket API under the /api/tools/traffic-inspector namespace, protected by a LOCAL_ONLY policy that restricts access to the local OmniRoute process and dashboard UI.

Key endpoints include:

• /ws: WebSocket connection streaming live buffer events (new, update, delete) to connected dashboard clients
• /sessions (POST): Creates new capture sessions for optional request grouping
• /sessions/:id (GET/DELETE): Retrieves or deletes stored session data
• /sessions/:id/export.har (GET): Exports captured traffic as HTTP Archive (HAR) files compatible with browser DevTools and testing frameworks
• /internal/ingest (POST): Internal endpoint receiving InterceptedRequest objects from the MITM proxy components

Replaying Traffic with HAR Export

Replay functionality centers on the HAR (HTTP Archive) format, enabling interoperability with standard debugging tools.

src/lib/inspector/harExport.ts walks the SQLite inspector_sessions table and assembles a complete HAR object containing request/response headers, bodies (respecting truncation limits), and timing data. The generated HAR files can be imported directly into Chrome DevTools, Postman, or any HAR-compatible replay tool.

The OmniRoute dashboard provides a "Replay" button that fetches the HAR export and executes the stored requests against selected providers, enabling developers to debug model behavior or validate routing configurations using historical traffic patterns.

Security and Privacy Considerations

Before storage, src/mitm/maskSecrets.ts processes request bodies to mask sensitive information such as API keys and authentication tokens. The inspector ingest token remains scoped strictly to the local process, ensuring that captured traffic cannot be intercepted by external network actors even when the MITM proxy is active.

Summary

• OmniRoute's Traffic Inspector uses a MITM proxy architecture with both TPROXY transparent mode and explicit HTTP proxy mode to intercept HTTP/TLS traffic
• src/mitm/inspector/httpProxyServer.ts captures full request/response exchanges and forwards them to an in-memory ring buffer (TrafficBuffer) and SQLite persistence layer
• Real-time inspection occurs via WebSocket streams at /api/tools/traffic-inspector/ws, while historical analysis uses HAR exports from /sessions/:id/export.har
• The system handles TLS termination through dynamically generated per-SNI certificates managed in src/mitm/tproxy/captureMode.ts
• Security controls including body truncation, secret masking, and local-only API policies protect sensitive data during capture and storage

Frequently Asked Questions

How does OmniRoute handle TLS decryption without breaking certificate validation?

OmniRoute generates a dynamic Certificate Authority for each Server Name Indication (SNI) encountered, as implemented in src/mitm/tproxy/captureMode.ts. The system installs this CA into the local trust store, allowing the proxy to terminate TLS and inspect the decrypted HTTP stream while presenting a valid certificate chain to the client application. This transparent proxy approach requires either TPROXY network configuration or explicit HTTP proxy settings on the client.

What is the maximum number of requests the Traffic Inspector can buffer?

The in-memory ring buffer defined in src/mitm/inspector/buffer.ts stores up to INSPECTOR_BUFFER_SIZE entries (defaulting to 1000 requests). When the buffer reaches capacity, new entries overwrite the oldest ones. For long-term storage, the system persists all captured requests to the SQLite inspector_sessions table via src/lib/db/inspectorSessions.ts, which is limited only by available disk space.

Can I replay captured traffic against different LLM providers?

Yes. The Traffic Inspector exports captured sessions as HAR files using src/lib/inspector/harExport.ts, which standardizes the request format for interoperability. You can import these HAR files into API testing tools like Postman or use OmniRoute's dashboard "Replay" feature to execute historical requests against alternative providers, making it useful for testing model behavior across different routing configurations.

How does the Traffic Inspector protect sensitive data in request bodies?

Before storage and broadcasting, captured traffic passes through src/mitm/maskSecrets.ts, which identifies and redacts sensitive fields such as API keys, authentication tokens, and authorization headers. Additionally, the system enforces INSPECTOR_MAX_BODY_KB limits during buffering to prevent accidental logging of large binary payloads or excessive memory usage.

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