Inspect live traffic with Caddy and mitmproxy, no restart

TL;DR: @viaalink/caddy-api-client can send one Caddy route through mitmproxy and back again while Caddy keeps running. You see the exact requests that reach your backend. Watch the walkthrough on YouTube.

Why look at the wire

Many queries are never written down in your code. A search backend builds them from what the user picked: filters, categories, checkboxes, sort order. Reading the code shows you the pieces. It does not show the query that finally reaches Elasticsearch.

The traffic shows exactly that. Put a proxy in the path and read the requests as they happen.

Swap a route at runtime

Caddy’s Admin API can change one route without a reload. The client uses that to put mitmproxy in the path: it removes the direct route by its @id, adds the proxied route with the same @id, and later swaps back.

buildMitmproxyRoutePair builds both routes from one set of options:

import { CaddyClient, buildMitmproxyRoutePair } from "@viaalink/caddy-api-client/caddy";

const client = new CaddyClient({ adminUrl: "http://127.0.0.1:2019" });

const routes = buildMitmproxyRoutePair({
  host: "search.localhost",
  backendHost: "backend",
  backendPort: 3000,
  mitmproxyHost: "mitmproxy",
  routeId: "search_route",
});

// Start with direct routing
await client.addRoute("https_server", routes.direct, routes.direct["@id"]);

// Hot-swap to enable interception (no downtime)
await client.removeRouteById("https_server", routes.direct["@id"]);
await client.addRoute("https_server", routes.proxied, routes.proxied["@id"]);

// Hot-swap back to direct (disable interception)
await client.removeRouteById("https_server", routes.proxied["@id"]);
await client.addRoute("https_server", routes.direct, routes.direct["@id"]);

Caddy keeps running and only that one route changes. The remove and the add are two calls, so there is a short moment in between when the route does not exist. Use this on traffic you can afford to lose for that moment.

What the demo shows

The walkthrough runs a product search behind Caddy, with a backend and Elasticsearch behind it. One click on the search, and the request appears in mitmproxy.

It also shows a bug that the code alone would not reveal. Elasticsearch answers 200 OK with zero hits. The request asks for a field called product_name and the category electronics. An earlier, good response shows that the real documents use name and the category Electronics, with a capital E. The wire shows the mismatch in seconds.

On demand in the Viaalink CLI

If you run your services with the Viaalink CLI, set inspect: true on a service in your Viaalink CLI config. via then routes that service through its own mitmproxy, on demand, so you do not have to wire the swap yourself.

What it works with

The swap works for databases and services that speak HTTP, such as Elasticsearch, OpenSearch, CouchDB and ClickHouse over HTTP. It does not show SQL traffic from Postgres or MySQL over TCP. That is not supported yet.

Run this against development or staging traffic. mitmproxy sees request bodies, and those can contain credentials and personal data.

Get started

• NPM package
• Video: Inspect live traffic with Caddy and mitmproxy