base on Network intruder and presence detector. Scans for devices connected to your network and alerts you if new and unknown devices are found. [](https://hub.docker.com/r/jokobsk/netalertx) [](https://hub.docker.com/r/jokobsk/netalertx) [](https://github.com/jokob-sk/NetAlertX/releases) [](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 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. ## 📋 Table of Contents - [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) ## 🚀 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. Start NetAlertX in seconds with Docker: ```bash docker run -d \ --network=host \ --restart unless-stopped \ -v /local_data_dir:/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/jokob-sk/netalertx:latest ``` Note: Your `/local_data_dir` should contain a `config` and `db` folder. To deploy a containerized instance directly from the source repository, execute the following BASH sequence: ```bash git clone https://github.com/jokob-sk/NetAlertX.git cd NetAlertX docker compose up --force-recreate --build # To customize: edit docker-compose.yaml and run that last command again ``` Need help configuring it? Check the [usage guide](https://docs.netalertx.com/README) or [full documentation](https://docs.netalertx.com/). For Home Assistant users: [Click here to add NetAlertX](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons) 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) |----------------------| ----------------------| ----------------------| ----------------------| ----------------------| ![showcase][showcase] <details> <summary>📷 Click for more screenshots</summary> | ![Main screen][main] | ![device_details 1][device_details] | ![Screen network][network] | |----------------------|----------------------|----------------------| | ![presence][presence] | ![maintenance][maintenance] | ![settings][settings] | | ![sync_hub][sync_hub] | ![report1][report1] | ![device_nmap][device_nmap] | Head to [https://netalertx.com/](https://netalertx.com/) for even more gifs and screenshots 📷. </details> ## 📦 Features ### Scanners 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. ### Notification gateways Send notifications to more than 80+ services, including Telegram via [Apprise](https://hub.docker.com/r/caronc/apprise), or use native [Pushsafer](https://www.pushsafer.com/), [Pushover](https://www.pushover.net/), or [NTFY](https://ntfy.sh/) publishers. ### Integrations and Plugins Feed your data and device changes into [Home Assistant](https://docs.netalertx.com/HOME_ASSISTANT), read [API endpoints](https://docs.netalertx.com/API), or use [Webhooks](https://docs.netalertx.com/WEBHOOK_N8N) to setup custom automation flows. You can also build your own scanners with the [Plugin system](https://docs.netalertx.com/PLUGINS#readme) in as little as [15 minutes](https://www.youtube.com/watch?v=cdbxlwiWhv8). ### 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. ## 📚 Documentation <!--- --------------------------------------------------------------------- ---> Supported browsers: Chrome, Firefox - [[Installation] Docker](https://docs.netalertx.com/DOCKER_INSTALLATION) - [[Installation] Home Assistant](https://github.com/alexbelgium/hassio-addons/tree/master/netalertx) - [[Installation] Bare metal](https://docs.netalertx.com/HW_INSTALL) - [[Installation] Unraid App](https://unraid.net/community/apps) - [[Setup] Usage and Configuration](https://docs.netalertx.com/README) - [[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 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: - 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 See [Security Best Practices](https://github.com/jokob-sk/NetAlertX/security) for more details. ## ❓ FAQ **Q: Why don’t I see any devices?** 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: 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). **Q: Where is the data stored?** A: In the `/data/config` and `/data/db` folders. Back up these folders regularly. ## 🐞 Known Issues - 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/). ## 📃 Everything else <!--- --------------------------------------------------------------------- ---> ### 📧 Get notified what's new Get notified about a new release, what new functionality you can use and about breaking changes. ![Follow and star][follow_star] ### 🔀 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) ### 💙 Donations Thank you to everyone who appreciates this tool and donates. <details> <summary>Click for more ways to donate</summary> <hr> | [](https://github.com/sponsors/jokob-sk) | [](https://www.buymeacoffee.com/jokobsk) | [](https://www.patreon.com/user?u=84385063) | | --- | --- | --- | - Bitcoin: `1N8tupjeCK12qRVU2XrV17WvKK7LCawyZM` - Ethereum: `0x6e2749Cb42F4411bc98501406BdcD82244e3f9C7` 📧 Email me at [[email protected]](mailto:[email protected]?subject=NetAlertX) if you want to get in touch or if I should add other sponsorship platforms. </details> ### 🏗 Contributors 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). ### 🌍 Translations Proudly using [Weblate](https://hosted.weblate.org/projects/pialert/). Help out and suggest languages in the [online portal of Weblate](https://hosted.weblate.org/projects/pialert/core/). <a href="https://hosted.weblate.org/engage/pialert/"> <img src="https://hosted.weblate.org/widget/pialert/core/multi-auto.svg" alt="Translation status" /> </a> ### License > GPL 3.0 | [Read more here](LICENSE.txt) | Source of the [animated GIF (Loading Animation)](https://commons.wikimedia.org/wiki/File:Loading_Animation.gif) | Source of the [selfhosted Fonts](https://github.com/adobe-fonts/source-sans) <!--- --------------------------------------------------------------------- ---> [main]: ./docs/img/devices_split.png "Main screen" [device_details]: ./docs/img/device_details.png "Screen 1" [events]: ./docs/img/events.png "Screen 2" [presence]: ./docs/img/presence.png "Screen 3" [maintenance]: ./docs/img/maintenance.png "Screen 4" [network]: ./docs/img/network.png "Screen 5" [settings]: ./docs/img/settings.png "Screen 6" [showcase]: ./docs/img/showcase.gif "Screen 6" [sync_hub]: ./docs/img/sync_hub.png "Screen 8" [notification_center]: ./docs/img/notification_center.png "Screen 8" [sent_reports_text]: ./docs/img/sent_reports_text.png "Screen 8" [device_nmap]: ./docs/img/device_nmap.png "Screen 9" [report1]: ./docs/img/report_sample.png "Report sample 1" [main_dark]: /docs/img/1_devices_dark.jpg "Main screen dark" [maintain_dark]: /docs/img/5_maintain.jpg "Maintain screen dark" [follow_star]: /docs/img/Follow_Releases_and_Star.gif "Follow and Star" ", Assign "at most 3 tags" to the expected json: {"id":"12670","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"