diff --git a/docs/PLUGINS_DEV.md b/docs/PLUGINS_DEV.md index d76780dd..6d948cc4 100755 --- a/docs/PLUGINS_DEV.md +++ b/docs/PLUGINS_DEV.md @@ -126,7 +126,7 @@ You can show or hide the UI on the "Plugins" page and "Plugins" tab for a plugin If the `data_source` is set to `script` the `CMD` setting (that you specify in the `settings` array section in the `config.json`) contains an executable Linux command, that usually generates a `last_result..log` file (not required if you don't import any data into the app). The `last_result..log` file needs to be saved in `/api/log/plugins`. > [!IMPORTANT] -> A lot of the work is taken care of by the [`plugin_helper.py` library](/front/plugins/plugin_helper.py). You don't need to manage the `last_result..log` file if using the helper objects. Check other `script.py` of other plugins for details (The [Undicoverables plugins `script.py` file](/front/plugins/undiscoverables/script.py) is a good example). +> A lot of the work is taken care of by the [`plugin_helper.py` library](/front/plugins/plugin_helper.py). You don't need to manage the `last_result..log` file if using the helper objects. Check other `script.py` of other plugins for details. The content of the `last_result..log` file needs to contain the columns as defined in the "Column order and values" section above. The order of columns can't be changed. After every scan it should contain only the results from the latest scan/execution. diff --git a/front/plugins/README.md b/front/plugins/README.md index 79d70953..278e4ac2 100755 --- a/front/plugins/README.md +++ b/front/plugins/README.md @@ -60,7 +60,6 @@ Device-detecting plugins insert values into the `CurrentScan` database table. T | `SYNC` | 🔍/⚙/📥| Sync & import from NetAlertX instances | 🖧 🔄 | Yes | Script | [sync](/front/plugins/sync/) | | `TELEGRAM` | ▶️ | Telegram notifications | | | Script | [_publisher_telegram](/front/plugins/_publisher_telegram/) | | `UI` | ♻ | UI specific settings | | Yes | Template | [ui_settings](/front/plugins/ui_settings/) | -| `UNDIS` | 🔍/📥 | Create dummy devices ❌ | | | Script | [undiscoverables](/front/plugins/undiscoverables/) | | `UNFIMP` | 🔍/📥/🆎| UniFi device import & sync | 🖧 | | Script | [unifi_import](/front/plugins/unifi_import/) | | `VNDRPDT` | ⚙ | Vendor database update | | | Script | [vendor_update](/front/plugins/vendor_update/) | | `WEBHOOK` | ▶️ | Webhook notifications | | | Script | [_publisher_webhook](/front/plugins/_publisher_webhook/) | @@ -69,7 +68,6 @@ Device-detecting plugins insert values into the `CurrentScan` database table. T > \* 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. > ❌ marked for removal > ⌚It's recommended to use the same schedule interval for all plugins responsible for discovering new devices. diff --git a/front/plugins/undiscoverables/README.md b/front/plugins/undiscoverables/README.md deleted file mode 100755 index 6dcef70a..00000000 --- a/front/plugins/undiscoverables/README.md +++ /dev/null @@ -1,30 +0,0 @@ -## Overview - -A plugin allowing for importing Un-Discoverable devices from the settings page. -The main usecase is to add dumb network gear like unmanaged hubs and switches to the network view. -There might be other usecases, please let me know. - -### Usage - -- Go to settings and find Un-Discoverabe Devices in the list of plugins. -- Enable the plugin by changing the RUN parameter from disabled to `once` or `always_after_scan`. -- Add the name of your device to the list. (remove the sample entry first) -- SAVE -- wait for the next scan to finish - -#### Examples: -Settings: -![settings](https://github.com/Data-Monkey/Pi.Alert/assets/7224371/52883307-19a5-4602-b13a-9825461f6cc4) - -resulting in these devices: -![devices](https://github.com/Data-Monkey/Pi.Alert/assets/7224371/9f7659e7-75a8-4ae9-9f5f-781bdbcbc949) - -Allowing Un-Discoverable devices like hubs, switches or APs to be added to the network view. -![network](https://github.com/Data-Monkey/Pi.Alert/assets/7224371/b5ccc3b3-f5fd-4f5b-b0f0-e4e637c6da33) - -### Known Limitations - - Un-Discoverable Devices always show as offline. That is expected as they can not be discovered by NetAlertX. - - All IPs are set to 0.0.0.0 therefore the "Random MAC" icon might show up. - -Made with ❤ by [@Data-Monkey](https://github.com/Data-Monkey) 🙏 - diff --git a/front/plugins/undiscoverables/config.json b/front/plugins/undiscoverables/config.json deleted file mode 100755 index 45787bfa..00000000 --- a/front/plugins/undiscoverables/config.json +++ /dev/null @@ -1,573 +0,0 @@ -{ - "code_name": "undiscoverables", - "unique_prefix": "UNDIS", - "plugin_type": "device_scanner", - "enabled": true, - "data_source": "script", - "mapped_to_table": "CurrentScan", - "show_ui": true, - "localized": ["display_name", "description", "icon"], - "display_name": [ - { - "language_code": "en_us", - "string": "Un-Discoverable Devices" - }, - { - "language_code": "es_es", - "string": "Dispositivos no detectables" - }, - { - "language_code": "de_de", - "string": "Nicht erkennbare Geräte" - } - ], - "icon": [ - { - "language_code": "en_us", - "string": "" - } - ], - "description": [ - { - "language_code": "en_us", - "string": "This plugin is to import undiscoverable devices from a file. Only ASCII characters are supported." - } - ], - "params": [ - { - "name": "devices", - "type": "setting", - "value": "UNDIS_devices_to_import" - } - ], - "settings": [ - { - "function": "RUN", - "events": ["run"], - "type": { - "dataType": "string", - "elements": [ - { "elementType": "select", "elementOptions": [], "transformers": [] } - ] - }, - "default_value": "disabled", - "options": ["disabled", "once", "schedule", "always_after_scan"], - "localized": ["name", "description"], - "name": [ - { - "language_code": "en_us", - "string": "When to run" - }, - { - "language_code": "es_es", - "string": "Cuándo ejecuta" - }, - { - "language_code": "de_de", - "string": "Wann ausführen" - } - ], - "description": [ - { - "language_code": "en_us", - "string": "When enabled, once is the preferred option, or set to schedule and align the UNDIS_RUN_SCHD setting with the other scanners if you want the devices to show up as ONLINE. It runs at startup and after every save of the config here.
Changes will only show in the devices after the next scan!" - }, - { - "language_code": "es_es", - "string": "Cuando está habilitado, once es la opción preferida. Se ejecuta al inicio y después de cada guardado de la configuración aquí.
¡Los cambios solo se mostrarán en los dispositivos después del próximo escaneo!" - }, - { - "language_code": "de_de", - "string": "Wenn dieses Plugin aktiviert ist, ist once die bevorzugte Methode. Das Plugin wird dann bei jedem Start und nach jedem Speichern der Einstellungen ausgeführt.
Änderungen scheinen in den Geräten erst nach dem nächsten Scan auf!" - } - ] - }, - { - "function": "CMD", - "type": { - "dataType": "string", - "elements": [ - { "elementType": "input", "elementOptions": [], "transformers": [] } - ] - }, - "default_value": "python3 /app/front/plugins/undiscoverables/script.py devices={devices}", - "options": [], - "localized": ["name", "description"], - "name": [ - { - "language_code": "en_us", - "string": "Command" - }, - { - "language_code": "es_es", - "string": "Comando" - }, - { - "language_code": "de_de", - "string": "Befehl" - } - ], - "description": [ - { - "language_code": "en_us", - "string": "Command to run. This can not be changed" - }, - { - "language_code": "es_es", - "string": "Comando a ejecutar. Esto no se puede cambiar" - }, - { - "language_code": "de_de", - "string": "Befehl zum Ausführen. Dies kann nicht geändert werden" - } - ] - }, - { - "function": "RUN_TIMEOUT", - "type": { - "dataType": "integer", - "elements": [ - { - "elementType": "input", - "elementOptions": [{ "type": "number" }], - "transformers": [] - } - ] - }, - "default_value": 10, - "options": [], - "localized": ["name", "description"], - "name": [ - { - "language_code": "en_us", - "string": "Run timeout" - }, - { - "language_code": "es_es", - "string": "Tiempo límite de ejecución" - }, - { - "language_code": "de_de", - "string": "Zeitlimit" - } - ], - "description": [ - { - "language_code": "en_us", - "string": "Maximum time in seconds to wait for the script to finish. If this time is exceeded the script is aborted." - }, - { - "language_code": "es_es", - "string": "Tiempo máximo en segundos para esperar a que finalice el script. Si se supera este tiempo, el script se cancela." - }, - { - "language_code": "de_de", - "string": "Maximale Zeit in Sekunden, die auf den Abschluss des Skripts gewartet werden soll. Bei Überschreitung dieser Zeit wird das Skript abgebrochen." - } - ] - }, - { - "function": "WATCH", - "type": { - "dataType": "string", - "elements": [ - { - "elementType": "input", - "elementOptions": [{ "readonly": "true" }], - "transformers": [] - } - ] - }, - "default_value": [], - "options": [], - "localized": ["name", "description"], - "name": [ - { - "language_code": "en_us", - "string": "Watched" - }, - { - "language_code": "es_es", - "string": "Visto" - }, - { - "language_code": "de_de", - "string": "Überwacht" - } - ], - "description": [ - { - "language_code": "en_us", - "string": "Undiscoverable Devices can not change their status, no watch is enabled." - }, - { - "language_code": "es_es", - "string": "Los dispositivos no detectables no pueden cambiar su estado, ningún reloj está habilitado." - }, - { - "language_code": "de_de", - "string": "Status von nicht erkennbaren Geräten können sich nicht ändern, keine Überwachung aktiviert." - } - ] - }, - { - "function": "REPORT_ON", - "type": { - "dataType": "string", - "elements": [ - { - "elementType": "input", - "elementOptions": [{ "readonly": "true" }], - "transformers": [] - } - ] - }, - "default_value": [], - "options": [ - "new", - "watched-changed", - "watched-not-changed", - "missing-in-last-scan" - ], - "localized": ["name", "description"], - "name": [ - { - "language_code": "en_us", - "string": "Report on" - }, - { - "language_code": "es_es", - "string": "Informar sobre" - }, - { - "language_code": "de_de", - "string": "Benachrichtige wenn" - } - ], - "description": [ - { - "language_code": "en_us", - "string": "No notifications will be sent." - }, - { - "language_code": "es_es", - "string": "No se enviarán notificaciones." - }, - { - "language_code": "de_de", - "string": "Keine Benachrichtigungen werden versendet." - } - ] - }, - { - "function": "devices_to_import", - "type": { - "dataType": "array", - "elements": [ - { - "elementType": "input", - "elementOptions": [ - { "placeholder": "Enter value" }, - { "suffix": "_in" }, - { "cssClasses": "col-sm-10" }, - { "prefillValue": "null" } - ], - "transformers": [] - }, - { - "elementType": "button", - "elementOptions": [ - { "sourceSuffixes": ["_in"] }, - { "separator": "" }, - { "cssClasses": "col-xs-12" }, - { "onClick": "addList(this, false)" }, - { "getStringKey": "Gen_Add" } - ], - "transformers": [] - }, - { - "elementType": "select", - "elementHasInputValue": 1, - "elementOptions": [ - { "multiple": "true" }, - { "readonly": "true" }, - { "editable": "true" } - ], - "transformers": [] - }, - { - "elementType": "button", - "elementOptions": [ - { "sourceSuffixes": [] }, - { "separator": "" }, - { "cssClasses": "col-xs-6" }, - { "onClick": "removeAllOptions(this)" }, - { "getStringKey": "Gen_Remove_All" } - ], - "transformers": [] - }, - { - "elementType": "button", - "elementOptions": [ - { "sourceSuffixes": [] }, - { "separator": "" }, - { "cssClasses": "col-xs-6" }, - { "onClick": "removeFromList(this)" }, - { "getStringKey": "Gen_Remove_Last" } - ], - "transformers": [] - } - ] - }, - "default_value": ["dummy_router"], - "options": [], - "localized": ["name", "description"], - "name": [ - { - "language_code": "en_us", - "string": "UnDiscoverable Devices" - }, - { - "language_code": "es_es", - "string": "Dispositivo no detectable" - }, - { - "language_code": "de_de", - "string": "Nicht erkennbare Geräte" - } - ], - "description": [ - { - "language_code": "en_us", - "string": "Devices to be added to the devices list." - }, - { - "language_code": "es_es", - "string": "Dispositivos que se añadirán a la lista de dispositivos." - }, - { - "language_code": "de_de", - "string": "Geräte, welche der Geräteliste hinzugefügt werden." - } - ] - }, - { - "function": "RUN_SCHD", - "type": { - "dataType": "string", - "elements": [ - { "elementType": "input", "elementOptions": [], "transformers": [] } - ] - }, - "default_value": "*/5 * * * *", - "options": [], - "localized": ["name", "description"], - "name": [ - { - "language_code": "en_us", - "string": "Schedule" - }, - { - "language_code": "es_es", - "string": "Schedule" - } - ], - "description": [ - { - "language_code": "en_us", - "string": "Only enabled if you select schedule in the UNDIS_RUN setting. Make sure you enter the schedule in the correct cron-like format (e.g. validate at crontab.guru). For example entering 0 4 * * * will run the scan after 4 am in the TIMEZONE you set above. Will be run NEXT time the time passes.
It's recommended to use the same schedule interval for all plugins responsible for discovering new devices. " - }, - { - "language_code": "es_es", - "string": "Solo está habilitado si selecciona schedule en la configuración UNDIS_RUN. Asegúrese de ingresar la programación en el formato similar a cron correcto (por ejemplo, valide en crontab.guru). Por ejemplo, ingresar 0 4 * * * ejecutará el escaneo después de las 4 a.m. en el TIMEZONE que configuró arriba. Se ejecutará la PRÓXIMA vez que pase el tiempo." - } - ] - } - ], - "database_column_definitions": [ - { - "column": "Index", - "css_classes": "col-sm-2", - "show": true, - "type": "none", - "default_value": "", - "options": [], - "localized": ["name"], - "name": [ - { - "language_code": "en_us", - "string": "Index" - } - ] - }, - { - "column": "Watched_Value1", - "mapped_to_column": "cur_Name", - "css_classes": "col-sm-2", - "show": true, - "type": "label", - "default_value": "", - "options": [], - "localized": ["name"], - "name": [ - { - "language_code": "en_us", - "string": "Device Name" - }, - { - "language_code": "es_es", - "string": "Nombre del dispositivo" - }, - { - "language_code": "de_de", - "string": "Gerätename" - } - ] - }, - { - "column": "Object_PrimaryID", - "mapped_to_column": "cur_MAC", - "css_classes": "col-sm-2", - "show": true, - "type": "label", - "default_value": "", - "options": [], - "localized": ["name"], - "name": [ - { - "language_code": "en_us", - "string": "MAC address" - }, - { - "language_code": "es_es", - "string": "Dirección MAC" - }, - { - "language_code": "de_de", - "string": "MAC-Adresse" - } - ] - }, - { - "column": "Object_SecondaryID", - "mapped_to_column": "cur_IP", - "css_classes": "col-sm-2", - "show": true, - "type": "device_ip", - "default_value": "", - "options": [], - "localized": ["name"], - "name": [ - { - "language_code": "en_us", - "string": "IP" - }, - { - "language_code": "es_es", - "string": "IP" - }, - { - "language_code": "de_de", - "string": "IP" - } - ] - }, - { - "column": "DateTimeCreated", - "css_classes": "col-sm-2", - "show": true, - "type": "label", - "default_value": "", - "options": [], - "localized": ["name"], - "name": [ - { - "language_code": "en_us", - "string": "Created" - }, - { - "language_code": "es_es", - "string": "Creado" - }, - { - "language_code": "de_de", - "string": "Erstellt" - } - ] - }, - { - "column": "DateTimeChanged", - "mapped_to_column": "cur_DateTime", - "css_classes": "col-sm-2", - "show": true, - "type": "label", - "default_value": "", - "options": [], - "localized": ["name"], - "name": [ - { - "language_code": "en_us", - "string": "Changed" - }, - { - "language_code": "es_es", - "string": "Cambiado" - }, - { - "language_code": "de_de", - "string": "Geändert" - } - ] - }, - { - "column": "Dummy", - "mapped_to_column": "cur_ScanMethod", - "mapped_to_column_data": { - "value": "UNDIS" - }, - "css_classes": "col-sm-2", - "show": true, - "type": "label", - "default_value": "", - "options": [], - "localized": ["name"], - "name": [ - { - "language_code": "en_us", - "string": "Scan method" - }, - { - "language_code": "es_es", - "string": "Método de escaneo" - }, - { - "language_code": "de_de", - "string": "Scanmethode" - } - ] - }, - { - "column": "ForeignKey", - "css_classes": "col-sm-2", - "show": false, - "type": "device_mac", - "default_value": "", - "options": [], - "localized": ["name"], - "name": [ - { - "language_code": "en_us", - "string": "MAC" - }, - { - "language_code": "es_es", - "string": "MAC" - }, - { - "language_code": "de_de", - "string": "MAC" - } - ] - } - ] -} diff --git a/front/plugins/undiscoverables/script.py b/front/plugins/undiscoverables/script.py deleted file mode 100755 index cb95eae6..00000000 --- a/front/plugins/undiscoverables/script.py +++ /dev/null @@ -1,76 +0,0 @@ -#!/usr/bin/env python -# test script by running python script.py devices=test,dummy - -import os -import pathlib -import argparse -import sys -import hashlib - -# Register NetAlertX directories -INSTALL_PATH="/app" -sys.path.extend([f"{INSTALL_PATH}/front/plugins", f"{INSTALL_PATH}/server"]) - -from plugin_helper import Plugin_Object, Plugin_Objects, decodeBase64 -from logger import mylog, Logger, append_line_to_file -from helper import timeNowTZ, get_setting_value -from const import logPath, applicationPath -import conf -from pytz import timezone - -# Make sure the TIMEZONE for logging is correct -conf.tz = timezone(get_setting_value('TIMEZONE')) - -# Make sure log level is initialized correctly -Logger(get_setting_value('LOG_LEVEL')) - -pluginName = 'UNDIS' - -LOG_PATH = logPath + '/plugins' -LOG_FILE = os.path.join(LOG_PATH, f'script.{pluginName}.log') -RESULT_FILE = os.path.join(LOG_PATH, f'last_result.{pluginName}.log') - -def main(): - - # the script expects a parameter in the format of devices=device1,device2,... - parser = argparse.ArgumentParser(description='Import devices from settings') - parser.add_argument('devices', action="store", help="list of device names separated by ','") - values = parser.parse_args() - - mylog('verbose', [f'[{pluginName}] In script']) - - plugin_objects = Plugin_Objects( RESULT_FILE ) - - if values.devices: - for fake_dev in values.devices.split('=')[1].split(','): - - fake_mac = string_to_mac_hash(fake_dev) - - plugin_objects.add_object( - primaryId=fake_mac, # MAC (Device Name) - secondaryId="0.0.0.0", # IP Address (always 0.0.0.0) - watched1=fake_dev, # Device Name - watched2="", - watched3="", - watched4="", - extra="", - foreignKey=fake_mac) - - plugin_objects.write_result_file() - - return 0 - -def string_to_mac_hash(input_string): - # Calculate a hash using SHA-256 - sha256_hash = hashlib.sha256(input_string.encode()).hexdigest() - - # Take the first 12 characters of the hash and format as a MAC address - mac_hash = ':'.join(sha256_hash[i:i+2] for i in range(0, 12, 2)) - - return mac_hash - -#=============================================================================== -# BEGIN -#=============================================================================== -if __name__ == '__main__': - main() \ No newline at end of file