feat: launch applications through doppel

Author: Rxflex

CHANGELOG.md

@@ -19,8 +19,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Single-port SOCKS5 and HTTP CONNECT proxy with protocol auto-detection and a
   client-negotiation deadline.
 - TLS interception that re-originates requests through the chosen profile.
-- `doppel` command-line interface: `init`, `run`, `profiles`, `ca`, `verify`.
+- `doppel` command-line interface: `init`, `run`, `launch`, `profiles`,
+  `ca`, `verify`.
 - 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.
 
 ### Known limitations
 

README.md

@@ -160,6 +160,7 @@ protocol: HTTP/2.0
 | --- | --- |
 | `doppel init` | Generate or reuse the local CA and print setup guidance |
 | `doppel run` | Start the local proxy |
+| `doppel launch` | Start Doppel and run one application through it |
 | `doppel profiles` | List built-in and user-supplied identity profiles |
 | `doppel ca` | Show or export the local CA certificate |
 | `doppel verify` | Check the selected profile against a remote endpoint |
@@ -171,13 +172,14 @@ Useful flags:
 
 | Flag | Commands | Purpose |
 | --- | --- | --- |
-| `--profile <name>` | `run`, `verify` | Select the identity profile |
-| `--addr <host:port>` | `init`, `run` | Change the proxy address; default is `127.0.0.1:8080` |
-| `--data <path>` | `init`, `run`, `profiles`, `ca`, `verify` | Use a custom data directory |
+| `--profile <name>` | `run`, `launch`, `verify` | Select the identity profile |
+| `--addr <host:port>` | `init`, `run`, `launch` | Change the proxy address; default is `127.0.0.1:8080` |
+| `--data <path>` | `init`, `run`, `launch`, `profiles`, `ca`, `verify` | Use a custom data directory |
 | `--force` | `init` | Regenerate the local CA |
 | `--export <path>` | `ca` | Write the CA certificate to a file |
-| `--insecure` | `run` | Skip upstream certificate verification for debugging only |
-| `-v` | `run` | Enable debug logging |
+| `--insecure` | `run`, `launch` | Skip upstream certificate verification for debugging only |
+| `-v` | `run`, `launch` | Enable debug logging |
+| `--electron` | `launch` | Add Chromium/Electron proxy switches to the child process |
 
 ## Built-in profiles
 
@@ -229,6 +231,26 @@ Supported `client_hello` templates are `chrome`, `firefox`, `safari`,
 
 ## Usage examples
 
+### Launch an app through Doppel
+
+`doppel launch` starts a temporary Doppel proxy, launches one child process with
+HTTPS proxy environment variables, and stops the proxy when the child exits:
+
+```sh
+doppel launch --profile chrome-windows -- curl https://example.com
+```
+
+For Electron or Chromium-based desktop apps, add `--electron`. Doppel appends
+Chromium proxy switches so the app does not need proxychains or LD_PRELOAD:
+
+```sh
+doppel launch --profile chrome-windows --electron -- /path/to/electron-app
+```
+
+By default the Chromium switch proxies HTTPS URLs only, because Doppel expects a
+TLS stream after CONNECT. See [Launching applications](docs/LAUNCHING_APPS.md)
+for Windows, macOS, Linux, and Electron notes.
+
 ### curl
 
 ```sh

cmd/doppel/main.go

@@ -9,13 +9,16 @@ import (
 	"fmt"
 	"io"
 	"log/slog"
+	"net"
 	"net/http"
 	"os"
 	"os/signal"
 	"sort"
+	"time"
 
 	"github.com/redstone-md/Doppel/internal/ca"
 	"github.com/redstone-md/Doppel/internal/config"
+	"github.com/redstone-md/Doppel/internal/launch"
 	"github.com/redstone-md/Doppel/internal/mitm"
 	"github.com/redstone-md/Doppel/internal/profile"
 	"github.com/redstone-md/Doppel/internal/proxy"
@@ -38,6 +41,8 @@ func main() {
 		err = cmdInit(os.Args[2:])
 	case "run":
 		err = cmdRun(os.Args[2:])
+	case "launch":
+		err = cmdLaunch(os.Args[2:])
 	case "profiles":
 		err = cmdProfiles(os.Args[2:])
 	case "ca":
@@ -152,6 +157,104 @@ func cmdRun(args []string) error {
 	return server.ListenAndServe(ctx)
 }
 
+// cmdLaunch starts the proxy, launches a child application configured to use it,
+// and stops the proxy when the child exits.
+func cmdLaunch(args []string) error {
+	cfg, err := config.Default()
+	if err != nil {
+		return err
+	}
+	fs := flag.NewFlagSet("launch", flag.ExitOnError)
+	addr := fs.String("addr", cfg.Addr, "proxy listen address")
+	profileName := fs.String("profile", cfg.Profile, "identity profile to emulate")
+	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)")
+	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")
+	bypass := fs.String("bypass", "<local>", "Chromium proxy bypass list used with -electron")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	argv := fs.Args()
+	if len(argv) == 0 {
+		return fmt.Errorf("usage: doppel launch [flags] -- <command> [args...]")
+	}
+	cfg.DataDir, cfg.Addr, cfg.Profile = *dataDir, *addr, *profileName
+
+	logger := newLogger(*verbose)
+
+	if !cfg.CAExists() {
+		return fmt.Errorf("no CA found in %s; run 'doppel init' first", cfg.DataDir)
+	}
+	authority, err := ca.Load(cfg.CACertPath(), cfg.CAKeyPath())
+	if err != nil {
+		return err
+	}
+
+	selected, err := loadProfile(cfg, cfg.Profile)
+	if err != nil {
+		return err
+	}
+
+	transport := &upstream.RoundTripper{
+		Dialer:  &upstream.Dialer{SkipVerify: *insecure},
+		Profile: selected,
+	}
+	defer transport.Close()
+
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
+	defer stop()
+
+	ln, err := net.Listen("tcp", cfg.Addr)
+	if err != nil {
+		return fmt.Errorf("listen on %s: %w", cfg.Addr, err)
+	}
+
+	server := &proxy.Server{
+		Addr:   cfg.Addr,
+		Logger: logger,
+		Interceptor: &mitm.Interceptor{
+			CA:        authority,
+			Profile:   selected,
+			Transport: transport,
+			Logger:    logger,
+		},
+	}
+
+	serveErr := make(chan error, 1)
+	go func() { serveErr <- server.Serve(ctx, ln) }()
+
+	proxyAddr := ln.Addr().String()
+	cmd, err := launch.Command(ctx, launch.Options{
+		ProxyAddr:       proxyAddr,
+		CACertPath:      cfg.CACertPath(),
+		IncludeEnv:      *includeEnv,
+		IncludeChromium: *electron,
+		ProxyAllSchemes: *allSchemes,
+		BypassList:      *bypass,
+	}, argv)
+	if err != nil {
+		stop()
+		return err
+	}
+
+	logger.Info("launching app", "profile", selected.Name, "proxy", proxyAddr, "command", argv[0])
+	runErr := cmd.Run()
+	stop()
+
+	select {
+	case err := <-serveErr:
+		if runErr == nil && err != nil {
+			return err
+		}
+	case <-time.After(5 * time.Second):
+		logger.Warn("proxy shutdown timed out; exiting with child status")
+	}
+	return runErr
+}
+
 // cmdProfiles lists every available identity profile.
 func cmdProfiles(args []string) error {
 	cfg, err := config.Default()
@@ -320,6 +423,7 @@ Usage:
 Commands:
   init       Generate the local CA and print setup instructions
   run        Start the proxy
+  launch     Start the proxy and run an application through it
   profiles   List available identity profiles
   ca         Show or export the local CA certificate
   verify     Check the emulated TLS fingerprint against a remote service

docs/LAUNCHING_APPS.md

@@ -0,0 +1,143 @@
+# Launching Applications Through Doppel
+
+`doppel launch` is the recommended way to run a single application through
+Doppel without proxychains-ng, LD_PRELOAD, or global OS proxy changes.
+
+It starts Doppel, launches the child process with proxy-related environment
+variables, and stops Doppel when the child process exits.
+
+## Basic usage
+
+Initialize the local CA once:
+
+```sh
+doppel init
+```
+
+Launch an application:
+
+```sh
+doppel launch --profile chrome-windows -- <command> [args...]
+```
+
+Example with curl:
+
+```sh
+doppel launch --profile chrome-windows -- curl https://example.com
+```
+
+The `--` separator matters when the child command has its own flags.
+
+## What the launcher sets
+
+By default, `doppel launch` sets HTTPS-oriented environment variables for the
+child process:
+
+```text
+HTTPS_PROXY=http://127.0.0.1:8080
+https_proxy=http://127.0.0.1:8080
+NO_PROXY=localhost,127.0.0.1,::1
+no_proxy=localhost,127.0.0.1,::1
+REQUESTS_CA_BUNDLE=<doppel ca.pem>
+NODE_EXTRA_CA_CERTS=<doppel ca.pem>
+SSL_CERT_FILE=<doppel ca.pem>
+```
+
+`HTTP_PROXY`, `http_proxy`, `ALL_PROXY`, and `all_proxy` are removed from the
+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.
+
+## Electron and Chromium apps
+
+Electron applications are Chromium-based, so environment variables are often
+not enough. Use `--electron` to append Chromium proxy switches to the launched
+process:
+
+```sh
+doppel launch --profile chrome-windows --electron -- /path/to/electron-app
+```
+
+The launcher appends:
+
+```text
+--proxy-server=https=http://127.0.0.1:8080
+--proxy-bypass-list=<local>
+```
+
+The HTTPS-only proxy rule is deliberate: Doppel handles HTTPS requests where the
+client opens a CONNECT tunnel and then starts TLS. If you need to force Chromium
+to send all URL schemes to Doppel for debugging, add `--all-schemes`, but plain
+HTTP requests will not be rewritten into TLS and may fail.
+
+```sh
+doppel launch --electron --all-schemes -- /path/to/electron-app
+```
+
+For Electron applications you control, the equivalent in the main process is:
+
+```js
+const { app } = require('electron')
+
+app.commandLine.appendSwitch('proxy-server', 'https=http://127.0.0.1:8080')
+app.commandLine.appendSwitch('proxy-bypass-list', '<local>')
+```
+
+Append these switches before `app.whenReady()`.
+
+## Windows examples
+
+PowerShell:
+
+```powershell
+doppel launch --profile chrome-windows --electron -- "C:\Users\you\AppData\Local\Programs\App\App.exe"
+```
+
+If the launched app is not Electron/Chromium-based, omit `--electron`:
+
+```powershell
+doppel launch --profile chrome-windows -- python .\client.py
+```
+
+## macOS examples
+
+Electron `.app` bundles usually need the real executable inside the bundle:
+
+```sh
+doppel launch --electron -- \
+  "/Applications/Example.app/Contents/MacOS/Example"
+```
+
+## Linux examples
+
+```sh
+doppel launch --electron -- /usr/bin/example-app
+```
+
+For AppImage builds:
+
+```sh
+doppel launch --electron -- ./Example.AppImage
+```
+
+## When to still use system proxy settings
+
+Some closed-source desktop apps sanitize command-line arguments or spawn helper
+processes without inheriting the parent environment. For those apps, use OS
+proxy settings or the app's own proxy settings and point HTTPS traffic at
+`127.0.0.1:8080`.
+
+System proxy mode is broader than `doppel launch`, so use it carefully and turn
+it off after the test. `doppel launch` is preferred when you want one target app
+without affecting the rest of the machine.
+
+## Known limits
+
+- Doppel handles HTTPS/TLS traffic, not arbitrary TCP protocols.
+- Plain HTTP URLs are not converted to HTTPS.
+- Apps with certificate pinning may reject Doppel's generated leaf
+  certificates even after the CA is trusted.
+- Electron apps that ignore Chromium command-line switches need in-app proxy
+  configuration or OS proxy settings.
+- Child processes that drop inherited environment variables may need explicit
+  app-level proxy configuration.