diff --git a/.nextchanges/cli/sandbox-forward.md b/.nextchanges/cli/sandbox-forward.md new file mode 100644 index 00000000000..40100fd8dea --- /dev/null +++ b/.nextchanges/cli/sandbox-forward.md @@ -0,0 +1 @@ +* Add `databricks sandbox forward`, which serves an app running in a sandbox at a local URL. ([#7395](https://github.com/databricks/cli/pull/7395)) diff --git a/acceptance/cmd/sandbox/forward/forward/out.test.toml b/acceptance/cmd/sandbox/forward/forward/out.test.toml new file mode 100644 index 00000000000..18b1a88417e --- /dev/null +++ b/acceptance/cmd/sandbox/forward/forward/out.test.toml @@ -0,0 +1 @@ +Cloud = false diff --git a/acceptance/cmd/sandbox/forward/forward/output.txt b/acceptance/cmd/sandbox/forward/forward/output.txt new file mode 100644 index 00000000000..53c9d2dd9d6 --- /dev/null +++ b/acceptance/cmd/sandbox/forward/forward/output.txt @@ -0,0 +1,28 @@ + +=== The command reports the forward once it is listening + +>>> retry --until Press Ctrl-C to stop. cat LOG.forward +Forwarding http://127.0.0.1:[LOCAL_PORT] -> happy-panda-1234:10080 +Press Ctrl-C to stop. + +=== A local request reaches the sandbox app through the forward route + +>>> curl -sS -X POST -H X-Databricks-Org-Id: 999 -d ping http://127.0.0.1:[LOCAL_PORT]/api/items?page=2 +hello from the sandbox app + +=== The workspace receives the CLI's routing header in place of the caller's + +>>> print_requests.py //sandbox-proxy +{ + "headers": { + "X-Databricks-Org-Id": [ + "[WORKSPACE_ID]" + ] + }, + "method": "POST", + "path": "/sandbox-proxy/sandboxes/happy-panda-1234/ports/10080/api/items", + "q": { + "page": "2" + }, + "raw_body": "ping" +} diff --git a/acceptance/cmd/sandbox/forward/forward/script b/acceptance/cmd/sandbox/forward/forward/script new file mode 100644 index 00000000000..893d1dd9e3a --- /dev/null +++ b/acceptance/cmd/sandbox/forward/forward/script @@ -0,0 +1,20 @@ +# Ports are allocated per run so that tests in parallel worktrees do not collide. +read -r LOCAL_PORT <<< "$(free_port.py 1)" + +# The forward runs until interrupted. Start it outside this shell's job table so +# stopping it doesn't print a "Killed" job notice, and stop it by port, which +# also works on Windows. +( $CLI sandbox forward happy-panda-1234 -L "$LOCAL_PORT:10080" &> LOG.forward & ) +trap 'kill_port.py "$LOCAL_PORT"' EXIT + +export RETRY_MAX_ATTEMPTS=30 + +title "The command reports the forward once it is listening" +trace retry --until "Press Ctrl-C to stop." cat LOG.forward + +title "A local request reaches the sandbox app through the forward route" +trace curl -sS -X POST -H "X-Databricks-Org-Id: 999" -d 'ping' "http://127.0.0.1:$LOCAL_PORT/api/items?page=2" +echo + +title "The workspace receives the CLI's routing header in place of the caller's" +trace print_requests.py //sandbox-proxy diff --git a/acceptance/cmd/sandbox/forward/forward/test.toml b/acceptance/cmd/sandbox/forward/forward/test.toml new file mode 100644 index 00000000000..a6be01cff60 --- /dev/null +++ b/acceptance/cmd/sandbox/forward/forward/test.toml @@ -0,0 +1,15 @@ +RecordRequests = true +IncludeRequestHeaders = ["X-Databricks-Org-Id"] + +[[Server]] +Pattern = "GET /api/2.0/lakebox/sandboxes/happy-panda-1234" +Response.Body = '{"sandboxId": "happy-panda-1234", "status": "Running"}' + +[[Server]] +Pattern = "POST /sandbox-proxy/sandboxes/happy-panda-1234/ports/10080/{path...}" +Response.Body = 'hello from the sandbox app' + +# The local port is allocated per run. +[[Repls]] +Old = '127\.0\.0\.1:\d+' +New = '127.0.0.1:[LOCAL_PORT]' diff --git a/acceptance/cmd/sandbox/forward/invalid-forward/out.test.toml b/acceptance/cmd/sandbox/forward/invalid-forward/out.test.toml new file mode 100644 index 00000000000..18b1a88417e --- /dev/null +++ b/acceptance/cmd/sandbox/forward/invalid-forward/out.test.toml @@ -0,0 +1 @@ +Cloud = false diff --git a/acceptance/cmd/sandbox/forward/invalid-forward/output.txt b/acceptance/cmd/sandbox/forward/invalid-forward/output.txt new file mode 100644 index 00000000000..067a76be641 --- /dev/null +++ b/acceptance/cmd/sandbox/forward/invalid-forward/output.txt @@ -0,0 +1,3 @@ +Error: invalid -L "8080": expected LOCAL:REMOTE ports, e.g. 8080:10080 +Error: invalid -L "8080:8080": remote port must be between 10000 and 65535 +Error: required flag(s) "forward" not set diff --git a/acceptance/cmd/sandbox/forward/invalid-forward/script b/acceptance/cmd/sandbox/forward/invalid-forward/script new file mode 100644 index 00000000000..fe6e995d628 --- /dev/null +++ b/acceptance/cmd/sandbox/forward/invalid-forward/script @@ -0,0 +1,8 @@ +# Malformed -L specs are rejected before any API call, so no [[Server]] stub is needed. +musterr $CLI sandbox forward happy-panda-1234 -L 8080 + +# Remote ports outside 10000-65535 are refused up front. +musterr $CLI sandbox forward happy-panda-1234 -L 8080:8080 + +# At least one -L is required. +musterr $CLI sandbox forward happy-panda-1234 diff --git a/acceptance/cmd/sandbox/forward/no-default/out.test.toml b/acceptance/cmd/sandbox/forward/no-default/out.test.toml new file mode 100644 index 00000000000..18b1a88417e --- /dev/null +++ b/acceptance/cmd/sandbox/forward/no-default/out.test.toml @@ -0,0 +1 @@ +Cloud = false diff --git a/acceptance/cmd/sandbox/forward/no-default/output.txt b/acceptance/cmd/sandbox/forward/no-default/output.txt new file mode 100644 index 00000000000..fdd78814b43 --- /dev/null +++ b/acceptance/cmd/sandbox/forward/no-default/output.txt @@ -0,0 +1 @@ +Error: no default sandbox configured — run `databricks sandbox create` to provision one, or `databricks sandbox default ` to set an existing sandbox as the default diff --git a/acceptance/cmd/sandbox/forward/no-default/script b/acceptance/cmd/sandbox/forward/no-default/script new file mode 100644 index 00000000000..bfe97bc713f --- /dev/null +++ b/acceptance/cmd/sandbox/forward/no-default/script @@ -0,0 +1,2 @@ +# Without a sandbox ID the default sandbox is used; the fresh home has none. +musterr $CLI sandbox forward -L 0:10080 diff --git a/acceptance/cmd/sandbox/forward/not-found/out.test.toml b/acceptance/cmd/sandbox/forward/not-found/out.test.toml new file mode 100644 index 00000000000..18b1a88417e --- /dev/null +++ b/acceptance/cmd/sandbox/forward/not-found/out.test.toml @@ -0,0 +1 @@ +Cloud = false diff --git a/acceptance/cmd/sandbox/forward/not-found/output.txt b/acceptance/cmd/sandbox/forward/not-found/output.txt new file mode 100644 index 00000000000..235a49bc669 --- /dev/null +++ b/acceptance/cmd/sandbox/forward/not-found/output.txt @@ -0,0 +1 @@ +Error: no sandbox named "no-such-box" — `databricks sandbox list` shows available IDs diff --git a/acceptance/cmd/sandbox/forward/not-found/script b/acceptance/cmd/sandbox/forward/not-found/script new file mode 100644 index 00000000000..1a7af8238a4 --- /dev/null +++ b/acceptance/cmd/sandbox/forward/not-found/script @@ -0,0 +1 @@ +musterr $CLI sandbox forward no-such-box -L 0:10080 diff --git a/acceptance/cmd/sandbox/forward/not-found/test.toml b/acceptance/cmd/sandbox/forward/not-found/test.toml new file mode 100644 index 00000000000..3d2b831b415 --- /dev/null +++ b/acceptance/cmd/sandbox/forward/not-found/test.toml @@ -0,0 +1,4 @@ +[[Server]] +Pattern = "GET /api/2.0/lakebox/sandboxes/no-such-box" +Response.StatusCode = 404 +Response.Body = '{"error_code": "NOT_FOUND", "message": "Sandbox not found"}' diff --git a/cmd/sandbox/forward.go b/cmd/sandbox/forward.go new file mode 100644 index 00000000000..901edb57641 --- /dev/null +++ b/cmd/sandbox/forward.go @@ -0,0 +1,362 @@ +package sandbox + +import ( + "context" + "crypto/tls" + "errors" + "fmt" + "log/slog" + "net" + "net/http" + "net/http/httputil" + "net/url" + "os" + "os/signal" + "strconv" + "strings" + "syscall" + "time" + "unicode" + + "github.com/databricks/cli/cmd/root" + "github.com/databricks/cli/libs/cmdctx" + "github.com/databricks/cli/libs/cmdio" + "github.com/databricks/cli/libs/log" + "github.com/databricks/databricks-sdk-go/config" + "github.com/spf13/cobra" + "golang.org/x/sync/errgroup" +) + +// forwardRoute is the workspace route that relays a request to an app +// listening on a sandbox port: //ports//. +const forwardRoute = "/sandbox-proxy/sandboxes/" + +// Forwards listen only on loopback, since every request through them carries +// the caller's credentials. Some clients (e.g. Node 17+) resolve localhost to +// ::1 first, so the IPv6 loopback is served too when it is available. +const ( + forwardBindHost = "127.0.0.1" + forwardBindHostIPv6 = "::1" +) + +// The sandbox only forwards to remote ports in this range. +const ( + minRemotePort = 10000 + maxRemotePort = 65535 +) + +// forwardReadHeaderTimeout bounds how long a local client may take to send +// request headers. Bodies and upgraded connections are not bounded. +const forwardReadHeaderTimeout = time.Minute + +// platformHeaderPrefixes mark the platform's auth, identity, and routing +// headers, in lowercase. Only the CLI's own values may reach the workspace. +var platformHeaderPrefixes = []string{"x-databricks-", "s2s-"} + +// forwardSpec is one parsed -L LOCAL:REMOTE spec. +type forwardSpec struct { + localPort int + remotePort int +} + +// forwardTarget is where and how forwarded requests are sent. +type forwardTarget struct { + workspace *url.URL + sandboxID string + authenticate func(*http.Request) error + headers map[string]string + transport http.RoundTripper +} + +func newForwardCommand() *cobra.Command { + var specs []string + + cmd := &cobra.Command{ + Use: "forward [sandbox-id] -L :...", + Short: "Forward local ports to apps in a Sandbox environment", + Long: `Forward local ports to apps running in a Sandbox environment. + +Each -L LOCAL:REMOTE serves http://127.0.0.1:LOCAL and relays HTTP and +WebSocket traffic to an app listening on 0.0.0.0:REMOTE in the sandbox, +authenticated as you. Remote ports must be between 10000 and 65535. Pass 0 +as the local port to pick a free one. A stopped sandbox is started first. +Runs until interrupted. + +Examples: + databricks sandbox forward -L 8080:10080 # default sandbox + databricks sandbox forward happy-panda-1234 -L 8080:10080 -L 8081:10081`, + Args: cobra.MaximumNArgs(1), + PreRunE: root.MustWorkspaceClient, + ValidArgsFunction: completeSandboxIDs, + RunE: func(cmd *cobra.Command, args []string) error { + forwards, err := parseForwards(specs) + if err != nil { + return err + } + + ctx := cmd.Context() + w := cmdctx.WorkspaceClient(ctx) + + profile := w.Config.Profile + if profile == "" { + profile = w.Config.Host + } + + api, err := newSandboxAPI(w) + if err != nil { + return err + } + var arg string + if len(args) > 0 { + arg = args[0] + } + sandboxID, sb, err := resolveSandbox(ctx, api, profile, arg) + if err != nil { + return err + } + if sb != nil { + if _, err := ensureRunning(ctx, api, sandboxID, sb.Status); err != nil { + return err + } + } + + workspace, err := url.Parse(w.Config.Host) + if err != nil { + return fmt.Errorf("failed to parse workspace host %q: %w", w.Config.Host, err) + } + transport, err := newForwardTransport(w.Config) + if err != nil { + return err + } + target := forwardTarget{ + workspace: workspace, + sandboxID: sandboxID, + authenticate: w.Config.Authenticate, + headers: api.headers(), + transport: transport, + } + + ctx, stop := signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM) + defer stop() + return serveForwards(ctx, target, forwards) + }, + } + + cmd.Flags().StringArrayVarP(&specs, "forward", "L", nil, "Forward LOCAL:REMOTE ports, e.g. 8080:10080 (repeatable)") + _ = cmd.MarkFlagRequired("forward") + + return cmd +} + +// parseForwards parses -L LOCAL:REMOTE specs. LOCAL may be 0 to pick a free +// port. A few platform ports inside the remote range are refused by the sandbox. +func parseForwards(specs []string) ([]forwardSpec, error) { + forwards := make([]forwardSpec, 0, len(specs)) + for _, spec := range specs { + local, remote, found := strings.Cut(spec, ":") + localPort, localErr := strconv.Atoi(local) + remotePort, remoteErr := strconv.Atoi(remote) + if !found || localErr != nil || remoteErr != nil || localPort < 0 || localPort > 65535 { + return nil, fmt.Errorf("invalid -L %q: expected LOCAL:REMOTE ports, e.g. 8080:10080", spec) + } + if remotePort < minRemotePort || remotePort > maxRemotePort { + return nil, fmt.Errorf("invalid -L %q: remote port must be between %d and %d", spec, minRemotePort, maxRemotePort) + } + forwards = append(forwards, forwardSpec{localPort: localPort, remotePort: remotePort}) + } + return forwards, nil +} + +// newForwardTransport returns the workspace config's transport, or the +// default one with the config's TLS verification setting. +func newForwardTransport(cfg *config.Config) (http.RoundTripper, error) { + clientCfg, err := config.HTTPClientConfigFromConfig(cfg) + if err != nil { + return nil, fmt.Errorf("failed to configure forward transport: %w", err) + } + if clientCfg.Transport != nil { + return clientCfg.Transport, nil + } + transport := http.DefaultTransport.(*http.Transport).Clone() + if clientCfg.InsecureSkipVerify { + transport.TLSClientConfig = &tls.Config{InsecureSkipVerify: true} + } + return transport, nil +} + +// serveForwards listens on every forward's local port before serving any, +// so a port that is already in use fails the command up front. +func serveForwards(ctx context.Context, target forwardTarget, forwards []forwardSpec) error { + var lc net.ListenConfig + listeners := make([][]net.Listener, 0, len(forwards)) + for _, f := range forwards { + ln, err := lc.Listen(ctx, "tcp", net.JoinHostPort(forwardBindHost, strconv.Itoa(f.localPort))) + if err != nil { + for _, group := range listeners { + for _, open := range group { + open.Close() + } + } + return fmt.Errorf("failed to listen on local port %d: %w", f.localPort, err) + } + group := []net.Listener{ln} + port := strconv.Itoa(ln.Addr().(*net.TCPAddr).Port) + if ln6, err := lc.Listen(ctx, "tcp", net.JoinHostPort(forwardBindHostIPv6, port)); err == nil { + group = append(group, ln6) + } else { + log.Debugf(ctx, "not forwarding [%s]:%s: %v", forwardBindHostIPv6, port, err) + } + listeners = append(listeners, group) + } + + // net/http reports routine client disconnects through ErrorLog; keep them at + // debug level in the CLI log instead of on stderr. + logger := log.GetLogger(ctx) + g, ctx := errgroup.WithContext(ctx) + for i, f := range forwards { + srv := &http.Server{ + Handler: newForwardHandler(target, f.remotePort, logger), + ReadHeaderTimeout: forwardReadHeaderTimeout, + ErrorLog: slog.NewLogLogger(logger.Handler(), slog.LevelDebug), + } + cmdio.LogString(ctx, fmt.Sprintf("Forwarding http://%s -> %s:%d", listeners[i][0].Addr(), target.sandboxID, f.remotePort)) + for _, ln := range listeners[i] { + g.Go(func() error { + if err := srv.Serve(ln); !errors.Is(err, http.ErrServerClosed) { + return fmt.Errorf("forward on %s failed: %w", ln.Addr(), err) + } + return nil + }) + } + // An interactive interrupt stops at once: WebSockets and streams never + // go idle, so a graceful Shutdown would only delay the exit. + g.Go(func() error { + <-ctx.Done() + return srv.Close() + }) + } + cmdio.LogString(ctx, "Press Ctrl-C to stop.") + return g.Wait() +} + +// newForwardHandler relays each request to remotePort in the sandbox +// through the workspace's forward route. +func newForwardHandler(target forwardTarget, remotePort int, logger *slog.Logger) http.Handler { + base := strings.TrimSuffix(target.workspace.Path, "/") + forwardRoute + port := "/ports/" + strconv.Itoa(remotePort) + proxy := &httputil.ReverseProxy{ + Rewrite: func(pr *httputil.ProxyRequest) { + pr.Out.URL.Scheme = target.workspace.Scheme + pr.Out.URL.Host = target.workspace.Host + pr.Out.URL.Path = base + target.sandboxID + port + pr.In.URL.Path + pr.Out.URL.RawPath = base + url.PathEscape(target.sandboxID) + port + pr.In.URL.EscapedPath() + pr.Out.Host = "" + pr.Out.Header.Del("Authorization") + for name := range pr.Out.Header { + if isPlatformHeader(name) { + pr.Out.Header.Del(name) + } + } + for name, value := range target.headers { + pr.Out.Header.Set(name, value) + } + }, + Transport: &authenticatingTransport{authenticate: target.authenticate, base: target.transport}, + ErrorLog: slog.NewLogLogger(logger.Handler(), slog.LevelDebug), + ErrorHandler: func(w http.ResponseWriter, r *http.Request, err error) { + log.Debugf(r.Context(), "forward to %s:%d failed: %v", target.sandboxID, remotePort, err) + http.Error(w, "forward failed: "+err.Error(), http.StatusBadGateway) + }, + } + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + switch { + case !isLoopbackHost(r.Host): + http.Error(w, "forward only accepts requests addressed to localhost", http.StatusForbidden) + case isCrossSiteRequest(r): + http.Error(w, "forward does not accept cross-site browser requests", http.StatusForbidden) + case isAmbiguousPath(r.URL.EscapedPath()): + http.Error(w, "forward does not accept . or .. path segments, malformed escapes, or segments containing ;, \\, control characters, or an encoded /, \\, %, ?, or #", http.StatusBadRequest) + default: + proxy.ServeHTTP(w, r) + } + }) +} + +// isLoopbackHost reports whether a Host header names this machine. A +// DNS-rebinding page in a browser sends its own hostname, so refusing other +// hosts keeps it from acting with the caller's credentials. +func isLoopbackHost(hostport string) bool { + host, _, err := net.SplitHostPort(hostport) + if err != nil { + host = hostport + } + if strings.EqualFold(host, "localhost") { + return true + } + ip := net.ParseIP(host) + return ip != nil && ip.IsLoopback() +} + +// isCrossSiteRequest reports whether a browser sent the request from a page +// outside this machine. WebSocket handshakes bypass CORS, so this is their only +// guard. Pages from any loopback origin, such as a local frontend, are allowed: +// browsers treat localhost and 127.0.0.1 as different sites, so their Origin +// decides rather than Sec-Fetch-Site. Requests without an Origin fall back to +// Sec-Fetch-Site, except that top-level GET navigations from other sites are +// allowed, as in the SDK, so links and sign-in redirects to the app work. +func isCrossSiteRequest(r *http.Request) bool { + if origin := r.Header.Get("Origin"); origin != "" { + u, err := url.Parse(origin) + return err != nil || !isLoopbackHost(u.Host) + } + if r.Header.Get("Sec-Fetch-Site") != "cross-site" { + return false + } + navigation := (r.Method == http.MethodGet || r.Method == http.MethodHead) && + r.Header.Get("Sec-Fetch-Mode") == "navigate" && + r.Header.Get("Sec-Fetch-Dest") == "document" + return !navigation +} + +// isAmbiguousPath reports whether a proxy on the way to the workspace could +// resolve a segment of escapedPath as "." or "..", moving the request off the +// forward route with the caller's credentials. Proxies also resolve forms +// such as a dot segment with path parameters, so only segments that decode +// once to plain text other than "." and ".." are accepted. +func isAmbiguousPath(escapedPath string) bool { + for segment := range strings.SplitSeq(escapedPath, "/") { + decoded, err := url.PathUnescape(segment) + if err != nil || decoded == "." || decoded == ".." || strings.ContainsAny(decoded, `;/\%?#`) || strings.ContainsFunc(decoded, unicode.IsControl) { + return true + } + } + return false +} + +// isPlatformHeader reports whether name starts with one of +// platformHeaderPrefixes, in any case. +func isPlatformHeader(name string) bool { + lower := strings.ToLower(name) + for _, prefix := range platformHeaderPrefixes { + if strings.HasPrefix(lower, prefix) { + return true + } + } + return false +} + +// authenticatingTransport adds the CLI's credentials to each outgoing request, +// so OAuth tokens refresh during a long-running forward. +type authenticatingTransport struct { + authenticate func(*http.Request) error + base http.RoundTripper +} + +func (t *authenticatingTransport) RoundTrip(req *http.Request) (*http.Response, error) { + // A RoundTripper must not modify the request it is given. + req = req.Clone(req.Context()) + if err := t.authenticate(req); err != nil { + return nil, fmt.Errorf("failed to authenticate with the workspace: %w", err) + } + return t.base.RoundTrip(req) +} diff --git a/cmd/sandbox/forward_test.go b/cmd/sandbox/forward_test.go new file mode 100644 index 00000000000..4b34ad60dcb --- /dev/null +++ b/cmd/sandbox/forward_test.go @@ -0,0 +1,358 @@ +package sandbox + +import ( + "bufio" + "context" + "errors" + "io" + "log/slog" + "net" + "net/http" + "net/http/httptest" + "net/url" + "strconv" + "strings" + "sync/atomic" + "testing" + + "github.com/databricks/cli/libs/cmdio" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +const testSandboxID = "happy-panda-1234" + +func TestParseForwards(t *testing.T) { + forwards, err := parseForwards([]string{"8080:10080", "0:10081"}) + require.NoError(t, err) + assert.Equal(t, []forwardSpec{{localPort: 8080, remotePort: 10080}, {localPort: 0, remotePort: 10081}}, forwards) +} + +func TestParseForwardsRejectsMalformedSpecs(t *testing.T) { + for _, spec := range []string{"8080", "8080:", ":10080", "a:10080", "8080:b", "-1:10080", "65536:10080", "8080:10080:1"} { + t.Run(spec, func(t *testing.T) { + _, err := parseForwards([]string{spec}) + assert.EqualError(t, err, `invalid -L "`+spec+`": expected LOCAL:REMOTE ports, e.g. 8080:10080`) + }) + } +} + +func TestParseForwardsRejectsRemotePortsOutsideRange(t *testing.T) { + for _, spec := range []string{"8080:0", "8080:8080", "8080:9999", "8080:65536"} { + t.Run(spec, func(t *testing.T) { + _, err := parseForwards([]string{spec}) + assert.EqualError(t, err, `invalid -L "`+spec+`": remote port must be between 10000 and 65535`) + }) + } +} + +func TestIsAmbiguousPath(t *testing.T) { + tests := []struct { + path string + want bool + }{ + {"/", false}, + {"/hello/a%20b", false}, + {"/files/%E2%9C%93", false}, + {"/a.b/.c/d..", false}, + {"/...", false}, + {"/../api/2.0/clusters/list", true}, + {"/a/./b", true}, + {"/a/..", true}, + {"/%2e%2e/api", true}, + {"/%2E/api", true}, + {"/a/..%5c..%5capi", true}, + {"/a%2F..%2Fapi", true}, + {"/hello/a%2Fb", true}, + {"/a/..;/b", true}, + {"/a/.;v=1/b", true}, + {"/a/..%3B/b", true}, + {"/a;v=1/b", true}, + {"/a/%252e%252e/b", true}, + {"/a/%zz/b", true}, + {"/a/..%00/b", true}, + {"/a/..%3F/b", true}, + {"/a/..%23/b", true}, + } + for _, tt := range tests { + t.Run(tt.path, func(t *testing.T) { + assert.Equal(t, tt.want, isAmbiguousPath(tt.path)) + }) + } +} + +// fakeAuth stands in for the SDK's config.Authenticate. +func fakeAuth(r *http.Request) error { + r.Header.Set("Authorization", "Bearer cli-token") + return nil +} + +// startForward serves a forward handler for remote port 10080 in front of upstream. +func startForward(t *testing.T, upstream *httptest.Server, authenticate func(*http.Request) error) *httptest.Server { + workspace, err := url.Parse(upstream.URL) + require.NoError(t, err) + target := forwardTarget{ + workspace: workspace, + sandboxID: testSandboxID, + authenticate: authenticate, + headers: map[string]string{"X-Databricks-Workspace-Id": "123"}, + transport: http.DefaultTransport, + } + forward := httptest.NewServer(newForwardHandler(target, 10080, slog.Default())) + t.Cleanup(forward.Close) + return forward +} + +// rawRequest sends request verbatim, so paths reach the handler without +// client-side cleaning, and returns the response status. The reader and conn +// stay usable after a 101, whose response has no body. +func rawRequest(t *testing.T, addr, request string) (int, *bufio.Reader, net.Conn) { + conn, err := net.Dial("tcp", addr) + require.NoError(t, err) + t.Cleanup(func() { conn.Close() }) + _, err = io.WriteString(conn, request) + require.NoError(t, err) + reader := bufio.NewReader(conn) + resp, err := http.ReadResponse(reader, nil) + require.NoError(t, err) + require.NoError(t, resp.Body.Close()) + return resp.StatusCode, reader, conn +} + +func TestForwardHandlerRewritesRequest(t *testing.T) { + var got *http.Request + var gotBody string + upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + body, _ := io.ReadAll(r.Body) + got, gotBody = r, string(body) + w.Header().Set("Set-Cookie", "app=1") + w.WriteHeader(http.StatusCreated) + _, _ = io.WriteString(w, "from app") + })) + defer upstream.Close() + forward := startForward(t, upstream, fakeAuth) + + req, err := http.NewRequestWithContext(t.Context(), http.MethodPost, forward.URL+"/hello/a%20b?x=1", strings.NewReader("payload")) + require.NoError(t, err) + req.Header.Set("Authorization", "Bearer local-secret") + req.Header.Set("Cookie", "sid=abc") + req.Header.Set("X-Databricks-Org-Id", "999") + req.Header.Set("X-Databricks-Workspace-Id", "999") + req.Header.Set("S2S-Principal-Context", "local") + resp, err := http.DefaultClient.Do(req) + require.NoError(t, err) + defer resp.Body.Close() + body, err := io.ReadAll(resp.Body) + require.NoError(t, err) + + assert.Equal(t, http.StatusCreated, resp.StatusCode) + assert.Equal(t, "app=1", resp.Header.Get("Set-Cookie")) + assert.Equal(t, "from app", string(body)) + + require.NotNil(t, got) + assert.Equal(t, http.MethodPost, got.Method) + assert.Equal(t, "/sandbox-proxy/sandboxes/"+testSandboxID+"/ports/10080/hello/a%20b", got.URL.EscapedPath()) + assert.Equal(t, "x=1", got.URL.RawQuery) + assert.Equal(t, strings.TrimPrefix(upstream.URL, "http://"), got.Host) + assert.Equal(t, "Bearer cli-token", got.Header.Get("Authorization")) + assert.Equal(t, "123", got.Header.Get("X-Databricks-Workspace-Id")) + assert.Empty(t, got.Header.Get("X-Databricks-Org-Id")) + assert.Empty(t, got.Header.Get("S2S-Principal-Context")) + assert.Equal(t, "sid=abc", got.Header.Get("Cookie")) + assert.Empty(t, got.Header.Get("X-Forwarded-For")) + assert.Equal(t, "payload", gotBody) +} + +func TestForwardHandlerRejectsAmbiguousPaths(t *testing.T) { + var calls atomic.Int32 + upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + calls.Add(1) + })) + defer upstream.Close() + forward := startForward(t, upstream, fakeAuth) + addr := strings.TrimPrefix(forward.URL, "http://") + + for _, path := range []string{"/../../api/2.0/clusters/list", "/%2e%2e/api/2.0/clusters/list", "/a/..%5c..%5capi", "/..;/..;/api/2.0/clusters/list", "/..%3b/api/2.0/clusters/list"} { + t.Run(path, func(t *testing.T) { + status, _, _ := rawRequest(t, addr, "GET "+path+" HTTP/1.1\r\nHost: "+addr+"\r\nConnection: close\r\n\r\n") + assert.Equal(t, http.StatusBadRequest, status) + }) + } + assert.Zero(t, calls.Load()) +} + +func TestForwardHandlerRejectsForeignHost(t *testing.T) { + var calls atomic.Int32 + upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + calls.Add(1) + })) + defer upstream.Close() + forward := startForward(t, upstream, fakeAuth) + addr := strings.TrimPrefix(forward.URL, "http://") + + status, _, _ := rawRequest(t, addr, "GET / HTTP/1.1\r\nHost: rebound.example:8080\r\nConnection: close\r\n\r\n") + assert.Equal(t, http.StatusForbidden, status) + assert.Zero(t, calls.Load()) +} + +func TestForwardHandlerRejectsCrossSiteRequests(t *testing.T) { + var calls atomic.Int32 + upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + calls.Add(1) + })) + defer upstream.Close() + forward := startForward(t, upstream, fakeAuth) + addr := strings.TrimPrefix(forward.URL, "http://") + + for name, headers := range map[string]string{ + "foreign origin": "Origin: https://attacker.example\r\n", + "null origin": "Origin: null\r\n", + "cross-site fetch": "Sec-Fetch-Site: cross-site\r\n", + "cross-site websocket": "Origin: https://attacker.example\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n", + "cross-site iframe": "Sec-Fetch-Site: cross-site\r\nSec-Fetch-Mode: navigate\r\nSec-Fetch-Dest: iframe\r\n", + } { + t.Run(name, func(t *testing.T) { + status, _, _ := rawRequest(t, addr, "GET / HTTP/1.1\r\nHost: "+addr+"\r\n"+headers+"Connection: close\r\n\r\n") + assert.Equal(t, http.StatusForbidden, status) + }) + } + assert.Zero(t, calls.Load()) +} + +func TestForwardHandlerAllowsLocalOrigins(t *testing.T) { + var calls atomic.Int32 + upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + calls.Add(1) + })) + defer upstream.Close() + forward := startForward(t, upstream, fakeAuth) + addr := strings.TrimPrefix(forward.URL, "http://") + + for _, headers := range []string{ + "Origin: http://localhost:3000\r\nSec-Fetch-Site: same-site\r\n", + "Origin: http://" + addr + "\r\nSec-Fetch-Site: same-origin\r\n", + // Browsers treat localhost and 127.0.0.1 as different sites. + "Origin: http://localhost:5173\r\nSec-Fetch-Site: cross-site\r\n", + "Sec-Fetch-Site: none\r\n", + } { + status, _, _ := rawRequest(t, addr, "POST / HTTP/1.1\r\nHost: "+addr+"\r\n"+headers+"Content-Length: 0\r\nConnection: close\r\n\r\n") + assert.Equal(t, http.StatusOK, status, headers) + } + assert.Equal(t, int32(4), calls.Load()) +} + +func TestForwardHandlerAllowsCrossSiteNavigations(t *testing.T) { + var calls atomic.Int32 + upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + calls.Add(1) + })) + defer upstream.Close() + forward := startForward(t, upstream, fakeAuth) + addr := strings.TrimPrefix(forward.URL, "http://") + + navigation := "Sec-Fetch-Site: cross-site\r\nSec-Fetch-Mode: navigate\r\nSec-Fetch-Dest: document\r\n" + status, _, _ := rawRequest(t, addr, "GET / HTTP/1.1\r\nHost: "+addr+"\r\n"+navigation+"Connection: close\r\n\r\n") + assert.Equal(t, http.StatusOK, status, "a link or sign-in redirect from another site") + + // Only GET and HEAD navigations: a form post from another site is refused. + status, _, _ = rawRequest(t, addr, "POST / HTTP/1.1\r\nHost: "+addr+"\r\n"+navigation+"Content-Length: 0\r\nConnection: close\r\n\r\n") + assert.Equal(t, http.StatusForbidden, status) + assert.Equal(t, int32(1), calls.Load()) +} + +func TestIsLoopbackHost(t *testing.T) { + tests := []struct { + host string + want bool + }{ + {"127.0.0.1:8080", true}, + {"localhost:8080", true}, + {"LOCALHOST:8080", true}, + {"[::1]:8080", true}, + {"localhost", true}, + {"rebound.example:8080", false}, + {"10.0.0.1:8080", false}, + {"", false}, + } + for _, tt := range tests { + t.Run(tt.host, func(t *testing.T) { + assert.Equal(t, tt.want, isLoopbackHost(tt.host)) + }) + } +} + +func TestForwardHandlerRelaysUpgrade(t *testing.T) { + upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Header.Get("Upgrade") != "websocket" { + http.Error(w, "expected an upgrade", http.StatusBadRequest) + return + } + conn, buf, err := http.NewResponseController(w).Hijack() + if err != nil { + return + } + defer conn.Close() + _, _ = buf.WriteString("HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n\r\n") + _ = buf.Flush() + _, _ = io.Copy(conn, buf) + })) + defer upstream.Close() + forward := startForward(t, upstream, fakeAuth) + addr := strings.TrimPrefix(forward.URL, "http://") + + status, reader, conn := rawRequest(t, addr, "GET /ws HTTP/1.1\r\nHost: "+addr+"\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n\r\n") + require.Equal(t, http.StatusSwitchingProtocols, status) + + _, err := io.WriteString(conn, "ping") + require.NoError(t, err) + echo := make([]byte, 4) + _, err = io.ReadFull(reader, echo) + require.NoError(t, err) + assert.Equal(t, "ping", string(echo)) +} + +func TestForwardHandlerReportsAuthFailure(t *testing.T) { + var calls atomic.Int32 + upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + calls.Add(1) + })) + defer upstream.Close() + forward := startForward(t, upstream, func(*http.Request) error { return errors.New("token expired") }) + + resp, err := http.Get(forward.URL + "/") + require.NoError(t, err) + defer resp.Body.Close() + body, err := io.ReadAll(resp.Body) + require.NoError(t, err) + + assert.Equal(t, http.StatusBadGateway, resp.StatusCode) + assert.Contains(t, string(body), "failed to authenticate with the workspace: token expired") + assert.Zero(t, calls.Load()) +} + +func TestServeForwardsFailsWhenLocalPortInUse(t *testing.T) { + taken, err := net.Listen("tcp", net.JoinHostPort(forwardBindHost, "0")) + require.NoError(t, err) + defer taken.Close() + port := taken.Addr().(*net.TCPAddr).Port + + err = serveForwards(cmdio.MockDiscard(t.Context()), testTarget(), []forwardSpec{{localPort: 0, remotePort: 10080}, {localPort: port, remotePort: 10081}}) + assert.ErrorContains(t, err, "failed to listen on local port "+strconv.Itoa(port)) +} + +func TestServeForwardsStopsWhenContextIsDone(t *testing.T) { + ctx, cancel := context.WithCancel(cmdio.MockDiscard(t.Context())) + cancel() + + err := serveForwards(ctx, testTarget(), []forwardSpec{{localPort: 0, remotePort: 10080}}) + assert.NoError(t, err) +} + +func testTarget() forwardTarget { + return forwardTarget{ + workspace: &url.URL{Scheme: "https", Host: "workspace.test"}, + sandboxID: testSandboxID, + authenticate: fakeAuth, + transport: http.DefaultTransport, + } +} diff --git a/cmd/sandbox/resolve.go b/cmd/sandbox/resolve.go index 21bbcb841b6..553163fdf8f 100644 --- a/cmd/sandbox/resolve.go +++ b/cmd/sandbox/resolve.go @@ -5,6 +5,8 @@ import ( "errors" "fmt" "strings" + + "github.com/databricks/databricks-sdk-go/apierr" ) // resolveLocalID maps a user-typed argument to a sandbox ID using only @@ -61,3 +63,59 @@ func resolveLocalID(ctx context.Context, profile, arg string) (string, error) { ) } } + +// defaultSandboxHint ends the errors for a missing or stale default sandbox. +const defaultSandboxHint = "run `databricks sandbox create` to provision one, or `databricks sandbox default ` to set an existing sandbox as the default" + +// resolveSandbox returns the ID of the sandbox named by arg, or of the +// profile's default sandbox when arg is empty, and the sandbox as the server +// reports it. The entry is nil when the lookup failed with an error other than +// not-found or a rejected request: those only warn, so a transient API hiccup +// doesn't block a connection the gateway can still route. +func resolveSandbox(ctx context.Context, api *sandboxAPI, profile, arg string) (string, *sandboxEntry, error) { + var sandboxID string + if arg == "" { + if sandboxID = getDefault(ctx, profile); sandboxID == "" { + return "", nil, errors.New("no default sandbox configured — " + defaultSandboxHint) + } + } else { + resolved, err := resolveLocalID(ctx, profile, arg) + if err != nil { + return "", nil, err + } + sandboxID = resolved + } + if err := validateSandboxID(sandboxID); err != nil { + return "", nil, err + } + + sb, err := api.get(ctx, sandboxID) + switch { + case err == nil: + return sandboxID, sb, nil + case errors.Is(err, apierr.ErrNotFound) && arg == "": + // A stale default is almost always user-correctable (deleted from + // another machine, reaped by an admin); fail fast with an actionable + // message. + _ = clearDefault(ctx, profile) + return "", nil, fmt.Errorf("saved default %q no longer exists (cleared) — %s", sandboxID, defaultSandboxHint) + case errors.Is(err, apierr.ErrNotFound): + return "", nil, fmt.Errorf("no sandbox named %q — `databricks sandbox list` shows available IDs", sandboxID) + case errors.Is(err, apierr.ErrBadRequest): + return "", nil, fmt.Errorf("failed to look up sandbox %s: %w", sandboxID, err) + default: + warn(ctx, fmt.Sprintf("Could not resolve sandbox %s: %v", sandboxID, err)) + return sandboxID, nil, nil + } +} + +// validateSandboxID rejects IDs that are not a single path segment. Commands +// put the ID in workspace URL paths, and the workspace decodes an escaped "/", +// so a separator or dot segment would move a request onto another API with the +// caller's credentials. +func validateSandboxID(id string) error { + if id == "." || id == ".." || strings.ContainsAny(id, `/\`) { + return fmt.Errorf("invalid sandbox ID %q", id) + } + return nil +} diff --git a/cmd/sandbox/resolve_test.go b/cmd/sandbox/resolve_test.go index b4b13f2b47a..69087aad5b4 100644 --- a/cmd/sandbox/resolve_test.go +++ b/cmd/sandbox/resolve_test.go @@ -1,9 +1,16 @@ package sandbox import ( + "encoding/json" + "fmt" + "io" + "net/http" + "net/http/httptest" "os" "testing" + "github.com/databricks/cli/libs/cmdio" + "github.com/databricks/databricks-sdk-go" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" ) @@ -150,3 +157,93 @@ func TestRemoveSandboxKeepsGatewayHostWhileSandboxesRemain(t *testing.T) { require.NoError(t, removeSandbox(ctx, "p", "drop")) assert.Equal(t, "gw.example.test", getGatewayHost(ctx, "p")) } + +// newLookupAPI returns a sandbox API whose GET for testSandboxID answers with status. +func newLookupAPI(t *testing.T, status int) *sandboxAPI { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path == "/.well-known/databricks-config" { + assert.NoError(t, json.NewEncoder(w).Encode(map[string]string{ + "oidc_endpoint": "https://workspace.example.test/oidc", + })) + return + } + assert.Equal(t, sandboxPath(testSandboxID), r.URL.Path) + w.WriteHeader(status) + if status == http.StatusOK { + assert.NoError(t, json.NewEncoder(w).Encode(sandboxEntry{SandboxID: testSandboxID, Status: "Running"})) + return + } + _, _ = io.WriteString(w, `{"error_code": "ERROR", "message": "lookup failed"}`) + })) + t.Cleanup(server.Close) + + workspaceClient, err := databricks.NewWorkspaceClient(&databricks.Config{Host: server.URL, Token: "test-token"}) + require.NoError(t, err) + api, err := newSandboxAPI(workspaceClient) + require.NoError(t, err) + return api +} + +func TestResolveSandboxUsesDefault(t *testing.T) { + ctx, _ := stateCtx(t) + ctx = cmdio.MockDiscard(ctx) + require.NoError(t, setDefault(ctx, "profile", testSandboxID)) + + got, sb, err := resolveSandbox(ctx, newLookupAPI(t, http.StatusOK), "profile", "") + require.NoError(t, err) + assert.Equal(t, testSandboxID, got) + assert.Equal(t, "Running", sb.Status) +} + +func TestResolveSandboxClearsMissingDefault(t *testing.T) { + ctx, _ := stateCtx(t) + ctx = cmdio.MockDiscard(ctx) + require.NoError(t, setDefault(ctx, "profile", testSandboxID)) + + _, _, err := resolveSandbox(ctx, newLookupAPI(t, http.StatusNotFound), "profile", "") + assert.ErrorContains(t, err, `saved default "`+testSandboxID+`" no longer exists (cleared)`) + assert.Empty(t, getDefault(ctx, "profile")) +} + +func TestResolveSandboxRejectsUnknownID(t *testing.T) { + ctx, _ := stateCtx(t) + ctx = cmdio.MockDiscard(ctx) + + _, _, err := resolveSandbox(ctx, newLookupAPI(t, http.StatusNotFound), "profile", testSandboxID) + assert.ErrorContains(t, err, `no sandbox named "`+testSandboxID+`"`) +} + +func TestResolveSandboxFailsOnRejectedLookup(t *testing.T) { + ctx, _ := stateCtx(t) + ctx = cmdio.MockDiscard(ctx) + + _, _, err := resolveSandbox(ctx, newLookupAPI(t, http.StatusBadRequest), "profile", testSandboxID) + assert.ErrorContains(t, err, "failed to look up sandbox "+testSandboxID) +} + +func TestResolveSandboxContinuesOnOtherLookupErrors(t *testing.T) { + ctx, _ := stateCtx(t) + ctx = cmdio.MockDiscard(ctx) + + got, sb, err := resolveSandbox(ctx, newLookupAPI(t, http.StatusForbidden), "profile", testSandboxID) + require.NoError(t, err) + assert.Equal(t, testSandboxID, got) + assert.Nil(t, sb) +} + +func TestResolveSandboxRejectsIDsThatAreNotOneSegment(t *testing.T) { + ctx, _ := stateCtx(t) + for _, id := range []string{".", "..", "a/../../api/2.0", `a\..\b`} { + t.Run(id, func(t *testing.T) { + _, _, err := resolveSandbox(ctx, nil, "profile", id) + assert.EqualError(t, err, fmt.Sprintf("invalid sandbox ID %q", id)) + }) + } +} + +func TestResolveSandboxRequiresDefault(t *testing.T) { + ctx, _ := stateCtx(t) + + _, _, err := resolveSandbox(ctx, nil, "profile", "") + assert.ErrorContains(t, err, "no default sandbox configured") +} diff --git a/cmd/sandbox/sandbox.go b/cmd/sandbox/sandbox.go index 9b40c16d370..e732ba6b547 100644 --- a/cmd/sandbox/sandbox.go +++ b/cmd/sandbox/sandbox.go @@ -29,6 +29,7 @@ Common workflows: databricks sandbox create # create a new sandbox databricks sandbox delete my-project # delete a sandbox databricks sandbox status my-project # show sandbox status + databricks sandbox forward -L 8080:10080 # open sandbox port 10080 at localhost:8080 `, } @@ -36,6 +37,7 @@ Common workflows: cmd.AddCommand(newSSHKeyCommand()) cmd.AddCommand(newSetDefaultCommand()) cmd.AddCommand(newSSHCommand()) + cmd.AddCommand(newForwardCommand()) cmd.AddCommand(newListCommand()) cmd.AddCommand(newCreateCommand()) cmd.AddCommand(newDeleteCommand()) diff --git a/cmd/sandbox/ssh.go b/cmd/sandbox/ssh.go index 7fbe7df1c20..711bbd8b9a4 100644 --- a/cmd/sandbox/ssh.go +++ b/cmd/sandbox/ssh.go @@ -13,7 +13,6 @@ import ( "github.com/databricks/cli/libs/cmdio" "github.com/databricks/cli/libs/execv" "github.com/databricks/cli/libs/shellquote" - "github.com/databricks/databricks-sdk-go/apierr" "github.com/spf13/cobra" ) @@ -72,21 +71,6 @@ Examples: extraArgs = args[dashAt:] } - if sandboxID != "" { - resolved, err := resolveLocalID(ctx, profile, sandboxID) - if err != nil { - return err - } - sandboxID = resolved - } - - // Captured from any Sandbox response we touch below; "" when - // we never hit the API in this invocation. - var ( - sandboxGatewayHost string - sandboxStatus string - ) - api, err := newSandboxAPI(w) if err != nil { return err @@ -97,47 +81,19 @@ Examples: return err } - if sandboxID == "" { - def := getDefault(ctx, profile) - if def == "" { - return errors.New("no default sandbox configured — run `databricks sandbox create` to provision one, or `databricks sandbox default ` to point at an existing sandbox") - } - // Confirm the saved default still exists. A stale entry is - // almost always user-correctable (deleted from another - // machine, reaped by an admin); fail fast with an actionable - // message rather than silently provisioning a fresh sandbox - // and surprising the user with a bill. - sb, err := api.get(ctx, def) - switch { - case err == nil: - sandboxID = def - sandboxGatewayHost = sb.GatewayHost - sandboxStatus = sb.Status - case errors.Is(err, apierr.ErrNotFound): - _ = clearDefault(ctx, profile) - return fmt.Errorf("saved default %q no longer exists (cleared) — run `databricks sandbox create` to provision a new one, or `databricks sandbox default ` to point at an existing sandbox", def) - default: - warn(ctx, fmt.Sprintf("Could not validate default %s: %v", def, err)) - sandboxID = def - } - } else { - // Validate the explicit ID against the server. Two reasons: - // 1. Surface `sandbox ssh fake-id` as a clear 404 instead of - // letting the user wade through `Permission denied` from - // ssh when the gateway can't route an unknown sandbox. - // 2. Capture `gateway_host` to drive the resolution below. - // Non-NotFound errors fall through so transient API hiccups - // don't block a connection the gateway can still route. - sb, err := api.get(ctx, sandboxID) - switch { - case err == nil: - sandboxGatewayHost = sb.GatewayHost - sandboxStatus = sb.Status - case errors.Is(err, apierr.ErrNotFound): - return fmt.Errorf("no sandbox named %q — `databricks sandbox list` shows available IDs", sandboxID) - default: - warn(ctx, fmt.Sprintf("Could not validate sandbox %s: %v", sandboxID, err)) - } + // Validating the sandbox against the server surfaces an unknown ID + // as a clear 404 instead of ssh's `Permission denied` when the + // gateway can't route it, and captures `gateway_host` for the + // resolution below. + sandboxID, sb, err := resolveSandbox(ctx, api, profile, sandboxID) + if err != nil { + return err + } + // "" when the lookup only warned. + var sandboxGatewayHost, sandboxStatus string + if sb != nil { + sandboxGatewayHost = sb.GatewayHost + sandboxStatus = sb.Status } // Drive start ourselves so the user sees a spinner instead