NetAlertX: The Network Monitor Every DevOps Team Needs

Your network is growing. Devices appear overnight. Shadow IT lurks in every corner. Are you truly aware of what's connected? NetAlertX emerges as the revolutionary open-source solution that transforms network chaos into crystal-clear visibility—delivering continuous asset discovery, automated compliance, and real-time change detection without the enterprise price tag.

Network administrators and security professionals face a critical challenge: maintaining accurate inventory across distributed environments. Traditional tools either overwhelm with complexity or lack essential features. NetAlertX bridges this gap perfectly, offering a sleek, powerful framework that monitors devices, detects changes, and keeps you aware across every network segment. This comprehensive guide reveals why developers are flocking to this tool and how you can implement it in minutes.

What Is NetAlertX? The Modern Network's Source of Truth

NetAlertX is an open-source Network Visibility & Asset Intelligence Framework designed to serve as your centralized Network Source of Truth (NSoT). Created by developer jokobsk, this powerful tool continuously monitors network infrastructure, discovers connected devices, and tracks configuration changes across distributed networks in real-time.

Unlike monolithic SIEM platforms that demand months of configuration, NetAlertX delivers actionable insights within minutes. The framework operates as a lightweight containerized application that scans your network using multiple discovery methods—including arp-scan, Pi-hole database imports, DHCP lease parsing, UNIFI controller integration, and SNMP-enabled router queries. This multi-vector approach ensures no device remains hidden, from rogue Raspberry Pis to unauthorized enterprise switches.

Why NetAlertX is trending now: The explosion of IoT devices, remote work infrastructure, and Shadow IT has created unprecedented network blind spots. Organizations struggle with regulatory compliance, asset management, and security posture. NetAlertX addresses these pain points directly, providing a free, self-hosted alternative to costly commercial solutions while offering plugin extensibility that enterprise tools can't match. Its seamless Home Assistant integration makes it equally valuable for prosumers and SMBs seeking enterprise-grade visibility without complexity.

The framework stores all data locally by default, ensuring privacy and compliance with strict data sovereignty requirements. With over 80 notification gateway integrations and a robust API, NetAlertX automates workflows that previously required manual intervention, saving teams countless hours while strengthening security posture.

Key Features That Make NetAlertX Revolutionary

Discovery & Asset Intelligence Engine

NetAlertX's core strength lies in its continuous monitoring capability. The framework doesn't just scan periodically—it maintains persistent awareness of your network's state. The discovery engine supports multiple scanning methods simultaneously:

• ARP-based discovery for immediate Layer 2 visibility
• Pi-hole integration (both database and DHCP leases) for DNS-level device tracking
• Generic DHCP lease import for universal compatibility
• UNIFI controller import for Ubiquiti ecosystem users
• SNMP-enabled router import for enterprise-grade network gear

This multi-method approach creates a comprehensive device fingerprint that includes MAC addresses, IP assignments, hostnames, vendors, and connection history. The system automatically detects Shadow IT devices—unauthorized hardware that bypasses normal procurement—and flags them for review, crucial for maintaining regulatory compliance in SOC 2, ISO 27001, and HIPAA environments.

80+ Notification Gateways

Stay informed through your preferred communication channel. NetAlertX integrates with Apprise, supporting over 80 notification services including Telegram, Discord, Slack, Microsoft Teams, and custom webhooks. Native support for Pushsafer, Pushover, and NTFY ensures reliable mobile alerts even when corporate messaging systems fail.

Plugin Architecture

The extensible plugin system allows custom scanner development in as little as 15 minutes. This revolutionary approach means you're not limited to built-in discovery methods. Create specialized scanners for proprietary hardware, industrial IoT protocols, or cloud metadata services. The plugin API provides access to the full device lifecycle, enabling custom metadata enrichment and automated classification.

Workflow Automation

The workflows module transforms NetAlertX from a monitoring tool into an automation engine. Define policies that automatically categorize devices by vendor, assign network nodes, archive offline devices, or trigger deletion after specified periods. This IT governance automation ensures your asset inventory remains clean and actionable without manual intervention.

Home Assistant Integration

NetAlertX offers first-class Home Assistant integration through the official add-on repository. This transforms your home automation hub into a powerful network monitoring center, enabling automations based on device presence, triggering alerts when unknown devices connect, and maintaining historical presence data for every smart home gadget.

Security & Privacy by Design

All scan data remains local by default. No telemetry, no cloud dependencies, no data exfiltration. The framework supports role-based access control via reverse proxy integration, allowing SSO provider authentication. Run behind firewalls, restrict web UI access, and maintain complete data sovereignty—critical for government, healthcare, and financial sectors.

Real-World Use Cases: Where NetAlertX Shines

1. Enterprise Shadow IT Detection & Compliance

A mid-sized financial services firm struggled with unauthorized devices appearing on their network. Employees connected personal laptops, mobile hotspots, and unauthorized IoT devices, creating compliance violations for PCI DSS audits. By deploying NetAlertX across their VLANs, the security team established continuous asset discovery that immediately flagged new devices. Workflow automation categorized devices by MAC vendor OUI, assigned risk scores, and triggered approval workflows. Within 30 days, they identified 47 unauthorized devices and reduced audit preparation time by 70%.

2. Managed Service Provider (MSP) Multi-Tenant Monitoring

An MSP supporting 200+ small business clients needed centralized visibility without deploying agents on client networks. NetAlertX's lightweight containerized deployment allowed them to run instances at each client site, syncing data to a central dashboard via the GraphQL API. The plugin system enabled custom integrations with their ticketing system, automatically creating tickets for critical device changes. This agentless approach reduced deployment costs by 90% while providing better visibility than traditional RMM tools.

3. Smart Home Security & IoT Governance

A technology enthusiast's Home Assistant setup included 80+ IoT devices from various vendors. Unknown devices periodically appeared on the network—some were neighbor's devices connecting to guest networks, others were potentially compromised smart plugs. NetAlertX's Home Assistant integration provided real-time presence detection and automated alerts. When a new device connected, the system cross-referenced it against an approved device list and sent immediate notifications. Historical tracking revealed that several cheap smart bulbs were beaconing to suspicious external IPs, prompting immediate removal.

4. University Campus Network Hygiene

A university's IT department managed 15,000+ devices across dormitories, labs, and administrative buildings. IP address management was chaotic, with students connecting routers and creating rogue DHCP servers. NetAlertX's IPAM drift detection identified IP conflicts and unauthorized DHCP announcements. The SNMP router import provided visibility into switch port assignments, enabling the team to physically locate problem devices. Automated workflows archived student devices after semester end, keeping the database clean and relevant.

5. Industrial Control System (ICS) Security

A manufacturing facility needed to monitor their Operational Technology (OT) network without disrupting critical processes. Traditional scanning tools were too aggressive. Using NetAlertX's plugin system, they developed a passive scanner that monitored network traffic without generating probe packets. The system provided continuous asset discovery for PLCs, HMIs, and industrial IoT devices, alerting when unauthorized engineering workstations attempted to connect to the control network—preventing potential safety incidents.

Step-by-Step Installation & Setup Guide

Deploying NetAlertX requires just minutes with Docker. Follow these precise steps for a production-ready installation.

Prerequisites

• Linux host with Docker and Docker Compose installed
• Network access to the subnets you want to monitor
• Sufficient permissions for host network mode (required for ARP scanning)
• 2GB RAM minimum, 4GB recommended
• Persistent storage directory (e.g., /opt/netalertx)

Method 1: Quick Docker Run

The fastest way to start NetAlertX uses the official container image with host networking:

# Create persistent data directories
sudo mkdir -p /opt/netalertx/{config,db}

# Deploy NetAlertX container
docker run -d \
  --name netalertx \
  --network=host \
  --restart unless-stopped \
  -v /opt/netalertx:/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

Key parameters explained:

• --network=host: Essential for ARP scanning across local subnets
• -v /opt/netalertx:/data: Persistent storage for config and database
• --tmpfs /tmp: Secure temporary file storage with proper permissions
• -e PORT=20211: Web UI access port
• APP_CONF_OVERRIDE: JSON configuration for advanced settings like GraphQL API port

Access the web interface at http://your-server:20211. The initial setup wizard guides you through scan configuration.

Method 2: Docker Compose Deployment

For more control and easier updates, use Docker Compose:

# Clone the repository
git clone https://github.com/netalertx/NetAlertX.git
cd NetAlertX

# Create data directories
mkdir -p data/{config,db}

# Edit configuration if needed
nano docker-compose.yaml

# Deploy the stack
docker compose up -d --force-recreate --build

The docker-compose.yaml provides pre-configured volumes, environment variables, and restart policies. This method simplifies upgrades—just run docker compose pull && docker compose up -d to update.

Method 3: Home Assistant Add-On

For Home Assistant OS or supervised installations:

1. Navigate to Settings → Add-ons → Add-on Store
2. Click the three-dot menu → Repositories
3. Add repository: https://github.com/alexbelgium/hassio-addons
4. Refresh the store and install NetAlertX
5. Configure network access and start the add-on

This integration automatically configures presence sensors for each discovered device, enabling powerful automation based on network connectivity.

Initial Configuration

After installation, complete these critical steps:

1. Define scan targets: Specify subnets, IP ranges, or individual hosts
2. Select discovery methods: Enable ARP scanning, DHCP monitoring, or plugin-based discovery
3. Configure notifications: Set up Apprise URLs or native publishers for alerts
4. Create workflow rules: Automate device categorization and lifecycle management
5. Set up user authentication: Configure reverse proxy with OAuth/OIDC for secure access

REAL Code Examples from the Repository

Let's examine actual code snippets from NetAlertX's documentation and explain their practical implementation.

Example 1: Docker Run Command with Security Hardening

docker run -d \
  --name netalertx \
  --network=host \
  --restart unless-stopped \
  -v /opt/netalertx:/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","SCAN_SUBNETS":["192.168.1.0/24","10.0.0.0/24"]}' \
  --cap-drop=ALL \
  --cap-add=NET_RAW \
  --cap-add=NET_ADMIN \
  ghcr.io/netalertx/netalertx:latest

Explanation: This production-hardened version adds Linux capabilities control. --cap-drop=ALL removes unnecessary privileges, then explicitly adds only NET_RAW (for packet crafting in ARP scans) and NET_ADMIN (for network interface operations). The APP_CONF_OVERRIDE variable demonstrates JSON configuration injection, here pre-configuring scan subnets and GraphQL API port. This approach keeps sensitive settings in environment variables rather than config files, ideal for secrets management in CI/CD pipelines.

Example 2: Docker Compose with Custom Plugin Volume

version: '3.8'
services:
  netalertx:
    image: ghcr.io/netalertx/netalertx:latest
    container_name: netalertx
    network_mode: host
    restart: unless-stopped
    environment:
      - PORT=20211
      - TZ=America/New_York
      - APP_CONF_OVERRIDE={"GRAPHQL_PORT":"20214","DB_BACKUP_DAYS":7}
    volumes:
      - ./data:/data
      - /etc/localtime:/etc/localtime:ro
      - ./custom_plugins:/app/front/plugins/custom:z
    tmpfs:
      - /tmp:uid=20211,gid=20211,mode=1700
    cap_drop:
      - ALL
    cap_add:
      - NET_RAW
      - NET_ADMIN

Explanation: This compose file demonstrates advanced configuration. The custom_plugins volume mount (:z flag for SELinux contexts) allows hot-loading custom scanners without rebuilding the container. Environment variables set timezone and database backup retention. The capability restrictions mirror the Docker run example, providing defense-in-depth security. Using ./data relative path ensures portability across environments.

Example 3: Configuration Override Pattern

# Advanced configuration via environment variable
-e APP_CONF_OVERRIDE='{
  "GRAPHQL_PORT":"20214",
  "SCAN_SUBNETS":["192.168.1.0/24","10.0.0.0/24","172.16.0.0/24"],
  "ARP_SCAN_TIMEOUT":30,
  "DHCP_LEASES_PATH":"/data/dhcp.leases",
  "PIHOLE_DB_PATH":"/data/pihole.db",
  "NOTIFICATION_COOLDOWN":300,
  "WORKFLOW_ENABLED":true,
  "DEVICE_RETENTION_DAYS":90
}'

Explanation: This JSON configuration pattern centralizes critical settings. SCAN_SUBNETS defines multiple network segments for comprehensive coverage. ARP_SCAN_TIMEOUT adjusts probe patience for congested networks. NOTIFICATION_COOLDOWN prevents alert fatigue by throttling messages to once per 5 minutes per device. DEVICE_RETENTION_DAYS automates cleanup of stale inventory. This approach enables environment-specific configurations without modifying container images, perfect for GitOps workflows.

Example 4: Plugin Development Skeleton

Based on the repository's plugin architecture, here's a custom scanner template:

# /app/front/plugins/custom/my_custom_scanner.py
from plugin_utils import PluginBase
import json

class MyCustomScanner(PluginBase):
    def __init__(self):
        super().__init__()
        self.scan_name = "my_custom_scanner"
        self.scan_description = "Detects proprietary IoT devices"
        
    def run_scan(self):
        """Main scan execution method"""
        devices = []
        # Your discovery logic here
        # Example: Query proprietary API, parse logs, etc.
        
        discovered_device = {
            "mac": "aa:bb:cc:dd:ee:ff",
            "ip": "192.168.1.100",
            "hostname": "smart-switch-01",
            "vendor": "MyIoT Corp",
            "custom_field": "firmware_v1.2.3"
        }
        devices.append(discovered_device)
        
        return json.dumps(devices)
    
    def get_config(self):
        """Return plugin configuration"""
        return {
            "enabled": True,
            "scan_interval": 300,  # seconds
            "timeout": 30
        }

# Register the plugin
plugin = MyCustomScanner()

Explanation: This plugin skeleton demonstrates the 15-minute development promise. Inheriting from PluginBase provides automatic integration with NetAlertX's scheduling, logging, and database systems. The run_scan() method returns JSON-serialized device data that the framework automatically merges into the central inventory. The get_config() method enables runtime configuration through the web UI. This extensibility transforms NetAlertX from a tool into a platform, adapting to any network environment.

Advanced Usage & Best Practices

High-Availability Deployment

For mission-critical monitoring, deploy NetAlertX behind a reverse proxy (Nginx, Traefik) with health checks. Use Docker's --restart unless-stopped policy and mount volumes from redundant storage (NFS, Ceph). Configure database backups via the DB_BACKUP_DAYS setting, and sync the /data/db directory to S3 or equivalent object storage every 6 hours.

Performance Optimization

On large networks (/16 subnets or larger), increase ARP_SCAN_TIMEOUT to 60 seconds and reduce SCAN_INTERVAL to 300 seconds to prevent network congestion. Use the SNMP router import method instead of ARP scanning for network gear—it’s faster and less intrusive. Enable the DEVICE_CACHING option to reduce database queries on busy instances.

Security Hardening

Never expose NetAlertX directly to the internet. Always use a reverse proxy with TLS 1.3 and OAuth2/OIDC authentication. Implement network segmentation—run NetAlertX on a management VLAN with firewall rules restricting access to scan targets. Regularly update the container image: docker pull ghcr.io/netalertx/netalertx:latest && docker compose up -d.

Workflow Automation Patterns

Create workflows that:

• Auto-assign new devices to "Quarantine" group for manual review
• Tag devices by vendor using MAC OUI database lookups
• Archive devices offline for >30 days but retain historical data
• Trigger webhooks to ServiceNow/Jira for unauthorized device tickets
• Enrich device records with CMDB data via the GraphQL API

Integration with SIEM

While NetAlertX isn't a SIEM, it feeds them perfectly. Use the GraphQL API (GRAPHQL_PORT:20214) to query device changes:

curl -X POST http://localhost:20214/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ devices(lastSeen: \"24h\") { mac ip hostname lastSeen isNew } }"}'

Pipe this data into Splunk, ELK, or Sentinel for correlation with security events, creating a complete threat detection narrative.

Comparison with Alternatives: Why NetAlertX Wins

Key Differentiators:

• Speed: NetAlertX deploys in seconds versus hours for alternatives
• Flexibility: Plugin architecture adapts to any environment
• Focus: Purpose-built for asset discovery, not bloated with unnecessary features
• Privacy: Local-first design with zero telemetry
• Integration: Modern API-first approach with GraphQL

While Nmap excels at active reconnaissance and OpenVAS at vulnerability assessment, neither provides continuous monitoring or workflow automation. PRTG offers robust monitoring but at significant cost and complexity. LibreNMS focuses on SNMP infrastructure, missing IoT and ephemeral devices. NetAlertX occupies a unique sweet spot: comprehensive asset discovery with intelligent automation.

FAQ: Answering Your Critical Questions

Q: How do I monitor VLANs or remote subnets? A: Use --network=host mode on a Linux host with trunk port access to all VLANs. Configure SCAN_SUBNETS in APP_CONF_OVERRIDE to include each subnet (e.g., ["192.168.10.0/24","192.168.20.0/24"]). For remote sites, deploy NetAlertX instances per location and centralize data via the GraphQL API.

Q: What is the recommended deployment for high-availability? A: Deploy using Docker Compose with persistent volumes on redundant storage. Run behind a reverse proxy with health checks. Enable database backups with DB_BACKUP_DAYS: 7. For true HA, run multiple instances with shared SQLite on NFS (note: use SQLite WAL mode) or switch to PostgreSQL via custom configuration.

Q: Will this send any data to the internet? A: Never by default. All scanning and data storage remain local. The container image is pulled from GitHub Container Registry, but runtime operation is completely air-gapped. Only enabling cloud notifications (Discord, Telegram, etc.) transmits data—and only the alerts you configure.

Q: Can I use this without Docker? A: Yes, follow the bare metal installation guide. You'll need Python 3.9+, SQLite, and manual dependency management. Docker is strongly recommended for easier updates and dependency isolation.

Q: Where is the data stored? A: All data resides in the /data volume mount, specifically /data/config (settings) and /data/db (SQLite database). Back up these directories regularly. The database contains device metadata, scan history, and workflow logs—typically 10-50MB for 500 devices.

Q: How does the plugin system work? A: Plugins are Python classes inheriting from PluginBase. Place them in /app/front/plugins/ (or a mounted volume). NetAlertX auto-discovers plugins on startup, reads their configuration, and executes them on the defined interval. Output must be JSON-formatted device arrays. See the plugin development docs for complete API reference.

Q: Can NetAlertX replace my existing NMS? A: It complements rather than replaces. NetAlertX excels at asset discovery and change detection; traditional NMS tools focus on performance metrics and uptime monitoring. Use NetAlertX for security-focused inventory and NMS for operational monitoring. The webhook/API integration lets them work together seamlessly.

Conclusion: Take Control of Your Network Today

NetAlertX represents a paradigm shift in network visibility—delivering enterprise-grade asset discovery and continuous monitoring without enterprise complexity or cost. Its plugin architecture, workflow automation, and privacy-first design make it uniquely suited for modern network challenges, from Shadow IT detection to IoT governance.

The framework's rapid deployment (literally seconds with Docker) and extensive integration ecosystem (80+ notifications, Home Assistant, GraphQL API) empower both home users and enterprise teams to achieve unprecedented network awareness. Whether you're securing a university campus, managing an MSP client base, or simply want to know what's on your home network, NetAlertX provides the tools you need.

Ready to eliminate network blind spots?

⭐ Star the repository at github.com/netalertx/NetAlertX to support the project 🚀 Deploy now using the Docker commands above 📖 Explore the docs at docs.netalertx.com 💬 Join the community on Discord

Your network is changing every minute. With NetAlertX, you'll finally see it all.