Fall back to a free port when the dashboard port is unavailable

Starting the dashboard on a port that is already in use or blocked by the OS
raised an unhandled error (for example Windows error 10013) and printed a stack
trace. It now tries a short list of fallback ports and finally an OS-assigned
one, and reports the address it actually bound.

Author: sanmaxdev

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project are documented here. The format is loosely
 based on [Keep a Changelog](https://keepachangelog.com/), and the project aims
 to follow semantic versioning once it reaches 1.0.
 
+## [2.2.1] - 2026-06-29
+
+### Fixed
+
+- `sentineldeck dashboard` no longer crashes with a stack trace when its port is
+  already in use or blocked by the OS (for example Windows error 10013). It now
+  falls back to another free port — and finally an OS-assigned one — and prints
+  the address it actually bound.
+
 ## [2.2.0] - 2026-06-29
 
 ### Added

src/sentineldeck/__init__.py

@@ -1,3 +1,3 @@
 """SentinelDeck: passive attack-surface visibility for small businesses."""
 
-__version__ = "2.2.0"
+__version__ = "2.2.1"

src/sentineldeck/dashboard.py

@@ -12,6 +12,7 @@
 from __future__ import annotations
 
 import json
+import sys
 import webbrowser
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
@@ -98,10 +99,39 @@ def _scan(self) -> None:
     return DashboardHandler
 
 
+def _bind(host: str, port: int, timeout: int) -> ThreadingHTTPServer | None:
+    """Try to bind the dashboard server to ``port``; return None if unavailable."""
+    try:
+        return ThreadingHTTPServer((host, port), _make_handler(timeout))
+    except OSError:
+        # Port in use by another app, or blocked/reserved by the OS (e.g. Windows
+        # WinError 10013 / Hyper-V reserved ranges). Caller falls back.
+        return None
+
+
 def serve(host: str = "127.0.0.1", port: int = 8765, open_browser: bool = True, timeout: int = 10) -> int:
     """Run the dashboard server until interrupted. Returns a process exit code."""
-    httpd = ThreadingHTTPServer((host, port), _make_handler(timeout))
-    url = f"http://{host}:{port}"
+    # The requested port may be taken or blocked, so fall back to other ports and
+    # finally an OS-assigned one (0) instead of crashing with a stack trace.
+    candidates: list[int] = []
+    for candidate in (port, 8765, 8780, 8800, 8888, 9000, 0):
+        if candidate not in candidates:
+            candidates.append(candidate)
+
+    httpd = next((s for s in (_bind(host, c, timeout) for c in candidates) if s is not None), None)
+    if httpd is None:
+        print(
+            f"Could not start the dashboard: no free port was available "
+            f"(tried {', '.join(str(c) for c in candidates if c)}). "
+            f"Free a port or pass --port.",
+            file=sys.stderr,
+        )
+        return 1
+
+    actual = httpd.server_address[1]
+    if actual != port:
+        print(f"Port {port} was unavailable, so the dashboard is using port {actual} instead.")
+    url = f"http://{host}:{actual}"
     print(f"SentinelDeck dashboard running at {url}")
     print("Press Ctrl+C to stop.")
     if open_browser:

tests/test_dashboard.py

@@ -17,6 +17,45 @@ def _get(port, path):
         return response.status, response.read().decode("utf-8")
 
 
+def test_bind_returns_none_when_port_is_forbidden(monkeypatch):
+    real = dashboard.ThreadingHTTPServer
+
+    def fake(addr, handler):
+        if addr[1] == 8765:
+            raise PermissionError("WinError 10013")  # simulate a blocked port
+        return real(addr, handler)
+
+    monkeypatch.setattr(dashboard, "ThreadingHTTPServer", fake)
+
+    assert dashboard._bind("127.0.0.1", 8765, 5) is None
+    httpd = dashboard._bind("127.0.0.1", 0, 5)
+    assert httpd is not None
+    httpd.server_close()
+
+
+def test_serve_falls_back_to_a_free_port(monkeypatch):
+    real = dashboard.ThreadingHTTPServer
+    bound = {}
+
+    def stop(self):  # so serve() returns instead of blocking on serve_forever
+        raise KeyboardInterrupt
+
+    monkeypatch.setattr(real, "serve_forever", stop)
+
+    def fake(addr, handler):
+        if addr[1] == 8765:
+            raise PermissionError("WinError 10013")  # default port blocked
+        server = real(addr, handler)
+        bound["port"] = server.server_address[1]
+        return server
+
+    monkeypatch.setattr(dashboard, "ThreadingHTTPServer", fake)
+
+    rc = dashboard.serve(port=8765, open_browser=False)
+    assert rc == 0
+    assert bound["port"] != 8765  # fell back to a working port
+
+
 def test_dashboard_serves_static_assets():
     httpd, port = _start_server()
     try: