NetAlertX: Docker-based network asset discovery and change detection

The gap NetAlertX fills between DHCP leases and a full NMS

Most small networks have no inventory at all. The router knows which leases are active, the switch knows which ports are up, and nobody has a list of what should be there. NetAlertX targets that gap. The README describes it as a "network visibility and asset intelligence platform for homelabs, IT teams, MSPs, and distributed environments", and the use cases it names are concrete: shadow IT, unauthorized hardware, and IPAM drift.

The audience matters because it shapes the trade-offs. This is not a packet analyzer and not a replacement for a monitoring system that tracks CPU and interface counters. It answers a narrower question: what is connected, has it changed, and does anyone need to know. For a managed service provider watching branch offices, that question repeats per site, which is why the project ships Sync Nodes and a wallboard view rather than only a device table.

If your network is a single flat subnet with a handful of devices you recognize, the value is thin. The tool earns its keep when the device list is long enough that you cannot hold it in your head, or when sites are far enough apart that nobody visits them weekly.

How discovery, storage and alerting actually fit together

The mechanism is a scan-and-diff loop. Scanners collect device data, results land in a database, and the application compares the current state against what it recorded before. Anything new, missing, or altered becomes an event, and events feed the notification gateways and the workflows module.

The scanner list is the part worth reading closely. The README names arp-scan, Pi-hole DB import, Pi-hole DHCP leases import, generic DHCP leases import, UNIFI controller import, and SNMP-enabled router import. Those are different collection strategies, not variations on one. arp-scan sees whatever answers on the local segment, which means it cannot cross a router. The import plugins read a source that already knows about devices elsewhere, so a UNIFI controller or a Pi-hole instance extends visibility past the subnet the container sits on.

That distinction explains the networking requirements. The compose file uses host networking and states the reason directly: "Use host networking for ARP scanning and other services". The same file adds NET_ADMIN, NET_RAW and NET_BIND_SERVICE, and comments that NET_ADMIN and NET_RAW are needed for arp-scan, nmap, nbtscan, traceroute and zero-conf. It also sets arp_ignore and arp_announce sysctls, described as ARP flux mitigation for host networking accuracy. Those are not optional hardening extras. They are the conditions under which the primary scanner produces usable output.

Outputs are not limited to the web UI. The README points to API endpoints, webhooks for custom automation, Prometheus metrics export, and a Home Assistant integration. The requirements file backs this up with graphene and flask for the API layer, paho-mqtt for MQTT, and a long list of device-specific libraries including pyunifi, tplink-omada-client, librouteros, fritzconnection, freebox-api and asusrouter. Each of those corresponds to an import path for a particular vendor's equipment.

Installing NetAlertX with Docker and reaching the first scan

The README's quick start is a single docker run command. It publishes port 20211, mounts a local data directory at /data, and grants the three capabilities the scanners need. The README notes that your local data directory should contain config and db folders, so create them before starting the container or the mount will be incomplete.

docker run -d \
  --network=host \
  --restart unless-stopped \
  --cap-add=NET_RAW \
  --cap-add=NET_ADMIN \
  --cap-add=NET_BIND_SERVICE \
  -v /local_data_dir:/data \
  -v /etc/localtime:/etc/localtime:ro \
  --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
  -e PORT=20211 \
  -e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \
  ghcr.io/netalertx/netalertx:latest

After it starts, the interface is served on the port passed through the PORT environment variable, which the example sets to 20211. The GraphQL port is overridden separately through APP_CONF_OVERRIDE, shown here as 20214. Because the container uses host networking, there is no port mapping to add; the values in the environment are what the application binds to.

If you would rather build from source, the README gives a three-command sequence. It clones the repository, changes into it, and brings the compose stack up with a rebuild.

git clone https://github.com/netalertx/NetAlertX.git
cd NetAlertX
docker compose up --force-recreate --build

The README adds that you can edit docker-compose.yaml and rerun the last command to customize. That file is also where the security posture is set. It runs the container read-only, drops all capabilities, and adds back only the six listed, each with a comment explaining why it is needed. One comment notes that starting as user 20211 is more secure but loses provisioning capabilities, so the user line is present and commented out by default.

The README carries a warning above the quick start: the docker-compose has changed recently, and readers should check the migration guide before upgrading. If you are moving from an older deployment, read that page first rather than assuming your existing compose file still matches.

Where the design costs you: privileges, scope and the plugin dependency list

The first real constraint is that NetAlertX wants privileges that many operators refuse to grant. Host networking plus NET_ADMIN and NET_RAW is effectively a container that can see and touch the local segment. The compose file mitigates this by dropping all capabilities and adding back a named set, and the hardened Dockerfile stage is described as removing root, sudoers and folders so that only project code runs after each restart. That is a thoughtful posture, but it does not change the fact that the container needs raw socket access to do its main job.

Second, discovery scope is bounded by collection method. arp-scan only reports what responds on the segment the container is attached to. Anything behind a router needs an import plugin, which means the quality of your inventory depends on the quality of your router, controller or DHCP source. If you run hardware none of the bundled integrations cover, you are either writing a plugin or accepting partial coverage. The README does point to a plugin tutorial described as taking as little as 15 minutes, but writing one is still your work, not the project's.

Third, the dependency surface is wide. requirements.txt lists dozens of vendor libraries, from unifi-sm-api and pyunifi to fritzconnection and freebox-api, plus scapy and python-nmap for scanning. Each is a moving part that can break against a firmware update on the device it talks to. The project's own release notes for v26.9.0 mention a "Plugin architecture shift", which is a signal that the extension model has been changing. If you build on it, expect to track releases.

Finally, this is not a traffic monitor. Nothing in the README describes flow analysis, bandwidth accounting per host, or deep packet inspection. If your question is what a device is doing rather than whether it is present, this is the wrong tool.

NetAlertX compared with running Pi-hole and a scanner script

The closest thing to a natural alternative is the combination people already have: Pi-hole for DNS and DHCP visibility, plus a cron job running arp-scan or nmap and mailing the diff. That setup shares the core idea, which is why NetAlertX ships Pi-hole import plugins in the first place.

The difference is state and workflow. A cron script produces a text diff with no memory of what a device is, when it was first seen, or whether someone already acknowledged it. NetAlertX keeps devices in a database with a per-device change log, which the v26.8.5 release notes added, and layers workflows on top. The README describes the workflows module as enforcing device categorization and cleanup policies, with examples including assigning newly discovered devices to a Network Node, auto-grouping devices from a given vendor, unarchiving a device when it comes back online, and automatically deleting devices. A shell script can do the first and the last of those; the middle two require the data model.

The other axis is multi-site. The README describes Sync Nodes for VLANs and branch offices, giving unified visibility across networks from one interface. Reproducing that with scripts means writing your own aggregation and authentication between sites. If you have one site, the script is genuinely simpler. If you have five, the script becomes a small application you maintain yourself.

Licence, maintenance and what an upgrade actually costs

NetAlertX is licensed under GPL-3.0. For most self-hosters that changes nothing. For anyone embedding it in a product, the copyleft terms apply to distributed derivative work, and the plugin system is the area where that question gets interesting, since plugins that link into the application are different from separate processes that talk to its API. That is a question for your own counsel, not something the README settles.

The repository is not archived, and the last push was on 2026-09-21. Releases are frequent: v26.7.1 on 2026-07-01, v26.8.5 on 2026-08-04, and v26.9.0 on 2026-09-02. The v26.9.0 title mentions a "CalVer transition", so version numbers now track the calendar, which makes it easier to judge how stale a running instance is.

Frequent releases cut both ways. Fixes arrive quickly, and so does change. The README already warns that the docker-compose changed and points at a migration guide, and the v26.9.0 notes mention a plugin architecture shift. The upgrade cost is therefore not just pulling a new image. It is reading the release notes, checking whether your compose file still matches, and confirming that any plugin you depend on still works. Budget that as recurring work rather than a one-time setup.

Editorial conclusion

Adopt NetAlertX if you run several VLANs or branch sites and want change alerts without operating a full NMS. Skip it if you cannot grant a container NET_ADMIN and NET_RAW on the host, or if you only need periodic port scans. Before deploying, confirm your /data directory already contains config and db folders, check which plugin matches your router or DHCP source, and read the migration guide if you are moving from an older docker-compose layout.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. netalertx/NetAlertX on GitHub
3. Project website
4. README
5. Releases