Skip to content

Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring

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.py
index 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.py
index 4b86661..54a6457 100644
--- a/backend/app/services/scanner.py
+++ b/backend/app/services/scanner.py
@@ -7,6 +7,7 @@ import re
import socket
import subprocess
import threading
+import time
from dataclasses import dataclass, field
from datetime import datetime, timezone
from 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 = 0
if 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 = partial
run.finished_at = datetime.now(timezone.utc)
await db.commit()
diff --git a/backend/tests/test_scanner.py b/backend/tests/test_scanner.py
index 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_dict
async 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.error
diff --git a/frontend/src/components/modals/InventoryDeviceModal.tsx b/frontend/src/components/modals/InventoryDeviceModal.tsx
index 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, onIgn
useCanvasStore.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.tsx
index 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')