Network Map Kit

id: net · sections: Map, Networks, Services and ports, Addresses · state: works, the map is in place.

Network inventory: host discovery, port scanning, and an interactive map with hand-drawn links. The product's former name was LanWeaver; it stays with this kit.

What it does

Two scans, not one

"Finding hosts is quick and answers who is on the network; scanning the ports is the long one and answers what they are running — and it is what everything else in the platform reads. A network whose hosts have no ports scanned looks empty to the kits that go looking for databases in the inventory, and they will say so rather than guess."

• Find hosts (discover). Targets are a string: CIDR (10.34.1.0/24), a range of the last octet (10.34.1.10-20), a full range (10.34.1.10-10.34.1.20), single addresses, separated by commas, spaces or newlines. Three independent methods, in order, each catching what the others miss:

  1. an ICMP sweep through a raw socket;
  2. the kernel ARP table, read right after the sweep — to send ICMP to a neighbour the kernel first asks ARP, and a host that silently drops ICMP answers ARP. It costs no extra packet;
  3. TCP knocking on a set of ports, only for addresses silent in the first two. 33 ports by default: shells, web, databases, caches, brokers, cluster services. "Why the default set is not nmap's top-100: because it does not know about 6379, 8123, 27017 or 5672 — and those are exactly the ports the rest of this platform goes looking for."

  ECONNREFUSED counts as a sign of life — it proves the host exists. MAC (from ARP) and name (reverse DNS) are added where available; their absence is normal. Control figure on a test /24: ICMP alone found 20 hosts, with ARP and port knocking — 76.

• Scan the ports (ports). A TCP connect scan — not SYN: a completed handshake is proof, and stealth is not needed when inventorying your own network. Port sets: By the service catalogue, Top-100, Extended, all 65535, or a list with ranges (22,80,8000-8100). Open ports get a banner and the service name is refined by it; silent ports get a protocol nudge (HTTP HEAD, Redis PING); TLS ports are not knocked in clear text. Ambiguous ports are told apart by banner rather than guessed — 8123 is ClickHouse or Home Assistant, 9100 is JetDirect or node_exporter. A partial scan never erases the results of a wider one: only ports actually checked are updated.

• Who is still here (sweep). A separate, cheap job — one packet per address, no ARP, no ports, no DNS — that answers "are the machines we know still alive". Nothing is added or removed: a host that stopped answering stays in the inventory as down, because "was there on Tuesday, not now" is the fact the whole thing exists for. Cheap enough to put on a schedule, which is the point: every other kit reads a host's up from here.

Watching a scan

A scan does not go quiet. While it runs, the Networks screen shows a panel for it: the phase it is in, how far along, and — for a discovery — every address that has answered so far and how it proved it exists (a ping reply, the kernel's ARP cache, a knock on a well-known port), with its MAC and name as they arrive; for a port scan — every host, which are queued, scanning or done, the ports as they open with the catalogue's tag beside each, and the role the catalogue would give the host once its list is complete. The role is provisional until the scan finishes and the classification is written; the panel says so. A scan handed to an agent has no narration: the agent reports when it is done. The inventory itself is still written once, at the end.

The model

• A network is a scan area: name, targets, profile, colour, site. A site (a core entity) is what is shown as one map and may contain several networks. Links may join nodes of different networks of one site — that is what a site exists for.
• An address is unique within a network, not globally. 10.0.0.5 in dev and 10.0.0.5 in prod are different hosts; the network of a node is therefore always visible on the map. The reference example is a site with seven Proxmox nodes and nine VLANs, one of which (vmbr_nat, 10.11.1.0/28) repeats on every node.
• A node is a host, not an address. A machine may have interfaces in several networks (a Proxmox node in six VLANs, a Kubernetes node in dev, test and prod). Interfaces are what the scanner finds; the host is what joins them; ports belong to an interface and are shown grouped on the host.
• Merging interfaces into a host starts from the safe state — every address its own host — and uses one rule that decides everything: the same MAC in different networks is one physical card with tagged sub-interfaces (merge); the same MAC in one network is a machine announcing others' addresses, as MetalLB does in L2 mode (link, do not merge). Mixing the two would glue a Kubernetes node to all its service addresses. Reverse-DNS name matching is the weaker second signal. Manual merge and split are ordinary operations, and what a person merged or split, automation never undoes.
• A host that disappeared stays on the map, dimmed, not deleted — the drawn diagram and notes are still valuable, and the disappearance is what needs seeing. A host counts as gone only when all its addresses are silent.

The map

Cytoscape, vendored, works offline. Nodes are dragged and positions saved; node size reflects the number of links, so a hub reads as a hub at a glance; labels wrap, hide when unreadable, and no layout may overlap them at maximum zoom. Layouts: as it is, clusters (stars), tree, buses (networks as horizontal bars, hosts wired to every bar they have an interface in — the familiar "who is in which VLAN" diagram), rings, grid, force. A layout applied with two or more nodes selected moves only them; [ and ] squeeze or stretch a selection without changing its structure; G drags a hub together with its neighbours.

Links are drawn by hand, from node to node, with a label, colour, direction, style and note; S makes a star from a selection. Inferred links (several addresses answering ARP with one MAC, within one network) are dashed, marked auto, and rebuilt every run. A link drawn by a person is never changed or deleted automatically.

The service catalogue

A record of what an open port means: name, ports, an optional banner pattern, icon, colour, priority, and whether it defines the role of a node. Shipped with postgres 5432, redis 6379, mysql 3306, mongodb 27017, clickhouse 8123/9000, rabbitmq 5672/15672, https, http, ssh, rdp, smb, dns, k8s-api 6443, node-exporter 9100, docker 2375/2376, proxmox 8006, mikrotik 8728, elasticsearch 9200, prometheus 9090, grafana 3000, wireguard 51820. Editable by the user; a built-in entry a person changed is that person's data and survives upgrades. Services that are almost everywhere — ssh, node-exporter, dns — do not define a role by default, or every machine in a cluster would be an "SSH server". An icon picked on a node by hand always wins.

History

Appeared, went away, came back, a port opened, a port closed, the role changed — kept for 180 days, per host ("This host's history"). The first role classification is not journaled, only changes; a record survives the deletion of what it is about.

What it needs

• The host network and NET_RAW. A scanner that cannot see the L2 segment gets no ICMP replies and no ARP cache. Hence network_mode: host and cap_add: NET_RAW in the compose file; no privileged mode. Two consequences, both deliberate: the platform's PostgreSQL is published on 127.0.0.1 so the kit can reach it, and the kit's port 8101 is on the LAN — which is why AG_MODULE_SECRET is required.

• A traffic budget. AG_NET_PROFILE, polite by default: "Gentle by default, because a scan that saturates a switch is a scan somebody bans."

  Profile	ICMP rate/s	ICMP passes	Discovery sockets	Port-scan sockets per host	Hosts scanned at once
  polite (Gentle)	100	2	48	32	2
  normal	300	2	160	96	4
  fast	1000	1	512	256	8

  Hard ceilings no profile can exceed: AG_NET_MAX_TARGETS (8192 addresses per scan) and AG_NET_MAX_SOCKETS (768). One scan at a time, always — max_parallel: 1 on every job kind; the traffic ceiling belongs to the installation, not to each schedule. Of overdue networks the one that waited longest goes first.

What it measures

Metric	Help
hosts_total	Hosts on the map
hosts_down	Hosts that have stopped answering
ports_open	Open ports
networks_total	Networks

Every host is also a platform resource with identities, so owner, on-call team, environment and criticality live on it in the core, and the /export/v1 API hands them to Zabbix together with the host. A repeated scan does not create duplicates and does not overwrite what a person typed.

What it refuses to do, and why

• Scan outside RFC 1918. "refusing to scan public addresses ({sample} and N more). Set AG_NET_ALLOW_PUBLIC=1 only if you are authorised to scan them." A typo in a prefix is the difference between sweeping your lab and sending traffic towards the internet, so it is closed by default.
• Exceed the target ceiling. "target list exceeds {limit} addresses — narrow the range."
• Anything but IPv4. "only IPv4 is supported."
• Declare ports closed that it did not check. A scan of one port learned nothing about the others.
• Report a shared MAC as a host identity. Inside one network a shared MAC means "announces on behalf of", and handing it to the core as an identity would glue a Kubernetes node to all its service addresses.
• Run two scans at once.
• Overwrite what a person entered — positions, labels, colours, notes, manual links, manually chosen icons, manual merges. Enforced by the code, not by attention: the scanner writes through a path that has no access to the columns a person edits.
• Leave a service with no ports. "ports are what it is matched by, so such an entry would find nothing. To switch a service off, clear 'enabled'."

Known limitations

• No IPv6.
• No SNMP, no LLDP, no automatic L2 topology — possibly later. Links between hosts are drawn by hand or inferred from shared MACs only.
• Verified on one /24 with 76 hosts; behaviour on large networks has not been measured.
• What the map looks like under the mouse and whether it is pleasant to use is checked by a person, not by the suite.

Free level

From the manifest: export is a free feature, agents is not; the limits networks and hosts are declared but not capped yet (-1).

Configuration

AG_NET_PROFILE, AG_NET_ALLOW_PUBLIC, AG_NET_MAX_TARGETS, AG_NET_MAX_SOCKETS, AG_NET_PROBE_PORTS, AG_NET_PORT, AG_NET_HOST — see Configuration.