vh/NetAlertX
1
0
Fork 0
mirror of https://github.com/jokob-sk/NetAlertX.git synced 2026-04-02 00:02:19 -07:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Refactor event and session column names to camelCase

Browse Source 
- Updated test cases to reflect new column names (eve_MAC -> eveMac, eve_DateTime -> eveDateTime, etc.) across various test files.
- Modified SQL table definitions in the database cleanup and migration tests to use camelCase naming conventions.
- Implemented migration tests to ensure legacy column names are correctly renamed to camelCase equivalents.
- Ensured that existing data is preserved during the migration process and that views referencing old column names are dropped before renaming.
- Verified that the migration function is idempotent, allowing for safe re-execution without data loss.
This commit is contained in:
Jokob @NetAlertX
2026-03-16 10:11:22 +00:00
parent 0bb6db155b
commit c7399215ec
109 changed files with 2403 additions and 1967 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/API_EVENTS.md
View File

@@ -58,12 +58,12 @@ The Events API provides access to **device event logs**, allowing creation, retr
"success": true,
"events": [
{
"eve_MAC": "00:11:22:33:44:55",
"eve_IP": "192.168.1.10",
"eve_DateTime": "2025-08-24T12:00:00Z",
"eve_EventType": "Device Down",
"eve_AdditionalInfo": "",
"eve_PendingAlertEmail": 1
"eveMac": "00:11:22:33:44:55",
"eveIp": "192.168.1.10",
"eveDateTime": "2025-08-24T12:00:00Z",
"eveEventType": "Device Down",
"eveAdditionalInfo": "",
"evePendingAlertEmail": 1
}
]
}
@@ -102,11 +102,11 @@ The Events API provides access to **device event logs**, allowing creation, retr
"count": 5,
"events": [
{
"eve_DateTime": "2025-12-07 12:00:00",
"eve_EventType": "New Device",
"eve_MAC": "AA:BB:CC:DD:EE:FF",
"eve_IP": "192.168.1.100",
"eve_AdditionalInfo": "Device detected"
"eveDateTime": "2025-12-07 12:00:00",
"eveEventType": "New Device",
"eveMac": "AA:BB:CC:DD:EE:FF",
"eveIp": "192.168.1.100",
"eveAdditionalInfo": "Device detected"
}
]
}
@@ -127,9 +127,9 @@ The Events API provides access to **device event logs**, allowing creation, retr
"count": 10,
"events": [
{
"eve_DateTime": "2025-12-07 12:00:00",
"eve_EventType": "Device Down",
"eve_MAC": "AA:BB:CC:DD:EE:FF"
"eveDateTime": "2025-12-07 12:00:00",
"eveEventType": "Device Down",
"eveMac": "AA:BB:CC:DD:EE:FF"
}
]
}
@@ -159,9 +159,9 @@ The Events API provides access to **device event logs**, allowing creation, retr
1. Total events in the period
2. Total sessions
3. Missing sessions
4. Voided events (`eve_EventType LIKE 'VOIDED%'`)
5. New device events (`eve_EventType LIKE 'New Device'`)
6. Device down events (`eve_EventType LIKE 'Device Down'`)
4. Voided events (`eveEventType LIKE 'VOIDED%'`)
5. New device events (`eveEventType LIKE 'New Device'`)
6. Device down events (`eveEventType LIKE 'Device Down'`)
---
@@ -187,7 +187,7 @@ Event endpoints are available as **MCP Tools** for AI assistant integration:
```
* Events are stored in the **Events table** with the following fields:
`eve_MAC`, `eve_IP`, `eve_DateTime`, `eve_EventType`, `eve_AdditionalInfo`, `eve_PendingAlertEmail`.
`eveMac`, `eveIp`, `eveDateTime`, `eveEventType`, `eveAdditionalInfo`, `evePendingAlertEmail`.
* Event creation automatically logs activity for debugging.

24
docs/API_SESSIONS.md
View File

@@ -106,12 +106,12 @@ curl -X DELETE "http://<server_ip>:<GRAPHQL_PORT>/sessions/delete" \
"success": true,
"sessions": [
{
"ses_MAC": "AA:BB:CC:DD:EE:FF",
"ses_Connection": "2025-08-01 10:00",
"ses_Disconnection": "2025-08-01 12:00",
"ses_Duration": "2h 0m",
"ses_IP": "192.168.1.10",
"ses_Info": ""
"sesMac": "AA:BB:CC:DD:EE:FF",
"sesDateTimeConnection": "2025-08-01 10:00",
"sesDateTimeDisconnection": "2025-08-01 12:00",
"sesDuration": "2h 0m",
"sesIp": "192.168.1.10",
"sesAdditionalInfo": ""
}
]
}
@@ -194,12 +194,12 @@ curl -X GET "http://<server_ip>:<GRAPHQL_PORT>/sessions/calendar?start=2025-08-0
"success": true,
"sessions": [
{
"ses_MAC": "AA:BB:CC:DD:EE:FF",
"ses_Connection": "2025-08-01 10:00",
"ses_Disconnection": "2025-08-01 12:00",
"ses_Duration": "2h 0m",
"ses_IP": "192.168.1.10",
"ses_Info": ""
"sesMac": "AA:BB:CC:DD:EE:FF",
"sesDateTimeConnection": "2025-08-01 10:00",
"sesDateTimeDisconnection": "2025-08-01 12:00",
"sesDuration": "2h 0m",
"sesIp": "192.168.1.10",
"sesAdditionalInfo": ""
}
]
}

4
docs/DEBUG_PLUGINS.md
View File

@@ -43,7 +43,7 @@ Input data from the plugin might cause mapping issues in specific edge cases. Lo
17:31:05 [Scheduler] run for PIHOLE: YES
17:31:05 [Plugin utils] ---------------------------------------------
17:31:05 [Plugin utils] display_name: PiHole (Device sync)
17:31:05 [Plugins] CMD: SELECT n.hwaddr AS Object_PrimaryID, {s-quote}null{s-quote} AS Object_SecondaryID, datetime() AS DateTime, na.ip AS Watched_Value1, n.lastQuery AS Watched_Value2, na.name AS Watched_Value3, n.macVendor AS Watched_Value4, {s-quote}null{s-quote} AS Extra, n.hwaddr AS ForeignKey FROM EXTERNAL_PIHOLE.Network AS n LEFT JOIN EXTERNAL_PIHOLE.Network_Addresses AS na ON na.network_id = n.id WHERE n.hwaddr NOT LIKE {s-quote}ip-%{s-quote} AND n.hwaddr is not {s-quote}00:00:00:00:00:00{s-quote} AND na.ip is not null
17:31:05 [Plugins] CMD: SELECT n.hwaddr AS objectPrimaryId, {s-quote}null{s-quote} AS objectSecondaryId, datetime() AS DateTime, na.ip AS watchedValue1, n.lastQuery AS watchedValue2, na.name AS watchedValue3, n.macVendor AS watchedValue4, {s-quote}null{s-quote} AS Extra, n.hwaddr AS ForeignKey FROM EXTERNAL_PIHOLE.Network AS n LEFT JOIN EXTERNAL_PIHOLE.Network_Addresses AS na ON na.network_id = n.id WHERE n.hwaddr NOT LIKE {s-quote}ip-%{s-quote} AND n.hwaddr is not {s-quote}00:00:00:00:00:00{s-quote} AND na.ip is not null
17:31:05 [Plugins] setTyp: subnets
17:31:05 [Plugin utils] Flattening the below array
17:31:05 ['192.168.1.0/24 --interface=eth1']
@@ -52,7 +52,7 @@ Input data from the plugin might cause mapping issues in specific edge cases. Lo
17:31:05 [Plugins] Convert to Base64: True
17:31:05 [Plugins] base64 value: b'MTkyLjE2OC4xLjAvMjQgLS1pbnRlcmZhY2U9ZXRoMQ=='
17:31:05 [Plugins] Timeout: 10
17:31:05 [Plugins] Executing: SELECT n.hwaddr AS Object_PrimaryID, 'null' AS Object_SecondaryID, datetime() AS DateTime, na.ip AS Watched_Value1, n.lastQuery AS Watched_Value2, na.name AS Watched_Value3, n.macVendor AS Watched_Value4, 'null' AS Extra, n.hwaddr AS ForeignKey FROM EXTERNAL_PIHOLE.Network AS n LEFT JOIN EXTERNAL_PIHOLE.Network_Addresses AS na ON na.network_id = n.id WHERE n.hwaddr NOT LIKE 'ip-%' AND n.hwaddr is not '00:00:00:00:00:00' AND na.ip is not null
17:31:05 [Plugins] Executing: SELECT n.hwaddr AS objectPrimaryId, 'null' AS objectSecondaryId, datetime() AS DateTime, na.ip AS watchedValue1, n.lastQuery AS watchedValue2, na.name AS watchedValue3, n.macVendor AS watchedValue4, 'null' AS Extra, n.hwaddr AS ForeignKey FROM EXTERNAL_PIHOLE.Network AS n LEFT JOIN EXTERNAL_PIHOLE.Network_Addresses AS na ON na.network_id = n.id WHERE n.hwaddr NOT LIKE 'ip-%' AND n.hwaddr is not '00:00:00:00:00:00' AND na.ip is not null
🔻
17:31:05 [Plugins] SUCCESS, received 2 entries
17:31:05 [Plugins] sqlParam entries: [(0, 'PIHOLE', '01:01:01:01:01:01', 'null', 'null', '2023-12-25 06:31:05', '172.30.0.1', 0, 'aaaa', 'vvvvvvvvv', 'not-processed', 'null', 'null', '01:01:01:01:01:01'), (0, 'PIHOLE', '02:42:ac:1e:00:02', 'null', 'null', '2023-12-25 06:31:05', '172.30.0.2', 0, 'dddd', 'vvvvv2222', 'not-processed', 'null', 'null', '02:42:ac:1e:00:02')]

2
docs/NOTIFICATIONS.md
View File

@@ -36,7 +36,7 @@ The following device properties influence notifications. You can:
On almost all plugins there are 2 core settings, `<plugin>_WATCH` and `<plugin>_REPORT_ON`.
1. `<plugin>_WATCH` specifies the columns which the app should watch. If watched columns change the device state is considered changed. This changed status is then used to decide to send out notifications based on the `<plugin>_REPORT_ON` setting.
2. `<plugin>_REPORT_ON` let's you specify on which events the app should notify you. This is related to the `<plugin>_WATCH` setting. So if you select `watched-changed` and in `<plugin>_WATCH` you only select `Watched_Value1`, then a notification is triggered if `Watched_Value1` is changed from the previous value, but no notification is send if `Watched_Value2` changes.
2. `<plugin>_REPORT_ON` let's you specify on which events the app should notify you. This is related to the `<plugin>_WATCH` setting. So if you select `watched-changed` and in `<plugin>_WATCH` you only select `watchedValue1`, then a notification is triggered if `watchedValue1` is changed from the previous value, but no notification is send if `watchedValue2` changes.
Click the **Read more in the docs.** Link at the top of each plugin to get more details on how the given plugin works.

48
docs/NOTIFICATION_TEMPLATES.md
View File

@@ -10,7 +10,7 @@ HTML email tables are **not affected** by these templates.
1. Go to **Settings → Notification Processing**.
2. Set a template string for the section you want to customize, e.g.:
- **Text Template: New Devices** → `{devName} ({eve_MAC}) - {eve_IP}`
- **Text Template: New Devices** → `{devName} ({eveMac}) - {eveIp}`
3. Save. The next notification will use your format.
**Before (default):**
@@ -18,15 +18,15 @@ HTML email tables are **not affected** by these templates.
🆕 New devices
---------
devName: MyPhone
eve_MAC: aa:bb:cc:dd:ee:ff
eveMac: aa:bb:cc:dd:ee:ff
devVendor: Apple
eve_IP: 192.168.1.42
eve_DateTime: 2025-01-15 10:30:00
eve_EventType: New Device
eveIp: 192.168.1.42
eveDateTime: 2025-01-15 10:30:00
eveEventType: New Device
devComments:
```
**After (with template `{devName} ({eve_MAC}) - {eve_IP}`):**
**After (with template `{devName} ({eveMac}) - {eveIp}`):**
```
🆕 New devices
---------
@@ -51,7 +51,7 @@ When a template is **empty**, the section uses the original vertical `Header: Va
Use `{FieldName}` to insert a value from the notification data. Field names are **case-sensitive** and must match the column names exactly.
```
{devName} ({eve_MAC}) connected at {eve_DateTime}
{devName} ({eveMac}) connected at {eveDateTime}
```
- No loops, conditionals, or nesting — just simple string replacement.
@@ -66,34 +66,34 @@ All four device sections (`new_devices`, `down_devices`, `down_reconnected`, `ev
| Variable | Description |
|----------|-------------|
| `{devName}` | Device display name |
| `{eve_MAC}` | Device MAC address |
| `{eveMac}` | Device MAC address |
| `{devVendor}` | Device vendor/manufacturer |
| `{eve_IP}` | Device IP address |
| `{eve_DateTime}` | Event timestamp |
| `{eve_EventType}` | Type of event (e.g. `New Device`, `Connected`, `Device Down`) |
| `{eveIp}` | Device IP address |
| `{eveDateTime}` | Event timestamp |
| `{eveEventType}` | Type of event (e.g. `New Device`, `Connected`, `Device Down`) |
| `{devComments}` | Device comments |
**Example (new_devices/events):** `{devName} ({eve_MAC}) - {eve_IP} [{eve_EventType}]`
**Example (new_devices/events):** `{devName} ({eveMac}) - {eveIp} [{eveEventType}]`
**Example (down_devices):** `{devName} ({eve_MAC}) {devVendor} - went down at {eve_DateTime}`
**Example (down_devices):** `{devName} ({eveMac}) {devVendor} - went down at {eveDateTime}`
**Example (down_reconnected):** `{devName} ({eve_MAC}) reconnected at {eve_DateTime}`
**Example (down_reconnected):** `{devName} ({eveMac}) reconnected at {eveDateTime}`
### `plugins`
| Variable | Description |
|----------|-------------|
| `{Plugin}` | Plugin code name |
| `{Object_PrimaryId}` | Primary identifier of the object |
| `{Object_SecondaryId}` | Secondary identifier |
| `{DateTimeChanged}` | Timestamp of change |
| `{Watched_Value1}` | First watched value |
| `{Watched_Value2}` | Second watched value |
| `{Watched_Value3}` | Third watched value |
| `{Watched_Value4}` | Fourth watched value |
| `{Status}` | Plugin event status |
| `{plugin}` | Plugin code name |
| `{objectPrimaryId}` | Primary identifier of the object |
| `{objectSecondaryId}` | Secondary identifier |
| `{dateTimeChanged}` | Timestamp of change |
| `{watchedValue1}` | First watched value |
| `{watchedValue2}` | Second watched value |
| `{watchedValue3}` | Third watched value |
| `{watchedValue4}` | Fourth watched value |
| `{status}` | Plugin event status |
**Example:** `{Plugin}: {Object_PrimaryId} - {Status}`
**Example:** `{plugin}: {objectPrimaryId} - {status}`
## Section Headers Toggle

18
docs/PLUGINS_DEV.md
View File

@@ -179,13 +179,13 @@ Quick reference:
| Column | Name | Required | Example |
|--------|------|----------|---------|
| 0 | Object_PrimaryID | **YES** | `"device_name"` or `"192.168.1.1"` |
| 1 | Object_SecondaryID | no | `"secondary_id"` or `null` |
| 0 | objectPrimaryId | **YES** | `"device_name"` or `"192.168.1.1"` |
| 1 | objectSecondaryId | no | `"secondary_id"` or `null` |
| 2 | DateTime | **YES** | `"2023-01-02 15:56:30"` |
| 3 | Watched_Value1 | **YES** | `"online"` or `"200"` |
| 4 | Watched_Value2 | no | `"ip_address"` or `null` |
| 5 | Watched_Value3 | no | `null` |
| 6 | Watched_Value4 | no | `null` |
| 3 | watchedValue1 | **YES** | `"online"` or `"200"` |
| 4 | watchedValue2 | no | `"ip_address"` or `null` |
| 5 | watchedValue3 | no | `null` |
| 6 | watchedValue4 | no | `null` |
| 7 | Extra | no | `"additional data"` or `null` |
| 8 | ForeignKey | no | `"aa:bb:cc:dd:ee:ff"` or `null` |
@@ -243,7 +243,7 @@ Control which rows display in the UI:
{
"data_filters": [
{
"compare_column": "Object_PrimaryID",
"compare_column": "objectPrimaryId",
"compare_operator": "==",
"compare_field_id": "txtMacFilter",
"compare_js_template": "'{value}'.toString()",
@@ -267,7 +267,7 @@ To import plugin data into NetAlertX tables for device discovery or notification
"mapped_to_table": "CurrentScan",
"database_column_definitions": [
{
"column": "Object_PrimaryID",
"column": "objectPrimaryId",
"mapped_to_column": "scanMac",
"show": true,
"type": "device_mac",
@@ -345,7 +345,7 @@ See [PLUGINS_DEV_SETTINGS.md](PLUGINS_DEV_SETTINGS.md) for complete settings doc
### Plugin Output Format
```
Object_PrimaryID|Object_SecondaryID|DateTime|Watched_Value1|Watched_Value2|Watched_Value3|Watched_Value4|Extra|ForeignKey
objectPrimaryId|objectSecondaryId|DateTime|watchedValue1|watchedValue2|watchedValue3|watchedValue4|Extra|ForeignKey
```
9 required columns, 4 optional helpers = 13 max

8
docs/PLUGINS_DEV_CONFIG.md
View File

@@ -77,7 +77,7 @@ It also describes plugin output expectations and the main plugin categories.
* `database_column_definitions`
* `mapped_to_table`
**Example:** `Object_PrimaryID → devMAC`
**Example:** `objectPrimaryId → devMAC`
---
@@ -88,9 +88,9 @@ Output values are pipe-delimited in a fixed order.
#### Identifiers
* `Object_PrimaryID` and `Object_SecondaryID` uniquely identify records (for example, `MAC|IP`).
* `objectPrimaryId` and `objectSecondaryId` uniquely identify records (for example, `MAC|IP`).
#### Watched Values (`Watched_Value1–4`)
#### Watched Values (`watchedValue1–4`)
* Used by the core to detect changes between runs.
* Changes in these fields can trigger notifications.
@@ -114,7 +114,7 @@ Output values are pipe-delimited in a fixed order.
### 7. Persistence
* Parsed data is **upserted** into the database.
* Conflicts are resolved using the combined key: `Object_PrimaryID + Object_SecondaryID`.
* Conflicts are resolved using the combined key: `objectPrimaryId + objectSecondaryId`.
---

16
docs/PLUGINS_DEV_DATASOURCES.md
View File

@@ -107,7 +107,7 @@ Query the NetAlertX SQLite database and display results.
{
"function": "CMD",
"type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
"default_value": "SELECT dv.devName as Object_PrimaryID, cast(dv.devLastIP as VARCHAR(100)) || ':' || cast(SUBSTR(ns.Port, 0, INSTR(ns.Port, '/')) as VARCHAR(100)) as Object_SecondaryID, datetime() as DateTime, ns.Service as Watched_Value1, ns.State as Watched_Value2, null as Watched_Value3, null as Watched_Value4, ns.Extra as Extra, dv.devMac as ForeignKey FROM (SELECT * FROM Nmap_Scan) ns LEFT JOIN (SELECT devName, devMac, devLastIP FROM Devices) dv ON ns.MAC = dv.devMac",
"default_value": "SELECT dv.devName as objectPrimaryId, cast(dv.devLastIP as VARCHAR(100)) || ':' || cast(SUBSTR(ns.Port, 0, INSTR(ns.Port, '/')) as VARCHAR(100)) as objectSecondaryId, datetime() as DateTime, ns.Service as watchedValue1, ns.State as watchedValue2, null as watchedValue3, null as watchedValue4, ns.Extra as Extra, dv.devMac as ForeignKey FROM (SELECT * FROM Nmap_Scan) ns LEFT JOIN (SELECT devName, devMac, devLastIP FROM Devices) dv ON ns.MAC = dv.devMac",
"localized": ["name"],
"name": [{"language_code": "en_us", "string": "SQL to run"}],
"description": [{"language_code": "en_us", "string": "This SQL query populates the plugin table"}]
@@ -118,13 +118,13 @@ Query the NetAlertX SQLite database and display results.
```sql
SELECT
e.EventValue as Object_PrimaryID,
d.devName as Object_SecondaryID,
e.EventValue as objectPrimaryId,
d.devName as objectSecondaryId,
e.EventDateTime as DateTime,
e.EventType as Watched_Value1,
d.devLastIP as Watched_Value2,
null as Watched_Value3,
null as Watched_Value4,
e.EventType as watchedValue1,
d.devLastIP as watchedValue2,
null as watchedValue3,
null as watchedValue4,
e.EventDetails as Extra,
d.devMac as ForeignKey
FROM
@@ -181,7 +181,7 @@ Then set data source and query:
```json
{
"function": "CMD",
"default_value": "SELECT hwaddr as Object_PrimaryID, cast('http://' || (SELECT ip FROM EXTERNAL_PIHOLE.network_addresses WHERE network_id = id ORDER BY lastseen DESC LIMIT 1) as VARCHAR(100)) || ':' || cast(SUBSTR((SELECT name FROM EXTERNAL_PIHOLE.network_addresses WHERE network_id = id ORDER BY lastseen DESC LIMIT 1), 0, INSTR((SELECT name FROM EXTERNAL_PIHOLE.network_addresses WHERE network_id = id ORDER BY lastseen DESC LIMIT 1), '/')) as VARCHAR(100)) as Object_SecondaryID, datetime() as DateTime, macVendor as Watched_Value1, lastQuery as Watched_Value2, (SELECT name FROM EXTERNAL_PIHOLE.network_addresses WHERE network_id = id ORDER BY lastseen DESC LIMIT 1) as Watched_Value3, null as Watched_Value4, '' as Extra, hwaddr as ForeignKey FROM EXTERNAL_PIHOLE.network WHERE hwaddr NOT LIKE 'ip-%' AND hwaddr <> '00:00:00:00:00:00'",
"default_value": "SELECT hwaddr as objectPrimaryId, cast('http://' || (SELECT ip FROM EXTERNAL_PIHOLE.network_addresses WHERE network_id = id ORDER BY lastseen DESC LIMIT 1) as VARCHAR(100)) || ':' || cast(SUBSTR((SELECT name FROM EXTERNAL_PIHOLE.network_addresses WHERE network_id = id ORDER BY lastseen DESC LIMIT 1), 0, INSTR((SELECT name FROM EXTERNAL_PIHOLE.network_addresses WHERE network_id = id ORDER BY lastseen DESC LIMIT 1), '/')) as VARCHAR(100)) as objectSecondaryId, datetime() as DateTime, macVendor as watchedValue1, lastQuery as watchedValue2, (SELECT name FROM EXTERNAL_PIHOLE.network_addresses WHERE network_id = id ORDER BY lastseen DESC LIMIT 1) as watchedValue3, null as watchedValue4, '' as Extra, hwaddr as ForeignKey FROM EXTERNAL_PIHOLE.network WHERE hwaddr NOT LIKE 'ip-%' AND hwaddr <> '00:00:00:00:00:00'",
"localized": ["name"],
"name": [{"language_code": "en_us", "string": "SQL to run"}]
}

62
docs/PLUGINS_DEV_DATA_CONTRACT.md
View File

@@ -18,19 +18,19 @@ Plugins communicate with NetAlertX by writing results to a **pipe-delimited log
## Column Specification
> [!NOTE]
> The order of columns is **FIXED** and cannot be changed. All 9 mandatory columns must be provided. If you use any optional column (`HelpVal1`), you must supply all optional columns (`HelpVal1` through `HelpVal4`).
> The order of columns is **FIXED** and cannot be changed. All 9 mandatory columns must be provided. If you use any optional column (`helpVal1`), you must supply all optional columns (`helpVal1` through `helpVal4`).
### Mandatory Columns (0–8)
| Order | Column Name | Type | Required | Description |
|-------|-------------|------|----------|-------------|
| 0 | `Object_PrimaryID` | string | **YES** | The primary identifier for grouping. Examples: device MAC, hostname, service name, or any unique ID |
| 1 | `Object_SecondaryID` | string | no | Secondary identifier for relationships (e.g., IP address, port, sub-ID). Use `null` if not needed |
| 0 | `objectPrimaryId` | string | **YES** | The primary identifier for grouping. Examples: device MAC, hostname, service name, or any unique ID |
| 1 | `objectSecondaryId` | string | no | Secondary identifier for relationships (e.g., IP address, port, sub-ID). Use `null` if not needed |
| 2 | `DateTime` | string | **YES** | Timestamp when the event/data was collected. Format: `YYYY-MM-DD HH:MM:SS` |
| 3 | `Watched_Value1` | string | **YES** | Primary watched value. Changes trigger notifications. Examples: IP address, status, version |
| 4 | `Watched_Value2` | string | no | Secondary watched value. Use `null` if not needed |
| 5 | `Watched_Value3` | string | no | Tertiary watched value. Use `null` if not needed |
| 6 | `Watched_Value4` | string | no | Quaternary watched value. Use `null` if not needed |
| 3 | `watchedValue1` | string | **YES** | Primary watched value. Changes trigger notifications. Examples: IP address, status, version |
| 4 | `watchedValue2` | string | no | Secondary watched value. Use `null` if not needed |
| 5 | `watchedValue3` | string | no | Tertiary watched value. Use `null` if not needed |
| 6 | `watchedValue4` | string | no | Quaternary watched value. Use `null` if not needed |
| 7 | `Extra` | string | no | Any additional metadata to display in UI and notifications. Use `null` if not needed |
| 8 | `ForeignKey` | string | no | Foreign key linking to parent object (usually MAC address for device relationship). Use `null` if not needed |
@@ -38,10 +38,10 @@ Plugins communicate with NetAlertX by writing results to a **pipe-delimited log
| Order | Column Name | Type | Required | Description |
|-------|-------------|------|----------|-------------|
| 9 | `HelpVal1` | string | *conditional* | Helper value 1. If used, all help values must be supplied |
| 10 | `HelpVal2` | string | *conditional* | Helper value 2. If used, all help values must be supplied |
| 11 | `HelpVal3` | string | *conditional* | Helper value 3. If used, all help values must be supplied |
| 12 | `HelpVal4` | string | *conditional* | Helper value 4. If used, all help values must be supplied |
| 9 | `helpVal1` | string | *conditional* | Helper value 1. If used, all help values must be supplied |
| 10 | `helpVal2` | string | *conditional* | Helper value 2. If used, all help values must be supplied |
| 11 | `helpVal3` | string | *conditional* | Helper value 3. If used, all help values must be supplied |
| 12 | `helpVal4` | string | *conditional* | Helper value 4. If used, all help values must be supplied |
## Usage Guide
@@ -58,15 +58,15 @@ Watched values are fields that the NetAlertX core monitors for **changes between
**How to use them:**
- `Watched_Value1`: Always required; primary indicator of status/state
- `Watched_Value2–4`: Optional; use for secondary/tertiary state information
- `watchedValue1`: Always required; primary indicator of status/state
- `watchedValue2–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)
- Device scanner: `watchedValue1 = "online"` or `"offline"`
- Port scanner: `watchedValue1 = "80"` (port number), `watchedValue2 = "open"` (state)
- Service monitor: `watchedValue1 = "200"` (HTTP status), `watchedValue2 = "0.45"` (response time)
### Foreign Key
@@ -110,14 +110,14 @@ https://google.com|null|2023-01-02 15:56:30|200|0.7898||null|null
Missing pipe
```
❌ **Missing mandatory Watched_Value1** (column 3):
❌ **Missing mandatory watchedValue1** (column 3):
```csv
https://duckduckgo.com|192.168.1.1|2023-01-02 15:56:30|null|0.9898|null|null|Best|null
↑
Must not be null
```
❌ **Incomplete optional columns** (has HelpVal1 but missing HelpVal2–4):
❌ **Incomplete optional columns** (has helpVal1 but missing helpVal2–4):
```csv
device|null|2023-01-02 15:56:30|status|null|null|null|null|null|helper1
↑
@@ -146,19 +146,19 @@ plugin_objects = Plugin_Objects("YOURPREFIX")
# Add objects
plugin_objects.add_object(
Object_PrimaryID="device_id",
Object_SecondaryID="192.168.1.1",
objectPrimaryId="device_id",
objectSecondaryId="192.168.1.1",
DateTime="2023-01-02 15:56:30",
Watched_Value1="online",
Watched_Value2=None,
Watched_Value3=None,
Watched_Value4=None,
watchedValue1="online",
watchedValue2=None,
watchedValue3=None,
watchedValue4=None,
Extra="Additional data",
ForeignKey="aa:bb:cc:dd:ee:ff",
HelpVal1=None,
HelpVal2=None,
HelpVal3=None,
HelpVal4=None
helpVal1=None,
helpVal2=None,
helpVal3=None,
helpVal4=None
)
# Write results (handles formatting, sanitization, and file creation)
@@ -177,7 +177,7 @@ The library automatically:
The core runs **de-duplication once per hour** on the `Plugins_Objects` table:
- **Duplicate Detection Key:** Combination of `Object_PrimaryID`, `Object_SecondaryID`, `Plugin` (auto-filled from `unique_prefix`), and `UserData`
- **Duplicate Detection Key:** Combination of `objectPrimaryId`, `objectSecondaryId`, `Plugin` (auto-filled from `unique_prefix`), and `UserData`
- **Resolution:** Oldest duplicate entries are removed, newest are kept
- **Use Case:** Prevents duplicate notifications when the same object is detected multiple times
@@ -213,9 +213,9 @@ Before writing your plugin's `script.py`, ensure:
- [ ] **9 or 13 columns** in each output line (8 or 12 pipe separators)
- [ ] **Mandatory columns filled:**
- Column 0: `Object_PrimaryID` (not null)
- Column 0: `objectPrimaryId` (not null)
- Column 2: `DateTime` in `YYYY-MM-DD HH:MM:SS` format
- Column 3: `Watched_Value1` (not null)
- Column 3: `watchedValue1` (not null)
- [ ] **Null values as literal string** `null` (not empty string or special chars)
- [ ] **No extra pipes or misaligned columns**
- [ ] **If using optional helpers** (columns 9–12), all 4 must be present

12
docs/PLUGINS_DEV_QUICK_START.md
View File

@@ -68,13 +68,13 @@ try:
# Add an object to results
plugin_objects.add_object(
Object_PrimaryID="example_id",
Object_SecondaryID=None,
objectPrimaryId="example_id",
objectSecondaryId=None,
DateTime="2023-01-02 15:56:30",
Watched_Value1="value1",
Watched_Value2=None,
Watched_Value3=None,
Watched_Value4=None,
watchedValue1="value1",
watchedValue2=None,
watchedValue3=None,
watchedValue4=None,
Extra="additional_data",
ForeignKey=None
)

44
docs/PLUGINS_DEV_UI_COMPONENTS.md
View File

@@ -16,7 +16,7 @@ Each column definition specifies:
```json
{
"column": "Object_PrimaryID",
"column": "objectPrimaryId",
"mapped_to_column": "devMac",
"mapped_to_column_data": null,
"css_classes": "col-sm-2",
@@ -39,7 +39,7 @@ Each column definition specifies:
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `column` | string | **YES** | Source column name from data contract (e.g., `Object_PrimaryID`, `Watched_Value1`) |
| `column` | string | **YES** | Source column name from data contract (e.g., `objectPrimaryId`, `watchedValue1`) |
| `mapped_to_column` | string | no | Target database column if mapping to a table like `CurrentScan` |
| `mapped_to_column_data` | object | no | Static value to map instead of using column data |
| `css_classes` | string | no | Bootstrap CSS classes for width/spacing (e.g., `"col-sm-2"`, `"col-sm-6"`) |
@@ -64,7 +64,7 @@ Plain text display (read-only).
```json
{
"column": "Watched_Value1",
"column": "watchedValue1",
"show": true,
"type": "label",
"localized": ["name"],
@@ -99,7 +99,7 @@ Resolves an IP address to a MAC address and creates a device link.
```json
{
"column": "Object_SecondaryID",
"column": "objectSecondaryId",
"show": true,
"type": "device_ip",
"localized": ["name"],
@@ -117,7 +117,7 @@ Creates a device link with the target device's name as the link label.
```json
{
"column": "Object_PrimaryID",
"column": "objectPrimaryId",
"show": true,
"type": "device_name_mac",
"localized": ["name"],
@@ -135,7 +135,7 @@ Renders as a clickable HTTP/HTTPS link.
```json
{
"column": "Watched_Value1",
"column": "watchedValue1",
"show": true,
"type": "url",
"localized": ["name"],
@@ -153,7 +153,7 @@ Creates two links (HTTP and HTTPS) as lock icons for the given IP/hostname.
```json
{
"column": "Object_SecondaryID",
"column": "objectSecondaryId",
"show": true,
"type": "url_http_https",
"localized": ["name"],
@@ -207,7 +207,7 @@ Color-codes values based on ranges. Useful for status codes, latency, capacity p
```json
{
"column": "Watched_Value1",
"column": "watchedValue1",
"show": true,
"type": "threshold",
"options": [
@@ -252,7 +252,7 @@ Replaces specific values with display strings or HTML.
```json
{
"column": "Watched_Value2",
"column": "watchedValue2",
"show": true,
"type": "replace",
"options": [
@@ -286,7 +286,7 @@ Applies a regular expression to extract/transform values.
```json
{
"column": "Watched_Value1",
"column": "watchedValue1",
"show": true,
"type": "regex",
"options": [
@@ -310,7 +310,7 @@ Evaluates JavaScript code with access to the column value (use `${value}` or `{v
```json
{
"column": "Watched_Value1",
"column": "watchedValue1",
"show": true,
"type": "eval",
"default_value": "",
@@ -322,7 +322,7 @@ Evaluates JavaScript code with access to the column value (use `${value}` or `{v
**Example with custom formatting:**
```json
{
"column": "Watched_Value1",
"column": "watchedValue1",
"show": true,
"type": "eval",
"options": [
@@ -347,7 +347,7 @@ You can chain multiple transformations with dot notation:
```json
{
"column": "Watched_Value3",
"column": "watchedValue3",
"show": true,
"type": "regex.url_http_https",
"options": [
@@ -376,7 +376,7 @@ Use SQL query results to populate dropdown options:
```json
{
"column": "Watched_Value2",
"column": "watchedValue2",
"show": true,
"type": "select",
"options": ["{value}"],
@@ -405,7 +405,7 @@ Use plugin settings to populate options:
```json
{
"column": "Watched_Value1",
"column": "watchedValue1",
"show": true,
"type": "select",
"options": ["{value}"],
@@ -439,7 +439,7 @@ To import plugin data into the device scan pipeline (for notifications, heuristi
"mapped_to_table": "CurrentScan",
"database_column_definitions": [
{
"column": "Object_PrimaryID",
"column": "objectPrimaryId",
"mapped_to_column": "scanMac",
"show": true,
"type": "device_mac",
@@ -447,7 +447,7 @@ To import plugin data into the device scan pipeline (for notifications, heuristi
"name": [{"language_code": "en_us", "string": "MAC Address"}]
},
{
"column": "Object_SecondaryID",
"column": "objectSecondaryId",
"mapped_to_column": "scanLastIP",
"show": true,
"type": "device_ip",
@@ -501,7 +501,7 @@ Control which rows are displayed based on filter conditions. Filters are applied
{
"data_filters": [
{
"compare_column": "Object_PrimaryID",
"compare_column": "objectPrimaryId",
"compare_operator": "==",
"compare_field_id": "txtMacFilter",
"compare_js_template": "'{value}'.toString()",
@@ -545,7 +545,7 @@ When viewing a device detail page, the `txtMacFilter` field is populated with th
{
"database_column_definitions": [
{
"column": "Object_PrimaryID",
"column": "objectPrimaryId",
"mapped_to_column": "scanMac",
"css_classes": "col-sm-2",
"show": true,
@@ -555,7 +555,7 @@ When viewing a device detail page, the `txtMacFilter` field is populated with th
"name": [{"language_code": "en_us", "string": "MAC Address"}]
},
{
"column": "Object_SecondaryID",
"column": "objectSecondaryId",
"mapped_to_column": "scanLastIP",
"css_classes": "col-sm-2",
"show": true,
@@ -574,7 +574,7 @@ When viewing a device detail page, the `txtMacFilter` field is populated with th
"name": [{"language_code": "en_us", "string": "Last Seen"}]
},
{
"column": "Watched_Value1",
"column": "watchedValue1",
"css_classes": "col-sm-2",
"show": true,
"type": "threshold",
@@ -589,7 +589,7 @@ When viewing a device detail page, the `txtMacFilter` field is populated with th
"name": [{"language_code": "en_us", "string": "HTTP Status"}]
},
{
"column": "Watched_Value2",
"column": "watchedValue2",
"css_classes": "col-sm-1",
"show": true,
"type": "label",