mirror of
https://github.com/jokob-sk/NetAlertX.git
synced 2026-03-23 01:43:17 -04:00
jokob-sk
85
README.md
85
README.md
@@ -4,34 +4,28 @@
|
||||
[](https://discord.gg/NczTUTWyRr)
|
||||
[](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons)
|
||||
|
||||
# NetAlertX - Network, presence scanner and alert framework
|
||||
# NetAlertX - Network Visibility & Asset Intelligence Framework
|
||||
|
||||
Get visibility of what's going on on your WIFI/LAN network and enable presence detection of important devices. Schedule scans for devices, port changes and get alerts if unknown devices or changes are found. Write your own [Plugin](https://docs.netalertx.com/PLUGINS#readme) with auto-generated UI and in-build notification system. Build out and easily maintain your network source of truth (NSoT) and device inventory.
|
||||
Centralized network visibility and continuous asset discovery.
|
||||
|
||||
## 📋 Table of Contents
|
||||
Monitor devices, detect change, and stay aware across distributed networks.
|
||||
|
||||
- [NetAlertX - Network, presence scanner and alert framework](#netalertx---network-presence-scanner-and-alert-framework)
|
||||
- [📋 Table of Contents](#-table-of-contents)
|
||||
- [🚀 Quick Start](#-quick-start)
|
||||
- [📦 Features](#-features)
|
||||
- [Scanners](#scanners)
|
||||
- [Notification gateways](#notification-gateways)
|
||||
- [Integrations and Plugins](#integrations-and-plugins)
|
||||
- [Workflows](#workflows)
|
||||
- [📚 Documentation](#-documentation)
|
||||
- [🔐 Security \& Privacy](#-security--privacy)
|
||||
- [❓ FAQ](#-faq)
|
||||
- [🐞 Known Issues](#-known-issues)
|
||||
- [📃 Everything else](#-everything-else)
|
||||
- [📧 Get notified what's new](#-get-notified-whats-new)
|
||||
- [🔀 Other Alternative Apps](#-other-alternative-apps)
|
||||
- [💙 Donations](#-donations)
|
||||
- [🏗 Contributors](#-contributors)
|
||||
- [🌍 Translations](#-translations)
|
||||
- [License](#license)
|
||||
NetAlertX provides a centralized "Source of Truth" (NSoT) for network infrastructure. Maintain a real-time inventory of every connected device, identify Shadow IT and unauthorized hardware to maintain regulatory compliance, and automate compliance workflows across distributed sites.
|
||||
|
||||
NetAlertX is designed to bridge the gap between simple network scanning and complex SIEM tools, providing actionable insights without the overhead.
|
||||
|
||||
|
||||
## 🚀 Quick Start
|
||||
## Table of Contents
|
||||
|
||||
- [Quick Start](#quick-start)
|
||||
- [Features](#features)
|
||||
- [Documentation](#documentation)
|
||||
- [Security \& Privacy](#security--privacy)
|
||||
- [FAQ](#faq)
|
||||
- [Troubleshooting Tips](#troubleshooting-tips)
|
||||
- [Everything else](#everything-else)
|
||||
|
||||
## Quick Start
|
||||
|
||||
> [!WARNING]
|
||||
> ⚠️ **Important:** The docker-compose has recently changed. Carefully read the [Migration guide](https://docs.netalertx.com/MIGRATION/?h=migrat#12-migration-from-netalertx-v25524) for detailed instructions.
|
||||
@@ -67,7 +61,7 @@ For Home Assistant users: [Click here to add NetAlertX](https://my.home-assistan
|
||||
For other install methods, check the [installation docs](#-documentation)
|
||||
|
||||
|
||||
| [📑 Docker guide](https://docs.netalertx.com/DOCKER_INSTALLATION) | [🚀 Releases](https://github.com/jokob-sk/NetAlertX/releases) | [📚 Docs](https://docs.netalertx.com/) | [🔌 Plugins](https://docs.netalertx.com/PLUGINS) | [🤖 Ask AI](https://gurubase.io/g/netalertx)
|
||||
| [Docker guide](https://docs.netalertx.com/DOCKER_INSTALLATION) | [Releases](https://github.com/netalertx/NetAlertX/releases) | [Docs](https://docs.netalertx.com/) | [Plugins](https://docs.netalertx.com/PLUGINS) |
|
||||
|----------------------| ----------------------| ----------------------| ----------------------| ----------------------|
|
||||
|
||||
![showcase][showcase]
|
||||
@@ -84,11 +78,11 @@ For other install methods, check the [installation docs](#-documentation)
|
||||
|
||||
</details>
|
||||
|
||||
## 📦 Features
|
||||
## Features
|
||||
|
||||
### Scanners
|
||||
### Discovery & Asset Intelligence
|
||||
|
||||
The app scans your network for **New devices**, **New connections** (re-connections), **Disconnections**, **"Always Connected" devices down**, Devices **IP changes** and **Internet IP address changes**. Discovery & scan methods include: **arp-scan**, **Pi-hole - DB import**, **Pi-hole - DHCP leases import**, **Generic DHCP leases import**, **UNIFI controller import**, **SNMP-enabled router import**. Check the [Plugins](https://docs.netalertx.com/PLUGINS#readme) docs for a full list of avaliable plugins.
|
||||
Continuous monitoring for unauthorized asset discovery, connection state changes, and IP address management (IPAM) drift. Discovery & scan methods include: **arp-scan**, **Pi-hole - DB import**, **Pi-hole - DHCP leases import**, **Generic DHCP leases import**, **UNIFI controller import**, **SNMP-enabled router import**. Check the [Plugins](https://docs.netalertx.com/PLUGINS#readme) docs for a full list of avaliable plugins.
|
||||
|
||||
### Notification gateways
|
||||
|
||||
@@ -101,12 +95,14 @@ build your own scanners with the [Plugin system](https://docs.netalertx.com/PLUG
|
||||
|
||||
### Workflows
|
||||
|
||||
The [workflows module](https://docs.netalertx.com/WORKFLOWS) allows to automate repetitive tasks, making network management more efficient. Whether you need to assign newly discovered devices to a specific Network Node, auto-group devices from a given vendor, unarchive a device if detected online, or automatically delete devices, this module provides the flexibility to tailor the automations to your needs.
|
||||
The [workflows module](https://docs.netalertx.com/WORKFLOWS) automates IT governance by enforcing device categorization and cleanup policies. Whether you need to assign newly discovered devices to a specific Network Node, auto-group devices from a given vendor, unarchive a device if detected online, or automatically delete devices, this module provides the flexibility to tailor the automations to your needs.
|
||||
|
||||
|
||||
## 📚 Documentation
|
||||
## Documentation
|
||||
<!--- --------------------------------------------------------------------- --->
|
||||
|
||||
Explore all the [documentation here](https://docs.netalertx.com/) or navigate to a specific installation option below.
|
||||
|
||||
Supported browsers: Chrome, Firefox
|
||||
|
||||
- [[Installation] Docker](https://docs.netalertx.com/DOCKER_INSTALLATION)
|
||||
@@ -117,48 +113,47 @@ Supported browsers: Chrome, Firefox
|
||||
- [[Development] API docs](https://docs.netalertx.com/API)
|
||||
- [[Development] Custom Plugins](https://docs.netalertx.com/PLUGINS_DEV)
|
||||
|
||||
...or explore all the [documentation here](https://docs.netalertx.com/).
|
||||
|
||||
## 🔐 Security & Privacy
|
||||
## Security & Privacy
|
||||
|
||||
NetAlertX scans your local network and can store metadata about connected devices. By default, all data is stored **locally**. No information is sent to external services unless you explicitly configure notifications or integrations.
|
||||
|
||||
To further secure your installation:
|
||||
Compliance & Hardening:
|
||||
- Run it behind a reverse proxy with authentication
|
||||
- Use firewalls to restrict access to the web UI
|
||||
- Regularly update to the latest version for security patches
|
||||
- Role-Based Access Control (RBAC) via Reverse Proxy: Integrate with your existing SSO/Identity provider for secure dashboard access.
|
||||
|
||||
See [Security Best Practices](https://github.com/jokob-sk/NetAlertX/security) for more details.
|
||||
See [Security Best Practices](https://github.com/netalertx/NetAlertX/security) for more details.
|
||||
|
||||
|
||||
## ❓ FAQ
|
||||
## FAQ
|
||||
|
||||
**Q: Why don’t I see any devices?**
|
||||
**Q: How do I monitor VLANs or remote subnets?**
|
||||
A: Ensure the container has proper network access (e.g., use `--network host` on Linux). Also check that your scan method is properly configured in the UI.
|
||||
|
||||
**Q: Does this work on Wi-Fi-only devices like Raspberry Pi?**
|
||||
A: Yes, but some scanners (e.g. ARP) work best on Ethernet. For Wi-Fi, try SNMP, DHCP, or Pi-hole import.
|
||||
**Q: What is the recommended deployment for high-availability?**
|
||||
A: We recommend deploying via Docker with persistent volume mounts for database integrity and running behind a reverse proxy for secure access.
|
||||
|
||||
**Q: Will this send any data to the internet?**
|
||||
A: No. All scans and data remain local, unless you set up cloud-based notifications.
|
||||
|
||||
**Q: Can I use this without Docker?**
|
||||
A: Yes! You can install it bare-metal. See the [bare metal installation guide](https://docs.netalertx.com/HW_INSTALL).
|
||||
A: You can install the application directly on your own hardware by following the [bare metal installation guide](https://docs.netalertx.com/HW_INSTALL).
|
||||
|
||||
**Q: Where is the data stored?**
|
||||
A: In the `/data/config` and `/data/db` folders. Back up these folders regularly.
|
||||
|
||||
|
||||
## 🐞 Known Issues
|
||||
## Troubleshooting Tips
|
||||
|
||||
- Some scanners (e.g. ARP) may not detect devices on different subnets. See the [Remote networks guide](https://docs.netalertx.com/REMOTE_NETWORKS) for workarounds.
|
||||
- Wi-Fi-only networks may require alternate scanners for accurate detection.
|
||||
- Notification throttling may be needed for large networks to prevent spam.
|
||||
- On some systems, elevated permissions (like `CAP_NET_RAW`) may be needed for low-level scanning.
|
||||
|
||||
Check the [GitHub Issues](https://github.com/jokob-sk/NetAlertX/issues) for the latest bug reports and solutions and consult [the official documentation](https://docs.netalertx.com/).
|
||||
Check the [GitHub Issues](https://github.com/netalertx/NetAlertX/issues) for the latest bug reports and solutions and consult [the official documentation](https://docs.netalertx.com/).
|
||||
|
||||
## 📃 Everything else
|
||||
## Everything else
|
||||
<!--- --------------------------------------------------------------------- --->
|
||||
|
||||
### 📧 Get notified what's new
|
||||
@@ -169,10 +164,10 @@ Get notified about a new release, what new functionality you can use and about b
|
||||
|
||||
### 🔀 Other Alternative Apps
|
||||
|
||||
- [PiAlert by leiweibau](https://github.com/leiweibau/Pi.Alert/) (maintained, bare-metal install)
|
||||
- [WatchYourLAN](https://github.com/aceberg/WatchYourLAN) - Lightweight network IP scanner with web GUI (Open source)
|
||||
- [Fing](https://www.fing.com/) - Network scanner app for your Internet security (Commercial, Phone App, Proprietary hardware)
|
||||
- [NetBox](https://netboxlabs.com/) - Network management software (Commercial)
|
||||
- [Zabbix](https://www.zabbix.com/) or [Nagios](https://www.nagios.org/) - Strong focus on infrastructure monitoring.
|
||||
- [NetAlertX](https://netalertx.com) - The streamlined, discovery-focused alternative for real-time asset intelligence.
|
||||
|
||||
### 💙 Donations
|
||||
|
||||
@@ -197,7 +192,7 @@ Thank you to everyone who appreciates this tool and donates.
|
||||
|
||||
This project would be nothing without the amazing work of the community, with special thanks to:
|
||||
|
||||
> [pucherot/Pi.Alert](https://github.com/pucherot/Pi.Alert) (the original creator of PiAlert), [leiweibau](https://github.com/leiweibau/Pi.Alert): Dark mode (and much more), [Macleykun](https://github.com/Macleykun) (Help with Dockerfile clean-up), [vladaurosh](https://github.com/vladaurosh) for Alpine re-base help, [Final-Hawk](https://github.com/Final-Hawk) (Help with NTFY, styling and other fixes), [TeroRERO](https://github.com/terorero) (Spanish translations), [Data-Monkey](https://github.com/Data-Monkey), (Split-up of the python.py file and more), [cvc90](https://github.com/cvc90) (Spanish translation and various UI work) to name a few. Check out all the [amazing contributors](https://github.com/jokob-sk/NetAlertX/graphs/contributors).
|
||||
> [pucherot/Pi.Alert](https://github.com/pucherot/Pi.Alert) (the original creator of PiAlert), [leiweibau](https://github.com/leiweibau/Pi.Alert): Dark mode (and much more), [Macleykun](https://github.com/Macleykun) (Help with Dockerfile clean-up), [vladaurosh](https://github.com/vladaurosh) for Alpine re-base help, [Final-Hawk](https://github.com/Final-Hawk) (Help with NTFY, styling and other fixes), [TeroRERO](https://github.com/terorero) (Spanish translations), [Data-Monkey](https://github.com/Data-Monkey), (Split-up of the python.py file and more), [cvc90](https://github.com/cvc90) (Spanish translation and various UI work) to name a few. Check out all the [amazing contributors](https://github.com/netalertx/NetAlertX/graphs/contributors).
|
||||
|
||||
### 🌍 Translations
|
||||
|
||||
|
||||
@@ -113,12 +113,14 @@ Each locked field has a "source" indicator that shows you why the value is prote
|
||||
## When to Lock vs. When NOT to Lock
|
||||
|
||||
### ✅ **Good reasons to lock:**
|
||||
|
||||
- You've customized the device name and it's correct
|
||||
- You've set a static IP and it shouldn't change
|
||||
- You've configured VLAN information
|
||||
- You know the parent device and don't want it auto-corrected
|
||||
|
||||
### ❌ **Bad reasons to lock:**
|
||||
|
||||
- The value seems wrong—edit it first, then lock
|
||||
- You want to prevent data from another source—use field lock, not to hide problems
|
||||
- You're trying to force a value the system disagrees with
|
||||
@@ -126,17 +128,20 @@ Each locked field has a "source" indicator that shows you why the value is prote
|
||||
## Troubleshooting
|
||||
|
||||
**Lock button not appearing:**
|
||||
|
||||
- Confirm the field is one of the tracked fields (see list above)
|
||||
- Confirm the device is already saved (new devices don't show lock buttons)
|
||||
- Refresh the page
|
||||
|
||||
**Lock button is there but click doesn't work:**
|
||||
|
||||
- Check your internet connection
|
||||
- Check you have permission to edit devices
|
||||
- Look at browser console (F12 > Console tab) for error messages
|
||||
- Try again in a few seconds
|
||||
|
||||
**Field still changes after locking:**
|
||||
|
||||
- Double-check the lock icon shows
|
||||
- Reload the page—the change might be a display issue
|
||||
- Check if you accidentally unlocked it
|
||||
|
||||
@@ -59,11 +59,6 @@ NetAlertX allows you to "lock" specific device fields to prevent plugins from au
|
||||
2. Click the **lock button** (🔒) next to any tracked field
|
||||
3. The field is now protected—plugins cannot change it until you unlock it
|
||||
|
||||
### Tracked Fields
|
||||
|
||||
The following 10 fields support locking:
|
||||
- devMac, devName, devLastIP, devVendor, devFQDN, devSSID, devParentMAC, devParentPort, devParentRelType, devVlan
|
||||
|
||||
### See Also
|
||||
|
||||
- **For Users:** [Quick Reference - Device Field Lock/Unlock](DEVICE_FIELD_LOCK.md) - How to use field locking
|
||||
|
||||
@@ -138,7 +138,7 @@ function getDeviceData() {
|
||||
},
|
||||
// Group for event and alert settings
|
||||
DevDetail_EveandAl_Title: {
|
||||
data: ["devAlertEvents", "devAlertDown", "devSkipRepeated", "devReqNicsOnline", "devChildrenNicsDynamic"],
|
||||
data: ["devAlertEvents", "devAlertDown", "devSkipRepeated", "devReqNicsOnline", "devChildrenNicsDynamic", "devForceStatus"],
|
||||
docs: "https://docs.netalertx.com/NOTIFICATIONS",
|
||||
iconClass: "fa fa-bell",
|
||||
inputGroupClasses: "field-group alert-group col-lg-4 col-sm-6 col-xs-12",
|
||||
@@ -156,7 +156,7 @@ function getDeviceData() {
|
||||
},
|
||||
// Group for other fields like static IP, archived status, etc.
|
||||
DevDetail_DisplayFields_Title: {
|
||||
data: ["devStaticIP", "devIsNew", "devFavorite", "devIsArchived", "devForceStatus"],
|
||||
data: ["devStaticIP", "devIsNew", "devFavorite", "devIsArchived"],
|
||||
docs: "https://docs.netalertx.com/DEVICE_DISPLAY_SETTINGS",
|
||||
iconClass: "fa fa-list-check",
|
||||
inputGroupClasses: "field-group display-group col-lg-4 col-sm-6 col-xs-12",
|
||||
|
||||
Reference in New Issue
Block a user