Local Network Monitoring with NetAlertX, WatchYourLan, and Nmap

Monitoring your local network is critical for maintaining security, managing devices, and ensuring overall performance. In this post, we'll cover how to set up three powerful tools: NetAlertX, WatchYourLan, and nmap. Each tool offers a different approach to network monitoring, ranging from lightweight solutions for smaller environments to more comprehensive systems designed for distributed networks.

We are not diving into enterprise monitoring tools such as PRTG Network Monitor, SolarWinds, or Nagios as the edge case I came across required me to be able to monitor networks that I do not have control over. I needed to know the devices on the LAN and keep them logged—similar to wardriving, but in fixed environments.

1. NetAlertX: Advanced Network Monitoring and Device Tracking

NetAlertX is the continuation of the now-discontinued PiAlert project, traditionally used with Raspberry Pis to monitor local networks. NetAlertX introduces distributed monitoring with master-slave architecture, allowing for scalability and flexibility in larger environments.

Key Features of NetAlertX:

• Distributed Monitoring: In multi-instance setups, one node serves as the master, while others (slave nodes) push data to the master instance via Sync Hub.
• Efficient Scanning: Scans the network every 5 minutes, detecting new devices and changes.
• Historical Analysis: Tracks device history for up to 3 years (configurable).
• API Support: Easily integrate with external platforms for advanced analysis.

Docker Deployment for NetAlertX:

services:
  netalertx:
    container_name: netalertx
    image: "jokobsk/netalertx:latest"      
    network_mode: "host"        
    restart: always
    volumes:
      - netalertx_config:/app/config
      - netalertx_db:/app/db
      - netalertx_logs:/app/log
      - type: tmpfs
        target: /app/api
    environment:
      - TZ=Europe/London      
      - PORT=20221
volumes:
  netalertx_config:
  netalertx_db:
  netalertx_logs:

Configuration Steps:

1. Access the Interface: Navigate to http://[IP]:20221.
2. Initial Setup:
   • Go to Settings > System and set an admin password.
   • Under Core > General, define the network range to scan.
   • Adjust event retention to 3 years (1095 days) under Core > Delete Events to comply with NIST standards.
3. Enable Device Scanners:
   • ARP Scanning: Report on new devices, changes, and missing devices.
   • Internet Check: Detect external connectivity issues and watch for device drops.
4. Multi-Node Setup (Optional):
   • On the master node, generate an API token under Core > API Token and sync it to all slave nodes.
   • Set an encryption key under Sync Hub > Encryption Key (same on all nodes).
   • Configure slave nodes to push data by setting the Hub URL and enabling Sync Devices.

Analysis and Data Aggregation:

Data collected by NetAlertX can be exported to external platforms such as Business Intelligence tools or data aggregators for further processing, providing deeper insights into your network's health and activity.

2. WatchYourLan: Lightweight and Fast Network Monitoring

WatchYourLan is a simple, lightweight tool designed for small networks. It offers quick device detection without complex configurations but lacks authentication or custom user settings.

Key Features of WatchYourLan:

• Minimal Setup: Simple Docker deployment with minimal configuration.
• Real-Time Device Monitoring: Continuously scans the network and lists active devices.
• User-Friendly: Web-based interface with no additional authentication.

Docker Deployment for WatchYourLan:

services:
  wyl:
    image: aceberg/watchyourlan
    network_mode: "host"        
    restart: unless-stopped
    volumes:
    - wyl:/data/WatchYourLAN
    environment:
      TZ: Europe/London              # Required for correct time
      IFACES: "ens18"  # Use wlan0 for Raspberry Pi
      HOST: "0.0.0.0"  # Default: 0.0.0.0
      PORT: "8840"       # Default: 8840
      TIMEOUT: "120"     # Timeout in seconds
volumes:
  wyl:

Access and Usage:

• Navigate to http://[IP]:8840.
• Devices on the local network will automatically appear.

Best Use Case:

WatchYourLan is perfect for small home networks or simple setups where basic device detection is sufficient.

3. nmap: Flexible and Scriptable Network Scanning

nmap is a powerful command-line tool for network scanning and mapping. It provides detailed information about devices, open ports, and operating systems.

Why Use nmap:

• Versatile: Supports various scanning techniques (ping sweeps, port scans, OS detection).
• Automatable: Easily scriptable for continuous monitoring.
• Detailed Reports: Comprehensive output, ideal for analyzing network activity.

Automating nmap with Bash (Raspberry Pi):

The script scans a local network for live hosts, performs service detection on them, compiles the results into a JSON file, and uploads the file to a remote server via SFTP. It sends webhook notifications for errors and progress updates.

#!/bin/bash

# Webhook URL for error notifications
WEBHOOK_URL="webhooklink"

# Get the local subnet dynamically
SUBNET=$(ip -o -f inet addr show | awk '/scope global/ {print $4}')
if [ -z "$SUBNET" ]; then
    curl -X POST -H 'Content-Type: application/json' -d '{"text":"Error: Unable to determine local subnet."}' "$WEBHOOK_URL"
    exit 1
fi

# Perform initial nmap scan to discover live hosts
MAPFILE=()
echo "[+] Scanning for live hosts on subnet: $SUBNET..."
while IFS= read -r line; do
    if [[ $line == *"Nmap scan report for"* ]]; then
        IP=$(echo $line | awk '{print $5}')
        MAPFILE+=("$IP")
        echo "[+] Found live host: $IP"
    fi
done < <(nmap -sn $SUBNET)

# Start building the JSON
JSON_OUTPUT="{\"devices\":["

parallel_scan() {
    local IP=$1
    echo "[+] Scanning host: $IP"
    local RESULT
    RESULT=$(nmap -sV --top-ports 50 $IP 2>&1)

    if [ $? -ne 0 ]; then
        curl -X POST -H 'Content-Type: application/json' -d '{"text":"Error scanning host: '$IP'"}' "$WEBHOOK_URL"
        return
    fi

    HOSTNAME=$(echo "$RESULT" | awk '/Nmap scan report for/ {print $5}' | tr -d '()')
    MAC=$(echo "$RESULT" | grep -i "MAC Address" | awk '{print $3}')
    PORTS=$(echo "$RESULT" | grep -oP '\\d+/tcp.*open.*' | awk '{print $1}' | jq -R . | jq -sc .)

    PORTS=${PORTS:-"[]"}
    TIMESTAMP=$(date +'%Y-%m-%d %H:%M:%S')
    HOSTNAME=${HOSTNAME:-"unknown"}
    MAC=${MAC:-"unknown"}

    echo "[+] Completed scan for: $IP at $TIMESTAMP"
    echo "{\"ip\":\"$IP\",\"hostname\":\"$HOSTNAME\",\"mac\":\"$MAC\",\"ports\":$PORTS,\"timestamp\":\"$TIMESTAMP\"},"
}

export -f parallel_scan

JSON_ENTRIES=$(printf "%s\n" "${MAPFILE[@]}" | xargs -n 1 -P 10 -I {} bash -c 'parallel_scan {}')

JSON_OUTPUT+="$JSON_ENTRIES"
JSON_OUTPUT=${JSON_OUTPUT%,}
JSON_OUTPUT+="]}"

TIMESTAMP=$(date +'%Y%m%d_%H%M%S')
OUTPUT_FILE="/root/scan_output_$TIMESTAMP.json"
echo "$JSON_OUTPUT" > "$OUTPUT_FILE"

# SFTP Credentials
SFTP_HOST="IP"
SFTP_PORT="PORT"
SFTP_USER="USERNAME"
SFTP_PASS="PASSWORD"
REMOTE_DIR="/PATH/TO/FOLDER"

lftp -u "$SFTP_USER,$SFTP_PASS" -e "set sftp:connect-program 'ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -a -x -p $SFTP_PORT'; put $OUTPUT_FILE -o $REMOTE_DIR/$(basename $OUTPUT_FILE); bye" sftp://$SFTP_HOST

if [ $? -ne 0 ]; then
    curl -X POST -H 'Content-Type: application/json' -d '{"text":"SFTP upload failed."}' "$WEBHOOK_URL"
    exit 1
fi

# Cleanup local file
rm -f "$OUTPUT_FILE"
echo "[+] Scan and upload complete. Local file deleted."

Automating with Cron:

Add the following to crontab to schedule scans every 10 minutes:

*/10 * * * * /home/pi/nmap_monitor.sh