stacklok / stacklok/toolhive

Envoy Proxy: Explore transparent L3/L4 interception via Envoy TPROXY

Open
#5,947 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement p2
Dominant language
Go
Stars
2.2k
Forks
300
Avg merge
1d 15h
Merged PRs (30d)
184

Description

Goal

Non-cooperative egress (workloads that ignore HTTP_PROXY) is currently contained only by the Internal: true Docker network blackhole. Transparent L3/L4 interception would make enforcement non-bypassable: all TCP traffic — including from workloads that never read HTTP_PROXY — is redirected through Envoy.

Why this matters

  • Eliminates the cooperative-proxy assumption entirely.
  • Enables per-flow policy enforcement (host, port, protocol) for any TCP connection, not just HTTP/HTTPS.
  • Is the path to dropping the dnsmasq container (DNS port 53 can also be intercepted).

Approach (sketch only)

  • Init container with CAP_NET_ADMIN installs iptables REDIRECT/TPROXY rules in the workload's network namespace, then exits. The workload container never holds NET_ADMIN.
  • Envoy original_dst listener receives redirected connections and applies policy.
  • The Internal: true blackhole is retained as the fail-closed backstop even if rule installation fails.

Open questions (must be resolved in a design doc before implementation)

  • How to install netns rules without granting the workload NET_ADMIN under plain Docker (no Kubernetes).
  • Behaviour of original_dst/TPROXY inside the Docker Desktop LinuxKit VM and Colima/Rancher Desktop VMs.
  • Whether DNS (port 53) must also be redirected, and how dnsmasq interacts with TPROXY.
  • xt_TPROXY kernel module availability on CI runners and Docker Desktop VMs.

Gate

A docs/arch/ design doc, human architect sign-off, and per-platform validation are required before any code is written. This issue is a placeholder and exploration tracker, not an implementation ticket.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the issue's open questions on namespace rule installation, Docker Desktop and Colima/Rancher Desktop behavior, DNS interception, and xt_TPROXY availability. Document the findings in docs/arch/, then obtain human architect sign-off and per-platform validation; no code should be written until those gates are complete.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker
Domain
infrastructure, networking, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.