Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
fix(scan): slice the deep rescan instead of timing out the host
Pouzorfbb660504e4c
diff --git a/backend/app/core/config.py b/backend/app/core/config.pyindex f2dd09f..652ff72 100644--- a/backend/app/core/config.py+++ b/backend/app/core/config.py@@ -117,6 +117,14 @@ class Settings(BaseSettings):# ports survive a timeout regardless; raise this on slow/overlay networks.scanner_version_host_timeout: int = 60+ # Per-device deep rescan: total time budget in seconds, checked between port+ # slices. Unprivileged nmap falls back to a connect scan (-sT), and a host+ # that drops packets makes every filtered port wait out its RTT — the whole+ # range against such a host runs ~20-45 min. When the budget is spent the+ # run keeps what it found and says how much it did not reach. This is NOT an+ # nmap --host-timeout: that one discards a host's results wholesale.+ scanner_deep_host_timeout: int = 2700+# Deep scan — persisted defaults (overridable per-scan from the scan dialog).# http_ranges: extra nmap port ranges, opt-in, no default. Probe + TLS off by default.scanner_http_ranges: list[str] = []diff --git a/backend/app/services/scanner.py b/backend/app/services/scanner.pyindex 4b86661..54a6457 100644--- a/backend/app/services/scanner.py+++ b/backend/app/services/scanner.py@@ -7,6 +7,7 @@ import reimport socketimport subprocessimport threading+import timefrom dataclasses import dataclass, fieldfrom datetime import datetime, timezonefrom typing import Any@@ -66,6 +67,18 @@ def _valid_port_range(spec: str) -> bool:# nmap time for a service list that no curated port list can promise._FULL_PORTS = "1-65535"+# The deep rescan runs the full range in slices, one nmap call each, unioning+# what they find. A slice that runs long costs only its own ports — where a+# single 65535-port call that overruns costs everything (see _nmap_scan_single).+# It also gives the run somewhere to notice a stop request, and somewhere to+# give up when the budget is spent, without abandoning the ports already found.+_DEEP_CHUNK_SIZE = 8192+++def _deep_port_chunks(size: int = _DEEP_CHUNK_SIZE) -> list[str]:+ """Slice the whole TCP range into nmap ``-p`` specs of ``size`` ports."""+ return [f"{start}-{min(start + size - 1, 65535)}" for start in range(1, 65536, size)]+def _build_port_spec(http_ranges: list[str] | None, full: bool = False) -> str:"""Combine the default port list with validated user ranges for nmap -p.@@ -249,7 +262,9 @@ async def _ping_sweep(target: str, run_id: str | None = None) -> dict[str, dict[return alive-def _nmap_scan_single(host_dict: dict[str, Any], port_spec: str = _EXTRA_PORTS) -> dict[str, Any]:+def _nmap_scan_single(+ host_dict: dict[str, Any], port_spec: str = _EXTRA_PORTS, bounded: bool = False+) -> dict[str, Any]:"""Phase 2 — single-IP port scan with service detection.Runs in a thread (blocking). Returns the host dict enriched with open_ports.@@ -273,8 +288,26 @@ def _nmap_scan_single(host_dict: dict[str, Any], port_spec: str = _EXTRA_PORTS)# -sT without root but being explicit avoids edge cases.scan_type = "-sS" if os.geteuid() == 0 else "-sT"- # --- Pass A: port discovery (no -sV, no host-timeout) ---+ # --- Pass A: port discovery (no -sV) ---+ # Default timing for the range scan: its ports are authoritative and a+ # curated port list is fast either way.+ #+ # ``bounded`` is the deep rescan's timing, and carries NO --host-timeout on+ # purpose: nmap answers a host timeout with "Skipping host <ip> due to host+ # timeout" and discards *every* port it had already found, so a ceiling here+ # turns a slow scan into one that reports nothing. The caller bounds total+ # runtime by slicing the range instead.+ #+ # What costs the time is a host that drops packets: 8188 of 8192 ports+ # filtered, each waiting out its probe. Measured against such a host, the+ # retry pass is the whole cost — 8192 ports took 329s at --max-retries 1+ # and 164s at 0, finding the same ports. Capping the RTT changed nothing+ # (329s), so it is not set. Dropping retries risks missing a port that+ # loses its one probe; that trade belongs to the deep scan alone, and the+ # curated-port range scan keeps nmap's default retries.discovery_args = f"{scan_type} --open -T4 -Pn -p {port_spec}"+ if bounded:+ discovery_args += " --max-retries 0 --min-rate 2000"logger.debug("[Phase 2] %s discovery args: %s", ip, discovery_args)nm_disc = nmap.PortScanner()try:@@ -757,8 +790,46 @@ async def run_device_scan("open_ports": [],}- if not _is_cancelled(run_id):- host = await asyncio.to_thread(_nmap_scan_single, host, port_spec)+ # The full range goes out in slices so a stop request lands within one+ # slice instead of at the end, and so a spent budget keeps the ports+ # found so far. A curated port list is one call, as before.+ chunks = _deep_port_chunks() if full_ports else [port_spec]+ deadline = time.monotonic() + settings.scanner_deep_host_timeout+ found: list[dict[str, Any]] = []+ seen: set[tuple[str, int]] = set()+ skipped = 0++ for i, chunk in enumerate(chunks):+ if _is_cancelled(run_id):+ skipped = len(chunks) - i+ break+ if i and time.monotonic() > deadline:+ skipped = len(chunks) - i+ logger.warning(+ "[Deep scan] %s — budget of %ds spent, %d port range(s) not scanned",+ host["ip"], settings.scanner_deep_host_timeout, skipped,+ )+ break+ # bounded: retry-free timing, for a host that drops packets.+ scanned = await asyncio.to_thread(+ _nmap_scan_single, dict(host), chunk, full_ports+ )+ for port in scanned.get("open_ports") or []:+ key = (port["protocol"], port["port"])+ if key not in seen:+ seen.add(key)+ found.append(port)+ host["mac"] = host["mac"] or scanned.get("mac")+ host["os"] = scanned.get("os") or host["os"]++ host["open_ports"] = found+ # A partial sweep still says what it saw; the row unions it in.+ partial = (+ f"Scanned {len(chunks) - skipped}/{len(chunks)} port ranges "+ f"({len(found)} open) — the rest was not reached"+ if skipped+ else None+ )devices_found = 0if not _is_cancelled(run_id):@@ -775,6 +846,11 @@ async def run_device_scan(if run:run.status = "cancelled" if _is_cancelled(run_id) else "done"run.devices_found = devices_found+ # Not a failure: a done run carrying an advisory, the way a Proxmox+ # import reports what it could not see. Never let a partial sweep+ # read as a complete one.+ if partial and run.status == "done":+ run.error = partialrun.finished_at = datetime.now(timezone.utc)await db.commit()diff --git a/backend/tests/test_scanner.py b/backend/tests/test_scanner.pyindex 3fca83c..cce5863 100644--- a/backend/tests/test_scanner.py+++ b/backend/tests/test_scanner.py@@ -375,6 +375,58 @@ def test_nmap_scan_single_non_root_uses_connect_scan():assert result["open_ports"][0]["banner"] == "nginx 1.24"+def test_nmap_scan_single_discovery_is_unbounded_by_default():+ """The range scan's discovery pass keeps its authoritative, untimed run."""+ from app.services.scanner import _nmap_scan_single++ host = {"ip": "192.168.1.14", "hostname": None, "mac": None, "os": None, "open_ports": []}+ disc = _fake_scanner("192.168.1.14", {})++ with patch("app.services.scanner.nmap.PortScanner", side_effect=[disc]), \+ patch("app.services.scanner.os.geteuid", return_value=1000):+ _nmap_scan_single(host)++ args = disc.scan.call_args.kwargs["arguments"]+ assert "--host-timeout" not in args+ assert "--min-rate" not in args+++def test_nmap_scan_single_bounded_never_sets_a_host_timeout():+ """A deep slice drops retries — never --host-timeout.++ nmap answers a host timeout with "Skipping host <ip> due to host timeout"+ and throws away every port it had already found, so a ceiling here turns a+ slow scan into one that reports nothing. The time on a dropping host goes to+ the retry pass — measured 2x — so that is what the deep scan gives up.+ """+ from app.services.scanner import _nmap_scan_single++ host = {"ip": "192.168.1.15", "hostname": None, "mac": None, "os": None, "open_ports": []}+ disc = _fake_scanner("192.168.1.15", {})++ with patch("app.services.scanner.nmap.PortScanner", side_effect=[disc]), \+ patch("app.services.scanner.os.geteuid", return_value=1000):+ _nmap_scan_single(host, "1-8192", True)++ args = disc.scan.call_args.kwargs["arguments"]+ assert "-p 1-8192" in args+ assert "--host-timeout" not in args+ assert "--max-retries 0" in args+++def test_deep_port_chunks_cover_every_port_once():+ from app.services.scanner import _deep_port_chunks++ chunks = _deep_port_chunks(8192)+ assert chunks[0] == "1-8192"+ assert chunks[-1].endswith("-65535")+ covered = []+ for c in chunks:+ lo, hi = (int(x) for x in c.split("-"))+ covered.extend(range(lo, hi + 1))+ assert covered == list(range(1, 65536))++# ---------------------------------------------------------------------------# _nmap_scan# ---------------------------------------------------------------------------@@ -1055,9 +1107,15 @@ async def test_run_device_scan_refreshes_services_and_marks_run_done(mem_db):session.add(InventoryDevice(id="d1", ip="192.168.1.9", status="approved", services=[]))await session.commit()- def _scanned(host_dict, port_spec):- assert port_spec == "1-65535"- host_dict["open_ports"] = [{"port": 22, "protocol": "tcp", "banner": "OpenSSH 9.2"}]+ seen_specs = []++ def _scanned(host_dict, port_spec, bounded=False):+ seen_specs.append(port_spec)+ # A full-range rescan is always bounded, or it never ends.+ assert bounded is True+ # Only the slice holding 22 reports it — the union is the caller's job.+ if port_spec == "1-8192":+ host_dict["open_ports"] = [{"port": 22, "protocol": "tcp", "banner": "OpenSSH 9.2"}]return host_dictasync with mem_db() as session:@@ -1093,7 +1151,7 @@ async def test_run_device_scan_keeps_hand_added_services(mem_db):session.add(InventoryDevice(id="d1", ip="192.168.1.9", status="pending", services=[hand_added]))await session.commit()- def _scanned(host_dict, port_spec):+ def _scanned(host_dict, port_spec, bounded=False):host_dict["open_ports"] = [{"port": 22, "protocol": "tcp", "banner": "OpenSSH 9.2"}]return host_dict@@ -1158,3 +1216,81 @@ async def test_run_device_scan_skips_nmap_when_cancelled(mem_db):assert run.status == "cancelled"# The run cleans up its cancellation flag on the way out.assert run_id not in _cancelled_runs+++async def test_run_device_scan_unions_ports_across_slices(mem_db):+ """Every slice contributes; a slow one costs only its own ports."""+ from app.services.scanner import _deep_port_chunks, run_device_scan++ run_id = _make_run_id()+ async with mem_db() as session:+ session.add(ScanRun(id=run_id, status="running", kind="device", ranges=["192.168.1.9/32"]))+ session.add(InventoryDevice(id="d1", ip="192.168.1.9", status="pending", services=[]))+ await session.commit()++ def _scanned(host_dict, port_spec, bounded=False):+ lo = int(port_spec.split("-")[0])+ if lo == 1:+ host_dict["open_ports"] = [{"port": 22, "protocol": "tcp", "banner": ""}]+ elif lo == 8193:+ host_dict["open_ports"] = [{"port": 8096, "protocol": "tcp", "banner": ""}]+ return host_dict++ async with mem_db() as session:+ with patch("app.services.scanner._nmap_scan_single", side_effect=_scanned), \+ patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):+ await run_device_scan("d1", session, run_id)++ async with mem_db() as session:+ device = await session.get(InventoryDevice, "d1")+ run = await session.get(ScanRun, run_id)++ assert device is not None and run is not None+ assert {s.get("port") for s in device.services} == {22, 8096}+ # A complete sweep carries no advisory.+ assert run.error is None+ assert len(_deep_port_chunks()) == 8+++async def test_run_device_scan_keeps_what_it_found_when_the_budget_runs_out(mem_db):+ """A spent budget stops the sweep — it never discards the ports found.++ The earlier --host-timeout did exactly that (nmap skips the host wholesale),+ which is why a deep scan could come back empty on a slow host.+ """+ from app.services.scanner import run_device_scan++ run_id = _make_run_id()+ async with mem_db() as session:+ session.add(ScanRun(id=run_id, status="running", kind="device", ranges=["192.168.1.9/32"]))+ session.add(InventoryDevice(id="d1", ip="192.168.1.9", status="pending", services=[]))+ await session.commit()++ calls = []++ def _scanned(host_dict, port_spec, bounded=False):+ calls.append(port_spec)+ host_dict["open_ports"] = [{"port": 22, "protocol": "tcp", "banner": ""}]+ return host_dict++ async with mem_db() as session:+ # Budget already spent when the first slice returns.+ with patch("app.services.scanner._nmap_scan_single", side_effect=_scanned), \+ patch("app.services.scanner.settings") as mock_settings, \+ patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):+ mock_settings.scanner_deep_host_timeout = -1+ await run_device_scan("d1", session, run_id)++ async with mem_db() as session:+ device = await session.get(InventoryDevice, "d1")+ run = await session.get(ScanRun, run_id)++ assert calls == ["1-8192"]+ assert device is not None and run is not None+ assert {s.get("port") for s in device.services} == {22}+ assert run.status == "done"+ # Partial coverage is reported, never passed off as a full sweep.+ assert run.error is not None+ assert "1/8" in run.errordiff --git a/frontend/src/components/modals/InventoryDeviceModal.tsx b/frontend/src/components/modals/InventoryDeviceModal.tsxindex dd68221..f173854 100644--- a/frontend/src/components/modals/InventoryDeviceModal.tsx+++ b/frontend/src/components/modals/InventoryDeviceModal.tsx@@ -317,7 +317,14 @@ export function InventoryDeviceModal({ device, onClose, onApprove, onHide, onIgnuseCanvasStore.getState().notifyScanDeviceFound()onSavedRef.current?.(fresh)const n = fresh.services?.length ?? 0- toast.success(`Scan done — ${n} service${n !== 1 ? 's' : ''}`)+ const summary = `${n} service${n !== 1 ? 's' : ''}`+ // A done run can still carry an advisory: the sweep ran out of budget+ // before every port range. Saying "done" flat would read as complete.+ if (run.error) {+ toast.warning(`Scan partial — ${summary}. ${run.error}`)+ } else {+ toast.success(`Scan done — ${summary}`)+ }} catch {// Transient failure: keep polling, the run is still on the server.}diff --git a/frontend/src/components/modals/__tests__/InventoryDeviceModalRescan.test.tsx b/frontend/src/components/modals/__tests__/InventoryDeviceModalRescan.test.tsxindex bb07120..9225141 100644--- a/frontend/src/components/modals/__tests__/InventoryDeviceModalRescan.test.tsx+++ b/frontend/src/components/modals/__tests__/InventoryDeviceModalRescan.test.tsx@@ -125,6 +125,29 @@ describe('InventoryDeviceModal — deep rescan', () => {expect(mockRun.mock.calls.length).toBe(calls)})+ it('says partial when the sweep ran out of budget', async () => {+ vi.useFakeTimers({ shouldAdvanceTime: true })+ const { toast } = await import('sonner')+ const fresh = makeDevice({ services: [{ port: 22, protocol: 'tcp', service_name: 'SSH' }] })+ render(<InventoryDeviceModal {...noop} device={makeDevice()} />)+ fireEvent.click(screen.getByTestId('device-rescan'))+ await waitFor(() => expect(screen.getByTestId('device-rescan-stop')).toBeInTheDocument())++ // A done run carrying an advisory — it scanned part of the range only.+ mockRun.mockResolvedValue({+ data: { id: 'run-1', status: 'done', error: 'Scanned 3/8 port ranges (1 open) — the rest was not reached' },+ })+ mockPending.mockResolvedValue({ data: [fresh] })+ await act(async () => { await vi.advanceTimersByTimeAsync(3100) })++ await waitFor(() =>+ expect(toast.warning).toHaveBeenCalledWith(+ expect.stringContaining('Scan partial — 1 service')+ )+ )+ expect(toast.success).not.toHaveBeenCalled()+ })+it('surfaces a failed run instead of silently ending', async () => {vi.useFakeTimers({ shouldAdvanceTime: true })const { toast } = await import('sonner')