Block Docker gateway addresses in egress proxy by default (#4395)

## Why

Containerized MCP servers can reach host services via `host.docker.internal`,
`gateway.docker.internal`, and the Docker bridge gateway IP (`172.17.0.1`).
This enables lateral movement from a compromised or malicious MCP server to
services running on the host, bypassing the container network boundary.

The existing `insecure_allow_all` permission flag does not protect against this:
users enabling it intend to open general internet access, not necessarily host
access. These are distinct threat surfaces and warrant separate opt-ins.

## What changed

The Squid egress proxy config now emits ACL deny rules for the three Docker
gateway addresses **before** any allow rules. Squid evaluates access control
in first-match-wins order, so placing the deny first ensures it cannot be
bypassed by a subsequent `http_access allow all`.

A new `--allow-docker-gateway` CLI flag (default `false`) provides an explicit
opt-in for the small number of MCP servers that legitimately need host access.
The flag threads through the full call chain:

```
--allow-docker-gateway (run_flags.go)
  → RunConfig.AllowDockerGateway (config.go)
  → runtime.Setup() (setup.go)
  → DeployWorkloadOptions.AllowDockerGateway (types.go)
  → createEgressSquidContainer() (client.go)
  → createTempEgressSquidConf() (squid.go)
```

Generated Squid config with default settings (blocking active):

```squid
acl docker_gateway_hosts dstdomain host.docker.internal gateway.docker.internal
acl docker_gateway_ip dst 172.17.0.1
http_access deny docker_gateway_hosts
http_access deny docker_gateway_ip

http_access allow all   # (or ACL-based allow rules)
http_access deny all
```

Author: tgrunnagle

cmd/thv/app/run_flags.go

@@ -91,7 +91,8 @@ type RunFlags struct {
 	OtelUseLegacyAttributes         bool     // Emit legacy attribute names alongside new ones
 
 	// Network isolation
-	IsolateNetwork bool
+	IsolateNetwork     bool
+	AllowDockerGateway bool
 
 	// Proxy headers
 	TrustProxyHeaders bool
@@ -246,6 +247,9 @@ func AddRunFlags(cmd *cobra.Command, config *RunFlags) {
 
 	cmd.Flags().BoolVar(&config.IsolateNetwork, "isolate-network", false,
 		"Isolate the container network from the host (default false)")
+	cmd.Flags().BoolVar(&config.AllowDockerGateway, "allow-docker-gateway", false,
+		"Allow outbound connections to Docker gateway addresses (host.docker.internal, gateway.docker.internal, 172.17.0.1). "+
+			"Only applies when --isolate-network is set. These are blocked by default even when insecure_allow_all is enabled.")
 	cmd.Flags().BoolVar(&config.TrustProxyHeaders, "trust-proxy-headers", false,
 		"Trust X-Forwarded-* headers from reverse proxies (X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Prefix) "+
 			"(default false)")
@@ -596,6 +600,7 @@ func buildRunnerConfig(
 		runner.WithAuditConfigPath(runFlags.AuditConfig),
 		runner.WithPermissionProfileNameOrPath(runFlags.PermissionProfile),
 		runner.WithNetworkIsolation(runFlags.IsolateNetwork),
+		runner.WithAllowDockerGateway(runFlags.AllowDockerGateway),
 		runner.WithTrustProxyHeaders(runFlags.TrustProxyHeaders),
 		runner.WithEndpointPrefix(runFlags.EndpointPrefix),
 		runner.WithNetworkMode(runFlags.Network),

docs/cli/thv_run.md

@@ -98,6 +98,7 @@ type deployOps interface {
 		exposedPorts map[string]struct{},
 		endpointsConfig map[string]*network.EndpointSettings,
 		perm *permissions.NetworkPermissions,
+		allowDockerGateway bool,
 	) (string, error)
 	createMcpContainer(
 		ctx context.Context,
@@ -165,8 +166,14 @@ func (c *Client) createEgressSquidContainer(
 	exposedPorts map[string]struct{},
 	endpointsConfig map[string]*network.EndpointSettings,
 	perm *permissions.NetworkPermissions,
+	allowDockerGateway bool,
 ) (string, error) {
-	return createEgressSquidContainer(ctx, c, containerName, squidContainerName, attachStdio, exposedPorts, endpointsConfig, perm)
+	gatewayIP := c.getDockerBridgeGatewayIP(ctx)
+	return createEgressSquidContainer(
+		ctx, c, containerName, squidContainerName,
+		attachStdio, exposedPorts, endpointsConfig, perm,
+		allowDockerGateway, gatewayIP,
+	)
 }
 
 // DeployWorkload creates and starts a workload.
@@ -243,6 +250,7 @@ func (c *Client) DeployWorkload(
 
 		// create egress container
 		egressContainerName := fmt.Sprintf("%s-egress", name)
+		allowDockerGateway := options != nil && options.AllowDockerGateway
 		_, err = c.ops.createEgressSquidContainer(
 			ctx,
 			name,
@@ -251,6 +259,7 @@ func (c *Client) DeployWorkload(
 			nil,
 			externalEndpointsConfig,
 			permissionProfile.Network,
+			allowDockerGateway,
 		)
 		if err != nil {
 			return 0, fmt.Errorf("failed to create egress container: %w", err)
@@ -1167,6 +1176,27 @@ func (c *Client) createNetwork(
 	return nil
 }
 
+// getDockerBridgeGatewayIP returns the gateway IP of the Docker default bridge
+// network by inspecting it at runtime. This handles platform differences:
+// Linux Docker Engine uses 172.17.0.1 by default, while Docker Desktop on macOS
+// uses 192.168.65.1 and Colima typically uses 192.168.5.1 or similar. Querying
+// the daemon directly is more accurate than hardcoding platform-specific IPs.
+// Falls back to dockerDefaultBridgeGatewayIP on any error.
+func (c *Client) getDockerBridgeGatewayIP(ctx context.Context) string {
+	nr, err := c.client.NetworkInspect(ctx, "bridge", network.InspectOptions{})
+	if err != nil {
+		slog.Debug("failed to inspect bridge network, using default gateway IP", "error", err)
+		return dockerDefaultBridgeGatewayIP
+	}
+	for _, cfg := range nr.IPAM.Config {
+		if cfg.Gateway != "" {
+			return cfg.Gateway
+		}
+	}
+	slog.Debug("bridge network has no gateway in IPAM config, using default gateway IP")
+	return dockerDefaultBridgeGatewayIP
+}
+
 // DeleteNetwork deletes a network by name.
 func (c *Client) deleteNetwork(ctx context.Context, name string) error {
 	// find the network by name using filter for efficiency but verify exact match

docs/server/docs.go

@@ -31,8 +31,9 @@ type fakeDeployOps struct {
 	dnsID     string
 	dnsIP     string
 
-	egressCalled bool
-	egressID     string
+	egressCalled        bool
+	egressID            string
+	egressAllowDockerGW bool
 
 	ingressCalled bool
 	ingressPort   int
@@ -79,8 +80,9 @@ func (f *fakeDeployOps) createDnsContainer(_ context.Context, _ string, _ bool,
 	return f.dnsID, f.dnsIP, f.errDNS
 }
 
-func (f *fakeDeployOps) createEgressSquidContainer(_ context.Context, _ string, _ string, _ bool, _ map[string]struct{}, _ map[string]*network.EndpointSettings, _ *permissions.NetworkPermissions) (string, error) {
+func (f *fakeDeployOps) createEgressSquidContainer(_ context.Context, _ string, _ string, _ bool, _ map[string]struct{}, _ map[string]*network.EndpointSettings, _ *permissions.NetworkPermissions, allowDockerGateway bool) (string, error) {
 	f.egressCalled = true
+	f.egressAllowDockerGW = allowDockerGateway
 	return f.egressID, f.errEgress
 }
 
@@ -282,6 +284,34 @@ func TestDeployWorkload_NoIsolation_ReturnsPortFromBindingsAndSkipsAuxContainers
 	assert.Equal(t, 56789, hostPort)
 }
 
+func TestDeployWorkload_AllowDockerGateway_ForwardedToEgress(t *testing.T) {
+	t.Parallel()
+
+	fops := &fakeDeployOps{dnsIP: "172.18.0.10"}
+	c := newClientWithOps(fops)
+
+	opts := runtime.NewDeployWorkloadOptions()
+	opts.AttachStdio = true
+	opts.AllowDockerGateway = true
+
+	_, err := c.DeployWorkload(
+		t.Context(),
+		"ghcr.io/example/mcp:latest",
+		"app",
+		[]string{"serve"},
+		map[string]string{},
+		map[string]string{},
+		&permissions.Profile{},
+		"stdio",
+		opts,
+		true, // isolateNetwork required for egress container to be created
+	)
+	require.NoError(t, err)
+
+	require.True(t, fops.egressCalled, "egress container must be created when isolateNetwork=true")
+	assert.True(t, fops.egressAllowDockerGW, "AllowDockerGateway must be forwarded to createEgressSquidContainer")
+}
+
 func TestDeployWorkload_UnsupportedTransport_PropagatesError(t *testing.T) {
 	t.Parallel()
 

docs/server/swagger.json

@@ -21,6 +21,15 @@ import (
 
 const defaultSquidImage = "ghcr.io/stacklok/toolhive/egress-proxy:latest"
 
+// dockerGateway* are Docker-specific addresses that resolve to the host network
+// interface from inside a container. They are blocked by default to prevent
+// containers from reaching host services unintentionally.
+const (
+	dockerGatewayHostname        = "host.docker.internal"
+	dockerAltGatewayHostname     = "gateway.docker.internal"
+	dockerDefaultBridgeGatewayIP = "172.17.0.1"
+)
+
 type proxyDirection int
 
 const (
@@ -69,8 +78,10 @@ func createEgressSquidContainer(
 	exposedPorts map[string]struct{},
 	endpointsConfig map[string]*network.EndpointSettings,
 	perm *permissions.NetworkPermissions,
+	allowDockerGateway bool,
+	gatewayIP string,
 ) (string, error) {
-	squidConfPath, err := createTempEgressSquidConf(perm, containerName)
+	squidConfPath, err := createTempEgressSquidConf(perm, containerName, allowDockerGateway, gatewayIP)
 	if err != nil {
 		return "", fmt.Errorf("failed to create temporary squid.conf: %w", err)
 	}
@@ -173,14 +184,46 @@ func createSquidContainer(
 	return squidContainerId, nil
 }
 
+// writeDockerGatewayDenyRules emits Squid ACL definitions and http_access deny
+// rules that block the Docker gateway addresses. These rules MUST be written
+// before any http_access allow rules: Squid evaluates access control in
+// first-match-wins order, so a deny placed after an allow is never reached.
+//
+// gatewayIP is the bridge network gateway IP resolved at runtime via
+// getDockerBridgeGatewayIP. It differs across platforms: 172.17.0.1 on Linux,
+// 192.168.65.1 on Docker Desktop for macOS, and varies on Colima/Rancher Desktop.
+// dockerGatewayHostname and dockerAltGatewayHostname cover hostname-based access;
+// the dst rule covers direct-IP access that bypasses DNS.
+// Note: gateway.docker.internal is Docker Desktop (macOS) specific; blocking it
+// on Linux is harmless since the name does not resolve there.
+func writeDockerGatewayDenyRules(sb *strings.Builder, gatewayIP string) {
+	sb.WriteString(
+		"# Block Docker gateway addresses — opt in with --allow-docker-gateway\n" +
+			"acl docker_gateway_hosts dstdomain " +
+			dockerGatewayHostname + " " + dockerAltGatewayHostname + "\n" +
+			"acl docker_gateway_ip dst " + gatewayIP + "\n" +
+			"http_access deny docker_gateway_hosts\n" +
+			"http_access deny docker_gateway_ip\n\n",
+	)
+}
+
 func createTempEgressSquidConf(
 	networkPermissions *permissions.NetworkPermissions,
 	serverHostname string,
+	allowDockerGateway bool,
+	gatewayIP string,
 ) (string, error) {
 	var sb strings.Builder
 
 	writeCommonConfig(&sb, serverHostname, proxyEgress)
 
+	// Always block Docker gateway addresses unless the caller explicitly opts
+	// in via --allow-docker-gateway. MUST precede any http_access allow —
+	// Squid is first-match-wins.
+	if !allowDockerGateway {
+		writeDockerGatewayDenyRules(&sb, gatewayIP)
+	}
+
 	if networkPermissions == nil || (networkPermissions.Outbound != nil && networkPermissions.Outbound.InsecureAllowAll) {
 		sb.WriteString("# Allow all traffic\nhttp_access allow all\n")
 	} else {