feat(api): SOCKS5 egress proxy on sandbox network config (BYOP) (#2642)

Sandboxes have two related egress problems we cannot solve from our
side: operators want a predictable egress identity (their public IP,
not ours), and they want sandboxes to reach hosts that are reachable
from their own proxy server — corporate networks, VPN endpoints,
internal LAN. This PR adds Bring-Your-Own-Proxy: an optional
`egressProxy: {address, username, password}` on the sandbox network
config tunnels all sandbox TCP egress through a user-supplied SOCKS5
server, with our allow/deny rules still applied before the tunnel.

Scope here is the API + orchestrator plumbing: OpenAPI, DB types,
proto, the API create/get handlers (password omitted from GET), the
`BYOPProxyEnabledFlag` LD gate, and a validator that rejects a SOCKS5
endpoint pointing at our own infra at create time and re-checks on
every dial (DNS-rebind guard). For BYOP-enabled sandboxes only, the
sandbox-netns kernel firewall is narrowed on demand so TCP destined
for the user's internal networks reaches the userspace egress proxy
instead of being dropped — without this the user's LAN destinations
would never make it past the kernel. Non-BYOP sandboxes keep the
existing hard kernel drop.

---------

Co-authored-by: Jakub Novák <jakub@e2b.dev>

Author: arkamar

packages/api/internal/api/api.gen.go

@@ -200,6 +200,32 @@ func (a *APIStore) PostSandboxes(c *gin.Context) {
 			},
 		}
 
+		if ep := n.EgressProxy; ep != nil {
+			if !a.featureFlags.BoolFlag(ctx, featureflags.BYOPProxyEnabledFlag) {
+				telemetry.ReportEvent(ctx, "egressProxy rejected by BYOPProxyEnabledFlag")
+				a.sendAPIStoreError(c, http.StatusForbidden,
+					"Egress proxy (network.egressProxy) is not enabled for this team.")
+
+				return
+			}
+
+			canonical, err := sandbox_network.ValidateEgressProxy(ctx, &sandbox_network.EgressProxyConfig{
+				Address:  ep.Address,
+				Username: sharedUtils.DerefOrDefault(ep.Username, ""),
+				Password: sharedUtils.DerefOrDefault(ep.Password, ""),
+			}, nil)
+			if err != nil {
+				telemetry.ReportError(ctx, "invalid egress proxy config", err, telemetry.WithSandboxID(sandboxID))
+				a.sendAPIStoreError(c, http.StatusBadRequest, fmt.Sprintf("Invalid egress proxy config: %s", err))
+
+				return
+			}
+
+			network.Egress.EgressProxyAddress = canonical.Address
+			network.Egress.EgressProxyUsername = canonical.Username
+			network.Egress.EgressProxyPassword = canonical.Password
+		}
+
 		// Make sure envd seucre access is enforced when public access is disabled,
 		// This requirement forces users using newer features to secure sandboxes properly.
 		if !sharedUtils.DerefOrDefault(network.Ingress.AllowPublicAccess, types.AllowPublicAccessDefault) && envdAccessToken == nil {

packages/api/internal/handlers/sandbox_create.go

@@ -74,6 +74,18 @@ func dbNetworkConfigToAPI(network *dbtypes.SandboxNetworkConfig) *api.SandboxNet
 			}
 			result.Rules = &apiRules
 		}
+
+		// Password is omitted so credentials never leak via GET.
+		if egress.EgressProxyAddress != "" {
+			proxyCfg := &api.SandboxEgressProxyConfig{
+				Address: egress.EgressProxyAddress,
+			}
+			if egress.EgressProxyUsername != "" {
+				username := egress.EgressProxyUsername
+				proxyCfg.Username = &username
+			}
+			result.EgressProxy = proxyCfg
+		}
 	}
 
 	return result

packages/api/internal/handlers/sandbox_get.go

@@ -11,8 +11,11 @@ import (
 	"github.com/e2b-dev/infra/packages/api/internal/sandbox"
 	"github.com/e2b-dev/infra/packages/api/internal/utils"
 	"github.com/e2b-dev/infra/packages/auth/pkg/auth"
+	"github.com/e2b-dev/infra/packages/shared/pkg/featureflags"
 	"github.com/e2b-dev/infra/packages/shared/pkg/ginutils"
+	sandbox_network "github.com/e2b-dev/infra/packages/shared/pkg/sandbox-network"
 	"github.com/e2b-dev/infra/packages/shared/pkg/telemetry"
+	sharedUtils "github.com/e2b-dev/infra/packages/shared/pkg/utils"
 )
 
 func (a *APIStore) PutSandboxesSandboxIDNetwork(c *gin.Context, sandboxID string) {
@@ -52,6 +55,31 @@ func (a *APIStore) PutSandboxesSandboxIDNetwork(c *gin.Context, sandboxID string
 		return
 	}
 
+	var egressProxy *sandbox_network.EgressProxyConfig
+	if ep := body.EgressProxy; ep != nil {
+		if !a.featureFlags.BoolFlag(ctx, featureflags.BYOPProxyEnabledFlag) {
+			telemetry.ReportEvent(ctx, "egressProxy update rejected by BYOPProxyEnabledFlag")
+			a.sendAPIStoreError(c, http.StatusForbidden,
+				"Egress proxy (egressProxy) is not enabled for this team.")
+
+			return
+		}
+
+		canonical, err := sandbox_network.ValidateEgressProxy(ctx, &sandbox_network.EgressProxyConfig{
+			Address:  ep.Address,
+			Username: sharedUtils.DerefOrDefault(ep.Username, ""),
+			Password: sharedUtils.DerefOrDefault(ep.Password, ""),
+		}, nil)
+		if err != nil {
+			telemetry.ReportError(ctx, "invalid egress proxy config", err)
+			a.sendAPIStoreError(c, http.StatusBadRequest, fmt.Sprintf("Invalid egress proxy config: %s", err))
+
+			return
+		}
+
+		egressProxy = canonical
+	}
+
 	if body.Rules != nil {
 		sbxInfo, err := a.orchestrator.GetSandbox(ctx, teamID, sandboxID)
 		if err != nil {
@@ -74,7 +102,7 @@ func (a *APIStore) PutSandboxesSandboxIDNetwork(c *gin.Context, sandboxID string
 
 	rules := apiRulesToDBRules(body.Rules)
 
-	if apiErr := a.orchestrator.UpdateSandboxNetworkConfig(ctx, teamID, sandboxID, allowedEntries, deniedEntries, rules, body.AllowInternetAccess); apiErr != nil {
+	if apiErr := a.orchestrator.UpdateSandboxNetworkConfig(ctx, teamID, sandboxID, allowedEntries, deniedEntries, rules, body.AllowInternetAccess, egressProxy); apiErr != nil {
 		telemetry.ReportErrorByCode(ctx, apiErr.Code, "error updating sandbox network config", apiErr.Err)
 		a.sendAPIStoreError(c, apiErr.Code, apiErr.ClientMsg)
 

packages/api/internal/handlers/sandbox_network_update.go

@@ -89,6 +89,16 @@ func buildEgressConfig(allowedEntries, deniedEntries []string, rules map[string]
 	}
 }
 
+// applyEgressProxy copies BYOP SOCKS5 fields from src to dst. No-op on nil.
+func applyEgressProxy(dst *orchestrator.SandboxNetworkEgressConfig, src *types.SandboxNetworkEgressConfig) {
+	if dst == nil || src == nil {
+		return
+	}
+	dst.EgressProxyAddress = src.EgressProxyAddress
+	dst.EgressProxyUsername = src.EgressProxyUsername
+	dst.EgressProxyPassword = src.EgressProxyPassword
+}
+
 // buildNetworkConfig constructs the orchestrator network configuration from the input parameters
 func buildNetworkConfig(network *types.SandboxNetworkConfig, allowInternetAccess *bool, trafficAccessToken *string) *orchestrator.SandboxNetworkConfig {
 	orchNetwork := &orchestrator.SandboxNetworkConfig{
@@ -99,7 +109,9 @@ func buildNetworkConfig(network *types.SandboxNetworkConfig, allowInternetAccess
 	}
 
 	if network != nil && network.Egress != nil {
-		orchNetwork.Egress = buildEgressConfig(network.Egress.AllowedAddresses, network.Egress.DeniedAddresses, network.Egress.Rules)
+		egress := buildEgressConfig(network.Egress.AllowedAddresses, network.Egress.DeniedAddresses, network.Egress.Rules)
+		applyEgressProxy(egress, network.Egress)
+		orchNetwork.Egress = egress
 	}
 
 	if network != nil && network.Ingress != nil {

packages/api/internal/orchestrator/create_instance.go

@@ -17,6 +17,7 @@ import (
 	"github.com/e2b-dev/infra/packages/api/internal/utils"
 	"github.com/e2b-dev/infra/packages/db/pkg/types"
 	orchestratorgrpc "github.com/e2b-dev/infra/packages/shared/pkg/grpc/orchestrator"
+	sandbox_network "github.com/e2b-dev/infra/packages/shared/pkg/sandbox-network"
 	"github.com/e2b-dev/infra/packages/shared/pkg/telemetry"
 )
 
@@ -28,14 +29,20 @@ func (o *Orchestrator) UpdateSandboxNetworkConfig(
 	deniedEntries []string,
 	rules map[string][]types.SandboxNetworkRule,
 	allowInternetAccess *bool,
+	egressProxy *sandbox_network.EgressProxyConfig,
 ) *api.APIError {
-	network := &types.SandboxNetworkConfig{
-		Egress: &types.SandboxNetworkEgressConfig{
-			AllowedAddresses: allowedEntries,
-			DeniedAddresses:  deniedEntries,
-			Rules:            rules,
-		},
+	// PUT is full-replace: omitting egressProxy clears BYOP.
+	egressConfig := &types.SandboxNetworkEgressConfig{
+		AllowedAddresses: allowedEntries,
+		DeniedAddresses:  deniedEntries,
+		Rules:            rules,
 	}
+	if egressProxy != nil {
+		egressConfig.EgressProxyAddress = egressProxy.Address
+		egressConfig.EgressProxyUsername = egressProxy.Username
+		egressConfig.EgressProxyPassword = egressProxy.Password
+	}
+	network := &types.SandboxNetworkConfig{Egress: egressConfig}
 	orchNetwork := buildNetworkConfig(network, allowInternetAccess, nil)
 	egress := orchNetwork.GetEgress()
 
@@ -48,11 +55,7 @@ func (o *Orchestrator) UpdateSandboxNetworkConfig(
 			sbx.Network = &types.SandboxNetworkConfig{}
 		}
 
-		sbx.Network.Egress = &types.SandboxNetworkEgressConfig{
-			AllowedAddresses: allowedEntries,
-			DeniedAddresses:  deniedEntries,
-			Rules:            rules,
-		}
+		sbx.Network.Egress = egressConfig
 
 		if allowInternetAccess != nil {
 			sbx.AllowInternetAccess = allowInternetAccess

packages/api/internal/orchestrator/update_network.go

@@ -75,6 +75,11 @@ type SandboxNetworkEgressConfig struct {
 	AllowedAddresses []string                        `json:"allowedAddresses,omitempty"`
 	DeniedAddresses  []string                        `json:"deniedAddresses,omitempty"`
 	Rules            map[string][]SandboxNetworkRule `json:"rules,omitempty"`
+
+	// SOCKS5 BYOP egress proxy configuration.
+	EgressProxyAddress  string `json:"egressProxyAddress,omitempty"`
+	EgressProxyUsername string `json:"egressProxyUsername,omitempty"`
+	EgressProxyPassword string `json:"egressProxyPassword,omitempty"`
 }
 
 const AllowPublicAccessDefault = true

packages/db/pkg/types/types.go

@@ -78,6 +78,16 @@ services:
     ports:
       - "6379:6379"
 
+  socks5:
+    image: python:3.12-alpine
+    command: >-
+      sh -c "pip install --quiet pproxy &&
+      exec python -u -m pproxy
+      -l socks5://0.0.0.0:1080#byopuser:byoppass
+      -v"
+    ports:
+      - "1080:1080"
+
   tempo:
     image: grafana/tempo:2.8.2
     command: [ "-config.file=/etc/tempo.yaml" ]

packages/local-dev/docker-compose.yaml

@@ -89,6 +89,11 @@ message SandboxNetworkEgressConfig {
   repeated string denied_cidrs = 2;
   repeated string allowed_domains = 3;
   map<string, SandboxNetworkDomainRules> rules = 4;
+
+  // BYOP SOCKS5 egress proxy.
+  string egress_proxy_address = 5;
+  string egress_proxy_username = 6;
+  string egress_proxy_password = 7;
 }
 
 message SandboxNetworkIngressConfig {

packages/orchestrator/orchestrator.proto

@@ -26,6 +26,7 @@ type mockEgressProxy struct {
 func (m *mockEgressProxy) OnSlotCreate(_ *network.Slot, _ *iptables.IPTables) error { return nil }
 func (m *mockEgressProxy) OnSlotDelete(_ *network.Slot, _ *iptables.IPTables) error { return nil }
 func (m *mockEgressProxy) CABundle() string                                         { return m.bundle }
+func (m *mockEgressProxy) SupportsBYOP() bool                                       { return false }
 
 // newTestSandboxWithBundle builds a minimal Sandbox with CABundle set —
 // mirroring what Factory.CreateSandbox does with f.egressProxy.CABundle().