Naming and Deduplication

Host Naming

A host takes its name from the strongest source Scanopy has for it. Sources rank like this, weakest first:

A stronger source replaces a weaker one, so a host first named for its IP address takes its controller's name once that integration runs. Each source also refreshes its own rank: rename a device in its controller and the new name reaches Scanopy on the next sync. A name you typed is replaced only by another name you type.

Choosing the scan fallback

A network scan on its own reaches the bottom three ranks, and each discovery chooses which of the lower two it prefers when no hostname is available:

• Best Service — the first named service found on the host, or the IP address if no service was detected.
• IP — the host's IP address.

A hostname takes precedence over both wherever one is available.

Host Deduplication

When a daemon discovers a host, Scanopy checks if it already exists before creating a new entry. This prevents duplicate hosts when:

• The same host is discovered by multiple daemons
• A host is rediscovered across multiple scan sessions
• Docker and network scanning both find the same machine

Host deduplication is only applied to hosts on the same Network. If two hosts on different Networks meet the criteria below, they will not be deduplicated.

Interface Matching

Scanopy primarily identifies duplicate hosts by comparing network interfaces. Two interfaces are considered the same if any of these conditions are true:

MAC addresses come from ARP on directly connected subnets, or from container network configuration — see Layer 2 vs Layer 3.

Floating virtual IPs (CARP/VRRP). A high-availability VIP has no hardware of its own — its only identity is the address it floats on, carried by a shared virtual-router MAC. Scanopy matches it on IP + subnet, so the VIP is recognized across scans rather than recreated each time. The shared virtual MAC is never matched on, which keeps the HA peers hosting it distinct instead of merging them into one host.

Matching a Host With No Address

A device with no IP address has nothing to match on above, so Scanopy falls back to its MAC address alone — the same tier also catches a device whose address moved, so it isn't recreated under the new one. Only a strong, vendor-assigned MAC is used for this; a locally administered address or one shared by a virtual router or group (the kind CARP/VRRP relies on) is not, since it doesn't identify a single device. Creating a new address-less host this way additionally requires the MAC to have been observed directly rather than only reported by another device, so a third party's unverified claim never invents a host.

A host with no address has no Rescan action, since a rescan targets an address, and it isn't placed in the Layer 3 topology view, which positions hosts by address.

Container Host Matching

Container discovery reports on exactly one host — the daemon's own, or the one a proxy credential points at — so there is nothing to deduplicate across hosts. What it does change is which host the containers land on: a proxy pointing at a remote machine attributes them there, not to the daemon's host.

Container names appear in a host's virtualization metadata, not as its hostname.

Upsert Behavior

When a duplicate is found, Scanopy merges the new discovery data into the existing host rather than creating a duplicate:

Entities merged

Ports, interfaces, and services discovered on the duplicate will be reconciled against the existing host and deduplicated.

• Ports: Must have same number and protocol to be considered a duplicate
• Interfaces: As described above, must have same IP + subnet OR same MAC address to be considered a duplicate
• Services: Follow complex deduplication logic that depends on the type of service detected. Refer to backend/src/server/services/impl/base.rs -> impl PartialEq if you are curious.

Fields merged (only if not already set):

• Hostname — DNS-discovered hostname fills in if the existing host has none

Fields preserved (never overwritten):

• Name — A name you typed stays intact. A derived name is replaced only when a stronger source appears, following the ranks under Host Naming
• Hidden status — Visibility preference preserved
• Tags — User tags unchanged
• Description — User-provided description unchanged

Always merged:

• Discovery metadata — Each discovery source is recorded, so you can see which daemons and discovery methods found the host
• Credential assignments — When hosts are consolidated, credential assignments are preserved using broadest-scope-wins merging

This means discovery enriches existing hosts without overwriting user customizations.

Manual Consolidation

Automatic deduplication handles most cases, but sometimes hosts slip through as duplicates — for example, when a server has interfaces on multiple VLANs that were scanned by different daemons before the interfaces could be matched.

Use manual consolidation to merge these. See Consolidating Duplicate Hosts.