diff --git a/README.md b/README.md index 31832462..ef19c9ab 100755 --- a/README.md +++ b/README.md @@ -4,34 +4,28 @@ [![Discord](https://img.shields.io/discord/1274490466481602755?color=0aa8d2&logoColor=fff&logo=Discord&style=for-the-badge)](https://discord.gg/NczTUTWyRr) [![Home Assistant](https://img.shields.io/badge/Repo-blue?logo=home-assistant&style=for-the-badge&color=0aa8d2&logoColor=fff&label=Add)](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) -## πŸ“¦ 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 diff --git a/docs/DEVICE_FIELD_LOCK.md b/docs/DEVICE_FIELD_LOCK.md index 2b40f80f..fcd24960 100644 --- a/docs/DEVICE_FIELD_LOCK.md +++ b/docs/DEVICE_FIELD_LOCK.md @@ -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 diff --git a/docs/DEVICE_MANAGEMENT.md b/docs/DEVICE_MANAGEMENT.md index 9d320bcf..51685323 100755 --- a/docs/DEVICE_MANAGEMENT.md +++ b/docs/DEVICE_MANAGEMENT.md @@ -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 diff --git a/front/deviceDetailsEdit.php b/front/deviceDetailsEdit.php index 1124763a..19e51351 100755 --- a/front/deviceDetailsEdit.php +++ b/front/deviceDetailsEdit.php @@ -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",