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

> Learn how OmniRoute's Traffic Inspector captures and replays HTTP/TLS traffic. It uses a MITM proxy to buffer, persist, and export requests for analysis and debugging.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.