Discovery

Discovery is the process of scanning your network to find hosts and services. Daemons perform discovery and report findings to the server.

Discovery Types

Network Scan

Scans IP addresses on configured subnets to find hosts and services.

• Detects open TCP and UDP ports
• Identifies services via pattern matching
• Performs reverse DNS lookups
• Collects MAC addresses (for directly connected subnets only)

Key principle: The daemon can scan any subnet it can route to. If the daemon's host can reach an IP address, the daemon can scan it.

Configuring subnets to scan: Go to Discover > Scheduled, edit a Network Scan discovery, and add subnets to the scan list. You can add any subnet — including ones the daemon doesn't have a direct interface on.

Layer 2 vs Layer 3: When the daemon has a network interface on the subnet being scanned, you get full Layer 2 access (MAC addresses via ARP, better host discovery). When scanning remote subnets, you're limited to Layer 3 — only hosts with open ports will be discovered. See limitations for details.

Docker

Discovers containers via the Docker socket on the daemon's host.

• Lists running containers with names and metadata
• Maps container networks and port bindings
• Identifies containerized services
• Creates Docker bridge subnets automatically

Requires Docker socket access — see Docker Socket Proxy for secure configuration.

Self-Report

Daemon reports its own capabilities to the server.

• Identifies which subnets the daemon can reach
• Reports Docker socket availability
• Runs automatically on daemon startup

Run Types

Discovery Duration

Benchmark: A /24 subnet (256 IPs) takes 5-10 minutes to scan.

Factors affecting speed:

• Subnet size (a /16 is 65,536 IPs — avoid scanning these via Network Scan)
• Concurrent scans setting (default: 15, configurable per daemon)
• Network latency and host responsiveness

Watch out: Accidentally added 172.17.0.0/16 to your network scan? That's 65,536 IPs. Docker bridge networks should use Docker discovery instead — it queries the Docker API directly and takes seconds.

Host Naming

When a host is discovered, Scanopy determines its name using this priority:

1. Reverse DNS — hostname from PTR record, if available
2. Best Service or IP — configurable fallback per discovery:
   • Best Service: Uses the first named service found on the host
   • IP: Uses the host's IP address
3. Remaining fallback — whichever option wasn't selected in step 2

Configure naming strategy in the discovery type settings.

Manage discoveries via Discover > Scheduled and monitor progress via Discover > Sessions.

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 discovery 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 are available when the daemon is directly connected to the subnet being scanned (via ARP) or from Docker container network configuration. See Layer 2 vs Layer 3 for details on when MAC addresses are collected.

Docker Host Matching

Docker discovery is local-only — it discovers containers on the daemon's own host, not remote machines. All discovered services are assigned to that host.

This has two implications:

• No cross-host deduplication: Since Docker discovery only sees one host, there's nothing to deduplicate
• Docker proxies don't change this: Even when using a Docker Socket Proxy pointing to a remote host, services are still assigned to the daemon's host

For accurate Docker discovery, run the daemon on the same machine as Docker.

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 — User-assigned name stays intact
• 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

This means discovery enriches existing hosts without overwriting user customizations.

Docker vs Network Discovery

Both discovery types use the same deduplication logic. The differences are in what data they provide:

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

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.