Observe Mode: Safe Configuration for Selective MITM

The Fear of the Transparent Proxy

Deploying a security gateway that relies on transparent TLS interception (MITM) carries an inherent risk. If the policy is wrong, developer workflows break immediately. When kubectl exec or a production deployment pipeline hangs because of an untested gateway rule, the natural response is to uninstall the proxy.

Iddio solves this with Observe Mode. Instead of guessing how policy behaves in production, the gateway provides a mechanism to safely intercept traffic, classify it, evaluate policy, and record what would have happened—all while guaranteeing the traffic continues to its destination.

Intercepting Without Dropping

At its core, Observe Mode alters the standard proxy pipeline. In a regular enforcement state, if a policy dictates a deny action for a specific kubectl or gcloud request, the proxy terminates the connection and returns a synthetic 403 response.

When Observe Mode is active, the request still flows through the standard classifier and policy engine, which still arrive at the deny decision. But before that decision is enacted, the observe session intervenes: the request is allowed through to the upstream server, and the original "would-be" decision is written as an observe record to the session log (observe.jsonl), alongside the lifecycle markers the audit log keeps.

This provides an exact preview of the policy impact. The developer experiences zero disruption, but the security operator sees exactly which rules fired.

Safely Capturing Context for Rule Authoring

Understanding why a rule fired requires context. Observe Mode captures up to 4 KB of the request and response bodies, along with relevant headers. This data is critical for writing specific, targeted rules—for example, knowing exactly which GraphQL mutation a CLI tool invoked.

However, capturing payload data introduces a new risk: logging sensitive credentials or PII. To mitigate this, the proxy implements an inline redaction engine.

The redactor processes every captured body through two distinct phases before it hits the disk:

1. Known Patterns: It scans for common secrets using default regex patterns (AWS access keys, GitHub PATs, Google API keys, Slack tokens, JWTs).
2. High Entropy Detection: It applies a Shannon entropy check to identify and mask strings that look suspiciously random (runs of 64 characters or more with entropy above 4.0 bits per character).

Furthermore, the proxy automatically strips sensitive headers like Authorization and Cookie, and bypasses body capture entirely for binary content types like octet-stream or application/grpc.

Expanding the Interception Radius

By default, Iddio only intercepts traffic explicitly listed in the policy's inspect list. Everything else is spliced through as raw TCP, invisible to the policy engine.

To widen the radius, add a wildcard ("*") to the policy's generic.inspect list. Every host then matches the policy, so the proxy intercepts everything, classifying it and running policy as usual — with any deny overridden to allow, like every other observe decision. (Hosts known to use certificate pinning are still spliced through rather than intercepted, so nothing breaks.) This generates a pure record of what the developer's tools are doing, allowing operators to discover new endpoints that might require policy coverage. Hosts that match no inspect route remain a transparent tunnel and leave no record at all.

Guardrails for the Observer

Observe Mode is not intended to be a permanent state. Every observe session is explicitly time-boxed: the caller picks a duration up front (the default is 30 minutes), and a sweeper automatically expires the session when it elapses — transitioning the proxy back to its standard enforcement posture and writing an expiry record to the audit log.

By combining non-disruptive interception, safe payload capture, and automatic expiration, Observe Mode allows security teams to confidently tune and deploy transparent proxy rules in live developer environments.