NetAlertX: Continuous Network Visibility & Intrusion Detection for Homelabs

Perimeter Awareness: Continuous Network Asset Discovery for Homelabs

As homelabs expand to accommodate dozens of IoT microcontrollers, virtual machines, smart appliances, and Docker containers, maintaining an accurate inventory of connected devices becomes a critical security requirement. Standard consumer routers offer rudimentary DHCP tables that lack historical retention and immediate alerting. NetAlertX solves this visibility gap through automated, continuous LAN surveillance.

Operating as an active sentinel on your local subnet, NetAlertX pairs asynchronous Layer-2 ARP polling with scheduled Nmap port scans and vendor MAC resolution. It alerts you instantly via encrypted webhooks whenever an unauthorized device associates with your network or a new listening port is exposed.

What It Is

NetAlertX is a comprehensive, self-hosted network asset management platform and the active, modernized continuation of the popular Pi.Alert project. It provides a rich web dashboard that graphs device presence timelines, connection histories, latency metrics, and open socket states.

Beyond basic presence detection, NetAlertX actively monitors infrastructure drift: IP address reassignments, MAC spoofing attempts, new service port bindings, and unexpected device dropouts. It integrates seamlessly with messaging pipelines including Discord, Telegram, Pushover, NTFY, and Home Assistant.

Why You Have Not Heard Of It

The project was forged when a dedicated community of homelab engineers took the dormant Pi.Alert codebase and rebuilt it into an enterprise-ready, container-native platform. Maintaining a fierce focus on reliability, Docker simplicity, and agentless discovery, NetAlertX has earned its status as an indispensable staple in modern self-hosted stacks.

How It Works

NetAlertX orchestrates multiple network scanning primitives in coordinated cycles:

Layer-2 ARP Scanning (arp-scan): Broadcasts low-overhead Layer-2 queries across the local subnet to detect every connected host—even those configured with firewalls that drop ICMP echo requests.
Nmap Service Fingerprinting: Periodically scans discovered endpoints to enumerate listening TCP/UDP ports, identifying unencrypted web portals, open database sockets, and SSH services.
Vendor & DNS Enrichment: Correlates MAC Organizationally Unique Identifiers (OUIs) with hardware manufacturer databases and queries local DNS resolvers (such as Pi-hole, AdGuard Home, or OPNsense) to auto-populate human-readable hostnames.

Running It

Because Layer-2 ARP discovery requires direct access to host network interfaces, NetAlertX is deployed using Docker in host network mode:

services:
  netalertx:
    image: jokobsk/netalertx:latest
    container_name: netalertx
    network_mode: "host"
    restart: unless-stopped
    volumes:
      - ./config:/app/config
      - ./db:/app/db
      - ./logs:/app/front/log
    environment:
      - TZ=UTC
      - PORT=20211

Start the service:

docker compose up -d

Open http://<SERVER_IP>:20211 in your browser to configure your target CIDR subnets (e.g., 192.168.1.0/24) and notification dispatchers.

What It Replaces

Proprietary Mobile Scanners (Fing): Replaces closed-source mobile scanning apps with an always-on 24/7 server appliance that never uploads your network topology to third parties.
Ephemeral Router DHCP Lists: Maintains persistent historical audit logs of every connection event across weeks and months.
Heavyweight Enterprise Monitoring (Zabbix/PRTG): Delivers instant, agentless home network visibility in a lightweight container without complex metric configurations.

Limitations

In complex multi-VLAN architectures, Layer-2 ARP broadcasts cannot cross routed boundaries without deploying NetAlertX scanning agents on each isolated VLAN segment or utilizing trunked network interfaces.

Who It Is For

Homelab sysadmins needing immediate notification when unfamiliar devices associate with Wi-Fi access points.
Security engineers auditing exposed service ports across internal development servers.
Smart home automators using device Wi-Fi association for robust presence detection in Home Assistant.

Conclusion

NetAlertX delivers total situational awareness to private local networks. With low system overhead, agentless discovery, and proactive alerting, it stands as the gold standard for homelab network inventory and security monitoring.