Use dynamic ports for Steve to avoid conflicts with other software

Steve previously listened on hardcoded port 9443, which could conflict
with other software. Allocate both the HTTPS and HTTP ports dynamically
at startup and propagate them to Steve, the dashboard proxy, and the
certificate-error handler.

Key changes:

- Add getAvailablePorts(), which binds all requested ports simultaneously
  before releasing any, guaranteeing distinct values despite the inherent
  TOCTOU window.

- Accept port arguments in Steve.start() instead of using a constant.
  Let startup errors propagate to the caller instead of swallowing them;
  the state-changed handler catches them locally so the Kubernetes ready
  notification still reaches the UI.

- Recreate dashboard proxy middleware on each Steve start via a new
  setStevePort() method.  Express routes use wrapper functions that
  dereference the current proxy instances, so routes survive recreation
  without re-registration.

- Add /api/steve-port endpoint for Rancher Dashboard to discover the
  dynamic HTTPS port.

- Rename the networking module's port setter to setSteveCertPort() to
  distinguish it from DashboardServer.setStevePort().

- Bump rancherDashboard to 2.11.1.rd4 (consumes the new endpoint).

Signed-off-by: Jan Dubois <jan.dubois@suse.com>

Author: jandubois

.github/actions/spelling/expect.txt

@@ -641,6 +641,7 @@ toggleable
 togglefullscreen
 tonistiigi
 toolsets
+TOCTOU
 topmenu
 TQF
 traefik

background.ts

@@ -35,7 +35,7 @@ import { ImageEventHandler } from '@pkg/main/imageEvents';
 import { getIpcMainProxy } from '@pkg/main/ipcMain';
 import mainEvents from '@pkg/main/mainEvents';
 import buildApplicationMenu from '@pkg/main/mainmenu';
-import setupNetworking from '@pkg/main/networking';
+import setupNetworking, { setSteveCertPort } from '@pkg/main/networking';
 import { Snapshots } from '@pkg/main/snapshots/snapshots';
 import { Snapshot, SnapshotDialog } from '@pkg/main/snapshots/types';
 import { Tray } from '@pkg/main/tray';
@@ -45,6 +45,7 @@ import getCommandLineArgs from '@pkg/utils/commandLine';
 import dockerDirManager from '@pkg/utils/dockerDirManager';
 import { isDevEnv } from '@pkg/utils/environment';
 import Logging, { clearLoggingDirectory, setLogLevel } from '@pkg/utils/logging';
+import { getAvailablePorts } from '@pkg/utils/networks';
 import { fetchMacOsVersion, getMacOsVersion } from '@pkg/utils/osVersion';
 import paths from '@pkg/utils/paths';
 import { protocolsRegistered, setupProtocolHandlers } from '@pkg/utils/protocols';
@@ -1268,21 +1269,29 @@ function newK8sManager() {
 
   mgr.on('state-changed', async(state: K8s.State) => {
     try {
-      mainEvents.emit('k8s-check-state', mgr);
-
       if ([K8s.State.STARTED, K8s.State.DISABLED].includes(state)) {
         if (!cfg.kubernetes.version) {
           writeSettings({ kubernetes: { version: mgr.kubeBackend.version } });
         }
         currentImageProcessor?.relayNamespaces();
 
         if (enabledK8s) {
-          await Steve.getInstance().start();
+          try {
+            const [steveHttpsPort, steveHttpPort] = await getAvailablePorts(2);
+
+            console.log(`Steve ports: HTTPS=${ steveHttpsPort } HTTP=${ steveHttpPort }`);
+            await Steve.getInstance().start(steveHttpsPort, steveHttpPort);
+            DashboardServer.getInstance().setStevePort(steveHttpsPort); // recreate proxy middleware
+            setSteveCertPort(steveHttpsPort); // update certificate-error allowed URLs
+          } catch (ex) {
+            console.error('Failed to start Steve:', ex);
+          }
         }
       }
 
-      // Notify UI after Steve is ready, so the dashboard button is only enabled
-      // when Steve can accept connections.
+      // Notify the tray and renderer after Steve is ready, so the dashboard
+      // button is only enabled when Steve can accept connections.
+      mainEvents.emit('k8s-check-state', mgr);
       window.send('k8s-check-state', state);
 
       if (state === K8s.State.STOPPING) {

pkg/rancher-desktop/assets/dependencies.yaml

@@ -13,7 +13,7 @@ dockerCompose: 5.1.0
 golangci-lint: 2.11.3
 trivy: 0.69.3
 steve: 0.1.0-beta9.1
-rancherDashboard: 2.11.1.rd3
+rancherDashboard: 2.11.1.rd4
 dockerProvidedCredentialHelpers: 0.9.5
 ECRCredentialHelper: 0.12.0
 mobyOpenAPISpec: "1.54"

pkg/rancher-desktop/backend/steve.ts

@@ -8,18 +8,17 @@ import K3sHelper from '@pkg/backend/k3sHelper';
 import Logging from '@pkg/utils/logging';
 import paths from '@pkg/utils/paths';
 
-const STEVE_PORT = 9443;
-
 const console = Logging.steve;
 
 /**
- * @description Singleton that manages the lifecycle of the Steve API
+ * @description Singleton that manages the lifecycle of the Steve API.
  */
 export class Steve {
   private static instance: Steve;
   private process!:        ChildProcess;
 
   private isRunning: boolean;
+  private httpsPort = 0;
 
   private constructor() {
     this.isRunning = false;
@@ -40,8 +39,10 @@ export class Steve {
   /**
    * @description Starts the Steve API if one is not already running.
    * Returns only after Steve is ready to accept connections.
+   * @param httpsPort The HTTPS port for Steve to listen on.
+   * @param httpPort The HTTP port for Steve to listen on.
    */
-  public async start() {
+  public async start(httpsPort: number, httpPort: number) {
     const { pid } = this.process || { };
 
     if (this.isRunning && pid) {
@@ -50,6 +51,8 @@ export class Steve {
       return;
     }
 
+    this.httpsPort = httpsPort;
+
     const osSpecificName = /^win/i.test(os.platform()) ? 'steve.exe' : 'steve';
     const stevePath = path.join(paths.resources, os.platform(), 'internal', osSpecificName);
     const env = Object.assign({}, process.env);
@@ -68,6 +71,10 @@ export class Steve {
         path.join(paths.resources, 'rancher-dashboard'),
         '--offline',
         'true',
+        '--https-listen-port',
+        String(httpsPort),
+        '--http-listen-port',
+        String(httpPort),
       ],
       { env },
     );
@@ -93,22 +100,18 @@ export class Steve {
       this.isRunning = false;
     });
 
-    try {
-      await new Promise<void>((resolve, reject) => {
-        this.process.once('spawn', () => {
-          this.isRunning = true;
-          console.debug(`Spawned child pid: ${ this.process.pid }`);
-          resolve();
-        });
-        this.process.once('error', (err) => {
-          reject(new Error(`Failed to spawn Steve: ${ err.message }`, { cause: err }));
-        });
+    await new Promise<void>((resolve, reject) => {
+      this.process.once('spawn', () => {
+        this.isRunning = true;
+        console.debug(`Spawned child pid: ${ this.process.pid }`);
+        resolve();
       });
+      this.process.once('error', (err) => {
+        reject(new Error(`Failed to spawn Steve: ${ err.message }`, { cause: err }));
+      });
+    });
 
-      await this.waitForReady();
-    } catch (ex) {
-      console.error(ex);
-    }
+    await this.waitForReady();
   }
 
   /**
@@ -136,7 +139,7 @@ export class Steve {
   }
 
   /**
-   * Check if Steve is accepting connections on its port.
+   * Check if Steve is accepting connections on its HTTPS port.
    */
   private isPortReady(): Promise<boolean> {
     return new Promise((resolve) => {
@@ -155,7 +158,7 @@ export class Steve {
         socket.destroy();
         resolve(false);
       });
-      socket.connect(STEVE_PORT, '127.0.0.1');
+      socket.connect(this.httpsPort, '127.0.0.1');
     });
   }
 

pkg/rancher-desktop/main/dashboardServer/index.ts

@@ -26,9 +26,28 @@ export class DashboardServer {
   private dashboardApp: Server = new Server();
   private host = '127.0.0.1';
   private port = 6120;
-  private api = 'https://127.0.0.1:9443';
+  private stevePort = 0;
+  private proxies:      Record<string, ReturnType<typeof createProxyMiddleware>> = Object.create(null);
 
-  private proxies = (() => {
+  /**
+   * Checks for an existing instance of Dashboard server.
+   * Instantiate a new one if it does not exist.
+   */
+  public static getInstance(): DashboardServer {
+    DashboardServer.instance ??= new DashboardServer();
+
+    return DashboardServer.instance;
+  }
+
+  /**
+   * Recreate proxy middleware instances with the current Steve URL as
+   * the target.  Each proxy must be created with a static `target` (not
+   * a dynamic `router`) because the onProxyReqWs callback in proxyUtils
+   * reads options.target to correct websocket paths — without a valid
+   * target URL, it destroys every websocket connection.
+   */
+  private createProxies() {
+    const api = `https://127.0.0.1:${ this.stevePort }`;
     const proxy: Record<ProxyKeys, Options> = {
       '/k8s':       proxyWsOpts, // Straight to a remote cluster (/k8s/clusters/<id>/)
       '/pp':        proxyWsOpts, // For (epinio) standalone API
@@ -42,20 +61,19 @@ export class DashboardServer {
       '/v1-*etc':   proxyOpts, // SAML, KDM, etc
     };
     const entries = Object.entries(proxy).map(([key, options]) => {
-      return [key, createProxyMiddleware({ ...options, target: this.api + key })] as const;
+      return [key, createProxyMiddleware({ ...options, target: api + key })] as const;
     });
 
-    return Object.fromEntries(entries);
-  })();
+    this.proxies = Object.fromEntries(entries) as typeof this.proxies;
+  }
 
   /**
-   * Checks for an existing instance of Dashboard server.
-   * Instantiate a new one if it does not exist.
+   * Update the Steve HTTPS port and recreate proxies with the new
+   * target.  Call this before each Steve start.
    */
-  public static getInstance(): DashboardServer {
-    DashboardServer.instance ??= new DashboardServer();
-
-    return DashboardServer.instance;
+  public setStevePort(stevePort: number) {
+    this.stevePort = stevePort;
+    this.createProxies();
   }
 
   /**
@@ -68,8 +86,24 @@ export class DashboardServer {
       return;
     }
 
+    // Consumed by Rancher Dashboard to discover Steve's dynamic HTTPS
+    // port.  Registered before the proxy routes so it is not captured
+    // by the /api proxy to Steve.
+    this.dashboardServer.get('/api/steve-port', (_req, res) => {
+      res.json({ port: this.stevePort });
+    });
+
+    // Register wrapper functions so that when createProxies() replaces
+    // this.proxies (on each Steve restart), express and the upgrade
+    // handler automatically use the new instances.  The optional
+    // chaining is safe: proxies are always created before the UI is
+    // notified that Kubernetes is ready, and the dashboard button is
+    // disabled until then.
+    //
+    // ?? next() fires only when the proxy is absent: createProxyMiddleware
+    // returns an async function, so the call always yields a Promise (truthy).
     ProxyKeys.forEach((key) => {
-      this.dashboardServer.use(key, this.proxies[key]);
+      this.dashboardServer.use(key, (req, res, next) => this.proxies[key]?.(req, res, next) ?? next());
     });
 
     this.dashboardApp = this.dashboardServer
@@ -99,17 +133,22 @@ export class DashboardServer {
           return;
         }
 
-        if (req.url?.startsWith('/v1')) {
-          return this.proxies['/v1'].upgrade(req, socket, head);
-        } else if (req.url?.startsWith('/v3')) {
-          return this.proxies['/v3'].upgrade(req, socket, head);
-        } else if (req.url?.startsWith('/k8s/')) {
-          return this.proxies['/k8s'].upgrade(req, socket, head);
-        } else if (req.url?.startsWith('/api/')) {
-          return this.proxies['/api'].upgrade(req, socket, head);
-        } else {
-          console.log(`Unknown Web socket upgrade request for ${ req.url }`);
+        // TODO: drive this from ProxyKeys instead of maintaining a parallel list.
+        const key = req.url?.startsWith('/v1')
+          ? '/v1'
+          : req.url?.startsWith('/v3')
+            ? '/v3'
+            : req.url?.startsWith('/k8s/')
+              ? '/k8s'
+              : req.url?.startsWith('/api/')
+                ? '/api'
+                : undefined;
+
+        if (key) {
+          return this.proxies[key]?.upgrade(req, socket, head);
         }
+        console.log(`Unknown Web socket upgrade request for ${ req.url }`);
+        socket.destroy();
       });
   }
 

pkg/rancher-desktop/main/networking/index.ts

@@ -17,6 +17,17 @@ import { windowMapping } from '@pkg/window';
 
 const console = Logging.networking;
 
+let stevePort = 0;
+
+/**
+ * Update the Steve HTTPS port used by the certificate-error handler.
+ * Call this before each Steve start so that dynamic port changes are
+ * reflected in the allowed-URL list.
+ */
+export function setSteveCertPort(port: number) {
+  stevePort = port;
+}
+
 export default async function setupNetworking() {
   const agentOptions = { ...https.globalAgent.options };
 
@@ -42,10 +53,11 @@ export default async function setupNetworking() {
 
   // Set up certificate handling for system certificates on Windows and macOS
   Electron.app.on('certificate-error', async(event, webContents, url, error, certificate, callback) => {
-    const tlsPort = 9443;
+    // stevePort is 0 until setSteveCertPort() is called, which is harmless:
+    // no cert errors for Steve can arrive before Steve starts.
     const dashboardUrls = [
-      `https://127.0.0.1:${ tlsPort }`,
-      `wss://127.0.0.1:${ tlsPort }`,
+      `https://127.0.0.1:${ stevePort }`,
+      `wss://127.0.0.1:${ stevePort }`,
       'http://127.0.0.1:6120',
       'ws://127.0.0.1:6120',
     ];

pkg/rancher-desktop/utils/__tests__/networks.spec.ts

@@ -0,0 +1,43 @@
+import net from 'net';
+
+import { getAvailablePorts } from '../networks';
+
+describe('getAvailablePorts', () => {
+  it('returns the requested number of ports', async() => {
+    const ports = await getAvailablePorts(3);
+
+    expect(ports).toHaveLength(3);
+  });
+
+  it('returns ports greater than zero', async() => {
+    const ports = await getAvailablePorts(2);
+
+    for (const port of ports) {
+      expect(port).toBeGreaterThan(0);
+    }
+  });
+
+  it('returns usable ports', async() => {
+    const ports = await getAvailablePorts(2);
+
+    // Verify both returned ports can actually be bound.
+    for (const port of ports) {
+      const server = net.createServer();
+
+      await new Promise<void>((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', resolve);
+      });
+
+      await new Promise<void>((resolve) => {
+        server.close(() => resolve());
+      });
+    }
+  });
+
+  it('returns distinct ports', async() => {
+    const ports = await getAvailablePorts(2);
+
+    expect(ports[0]).not.toBe(ports[1]);
+  });
+});