Skip to content

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

fix(scan): match a scanned host against every declared IP of a device

Pouzordf60664506ce
diff --git a/backend/app/services/inventory_sync.py b/backend/app/services/inventory_sync.py
index 53f0165..85a283e 100644
--- a/backend/app/services/inventory_sync.py
+++ b/backend/app/services/inventory_sync.py
@@ -54,11 +54,13 @@ def is_furniture(node_type: str | None) -> bool:
return (node_type or "") in FURNITURE_TYPES
-def _ip_tokens(ip: str | None) -> list[str]:
+def ip_tokens(ip: str | None) -> list[str]:
"""Split an ``ip`` field into individual addresses.
- A node or device may carry several comma-separated addresses, so identity
- matching compares per token — same rule as ``node_dedupe._ip_tokens``.
+ A node or device may carry several comma-separated addresses — a router with
+ a management VLAN, a host behind a VIP — so identity matching compares per
+ token rather than on the whole string. Every matcher that resolves a device
+ from addresses shares this rule, the scanner included.
"""
return [t.strip() for t in ip.split(",") if t.strip()] if ip else []
@@ -125,7 +127,7 @@ async def find_device_for(
Hidden rows are eligible: a hidden device is still that device, and silently
minting a second row for it would resurrect the duplicate the user hid.
"""
- ip_toks = _ip_tokens(ip)
+ ip_toks = ip_tokens(ip)
conds = []
if ieee:
# Case-insensitive: `0x00124B00…` and `0x00124b00…` are the same radio,
@@ -151,7 +153,7 @@ async def find_device_for(
for device in candidates:
# "1.2.3.4" must not match "1.2.3.40" — confirm the token, don't trust
# the SQL `contains`.
- if ip_toks and set(_ip_tokens(device.ip)) & set(ip_toks):
+ if ip_toks and set(ip_tokens(device.ip)) & set(ip_toks):
return device
for device in candidates:
if mac and device.mac == mac:
diff --git a/backend/app/services/scanner.py b/backend/app/services/scanner.py
index f067414..faddc38 100644
--- a/backend/app/services/scanner.py
+++ b/backend/app/services/scanner.py
@@ -20,7 +20,7 @@ from app.db.models import InventoryDevice, ScanRun
from app.services.discovery_sources import add_source
from app.services.fingerprint import fingerprint_ports, suggest_node_type
from app.services.http_probe import probe_open_ports
-from app.services.inventory_sync import merge_services
+from app.services.inventory_sync import ip_tokens, merge_services
from app.services.mac_utils import normalize_mac
logger = logging.getLogger(__name__)
@@ -572,11 +572,45 @@ def _mock_scan(target: str) -> list[dict[str, Any]]:
]
+def _group_by_shared_ip(rows: list[InventoryDevice]) -> list[list[InventoryDevice]]:
+ """Group rows that share at least one address, transitively.
+
+ A row may hold several comma-separated addresses, so grouping is per token:
+ ``10.0.0.1`` and ``10.0.0.1, 10.0.1.1`` are the same device, and a row
+ bridging two others (``A,B`` next to ``A`` and ``B``) puts all three in one
+ group. Input order is preserved inside each group, so a caller ordering by
+ ``discovered_at`` still gets the oldest row first.
+ """
+ # Union-find over row indices, keyed by the addresses they carry.
+ parent = list(range(len(rows)))
+
+ def find(i: int) -> int:
+ while parent[i] != i:
+ parent[i] = parent[parent[i]]
+ i = parent[i]
+ return i
+
+ owner: dict[str, int] = {}
+ for i, row in enumerate(rows):
+ for tok in ip_tokens(row.ip):
+ first = owner.setdefault(tok, i)
+ root_a, root_b = find(first), find(i)
+ if root_a != root_b:
+ parent[max(root_a, root_b)] = min(root_a, root_b)
+
+ groups: dict[int, list[InventoryDevice]] = {}
+ for i, row in enumerate(rows):
+ groups.setdefault(find(i), []).append(row)
+ return list(groups.values())
+
+
async def _dedupe_pending_by_ip(db: AsyncSession) -> int:
"""Collapse duplicate non-hidden inventory rows that share an IP into one.
Keeps an ``approved`` row when present (it carries canvas-link semantics),
otherwise the oldest row, and deletes the rest. Returns the number deleted.
+ Rows carrying several addresses count as duplicates of any row holding one
+ of them — that is what declaring the extra address is for.
"""
rows = (await db.execute(
select(InventoryDevice)
@@ -584,14 +618,8 @@ async def _dedupe_pending_by_ip(db: AsyncSession) -> int:
.order_by(InventoryDevice.discovered_at)
)).scalars().all()
- by_ip: dict[str, list[InventoryDevice]] = {}
- for row in rows:
- if row.ip is None: # guarded by the query, but keeps the type checker happy
- continue
- by_ip.setdefault(row.ip, []).append(row)
-
deleted = 0
- for group in by_ip.values():
+ for group in _group_by_shared_ip(list(rows)):
if len(group) < 2:
continue
keep = next((r for r in group if r.status == "approved"), group[0])
@@ -646,14 +674,25 @@ async def process_host(
# a duplicate — and so a device previously imported from Proxmox (which
# may have no IP but a known NIC MAC) reconciles with this scan instead
# of doubling up. Hidden rows are already skipped above.
- match_cond = [InventoryDevice.ip == ip]
+ #
+ # The IP side matches per token: a row may hold several comma-separated
+ # addresses (a router's LAN and VLAN legs, a host and its VIP), declared by
+ # the user precisely so this scan folds into it rather than minting a second
+ # row every run. `contains` only narrows the query — the tokens are confirmed
+ # below, because "10.0.0.4" is a substring of "10.0.0.40" and these rows are
+ # deleted, not merely skipped.
+ match_cond = [InventoryDevice.ip.contains(ip)]
if norm_mac:
match_cond.append(InventoryDevice.mac == norm_mac)
- existing_rows = (await db.execute(
+ candidates = (await db.execute(
select(InventoryDevice)
.where(or_(*match_cond), InventoryDevice.status != "hidden")
.order_by(InventoryDevice.discovered_at)
)).scalars().all()
+ existing_rows = [
+ row for row in candidates
+ if ip in ip_tokens(row.ip) or (norm_mac is not None and row.mac == norm_mac)
+ ]
if existing_rows:
# Prefer an approved row (it owns the canvas link semantics),
@@ -736,7 +775,11 @@ async def run_scan(
hidden_ips_result = await db.execute(
select(InventoryDevice.ip).where(InventoryDevice.status == "hidden")
)
- hidden_ips: set[str] = {row[0] for row in hidden_ips_result.fetchall()}
+ # Per address, not per row: a hidden device holding several addresses is
+ # hidden at every one of them.
+ hidden_ips: set[str] = {
+ tok for row in hidden_ips_result.fetchall() for tok in ip_tokens(row[0])
+ }
# Collapse any pre-existing duplicate inventory rows (same IP, non-hidden)
# left over from older scans, so the device shows up exactly once even if
diff --git a/backend/tests/test_scanner.py b/backend/tests/test_scanner.py
index 22e0ad2..6190836 100644
--- a/backend/tests/test_scanner.py
+++ b/backend/tests/test_scanner.py
@@ -1,5 +1,6 @@
"""Tests for scanner: two-phase nmap, mDNS discovery, run_scan integration."""
import uuid
+from datetime import datetime, timezone
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
@@ -1436,3 +1437,180 @@ async def test_run_device_scan_keeps_what_it_found_when_the_budget_runs_out(mem_
# Partial coverage is reported, never passed off as a full sweep.
assert run.error is not None
assert "1/8" in run.error
+
+
+# ---------------------------------------------------------------------------
+# Multi-IP devices — one row per device, not one per address (issue #373)
+# ---------------------------------------------------------------------------
+
+def _host(ip: str, *, mac: str | None = None, hostname: str | None = None):
+ return {"ip": ip, "hostname": hostname, "mac": mac, "os": None, "open_ports": []}
+
+
+async def test_process_host_folds_into_declared_secondary_ip(mem_db):
+ """A scan of a device's second address refreshes its row, never mints one.
+
+ The user declares the extra addresses by hand — a router's LAN and VLAN
+ legs, a host behind a VIP — precisely so the scanner stops reporting them
+ as separate discoveries.
+ """
+ from app.services.scanner import DeepScanOptions, process_host
+
+ async with mem_db() as session:
+ session.add(InventoryDevice(
+ id="d1", ip="192.168.1.1, 192.168.10.1", status="approved", label="router",
+ ))
+ await session.commit()
+
+ async with mem_db() as session:
+ outcome = await process_host(
+ session, _host("192.168.10.1", hostname="router-vlan.lan"),
+ hidden_ips=set(), deep_scan=DeepScanOptions(),
+ )
+
+ async with mem_db() as session:
+ devices = (await session.execute(sa_select(InventoryDevice))).scalars().all()
+
+ assert outcome == "updated"
+ assert len(devices) == 1
+ # The declared list is the user's, not the scanner's — it survives the merge.
+ assert devices[0].ip == "192.168.1.1, 192.168.10.1"
+ assert devices[0].hostname == "router-vlan.lan"
+
+
+async def test_process_host_does_not_match_an_address_prefix(mem_db):
+ """`192.168.1.4` is a substring of `192.168.1.40` — and a different host.
+
+ The query narrows with a substring match, so the per-token confirmation is
+ what stops a false match. It matters more than usual here: the losing rows
+ of a match are deleted, not skipped.
+ """
+ from app.services.scanner import DeepScanOptions, process_host
+
+ async with mem_db() as session:
+ session.add(InventoryDevice(id="d1", ip="192.168.1.40", status="approved"))
+ await session.commit()
+
+ async with mem_db() as session:
+ outcome = await process_host(
+ session, _host("192.168.1.4"), hidden_ips=set(), deep_scan=DeepScanOptions(),
+ )
+
+ async with mem_db() as session:
+ devices = (await session.execute(sa_select(InventoryDevice))).scalars().all()
+
+ assert outcome == "created"
+ assert {d.ip for d in devices} == {"192.168.1.40", "192.168.1.4"}
+
+
+async def test_process_host_matches_a_single_token_row_exactly_as_before(mem_db):
+ """The ordinary one-address case is untouched by the token matching."""
+ from app.services.scanner import DeepScanOptions, process_host
+
+ async with mem_db() as session:
+ session.add(InventoryDevice(id="d1", ip="192.168.1.5", status="pending"))
+ await session.commit()
+
+ async with mem_db() as session:
+ outcome = await process_host(
+ session, _host("192.168.1.5", hostname="nas.lan"),
+ hidden_ips=set(), deep_scan=DeepScanOptions(),
+ )
+
+ async with mem_db() as session:
+ devices = (await session.execute(sa_select(InventoryDevice))).scalars().all()
+
+ assert outcome == "updated"
+ assert len(devices) == 1 and devices[0].hostname == "nas.lan"
+
+
+async def test_run_scan_skips_the_secondary_ip_of_a_hidden_device(mem_db):
+ """Hiding a multi-address device hides it at every one of its addresses."""
+ from app.services.scanner import run_scan
+
+ run_id = _make_run_id()
+ async with mem_db() as session:
+ session.add(_make_scan_run(run_id))
+ session.add(InventoryDevice(id="d1", ip="192.168.1.1, 192.168.10.1", status="hidden"))
+ await session.commit()
+
+ async with mem_db() as session:
+ with patch("app.services.scanner._nmap_scan", return_value=[_host("192.168.10.1")]), \
+ patch("app.services.scanner._mdns_discover", new_callable=AsyncMock, return_value=[]), \
+ patch("app.api.routes.status.broadcast_scan_update", new_callable=AsyncMock):
+ await run_scan(["192.168.1.0/24"], session, run_id)
+
+ async with mem_db() as session:
+ devices = (await session.execute(sa_select(InventoryDevice))).scalars().all()
+
+ assert len(devices) == 1
+ assert devices[0].status == "hidden"
+
+
+async def test_dedupe_collapses_a_single_ip_row_into_a_multi_ip_one(mem_db):
+ """Declaring an extra address folds in the duplicate row it already spawned.
+
+ The approved row wins even though it is the younger of the two: it carries
+ the canvas links.
+ """
+ from app.services.scanner import _dedupe_pending_by_ip
+
+ async with mem_db() as session:
+ session.add(InventoryDevice(
+ id="stale", ip="192.168.10.1", status="pending",
+ discovered_at=datetime(2026, 1, 1, tzinfo=timezone.utc),
+ ))
+ session.add(InventoryDevice(
+ id="keep", ip="192.168.1.1, 192.168.10.1", status="approved",
+ discovered_at=datetime(2026, 2, 1, tzinfo=timezone.utc),
+ ))
+ await session.commit()
+
+ async with mem_db() as session:
+ deleted = await _dedupe_pending_by_ip(session)
+
+ async with mem_db() as session:
+ devices = (await session.execute(sa_select(InventoryDevice))).scalars().all()
+
+ assert deleted == 1
+ assert [d.id for d in devices] == ["keep"]
+
+
+async def test_dedupe_leaves_rows_that_share_no_address(mem_db):
+ from app.services.scanner import _dedupe_pending_by_ip
+
+ async with mem_db() as session:
+ session.add(InventoryDevice(id="a", ip="192.168.1.1, 192.168.10.1", status="pending"))
+ session.add(InventoryDevice(id="b", ip="192.168.1.2, 192.168.10.2", status="pending"))
+ await session.commit()
+
+ async with mem_db() as session:
+ deleted = await _dedupe_pending_by_ip(session)
+
+ async with mem_db() as session:
+ devices = (await session.execute(sa_select(InventoryDevice))).scalars().all()
+
+ assert deleted == 0
+ assert len(devices) == 2
+
+
+def test_group_by_shared_ip_is_transitive():
+ """`A,B` next to `A` and `B` is one device, not two pairs."""
+ from app.services.scanner import _group_by_shared_ip
+
+ rows = [
+ InventoryDevice(id="a", ip="10.0.0.1"),
+ InventoryDevice(id="b", ip="10.0.1.1"),
+ InventoryDevice(id="bridge", ip="10.0.0.1, 10.0.1.1"),
+ InventoryDevice(id="other", ip="10.0.2.1"),
+ ]
+
+ groups = {frozenset(r.id for r in group) for group in _group_by_shared_ip(rows)}
+
+ assert groups == {frozenset({"a", "b", "bridge"}), frozenset({"other"})}