diff --git a/docs/PLUGINS_DEV_DATASOURCES.md b/docs/PLUGINS_DEV_DATASOURCES.md index c9fa4f71..f6d547cd 100644 --- a/docs/PLUGINS_DEV_DATASOURCES.md +++ b/docs/PLUGINS_DEV_DATASOURCES.md @@ -12,7 +12,6 @@ Data sources determine **where the plugin gets its data** and **what format it r | `app-db-query` | Database Query | Query the NetAlertX database | Result set | Show devices, open ports, recent events | | `sqlite-db-query` | External DB | Query external SQLite databases | Result set | PiHole database, external logs | | `template` | Template | Generate values from templates | Values | Initialize default settings | -| `plugin_type` | Metadata | Declare plugin category | Metadata | Classify plugin (scanner, publisher, etc.) | ## Data Source: `script` @@ -24,7 +23,7 @@ Execute any Linux command or Python script and capture its output. { "data_source": "script", "show_ui": true, - "mapped_to_table": "Plugins_Objects" + "mapped_to_table": "CurrentScan" } ``` @@ -63,7 +62,7 @@ Execute any Linux command or Python script and capture its output. - **Always use absolute paths** (e.g., `/app/front/plugins/...`) - **Use `plugin_helper.py`** for output formatting - **Add timeouts** via `RUN_TIMEOUT` setting (default: 60s) -- **Log errors** to `/tmp/log/plugins/*.log` +- **Log errors** to `/tmp/log/plugins/.log` - **Handle missing dependencies gracefully** ### Output Format @@ -86,7 +85,7 @@ Query the NetAlertX SQLite database and display results. { "data_source": "app-db-query", "show_ui": true, - "mapped_to_table": "Plugins_Objects" + "mapped_to_table": "CurrentScan" } ``` @@ -138,33 +137,7 @@ ORDER BY e.EventDateTime DESC ``` -### Common Columns - -**Devices Table:** -- `devMac` - Device MAC address -- `devName` - Device name -- `devLastIP` - Last known IP -- `devType` - Device type -- `devStatus` - Online/offline status -- `devVendor` - Hardware vendor - -**CurrentScan Table:** -- `cur_MAC` - MAC address -- `cur_IP` - IP address -- `cur_ScanMethod` - How it was discovered - -**Nmap_Scan Table:** -- `MAC` - Device MAC -- `Port` - Port number -- `Service` - Service name -- `State` - open/closed/filtered -- `Extra` - Additional notes - -**Events Table:** -- `EventType` - Event type -- `EventValue` - Event value -- `EventDateTime` - When it occurred -- `DeviceMac` - Associated device +See the [Database documentation](./DATABASE.md) for a list of common columns. --- diff --git a/docs/PLUGINS_DEV_DATA_CONTRACT.md b/docs/PLUGINS_DEV_DATA_CONTRACT.md index c843290f..f0c5390b 100644 --- a/docs/PLUGINS_DEV_DATA_CONTRACT.md +++ b/docs/PLUGINS_DEV_DATA_CONTRACT.md @@ -57,11 +57,13 @@ Plugins communicate with NetAlertX by writing results to a **pipe-delimited log Watched values are fields that the NetAlertX core monitors for **changes between scans**. When a watched value differs from the previous scan, it can trigger notifications. **How to use them:** + - `Watched_Value1`: Always required; primary indicator of status/state - `Watched_Value2–4`: Optional; use for secondary/tertiary state information - Leave unused ones as `null` **Example:** + - Device scanner: `Watched_Value1 = "online"` or `"offline"` - Port scanner: `Watched_Value1 = "80"` (port number), `Watched_Value2 = "open"` (state) - Service monitor: `Watched_Value1 = "200"` (HTTP status), `Watched_Value2 = "0.45"` (response time) @@ -77,6 +79,7 @@ device_name|192.168.1.100|2023-01-02 15:56:30|online|null|null|null|Found on net ``` This allows NetAlertX to: + - Display the object on the device details page - Send notifications when the parent device is involved - Link events across plugins @@ -163,6 +166,7 @@ plugin_objects.write_result_file() ``` The library automatically: + - Validates data types - Sanitizes string values - Normalizes MAC addresses diff --git a/docs/PLUGINS_DEV_SETTINGS.md b/docs/PLUGINS_DEV_SETTINGS.md index 4579cdac..552bbf91 100644 --- a/docs/PLUGINS_DEV_SETTINGS.md +++ b/docs/PLUGINS_DEV_SETTINGS.md @@ -8,6 +8,7 @@ Learn how to let users configure your plugin via the NetAlertX UI Settings page. ## Overview Plugin settings allow users to configure: + - **Execution schedule** (when the plugin runs) - **Runtime parameters** (API keys, URLs, thresholds) - **Behavior options** (which features to enable/disable) @@ -59,17 +60,17 @@ Each setting is a JSON object with required and optional properties: | `default_value` | varies | Initial value shown in UI | `"https://example.com"` | | `localized` | array | Which properties have translations | `["name", "description"]` | | `name` | array | Display name in Settings UI (localized) | See [Localized Strings](#localized-strings) | +| `description` | array | Help text in Settings UI (localized) | See [Localized Strings](#localized-strings) | ## Optional Properties | Property | Type | Description | Example | |----------|------|-------------|---------| -| `description` | array | Help text in Settings UI (localized) | See [Localized Strings](#localized-strings) | | `options` | array | Valid values for select/checkbox controls | `["option1", "option2"]` | | `events` | string | Trigger action button: `"test"` or `"run"` | `"test"` for notifications | | `maxLength` | number | Character limit for input fields | `100` | | `readonly` | boolean | Make field read-only | `true` | -| `override_value` | object | Template-based value override (advanced) | See [Templates](#templates) | +| `override_value` | object | Template-based value override (WIP) | Work in Progress | ## Reserved Function Names diff --git a/front/settings.php b/front/settings.php index 173bf437..899cdef0 100755 --- a/front/settings.php +++ b/front/settings.php @@ -471,7 +471,7 @@ $settingsJSON_DB = json_encode($settings, JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX
`; - // OVERRIDE + // OVERRIDE (NOT YET IMPLEMENTED) // surface settings override functionality if the setting is a template that can be overridden with user defined values // if the setting is a json of the correct structure, handle like a template setting