feat: Transparent proxy using wireguard

[jakub-bochenski]

Related to SANDBOX-23

This could replace the current setup or there could be an option to use either explicit or transparent proxy.

The setup is in compose files and related scripts at https://github.com/VirtusLab/sandcat/

You can also see a standalone proxy setup here: https://github.com/Srikanth0824/side-projects/tree/main/mitm_wg

I tried setting up a transparent proxy w/o wireguard but I wasn't able to get DNS to work on a quick try.

I'm no wireguard expert but I expect it could also make it easier to expose outside services to the stack

[mattolson]

We evaluated transparent proxying when designing the current architecture. The explicit proxy + iptables gatekeeper approach was a deliberate choice, documented in ADR 001. Here's the reasoning and where I think it still holds.

The security model is equivalent. With explicit proxy + iptables, tools that ignore HTTP_PROXY hit an iptables REJECT and fail immediately. With transparent proxy, those same tools have their traffic intercepted and policy-checked. In both cases, unauthorized traffic is blocked. The difference is UX, not security: explicit proxy fails the tool, transparent proxy routes it through the policy engine.

The per-tool workaround cost is real but bounded. Honest accounting of what explicit proxying costs us today:

• HTTP_PROXY / HTTPS_PROXY / NO_PROXY env vars in every compose file
• GODEBUG=http2client=0 to work around Go's HTTP/2 header validation through mitmproxy (affects gh CLI)
• configure-apt-proxy.sh runtime script (requires sudo) to write apt proxy config
• JetBrains proxy settings in every devcontainer.json template (proxy_host, proxy_port, proxy_exceptions)
• Proxy CA certificate installation via install-proxy-ca.sh (also requires sudo)

That's five workarounds across compose files, devcontainer templates, Dockerfiles, and runtime scripts. Not catastrophic, but each one is a surface for bugs and a source of confusion when something doesn't honor the proxy and silently fails.

Where transparent proxy has a real edge: DNS. With explicit proxying, DNS resolution happens inside the agent container using Docker's internal resolver. We have no visibility into or control over DNS queries. With mitmproxy's WireGuard mode, DNS queries flow through the tunnel and are visible to the proxy. This matters for a future where we might want to detect DNS-based exfiltration or enforce DNS-level policy.

Where transparent proxy costs more than it's worth right now: WireGuard adds a container, key derivation, tunnel health checks, and a sysctl requirement (net.ipv4.conf.all.src_valid_mark=1). That's a meaningful jump in operational complexity for a local dev tool. Debugging "why can't my tool reach the network" is harder when the traffic path includes a WireGuard tunnel.

My position: not now, but the door is open.

If #105 lands (gateway sidecar with network_mode sharing), the incremental step to transparent proxying shrinks. The gateway container already owns the network namespace. Adding WireGuard routing to it becomes a smaller change that doesn't affect the agent container or its image.

I'd want to approach it as an optional mode rather than a replacement. Some users will prefer the explicit proxy model for its debuggability. Others will want transparent capture for maximum compatibility. The compose layer system we have could support both.

For now, the explicit proxy model works for the agents we support. The tools that matter (curl, git, npm, pip, cargo, Go programs, IDE extensions) all honor proxy env vars. If we hit a case where a supported agent or tool fundamentally can't work with explicit proxying, that changes the priority.

[jakub-bochenski]

re DNS exfiltration: https://github.com/VirtusLab/sandcat/pull/32/changes

[jakub-bochenski]

Transparent proxy would be better for Java, as it ignores the PROXY env variables (not only JetBrains IDE, any Java program)

You can address that with JAVA_TOOL_OPTIONS.
Yet then there is still a case of Maven and Gradle, that want the proxy configured in a settings file

I'd want to approach it as an optional mode rather than a replacement. Some users will prefer the explicit proxy model for its debuggability. Others will want transparent capture for maximum compatibility. The compose layer system we have could support both.

I agree.

I'm wondering if maybe this could be a compose profile instead of a layer. Just thinking out loud here. This setting feels more "operational". Being able to select proxy mode without regenerating/switching configuration could be useful to debug problems