qa: add RADIANCE_OUTBOUND_SOCKS_ADDRESS for whole-process residential egress

When this env var is set, every outbound connection radiance opens is
routed through that SOCKS5 server. Intended for censorship-circumvention
QA: pair with `pinger bridge --country ru` so the API request, sing-box
tunnel dials, and the bypass dialer all egress through a residential
proxy in the chosen country, simulating a real client there.

  * common/env: new key OutboundSocksAddress.
  * kindling/client: when set, swap kindling's stacked transport for a
    plain http.Transport whose DialContext goes via SOCKS5. Kindling's
    fronted/AMP/dnstt circumvention paths are skipped (kindling lacks a
    generic dialer override) — see comment.
  * vpn/boxoptions: append a SOCKS5 outbound and walk every leaf outbound
    setting DialerOptions.Detour to it; selector/urltest/block/dns are
    left alone (they don't dial directly).
  * bypass/bypass: route DialContext through SOCKS5 instead of the
    local-bypass-proxy / direct-fallback chain.
  * telemetry/otel: skip OTLP gRPC init in this mode — the gRPC exporter
    can't be routed via http.Transport.DialContext, so leaving it would
    leak the test process's real IP.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Adam Fisk

bypass/bypass.go

@@ -8,8 +8,12 @@ import (
 	"net"
 	"net/http"
 	"net/url"
+	"sync"
 	"time"
 
+	"golang.org/x/net/proxy"
+
+	"github.com/getlantern/radiance/common/env"
 	"github.com/getlantern/radiance/log"
 )
 
@@ -36,7 +40,14 @@ const (
 
 // DialContext tries to connect through the local bypass proxy. If the proxy is
 // not reachable (VPN not running), it falls back to a direct dial.
+//
+// QA: when env.OutboundSocksAddress is set, both the bypass-proxy path and the
+// direct-fallback path are replaced by a dial through that upstream SOCKS5,
+// so every dial out of radiance goes via the same residential egress.
 func DialContext(ctx context.Context, network, addr string) (net.Conn, error) {
+	if d, ok := outboundSocksDialer(); ok {
+		return d.DialContext(ctx, network, addr)
+	}
 	dialer := &net.Dialer{
 		Timeout:   dialTimeout,
 		KeepAlive: dialKeepAlive,
@@ -54,6 +65,31 @@ func DialContext(ctx context.Context, network, addr string) (net.Conn, error) {
 	return tunnelConn, nil
 }
 
+var (
+	outboundSocksOnce   sync.Once
+	outboundSocksDialFn proxy.ContextDialer
+)
+
+// outboundSocksDialer returns a SOCKS5 ContextDialer for env.OutboundSocksAddress
+// if set, cached after the first successful build.
+func outboundSocksDialer() (proxy.ContextDialer, bool) {
+	outboundSocksOnce.Do(func() {
+		addr, ok := env.Get(env.OutboundSocksAddress)
+		if !ok || addr == "" {
+			return
+		}
+		d, err := proxy.SOCKS5("tcp", addr, nil, proxy.Direct)
+		if err != nil {
+			slog.Error("invalid RADIANCE_OUTBOUND_SOCKS_ADDRESS for bypass dialer", slog.Any("error", err), slog.String("addr", addr))
+			return
+		}
+		if cd, ok := d.(proxy.ContextDialer); ok {
+			outboundSocksDialFn = cd
+		}
+	})
+	return outboundSocksDialFn, outboundSocksDialFn != nil
+}
+
 // Dial is a convenience wrapper without context, suitable for use with
 // amp.WithDialer which expects func(network, addr string) (net.Conn, error).
 func Dial(network, addr string) (net.Conn, error) {

common/env/env.go

@@ -26,6 +26,14 @@ var (
 	ENV              _key = "RADIANCE_ENV"
 	UseSocks         _key = "RADIANCE_USE_SOCKS_PROXY"
 	SocksAddress     _key = "RADIANCE_SOCKS_ADDRESS"
+	// OutboundSocksAddress, when set to host:port of a SOCKS5 server, routes
+	// every outbound connection that radiance opens (kindling HTTP client,
+	// sing-box outbound tunnel dials, the bypass dialer) through that server.
+	// Distinct from SocksAddress, which sets up an inbound listener for other
+	// apps to use radiance as a SOCKS proxy. Intended for censorship-
+	// circumvention QA — point it at a SOCKS server that egresses through a
+	// residential proxy in the country we want to simulate.
+	OutboundSocksAddress _key = "RADIANCE_OUTBOUND_SOCKS_ADDRESS"
 	Country          _key = "RADIANCE_COUNTRY"
 	FeatureOverrides _key = "RADIANCE_FEATURE_OVERRIDES"
 	AppVersion       _key = "RADIANCE_VERSION"

kindling/client.go

@@ -4,7 +4,9 @@ package kindling
 
 import (
 	"context"
+	"fmt"
 	"log/slog"
+	"net"
 	"net/http"
 	"path/filepath"
 	"strings"
@@ -14,8 +16,10 @@ import (
 	"go.opentelemetry.io/otel"
 	"go.opentelemetry.io/otel/attribute"
 	"go.opentelemetry.io/otel/trace"
+	"golang.org/x/net/proxy"
 
 	"github.com/getlantern/radiance/common"
+	"github.com/getlantern/radiance/common/env"
 	"github.com/getlantern/radiance/common/reporting"
 	"github.com/getlantern/radiance/common/settings"
 	"github.com/getlantern/radiance/kindling/dnstt"
@@ -44,6 +48,24 @@ var (
 // initKindling initializes the package-level kindling instance and shared
 // transport.
 func initKindling() {
+	// Censorship-circumvention QA path: when OutboundSocksAddress is set,
+	// every outbound HTTP dial goes through that SOCKS5 server. Kindling's
+	// stacked transports (fronted/AMP/dnstt/proxyless) are skipped — the
+	// SOCKS5 is providing egress, and kindling's per-transport internal
+	// dialers don't expose an override hook today. As a result, when this
+	// var is set we are testing "does the bandit/tunnel path work given a
+	// reachable API channel" rather than the full anti-censorship stack.
+	if addr, ok := env.Get(env.OutboundSocksAddress); ok && addr != "" {
+		t, err := socksOnlyTransport(addr)
+		if err != nil {
+			slog.Error("invalid RADIANCE_OUTBOUND_SOCKS_ADDRESS, falling back to default transport", slog.Any("error", err))
+			transport = traces.NewRoundTripper(traces.NewHeaderAnnotatingRoundTripper(defaultTransportClone))
+			return
+		}
+		slog.Info("RADIANCE_OUTBOUND_SOCKS_ADDRESS set — routing all radiance HTTP through upstream SOCKS5", slog.String("addr", addr))
+		transport = traces.NewRoundTripper(traces.NewHeaderAnnotatingRoundTripper(t))
+		return
+	}
 	newK, err := NewKindling(settings.GetString(settings.DataPathKey))
 	if err != nil {
 		slog.Error("failed to create kindling client", slog.Any("error", err))
@@ -57,6 +79,28 @@ func initKindling() {
 	}
 }
 
+// socksOnlyTransport returns an http.Transport that dials through the given
+// SOCKS5 server for every connection.
+func socksOnlyTransport(socksAddr string) (*http.Transport, error) {
+	d, err := proxy.SOCKS5("tcp", socksAddr, nil, proxy.Direct)
+	if err != nil {
+		return nil, fmt.Errorf("building SOCKS5 dialer for %s: %w", socksAddr, err)
+	}
+	ctxDialer, ok := d.(proxy.ContextDialer)
+	if !ok {
+		return nil, fmt.Errorf("SOCKS5 dialer does not support context")
+	}
+	t := defaultTransportClone.Clone()
+	t.DialContext = func(ctx context.Context, network, address string) (net.Conn, error) {
+		return ctxDialer.DialContext(ctx, network, address)
+	}
+	// Disable HTTP_PROXY env-based proxying — we route via DialContext instead.
+	// (x/net/proxy's SOCKS5 sends the hostname to the upstream as ATYP=domain,
+	// so DNS resolution also happens at the SOCKS5 server, no local leak.)
+	t.Proxy = nil
+	return t, nil
+}
+
 func Init() {
 	go initOnce.Do(initKindling)
 }

telemetry/otel.go

@@ -78,6 +78,15 @@ func Initialize(deviceID string, configResponse config.Config, pro bool) error {
 		return nil
 	}
 
+	// QA: when env.OutboundSocksAddress is set, the OTLP gRPC exporters do
+	// NOT honor the radiance dialer override and would phone home directly,
+	// leaking the test process's real IP and bypassing the SOCKS5 egress.
+	// Skip telemetry init in that mode.
+	if addr, ok := env.Get(env.OutboundSocksAddress); ok && addr != "" {
+		slog.Info("RADIANCE_OUTBOUND_SOCKS_ADDRESS set — skipping OpenTelemetry init (gRPC exporters cannot be routed via SOCKS5)", "addr", addr)
+		return nil
+	}
+
 	if shutdownOTEL != nil {
 		slog.Info("Shutting down existing OpenTelemetry SDK")
 		if err := shutdownOTEL(context.Background()); err != nil {

vpn/boxoptions.go

@@ -7,6 +7,7 @@ import (
 	"errors"
 	"fmt"
 	"log/slog"
+	"net"
 	"net/netip"
 	"path/filepath"
 	"slices"
@@ -331,6 +332,13 @@ func buildOptions(bOptions BoxOptions) (O.Options, error) {
 
 	tags := mergeAndCollectTags(&opts, &bOptions.Options)
 
+	// QA: route every leaf outbound through an upstream SOCKS5 (e.g. one that
+	// egresses through a residential proxy in the country we want to simulate)
+	// before reaching its real destination. See env.OutboundSocksAddress.
+	if err := applyOutboundSocksDetour(&opts); err != nil {
+		return O.Options{}, err
+	}
+
 	// add mode selector outbounds and rules
 	opts.Outbounds = append(opts.Outbounds, urlTestOutbound(AutoSelectTag, tags, bOptions.BanditURLOverrides))
 	opts.Outbounds = append(opts.Outbounds, selectorOutbound(ManualSelectTag, tags))
@@ -372,6 +380,60 @@ func writeBoxOptions(path string, opts O.Options) []byte {
 // Helper functions //
 //////////////////////
 
+// devOutboundSocksTag is the tag of the synthetic SOCKS5 outbound injected
+// when env.OutboundSocksAddress is set. Other outbounds get DialerOptions.Detour
+// pointing at this tag, so every real dial is wrapped in a SOCKS5 connection.
+const devOutboundSocksTag = "_dev_outbound_socks"
+
+// applyOutboundSocksDetour appends a SOCKS5 outbound to opts and rewrites every
+// other leaf outbound to dial through it, when env.OutboundSocksAddress is set.
+// Selector / urltest / block / dns outbounds are skipped — they don't dial
+// directly. No-op when the env var is unset.
+func applyOutboundSocksDetour(opts *O.Options) error {
+	addr, ok := env.Get(env.OutboundSocksAddress)
+	if !ok || addr == "" {
+		return nil
+	}
+	host, portStr, err := net.SplitHostPort(addr)
+	if err != nil {
+		return fmt.Errorf("invalid RADIANCE_OUTBOUND_SOCKS_ADDRESS %q: %w", addr, err)
+	}
+	port, err := strconv.ParseUint(portStr, 10, 16)
+	if err != nil {
+		return fmt.Errorf("invalid RADIANCE_OUTBOUND_SOCKS_ADDRESS port %q: %w", portStr, err)
+	}
+
+	for i := range opts.Outbounds {
+		out := &opts.Outbounds[i]
+		switch out.Type {
+		case C.TypeSelector, C.TypeURLTest, C.TypeBlock, C.TypeDNS:
+			continue
+		}
+		if w, ok := out.Options.(O.DialerOptionsWrapper); ok {
+			d := w.TakeDialerOptions()
+			d.Detour = devOutboundSocksTag
+			w.ReplaceDialerOptions(d)
+		}
+	}
+
+	opts.Outbounds = append(opts.Outbounds, O.Outbound{
+		Type: C.TypeSOCKS,
+		Tag:  devOutboundSocksTag,
+		Options: &O.SOCKSOutboundOptions{
+			ServerOptions: O.ServerOptions{
+				Server:     host,
+				ServerPort: uint16(port),
+			},
+			Version: "5",
+		},
+	})
+
+	slog.Info("RADIANCE_OUTBOUND_SOCKS_ADDRESS set — every sing-box outbound will dial via this SOCKS5",
+		slog.String("addr", addr),
+		slog.Int("rewritten_outbounds", len(opts.Outbounds)-1))
+	return nil
+}
+
 // mergeAndCollectTags merges src into dst and returns all outbound/endpoint tags from src.
 func mergeAndCollectTags(dst, src *O.Options) []string {
 	dst.Outbounds = append(dst.Outbounds, src.Outbounds...)