Discovery

Daemons scan your network to discover hosts and services, then report findings to the server. This page covers how discovery works and how to configure it.

How Discovery Works

Each daemon runs a single discovery that combines network scanning, Docker container discovery, and self-reporting into one flow. When a discovery runs, the daemon:

1. Scans configured subnets to find hosts via IP, port, and ARP scanning
2. Queries SNMP on discovered hosts (if credentials are configured)
3. Discovers Docker containers via the local socket or a Docker Proxy credential (local or remote)
4. Reports its own capabilities and reachable subnets to the server

Network Scanning

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)
• Queries SNMP for device details, interfaces, and neighbors (if credentials are configured)

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: Edit the discovery and add subnets to the scan list in the Targets tab. 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.

Large interfaced subnets: For very large subnets (larger than /15 by default), the daemon caps the number of IPs it ARP scans to prevent excessive memory use and scan times. You can adjust this via the arp_scan_cutoff scan setting — see Scan Performance for details.

Docker Container Discovery

Discovers containers via the Docker API.

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

Docker discovery can work in two modes:

• Local socket — the daemon connects directly to /var/run/docker.sock on its own host. Enable via the Scan local Docker socket toggle in the discovery targets.
• Docker Proxy credential — the daemon connects to a Docker socket proxy, which can be local or remote. See Set up a Docker Proxy for configuration.

Scanning Lifecycle

Discovery alternates between two scan depths on a configurable interval.

Light scans

Light scans focus on host and service discovery using a targeted port set — the ports defined in the discovery's port configuration plus any credential-specific ports (e.g., SNMP port 161). This is faster and sufficient for detecting new hosts and tracking port changes.

Deep scans

Deep scans perform a full 65,535-port TCP scan on each host. This catches open ports that aren't covered by the light scan's targeted port set.

Scan interval

The full scan interval setting (default: 3) controls how often deep scans run. A value of 3 means every third scan is deep, with light scans in between. Specifically:

You can also force a deep scan at any time from the discovery session controls.

Configure the scan interval in the discovery's Speed tab.

SNMP

SNMP enriches discovered hosts with device metadata that isn't available from port scanning alone.

What SNMP adds

Without SNMP, hosts have only what port scanning and DNS provide — IP addresses, open ports, detected services, and reverse DNS hostnames. With SNMP credentials configured, discovery also collects:

• System identity — sysName, sysDescr, sysLocation, sysContact
• Interface table — all network interfaces with names, speeds, MAC addresses, IP assignments, and operational status
• LLDP/CDP neighbors — directly connected devices reported by the host itself, enabling accurate physical topology mapping

How credentials are resolved

When the daemon queries a host via SNMP, it resolves which community string to use in this order:

1. Host-specific assignment — a credential assigned directly to the host
2. Network default — a Broadcast-scoped credential assigned to the host's network
3. Fallback — the community string public

What gets queried

Limitations

• SNMPv2c only — v3 support is planned but not yet available
• No trap handling — SNMP data is collected during discovery scans only (poll-based)
• No custom MIBs — only the standard MIBs listed above are queried

See SNMP reference for protocol details, timeouts, and the full list of collected OIDs.

Run Types

Discovery Duration

Duration depends primarily on the number of active hosts on the network, and will be estimated by the daemon during initial scan setup. You can view the estimated duration in Scans > Sessions

Factors affecting speed:

• Number of active hosts — more hosts means more deep scanning work
• Scan depth — deep scans take longer than light scans
• Network latency and host responsiveness
• Network prefix size — only a limiting factor without a Layer 2 interface, since the daemon must probe every IP individually via TCP

If scan time is longer than expected, see discovery takes hours.

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 settings.

Manage discoveries via Discover > Scan > Scheduled and monitor progress via Discover > Scan > 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 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 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 container discovery is local-only — it discovers containers on the daemon's own host (or on the host targeted by a Docker Proxy credential), not arbitrary 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 change the target: When using a Docker Proxy credential pointing to a remote host, services are assigned to the remote host, not the daemon's host

For accurate Docker discovery without a proxy, 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
• 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.

Network Scanning vs Docker Scanning

Both scanning methods 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.