NetAlertX/front/plugins

🔌 Plugins

Note

Please check this Plugins debugging guide and the corresponding Plugin documentation in the below table if you are facing issues.

⚡ Quick start

1. Pick your 🔍 dev scanner plugin (e.g. ARPSCAN or NMAPDEV), or import devices into the application with an 📥 importer plugin. (See ✅Enabling plugins below)
2. Pick a ▶️ publisher plugin, if you want to send notifications. If you don't see a publisher you'd like to use, look at the 📚_publisher_apprise plugin which is a proxy for over 80 notification services.
3. Setup your Network topology diagram
4. Fine-tune Notifications
5. Backup your setup
6. Contribute and Create custom plugins
7. Consider donating to keep me going

📑 Available Plugins

Device-detecting plugins insert values into the CurrentScan database table. The plugins that are not required are safe to ignore, however, it makes sense to have at least some device-detecting plugins enabled, such as ARPSCAN or NMAPDEV.

ID	Type	Description	Required	Data source	Detailed docs
APPRISE	▶️	Apprise notification proxy		Script	📚_publisher_apprise
ARPSCAN	🔍	ARP-scan on current network		Script	📚arp_scan
CSVBCKP	⚙	CSV devices backup		Script	📚csv_backup
DBCLNP	⚙	Database cleanup	Yes*	Script	📚db_cleanup
DDNS	⚙	DDNS update		Script	📚ddns_update
DHCPLSS	🔍/📥	Import devices from DHCP leases		Script	📚dhcp_leases
DHCPSRVS	♻	DHCP servers		Script	📚dhcp_servers
INTRNT	🔍	Internet IP scanner		Script	📚internet_ip
INTRSPD	♻	Internet speed test		Script	📚internet_speedtest
MAINT	⚙	Maintenance of logs, etc.		Script	📚maintenance
MQTT	▶️	MQTT for synching to Home Assistant		Script	📚_publisher_mqtt
NEWDEV	⚙	New device template	Yes	Template	📚newdev_template
NMAP	♻	Nmap port scanning & discovery		Script	📚nmap_scan
NMAPDEV	🔍	Nmap dev scan on current network		Script	📚nmap_dev_scan
NSLOOKUP	♻	NSLookup name resolution		Script	📚nslookup_scan
NTFPRCS	⚙	Notification processing	Yes	Template	📚notification_processing
NTFY	▶️	NTFY notifications		Script	📚_publisher_ntfy
PHOLUS	♻	Pholus name resolution		Script	📚pholus_scan
PIHOLE	🔍/📥	Pi-hole device import & sync		SQLite DB	📚pihole_scan
PUSHSAFER	▶️	Pushsafer notifications		Script	📚_publisher_pushsafer
PUSHOVER	▶️	Pushover notifications		Script	📚_publisher_pushover
SETPWD	⚙	Set password	Yes	Template	📚set_password
SMTP	▶️	Email notifications		Script	📚_publisher_email
SNMPDSC	🔍/📥	SNMP device import & sync		Script	📚snmp_discovery
SYNC	🔍/⚙/📥	Sync & import from other NetAlertX instances		Script	📚snmp_discovery
UNDIS	🔍/📥	Create dummy devices		Script	📚undiscoverables
UNFIMP	🔍/📥	UniFi device import & sync		Script	📚unifi_import
VNDRPDT	⚙	Vendor database update		Script	📚vendor_update
WEBHOOK	▶️	Webhook notifications		Script	📚_publisher_webhook
WEBMON	♻	Website down monitoring		Script	📚website_monitor

* The database cleanup plugin (DBCLNP) is not required but the app will become unusable after a while if not executed.

** The Undiscoverables plugin (UNDIS) inserts only user-specified dummy devices.

⌚It's recommended to use the same schedule interval for all plugins responsible for discovering new devices.

Plugin types

Plugin type	Icon	Description	When to run	Required	Data source ?
publisher	▶️	Sending notifications to services.	on_notification	✖	Script
dev scanner	🔍	Create devices in the app, usually scanning the current network.	schedule	✖	Script / SQLite DB
importer	📥	Importing devices from another service.	schedule	✖	Script / SQLite DB
system	⚙	Providing core system functionality.	schedule / always on	✖/✔	Script / Template
other	♻	Other scanners, e.g. for name resolution	misc	✖	Script / Template

✅Enabling plugins

Plugins can be enabled via Settings, and can be disabled as needed.

1. Research which plugin you'd like to use below and then load the required plugins in Settings via the LOADED_PLUGINS setting.
2. Save the changes and review the Settings of the newly loaded plugins.
3. Change the <prefix>_RUN Setting to the recommended or custom value as per the documentation of the given setting
   • If using schedule on a 🔍 dev scanner plugin, make sure the schedules are the same across all 🔍 dev scanner plugins

Disabling, Unloading and Ignoring plugins

1. Change the <prefix>_RUN Setting to disabled if you want to disable the plugin, but keep the settings
2. If you want to speed up the application, you can unload the plugin by unselecting it in the LOADED_PLUGINS setting.
   • Careful, once you save the Settings Unloaded plugin settings will be lost (old app.conf files are kept in the /config folder)
3. You can completely ignore plugins by placing a ignore_plugin file into the plugin directory. Ignored plugins won't show up in the LOADED_PLUGINS setting.

🆕 Developing new custom plugins

If you want to develop a custom plugin, please read this Plugin development guide.