Skip to content
alan.salmon
All projects
v2 · 2026

Verkko

Network scanner for a homelab: it continuously discovers the devices on each network, compares them with my inventory, editable from the interface, and flags anomalies. It runs on the NAS, behind a password.

Year
2026
Context
Personal tool for my homelab
  • Python
  • OOP
  • Networking
  • SQLite
  • Prometheus
  • Sphinx
Verkko v2 dashboard: device counters, a VM added automatically to the inventory, and a list of devices with their detected type, a random MAC and buttons to add an unknown device to the inventory

01 · Context

The challenge

A practical need: in a growing homelab (a NAS, a Proxmox hypervisor, about ten VMs, connected devices), I kept forgetting which static IP I had given to which device, and the router's "connected devices" page knows neither static IPs nor VMs. Version 1 answered three questions: what is online, does it match my inventory, and which IP is still free. Every two minutes it discovers the devices of each network (with ARP on a local segment, with ICMP and a TCP probe beyond a router), enriches them, then flags anomalies. Daily use showed its limits, and version 2 removed them: adding an unknown device no longer means editing a file on the NAS and restarting, a laptop on DHCP is declared by its MAC, a new Proxmox VM joins the inventory on its own, and Verkko is now part of the homelab's monitoring.

02 · Architecture

How it's built

Diagram of Verkko in the homelab: the browser, signed in with a password; the Synology NAS running Verkko, with its inventory in a database; the local segment lab2 seen with ARP, with Proxmox, its VMs and the other devices that can be woken with Wake-on-LAN; the routed network lab3 probed with ICMP and TCP through the router; and the monitoring (Prometheus, Grafana, Alertmanager to ntfy) reading the metrics with a token
Verkko in the homelab: the NAS scans the local segment with ARP and the routed network with ICMP and TCP, and the monitoring reads its metrics

Key points

  • Layered object-oriented architecture: each layer only depends on the ones below it
  • Discovery method chosen automatically for each network: ARP, or ICMP and a TCP probe
  • Inventory in a database, editable from the interface; devices recognised by their MAC, DHCP ones included
  • Rule-based device type detection with a confidence level, and Proxmox VMs added automatically
  • Token-protected Prometheus metrics, a Grafana dashboard and alerts; per-device availability that leaves out the hours when the NAS is off
  • Single argon2-hashed password, Wake-on-LAN to wake machines up, Sphinx documentation and 17 decision records

03 · In pictures

Gallery

  • Map of lab2 in demo mode: a grid of squares, one per address, coloured by state (static IP online or offline, known or unknown DHCP device, unknown, free), the zones of the addressing plan underlined in colour, the DHCP range outlined by a dashed line and eight numbered anomalies explained on the right
    The map of a /24 in demo mode: one square per address, the zones of the addressing plan, the DHCP range and the anomalies spotted
  • Comparison of two networks: on the left the local segment, seen with ARP with IP, ports, MAC, manufacturer and VM; on the right the routed network, seen with ICMP and TCP, without MAC or manufacturer
    What Verkko sees on a local segment and on a routed network
  • Diagram of how a scan unfolds in ten steps: plan, discovery, ports, enrichment, classification, inventory, storage, reconciliation, findings and web interface, with the unavailable-network case
    How a scan unfolds, from discovery to the web interface
  • Diagram of the code layers: web, service, then analysis, storage, enrichment, discovery, inventory and classification, above the domain, the sources and the configuration, with the composition root on the right
    The layers of the code and the direction of the dependencies

Click an image to open it full screen and browse through the screenshots.

04 · Takeaways

What I took away from it

I learned how to structure a real project in object-oriented style: layers that only depend on the ones below them, interchangeable strategies for discovery and enrichment, and a composition root that assembles everything and lets me swap any object in the tests and the demo mode. I also learned to document with Sphinx: pages in Markdown, decision records explaining the choices, a glossary, and diagrams generated by code rather than drawn by hand. With version 2, I learned how to evolve a project that is already running: revisiting my own choices, such as replacing the YAML inventory with a database, and recording it in a new decision record rather than erasing the old one.