Deploy NetAlertX on Docker: Automated HomeLab Network Scanning and Rogue Device Alerts

Table of Contents

The Real-World Problem: Silent Intruders and Network Blind Spots

During a routine weekend storage migration on my home cluster, an unfamiliar IP address caught my attention: 192.168.1.184. A quick MAC lookup revealed an unbranded Tuya Wi-Fi smart plug pinging remote AWS endpoints every four seconds.

A family member had plugged it in three weeks earlier behind a bedside lamp and forgotten about it. For twenty-one days, a budget IoT gadget with closed-source firmware sat directly on my primary management subnet—sharing Layer 2 broadcast traffic with my Proxmox hypervisor, TrueNAS backup pools, and IPMI out-of-band interfaces.

Most self-hosters face this exact blind spot. We run hypervisors, spin up dozens of containers, configure guest Wi-Fi, and patch smart home gear into isolated switches. But unless you constantly run manual terminal sweeps, you cannot see what attaches to your physical or wireless network at 2:00 AM. Unvetted IoT devices, rogue static IPs, visiting laptops, or even compromised microcontrollers can sit quietly on your subnets for weeks before anyone notices.

Root Cause Analysis: Why Standard Routers Leave You in the Dark

Why do commercial routers fail to catch these devices immediately? Standard prosumer gateways rely on passive mechanisms that miss non-standard network behavior:

Passive, Ephemeral DHCP Leases: Most consumer routers and entry-level firewalls only display active DHCP allocations. If a device boots with an unassigned static IP outside your DHCP pool, the router table never registers it. Once an existing lease expires, the audit trail vanishes completely.
Layer 2 Isolation from Layer 3 Gateways: Devices on the same local subnet communicate directly through Layer 2 Ethernet switches using Address Resolution Protocol (ARP). Unless that inter-device traffic needs to cross subnets via your default gateway, your router never inspects those local frames.
Zero Native Webhook Support: Typical router firmware writes connection events to a volatile RAM ring buffer. When an unknown MAC address associates with your access point, the router quietly increments a counter instead of firing a webhook to your phone.

Comparing Detection Strategies: Scripts vs. Firewall Rules vs. NetAlertX

HomeLab operators usually approach network discovery in one of three ways:

Custom Cron Scripts (Nmap / Arp-scan): A lightweight bash script can run arp-scan --localnet every five minutes, compare output against a text file, and curl a webhook on diffs. It works, but it breaks quickly. Mobile devices enter deep sleep modes and trigger constant false disconnections. You also lose MAC vendor resolution and historical uptime logs.
Firewall-Native Plugins (OPNsense / pfSense / MikroTik): You can monitor ARP tables and DHCP events using built-in scripts or packages on your firewall. While reliable, this approach couples your notification pipeline to core routing hardware. Heavy Nmap sweeps also consume valuable CPU cycles on your edge gateway.
Dedicated Network Watchdogs (NetAlertX): NetAlertX—the modernized successor to Pi.Alert—runs as a lightweight standalone daemon. It pairs active ARP sweeps, ICMP pings, and DNS lookups with automated MAC vendor identification. When an unapproved MAC address broadcasts its first frame, NetAlertX logs the event and pushes an instant alert to Discord, Telegram, or Pushover. Memory consumption stays around 120MB, and CPU overhead remains below 2% on an Intel N100 mini PC.

The Solution: Deploying NetAlertX on Docker

Containerizing NetAlertX provides clean persistence and effortless version upgrades without cluttering your base operating system. However, network discovery tools have one non-negotiable rule: you must enable host networking mode.

Docker’s default bridge network (docker0) places containers inside an isolated virtual namespace behind Network Address Translation (NAT). Because ARP requests are non-routable Layer 2 broadcast packets, they cannot cross that bridge boundary. Setting network_mode: "host" binds NetAlertX directly to your physical network interface (such as eth0 or enp3s0), giving the scanner raw access to broadcast traffic across the local wire.

Step 1: Create Directories and Set Permissions

SSH into your Docker host (such as Debian 12 or Ubuntu 24.04 LTS) and build the storage layout for persistent state, SQLite databases, and logs:

mkdir -p ~/netalertx/config
mkdir -p ~/netalertx/db
mkdir -p ~/netalertx/log
cd ~/netalertx

Step 2: Write the Docker Compose Configuration

Create your compose file:

nano docker-compose.yml

Paste the configuration below. Notice network_mode: "host", which lets the scanner bypass Docker’s virtual bridge and see your physical network adapters directly:

services:
  netalertx:
    image: jokobsk/netalertx:latest
    container_name: netalertx
    restart: unless-stopped
    network_mode: "host"
    environment:
      - TZ=America/New_York
      - PORT=20211
      - SCAN_SUBNETS=192.168.1.0/24
    volumes:
      - ./config:/app/config
      - ./db:/app/db
      - ./log:/app/log

Adjust SCAN_SUBNETS to match your LAN (for example, 10.0.10.0/24 if you scan an isolated management subnet). Set TZ to your local tz-database string.

Step 3: Launch NetAlertX and Inspect Startup Logs

Start the container in the background:

docker compose up -d

Monitor the initial startup sequence to verify that SQLite migrations completed and raw socket bindings succeeded:

docker compose logs -f netalertx

You should see confirmation messages showing the database initialized and the background ARP daemon started. Now open your browser and navigate to:

http://<DOCKER_HOST_IP>:20211

Step 4: Establish a Network Baseline and Enable Push Alerts

On the initial scan, NetAlertX flags every discovered device as an unknown asset. Take twenty minutes to audit this inventory before turning on aggressive notifications. Name each host cleanly (for instance, “Living Room Apple TV 4K” or “Dell R730 iDRAC”), assign an accurate device type, and mark the hardware as Connected / Known.

Once your trusted baseline is locked in, configure notifications so future unknown devices trigger an immediate alert:

In the NetAlertX web interface, open Settings > Alerting.
Select your target platform (such as Telegram, Discord Webhook, or Gotify).
For Telegram, enter your Bot Token and numeric Chat ID, then click the test button to verify receipt.
Check the box for Alert on New Devices Found.
Navigate to Settings > Core and set the scan interval. A 3-minute cycle detects foreign hardware quickly while keeping ARP broadcast volume under 15 packets per second across a standard /24 subnet.

Step 5: Test the Alert Pipeline

Verify your setup by introducing an uncataloged device. Grab a smartphone, open its Wi-Fi settings, switch off “Use Private Wi-Fi Address” (or toggle MAC randomization on), and reconnect to your LAN. You can also assign a temporary unused static IP to a secondary laptop.

Within two scan cycles, NetAlertX flags the unknown MAC address, identifies the vendor OUI prefix, and pushes a notification directly to your phone:

[NetAlertX Alert]
Status: New Device Detected
IP Address: 192.168.1.184
MAC Address: 4A:2B:11:89:C4:02 (Vendor: Randomized / Unknown)
Network Interface: eth0
First Seen: 2026-10-14 11:15:00

Your HomeLab now maintains continuous visibility over its physical segments. Unknown hardware no longer connects silently, and you get notified before rogue devices can probe your internal services.