🔌 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.

Pick your 🔍 dev scanner plugin (e.g. ARPSCAN or NMAPDEV), or import devices into the application with an 📥 importer plugin. (See ✅Enabling plugins below)
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.
Setup your Network topology diagram
Fine-tune Notifications
Backup your setup
Contribute and Create custom plugins

📑 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	Features	Required	Data source	Detailed docs
`APPRISE`	▶️	Apprise notification proxy			Script	_publisher_apprise
`ARPSCAN`	🔍	ARP-scan on current network			Script	arp_scan
`AVAHISCAN`	🆎	Avahi (mDNS-based) name resolution			Script	avahi_scan
`ASUSWRT`	🔍	Import connected devices from AsusWRT			Script	asuswrt_import
`CSVBCKP`	⚙	CSV devices backup			Script	csv_backup
`CUSTPROP`	⚙	Managing custom device properties values		Yes	Template	custom_props
`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
`FREEBOX`	🔍/♻/🆎	Pull data and names from Freebox/Iliadbox			Script	freebox
`ICMP`	🔍	ICMP (ping) status checker			Script	icmp_scan
`INTRNT`	🔍	Internet IP scanner			Script	internet_ip
`INTRSPD`	♻	Internet speed test			Script	internet_speedtest
`IPNEIGH`	🔍	Scan ARP (IPv4) and NDP (IPv6) tables			Script	ipneigh
`LUCIRPC`	🔍	Import connected devices from OpenWRT			Script	luci_import
`MAINT`	⚙	Maintenance of logs, etc.			Script	maintenance
`MQTT`	▶️	MQTT for synching to Home Assistant			Script	_publisher_mqtt
`NBTSCAN`	🆎	Nbtscan (NetBIOS-based) name resolution			Script	nbtscan_scan
`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 (DNS-based) name resolution			Script	nslookup_scan
`NTFPRCS`	⚙	Notification processing		Yes	Template	notification_processing
`NTFY`	▶️	NTFY notifications			Script	_publisher_ntfy
`OMDSDN`	📥/🆎	OMADA TP-Link import	🖧 🔄		Script	omada_sdn_imp
`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 NetAlertX instances	🖧 🔄	Yes	Script	sync
`TELEGRAM`	▶️	Telegram notifications			Script	_publisher_telegram
`UI`	♻	UI specific settings		Yes	Template	ui_settings
`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
`WOL`	♻	Automatic wake-on-lan			Script	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 ⌚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, manages online/offline device status.	`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

✅Enabling plugins

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

Research which plugin you'd like to use, enable DISCOVER_PLUGINS and load the required plugins in Settings via the LOADED_PLUGINS setting.
Save the changes and review the Settings of the newly loaded plugins.
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

Change the <prefix>_RUN Setting to disabled if you want to disable the plugin, but keep the settings
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)
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.