feat: support upstream socks5 egress

Author: Rxflex

CHANGELOG.md

@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - First-run setup wizard covering both OS and language-runtime trust stores.
 - Application launcher mode for running HTTPS clients and Electron apps through
   Doppel without proxychains.
+- Upstream SOCKS5 proxy support for `run`, `launch`, and `verify`.
 
 ### Known limitations
 

README.md

@@ -178,6 +178,7 @@ Useful flags:
 | `--force` | `init` | Regenerate the local CA |
 | `--export <path>` | `ca` | Write the CA certificate to a file |
 | `--insecure` | `run`, `launch` | Skip upstream certificate verification for debugging only |
+| `--upstream-proxy <url>` | `run`, `launch`, `verify` | Route Doppel egress through a SOCKS5 proxy |
 | `-v` | `run`, `launch` | Enable debug logging |
 | `--electron` | `launch` | Add Chromium/Electron proxy switches to the child process |
 
@@ -231,6 +232,17 @@ Supported `client_hello` templates are `chrome`, `firefox`, `safari`,
 
 ## Usage examples
 
+### Route Doppel through an upstream SOCKS5 proxy
+
+Use `--upstream-proxy` when Doppel itself should egress through another proxy:
+
+```sh
+doppel verify --upstream-proxy socks5://user:pass@proxy.example:1080
+```
+
+The same value can be supplied with `DOPPEL_UPSTREAM_PROXY` for `run`, `launch`,
+and `verify`. Provider-style `socks5://host:port:user:pass` URLs are accepted.
+
 ### Launch an app through Doppel
 
 `doppel launch` starts a temporary Doppel proxy, launches one child process with

cmd/doppel/main.go

@@ -113,6 +113,7 @@ func cmdRun(args []string) error {
 	dataDir := fs.String("data", cfg.DataDir, "data directory")
 	verbose := fs.Bool("v", false, "verbose (debug) logging")
 	insecure := fs.Bool("insecure", false, "skip upstream certificate verification (debugging only)")
+	upstreamProxyURL := fs.String("upstream-proxy", os.Getenv("DOPPEL_UPSTREAM_PROXY"), "upstream SOCKS5 proxy URL")
 	if err := fs.Parse(args); err != nil {
 		return err
 	}
@@ -132,9 +133,13 @@ func cmdRun(args []string) error {
 	if err != nil {
 		return err
 	}
+	upstreamProxy, err := upstream.ParseProxy(*upstreamProxyURL)
+	if err != nil {
+		return err
+	}
 
 	transport := &upstream.RoundTripper{
-		Dialer:  &upstream.Dialer{SkipVerify: *insecure},
+		Dialer:  &upstream.Dialer{SkipVerify: *insecure, UpstreamProxy: upstreamProxy},
 		Profile: selected,
 	}
 	defer transport.Close()
@@ -170,6 +175,7 @@ func cmdLaunch(args []string) error {
 	dataDir := fs.String("data", cfg.DataDir, "data directory")
 	verbose := fs.Bool("v", false, "verbose (debug) logging")
 	insecure := fs.Bool("insecure", false, "skip upstream certificate verification (debugging only)")
+	upstreamProxyURL := fs.String("upstream-proxy", os.Getenv("DOPPEL_UPSTREAM_PROXY"), "upstream SOCKS5 proxy URL")
 	includeEnv := fs.Bool("env", true, "set HTTPS proxy and CA environment variables for the child")
 	electron := fs.Bool("electron", false, "append Chromium/Electron proxy command-line switches")
 	allSchemes := fs.Bool("all-schemes", false, "with -electron, proxy every Chromium URL scheme instead of HTTPS only")
@@ -197,9 +203,13 @@ func cmdLaunch(args []string) error {
 	if err != nil {
 		return err
 	}
+	upstreamProxy, err := upstream.ParseProxy(*upstreamProxyURL)
+	if err != nil {
+		return err
+	}
 
 	transport := &upstream.RoundTripper{
-		Dialer:  &upstream.Dialer{SkipVerify: *insecure},
+		Dialer:  &upstream.Dialer{SkipVerify: *insecure, UpstreamProxy: upstreamProxy},
 		Profile: selected,
 	}
 	defer transport.Close()
@@ -330,6 +340,7 @@ func cmdVerify(args []string) error {
 	profileName := fs.String("profile", cfg.Profile, "identity profile to test")
 	url := fs.String("url", "https://get.ja3.zone/", "fingerprint-reporting endpoint")
 	dataDir := fs.String("data", cfg.DataDir, "data directory")
+	upstreamProxyURL := fs.String("upstream-proxy", os.Getenv("DOPPEL_UPSTREAM_PROXY"), "upstream SOCKS5 proxy URL")
 	if err := fs.Parse(args); err != nil {
 		return err
 	}
@@ -339,8 +350,12 @@ func cmdVerify(args []string) error {
 	if err != nil {
 		return err
 	}
+	upstreamProxy, err := upstream.ParseProxy(*upstreamProxyURL)
+	if err != nil {
+		return err
+	}
 
-	rt := &upstream.RoundTripper{Dialer: &upstream.Dialer{}, Profile: selected}
+	rt := &upstream.RoundTripper{Dialer: &upstream.Dialer{UpstreamProxy: upstreamProxy}, Profile: selected}
 	defer rt.Close()
 
 	req, err := http.NewRequest(http.MethodGet, *url, nil)

docs/LAUNCHING_APPS.md

@@ -48,6 +48,19 @@ child environment. Doppel is a TLS identity proxy and expects CONNECT/SOCKS5
 followed by a TLS stream. Plain HTTP forwarding is not part of the current
 design.
 
+## Upstream SOCKS5 egress
+
+`doppel launch` can also route Doppel's outbound side through a SOCKS5 proxy:
+
+```sh
+doppel launch --upstream-proxy socks5://user:pass@proxy.example:1080 -- \
+  curl https://example.com
+```
+
+The child application still talks only to local Doppel. The upstream proxy URL
+is consumed by Doppel and should be provided through a secret manager or
+short-lived environment variable in automation.
+
 ## Electron and Chromium apps
 
 Electron applications are Chromium-based, so environment variables are often

internal/upstream/dialer.go

@@ -30,6 +30,9 @@ type Dialer struct {
 	// It must remain false outside of debugging: skipping verification
 	// would let an attacker between Doppel and the server go unnoticed.
 	SkipVerify bool
+	// UpstreamProxy routes Doppel's outbound TCP connection through a proxy.
+	// Nil means direct egress.
+	UpstreamProxy *ProxyConfig
 }
 
 // Dial connects to host (host:port, defaulting to port 443) and performs a
@@ -47,8 +50,8 @@ func (d *Dialer) Dial(ctx context.Context, p *profile.Profile, host string) (*Co
 		timeout = defaultTimeout
 	}
 
-	tcpDialer := &net.Dialer{Timeout: timeout}
-	raw, err := tcpDialer.DialContext(ctx, "tcp", net.JoinHostPort(hostname, port))
+	target := net.JoinHostPort(hostname, port)
+	raw, err := d.dialTCP(ctx, target, timeout)
 	if err != nil {
 		return nil, fmt.Errorf("dial %s: %w", host, err)
 	}
@@ -80,6 +83,14 @@ func (d *Dialer) Dial(ctx context.Context, p *profile.Profile, host string) (*Co
 	return &Conn{Conn: uconn, ALPN: uconn.ConnectionState().NegotiatedProtocol}, nil
 }
 
+func (d *Dialer) dialTCP(ctx context.Context, target string, timeout time.Duration) (net.Conn, error) {
+	if d.UpstreamProxy != nil {
+		return d.UpstreamProxy.Dial(ctx, "tcp", target, timeout)
+	}
+	tcpDialer := &net.Dialer{Timeout: timeout}
+	return tcpDialer.DialContext(ctx, "tcp", target)
+}
+
 func splitHostPort(host string) (hostname, port string) {
 	if h, p, err := net.SplitHostPort(host); err == nil {
 		return h, p