NetAlertX/docs/PLUGINS.md

🔌 Plugins

NetAlertX supports additional plugins to extend its functionality, each with its own settings and options. Plugins can be loaded via the General -> LOADED_PLUGINS setting. For custom plugin development, refer to the Plugin development guide.

Note

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

⚡ Quick start

Tip

You can load additional Plugins via the General -> LOADED_PLUGINS setting. You need to save the settings for the new plugins to load (cache/page reload may be necessary).

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. Setup Workflows
6. Backup your setup
7. Contribute and Create custom plugins

Plugin types

Plugin type	Icon	Description	When to run	Required	Data source ?
publisher	▶️	Sending notifications to services.	on_notification	✖	Script
dev scanner	🔍	On-network scanner discovering devices without a 3rd party service	schedule	✖	Script / SQLite DB
name discovery	🆎	Discovers names of devices via various protocols.	before_name_updates, schedule	✖	Script
importer	📥	Importing devices from another service.	schedule	✖	Script / SQLite DB
system	⚙	Providing core system functionality.	schedule / always on	✖/✔	Script / Template
other	♻	Other plugins	misc	✖	Script / Template

Features

Icon	Description
🖧	Auto-imports the network topology diagram
🔄	Has the option to sync some data back into the plugin source

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	Plugin docs	Type	Description	Features	Required
APPRISE	_publisher_apprise	▶️	Apprise notification proxy
ARPSCAN	arp_scan	🔍	ARP-scan on current network
AVAHISCAN	avahi_scan	🆎	Avahi (mDNS-based) name resolution
ASUSWRT	asuswrt_import	📥	Import connected devices from AsusWRT
CSVBCKP	csv_backup	⚙	CSV devices backup
CUSTPROP	custom_props	⚙	Managing custom device properties values		Yes
DBCLNP	db_cleanup	⚙	Database cleanup		Yes*
DDNS	ddns_update	⚙	DDNS update
DHCPLSS	dhcp_leases	📥/🆎	Import devices from DHCP leases
DHCPSRVS	dhcp_servers	♻	DHCP servers
DIGSCAN	dig_scan	🆎	Dig (DNS) Name resolution
FREEBOX	freebox	📥/♻/🆎	Pull data and names from Freebox/Iliadbox
FRITZBOX	fritzbox	📥	Fritz!Box device scanner via TR-064
ICMP	icmp_scan	♻	ICMP (ping) status checker
INTRNT	internet_ip	🔍	Internet IP scanner
INTRSPD	internet_speedtest	♻	Internet speed test
IPNEIGH	ipneigh	🔍	Scan ARP (IPv4) and NDP (IPv6) tables
KEALSS	kea_api	📥/🆎	Pull lease data from the Kea DHCP API
LUCIRPC	luci_import	📥	Import connected devices from OpenWRT
MAINT	maintenance	⚙	Maintenance of logs, etc.
MQTT	_publisher_mqtt	▶️	MQTT for syncing to Home Assistant
MTSCAN	mikrotik_scan	🔍	Mikrotik device import & sync
NBTSCAN	nbtscan_scan	🆎	Nbtscan (NetBIOS-based) name resolution
NEWDEV	newdev_template	⚙	New device template		Yes
NMAP	nmap_scan	♻	Nmap port scanning & discovery
NMAPDEV	nmap_dev_scan	🔍	Nmap dev scan on current network
NSLOOKUP	nslookup_scan	🆎	NSLookup (DNS-based) name resolution
NTFPRCS	notification_processing	⚙	Notification processing		Yes
NTFY	_publisher_ntfy	▶️	NTFY notifications
OMDSDN	omada_sdn_imp	📥/🆎 ❌	UNMAINTAINED use OMDSDNOPENAPI	🖧 🔄
OMDSDNOPENAPI	omada_sdn_openapi	📥/🆎	OMADA TP-Link import via OpenAPI	🖧
PIHOLE	pihole_scan	🆎/📥	Pi-hole device import & sync
PIHOLEAPI	pihole_api_scan	🆎/📥	Pi-hole device import & sync via API v6+
PIHOLEMON	pihole_monitor	🆎/📥	Blocked-query anomaly detection (includes primary and secondary DNS import from Pi-hole)
PUSHSAFER	_publisher_pushsafer	▶️	Pushsafer notifications
PUSHOVER	_publisher_pushover	▶️	Pushover notifications
RSTIMPRT	rest_import	📥/🆎	Import via a REST API endpoint	🖧
SETPWD	set_password	⚙	Set password		Yes
SMTP	_publisher_email	▶️	Email notifications
SNMPDSC	snmp_discovery	🔍/📥	SNMP device import & sync
SYNC	sync	⚙/📥	Sync & import from NetAlertX instances	🖧 🔄	Yes
TELEGRAM	_publisher_telegram	▶️	Telegram notifications
UI	ui_settings	♻	UI specific settings		Yes
UNFIMP	unifi_import	📥/🆎	UniFi device import & sync	🖧
UNIFIAPI	unifi_api_import	📥/🆎	UniFi device import (SM API, multi-site)
VNDRPDT	vendor_update	⚙	Vendor database update
WEBHOOK	_publisher_webhook	▶️	Webhook notifications
WEBMON	website_monitor	♻	Website down monitoring
WOL	wake_on_lan	♻	Automatic wake-on-lan

* The database cleanup plugin (DBCLNP) is not required but the app will become unusable after a while if not executed. ❌ marked for removal/unmaintained - looking for help ⌚It's recommended to use the same schedule interval for all plugins responsible for discovering new devices.

Enabling plugins

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

1. Research which plugin you'd like to use, enable DISCOVER_PLUGINS and 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. (Important) Save the settings
3. (Optional) If you want to speed up the application, you can unload the plugin by unselecting it in the LOADED_PLUGINS setting (plugins have to be disabled first - see above steps).
   • Careful, once you save the Settings Unloaded plugin settings will be lost (old app.conf files are kept in the /config folder)
4. 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.