What the agent discovers

A sweep turns a range of addresses into a map of machines. Finding a host is the easy part; the work is saying what it is.

Finding hosts

Two ways, combined:

• ICMP echo — every address in the range is pinged.
• ARP — run first, on the segment. It finds hosts that ignore ping: Windows on a network it calls Public, most endpoint protection, printers and cameras with minimal stacks. A machine that does not answer ARP cannot receive a packet at all. A host found only this way is marked discoveredBy: arp.

ARP also gives the hardware address — the identifier a machine keeps when DHCP moves it — and, from its first three bytes, the manufacturer. A MAC is recorded only for hosts on the segment: past a router, ARP answers with the router’s own address, and recording it would fold the network into one node.

Naming hosts

Every source is asked, then one name wins.

Source	Who is speaking
Reverse DNS	The network: the name your DNS gives the address
mDNS	The host: the .local name a Mac, iPhone, printer or Linux box announces
NetBIOS	The host: Windows and Samba workstation names
LLMNR	The host: Windows with NetBIOS turned off
SNMP	The administrator: the name configured on a switch, router, firewall or printer
SSDP / UPnP	The device: televisions, consoles, NAS boxes, routers, cameras
TLS	The certificate’s common name — on a NAS or hypervisor, the name typed at setup
HTTP	The page title and Server: header. Weakest, and still better than an address

Reverse DNS wins — unless it looks generated. dhcp-192-168-1-57.lan is the address again with punctuation, so it ranks below anything the host said about itself. The names that lost are kept as aliases on the device; a generated PTR beside a real mDNS name says the DHCP server does not know its clients, which is worth knowing.

Each device records which source named it (nameSource). No source means nothing named it, and the name is the address. To get names on such hosts: a reverse DNS zone, your SNMP read community in discovery.snmp_community, or simply typing the name on the board — a name your team set is never overwritten.

Classifying hosts

What a device is drawn as, from the most to the least trustworthy signal:

1. The routing table. The address packets leave by is the router. Not a guess.
2. What it listens on. 9100 and 631 is a printer whatever it is called; 62078 is an iPhone; 554 without a media server is a camera; 8006 is Proxmox.
3. What it says its operating system is, over SNMP or mDNS.
4. Its name.
5. Its manufacturer — only when that vendor makes exactly one kind of thing. Espressif is a microcontroller; Intel is a network card in anything.
6. The TTL of its ping reply, the only signal from a host that answers nothing else.

A MAC with the locally administered bit set was made up by the host — a VM, a container, or a phone randomising its address on a network it does not trust — and is recorded as such.

The router is always on the board

The router is filed from the machine’s routing table whether or not it answered, because edge routers often drop pings as policy and without a router the board has no centre and no edges.

discoveredBy	Meaning
route	The default route, inside the swept range. Certain.
assumed	The first usable address of the range, used when the default route is outside it. The “.1 is the router” convention — right on most networks, and visibly labelled when it is not.

A sweep that ran out of time still gets its router. A sweep somebody stopped does not.

The uplink

Once per sweep the agent asks whether the network reaches anything, and writes the answer on two nodes only: the router and the agent’s own machine.

Field	Meaning
internet	A public resolver answered on 443. false is a network that goes nowhere.
dns	A public name resolved. Packets leaving while names do not is a common fault.
latencyMs	Round trip to the resolver.
dnsServers	The machine’s resolvers.
publicIp, country	How the network is seen from outside (discovery.public_ip).
isp	The registrable domain of the public address’s reverse lookup. A hint.

Absent means the probe did not run, not that the network is down.

What a device carries

On the device	From
Address, mac, vendor	The sweep, ARP, NetBIOS
Name, nameSource, aliases	See above
os, model, description	SNMP sysDescr, mDNS device info, UPnP, the SSH greeting, Server:
services, ports	mDNS service types; ports that accepted a connection
certExpiry	The TLS certificate’s expiry date — the certificate nobody is watching
rtt	Ping round trip in milliseconds. Absent on a host that only answered ARP
discoveredBy	icmp, arp, both, route or assumed
gateway, onLink	The routing table and ARP, not guessed
uplink	Router and agent’s own node only
lastSeenAt, missedScans	When a sweep last saw it, and how many have missed it since

How a sweep lands on the board

• Matching. A host is matched to an existing device by its id, its address or its MAC, so a machine that changed address moves rather than appearing twice; the old address is kept as previousAddress. A MAC carried by more than one device is used for nothing.
• Imported machines — drawn from Terraform, Proxmox or an inventory with a declared address — are matched by that address when a sweep of their range finds them, and light up as confirmed.
• Names and positions your team set are kept. A device still labelled with its own address takes the name the sweep found; one with a name keeps it, and what the sweep saw is written beside it (observedName).
• Placement. New hosts go on a spiral around the router, so no device moves because another arrived, and a host drawn live during a sweep is where it stays.
• Nothing is deleted. A device inside the swept range that a sweep missed has its missedScans count raised. A cancelled sweep marks nothing missed.
• Edges from the router to each host are drawn as inferred — the layout’s rule, not an observation — except where an ARP answer proves the host is on the router’s own link.

See scans on a board for how this reads in the dashboard.