vh/NetAlertX
1
0
Fork 0
mirror of https://github.com/jokob-sk/NetAlertX.git synced 2025-12-07 09:36:05 -08:00
Code Issues Actions Packages Projects Releases Wiki Activity

🔺GraphQL v0.1 + Devices table rebuild + removal of backend compatible scripts

Browse Source
This commit is contained in:
jokob-sk
2024-11-10 21:22:45 +11:00
parent 3cf3305b8f
commit 0bc8b39cec
76 changed files with 1622 additions and 2878 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
docs/API.md
View File

@@ -58,38 +58,38 @@ Example JSON of the `table_devices.json` endpoint with two Devices (database row
{
"data": [
{
"dev_MAC": "Internet",
"dev_Name": "Net - Huawei",
"dev_DeviceType": "Router",
"dev_Vendor": null,
"dev_Group": "Always on",
"dev_FirstConnection": "2021-01-01 00:00:00",
"dev_LastConnection": "2021-01-28 22:22:11",
"dev_LastIP": "192.168.1.24",
"dev_StaticIP": 0,
"dev_PresentLastScan": 1,
"dev_LastNotification": "2023-01-28 22:22:28.998715",
"dev_NewDevice": 0,
"dev_Network_Node_MAC_ADDR": "",
"dev_Network_Node_port": "",
"dev_Icon": "globe"
"devMac": "Internet",
"devName": "Net - Huawei",
"devType": "Router",
"devVendor": null,
"devGroup": "Always on",
"devFirstConnection": "2021-01-01 00:00:00",
"devLastConnection": "2021-01-28 22:22:11",
"devLastIP": "192.168.1.24",
"devStaticIP": 0,
"devPresentLastScan": 1,
"devLastNotification": "2023-01-28 22:22:28.998715",
"devIsNew": 0,
"devParentMAC": "",
"devParentPort": "",
"devIcon": "globe"
},
{
"dev_MAC": "a4:8f:ff:aa:ba:1f",
"dev_Name": "Net - USG",
"dev_DeviceType": "Firewall",
"dev_Vendor": "Ubiquiti Inc",
"dev_Group": "",
"dev_FirstConnection": "2021-02-12 22:05:00",
"dev_LastConnection": "2021-07-17 15:40:00",
"dev_LastIP": "192.168.1.1",
"dev_StaticIP": 1,
"dev_PresentLastScan": 1,
"dev_LastNotification": "2021-07-17 15:40:10.667717",
"dev_NewDevice": 0,
"dev_Network_Node_MAC_ADDR": "Internet",
"dev_Network_Node_port": 1,
"dev_Icon": "shield-halved"
"devMac": "a4:8f:ff:aa:ba:1f",
"devName": "Net - USG",
"devType": "Firewall",
"devVendor": "Ubiquiti Inc",
"devGroup": "",
"devFirstConnection": "2021-02-12 22:05:00",
"devLastConnection": "2021-07-17 15:40:00",
"devLastIP": "192.168.1.1",
"devStaticIP": 1,
"devPresentLastScan": 1,
"devLastNotification": "2021-07-17 15:40:10.667717",
"devIsNew": 0,
"devParentMAC": "Internet",
"devParentPort": 1,
"devIcon": "shield-halved"
}
]
}

2
docs/HW_INSTALL.md
View File

@@ -5,6 +5,8 @@ To download and install NetAlertX on the hardware/server directly use the `curl`
> [!NOTE]
> This is an Experimental feature 🧪 and it relies on community support.
>
> Looking for maintainers for this installation method 🙂
>
> There is no guarantee that the install script or any other script will gracefully handle other installed software.
> Data loss is a possibility, **it is recommended to install NetAlertX using the supplied Docker image**.

30
docs/PLUGINS_DEV.md
View File

@@ -170,20 +170,20 @@ This SQL query is executed on the `app.db` SQLite database file.
> SQL query example:
>
> ```SQL
> SELECT dv.dev_Name as Object_PrimaryID,
> cast(dv.dev_LastIP as VARCHAR(100)) || ':' || cast( SUBSTR(ns.Port ,0, INSTR(ns.Port , '/')) as VARCHAR(100)) as Object_SecondaryID,
> 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.dev_MAC as ForeignKey
> dv.devMac as ForeignKey
> FROM
> (SELECT * FROM Nmap_Scan) ns
> LEFT JOIN
> (SELECT dev_Name, dev_MAC, dev_LastIP FROM Devices) dv
> ON ns.MAC = dv.dev_MAC
> (SELECT devName, devMac, devLastIP FROM Devices) dv
> ON ns.MAC = dv.devMac
> ```
>
> Required `CMD` setting example with above query (you can set `"type": "label"` if you want it to make uneditable in the UI):
@@ -192,7 +192,7 @@ This SQL query is executed on the `app.db` SQLite database file.
> {
> "function": "CMD",
> "type": {"dataType":"string", "elements": [{"elementType" : "input", "elementOptions" : [] ,"transformers": []}]},
> "default_value":"SELECT dv.dev_Name as Object_PrimaryID, cast(dv.dev_LastIP 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 FROM (SELECT * FROM Nmap_Scan) ns LEFT JOIN (SELECT dev_Name, dev_MAC, dev_LastIP FROM Devices) dv ON ns.MAC = dv.dev_MAC",
> "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 FROM (SELECT * FROM Nmap_Scan) ns LEFT JOIN (SELECT devName, devMac, devLastIP FROM Devices) dv ON ns.MAC = dv.devMac",
> "options": [],
> "localized": ["name", "description"],
> "name" : [{
@@ -460,7 +460,7 @@ Below are some general additional notes, when defining `params`:
- `"name":"name_value"` - is used as a wildcard replacement in the `CMD` setting value by using curly brackets `{name_value}`. The wildcard is replaced by the result of the `"value" : "param_value"` and `"type":"type_value"` combo configuration below.
- `"type":"<sql|setting>"` - is used to specify the type of the params, currently only 2 supported (`sql`,`setting`).
- `"type":"sql"` - will execute the SQL query specified in the `value` property. The sql query needs to return only one column. The column is flattened and separated by commas (`,`), e.g: `SELECT dev_MAC from DEVICES` -> `Internet,74:ac:74:ac:74:ac,44:44:74:ac:74:ac`. This is then used to replace the wildcards in the `CMD` setting.
- `"type":"sql"` - will execute the SQL query specified in the `value` property. The sql query needs to return only one column. The column is flattened and separated by commas (`,`), e.g: `SELECT devMac from DEVICES` -> `Internet,74:ac:74:ac:74:ac,44:44:74:ac:74:ac`. This is then used to replace the wildcards in the `CMD` setting.
- `"type":"setting"` - The setting code name. A combination of the value from `unique_prefix` + `_` + `function` value, or otherwise the code name you can find in the Settings page under the Setting display name, e.g. `PIHOLE_RUN`.
- `"value": "param_value"` - Needs to contain a setting code name or SQL query without wildcards.
- `"timeoutMultiplier" : true` - used to indicate if the value should multiply the max timeout for the whole script run by the number of values in the given parameter.
@@ -474,13 +474,13 @@ Below are some general additional notes, when defining `params`:
> "params" : [{
> "name" : "ips",
> "type" : "sql",
> "value" : "SELECT dev_LastIP from DEVICES",
> "value" : "SELECT devLastIP from DEVICES",
> "timeoutMultiplier" : true
> },
> {
> "name" : "macs",
> "type" : "sql",
> "value" : "SELECT dev_MAC from DEVICES"
> "value" : "SELECT devMac from DEVICES"
> },
> {
> "name" : "timeout",
@@ -527,7 +527,7 @@ The UI component is defined as a JSON object containing a list of `elements`. Ea
```json
{
"function": "dev_Icon",
"function": "devIcon",
"type": {
"dataType": "string",
"elements": [
@@ -536,7 +536,7 @@ The UI component is defined as a JSON object containing a list of `elements`. Ea
"elementOptions": [
{ "cssClasses": "input-group-addon iconPreview" },
{ "getStringKey": "Gen_SelectToPreview" },
{ "customId": "NEWDEV_dev_Icon_preview" }
{ "customId": "NEWDEV_devIcon_preview" }
],
"transformers": []
},
@@ -548,7 +548,7 @@ The UI component is defined as a JSON object containing a list of `elements`. Ea
{
"onChange": "updateIconPreview(this)"
},
{ "customParams": "NEWDEV_dev_Icon,NEWDEV_dev_Icon_preview" }
{ "customParams": "NEWDEV_devIcon,NEWDEV_devIcon_preview" }
],
"transformers": []
}
@@ -649,7 +649,7 @@ The UI will adjust how columns are displayed in the UI based on the resolvers de
| See below for information on `threshold`, `replace`. | |
| | |
| `options` Property | Used in conjunction with types like `threshold`, `replace`, `regex`. |
| `options_params` Property | Used in conjunction with a `"options": "[{value}]"` template and `text.select`/`list.select`. Can specify SQL query (needs to return 2 columns `SELECT dev_Name as name, dev_Mac as id`) or Setting (not tested) to populate the dropdown. Check example below or have a look at the `NEWDEV` plugin `config.json` file. |
| `options_params` Property | Used in conjunction with a `"options": "[{value}]"` template and `text.select`/`list.select`. Can specify SQL query (needs to return 2 columns `SELECT devName as name, devMac as id`) or Setting (not tested) to populate the dropdown. Check example below or have a look at the `NEWDEV` plugin `config.json` file. |
| `threshold` | The `options` array contains objects ordered from the lowest `maximum` to the highest. The corresponding `hexColor` is used for the value background color if it's less than the specified `maximum` but more than the previous one in the `options` array. |
| `replace` | The `options` array contains objects with an `equals` property, which is compared to the "value." If the values are the same, the string in `replacement` is displayed in the UI instead of the actual "value". |
| `regex` | Applies a regex to the value. The `options` array contains objects with an `type` (must be set to `regex`) and `param` (must contain the regex itself) property. |
@@ -669,7 +669,7 @@ The UI will adjust how columns are displayed in the UI based on the resolvers de
```json
"function": "dev_DeviceType",
"function": "devType",
"type": {"dataType":"string", "elements": [{"elementType" : "select", "elementOptions" : [] ,"transformers": []}]},
"maxLength": 30,
"default_value": "",
@@ -678,7 +678,7 @@ The UI will adjust how columns are displayed in the UI based on the resolvers de
{
"name" : "value",
"type" : "sql",
"value" : "SELECT '' as id, '' as name UNION SELECT dev_DeviceType as id, dev_DeviceType as name FROM (SELECT dev_DeviceType FROM Devices UNION SELECT 'Smartphone' UNION SELECT 'Tablet' UNION SELECT 'Laptop' UNION SELECT 'PC' UNION SELECT 'Printer' UNION SELECT 'Server' UNION SELECT 'NAS' UNION SELECT 'Domotic' UNION SELECT 'Game Console' UNION SELECT 'SmartTV' UNION SELECT 'Clock' UNION SELECT 'House Appliance' UNION SELECT 'Phone' UNION SELECT 'AP' UNION SELECT 'Gateway' UNION SELECT 'Firewall' UNION SELECT 'Switch' UNION SELECT 'WLAN' UNION SELECT 'Router' UNION SELECT 'Other') AS all_devices ORDER BY id;"
"value" : "SELECT '' as id, '' as name UNION SELECT devType as id, devType as name FROM (SELECT devType FROM Devices UNION SELECT 'Smartphone' UNION SELECT 'Tablet' UNION SELECT 'Laptop' UNION SELECT 'PC' UNION SELECT 'Printer' UNION SELECT 'Server' UNION SELECT 'NAS' UNION SELECT 'Domotic' UNION SELECT 'Game Console' UNION SELECT 'SmartTV' UNION SELECT 'Clock' UNION SELECT 'House Appliance' UNION SELECT 'Phone' UNION SELECT 'AP' UNION SELECT 'Gateway' UNION SELECT 'Firewall' UNION SELECT 'Switch' UNION SELECT 'WLAN' UNION SELECT 'Router' UNION SELECT 'Other') AS all_devices ORDER BY id;"
},
{
"name" : "uilang",

110
docs/UPDATES.md Executable file
View File

@@ -0,0 +1,110 @@
# Docker Update Strategies for NetAlertX
This guide outlines several approaches for updating Docker containers, specifically using NetAlertX. Each method offers different benefits depending on the situation. Here are the methods:
- Manual: Direct commands to stop, remove, and rebuild containers.
- Dockcheck: Semi-automated with more control, suited for bulk updates.
- Watchtower: Fully automated, runs continuously to check and update containers.
You can choose any approach that fits your workflow.
> In the examples I assume that the container name is `netalertx` and the image name is `netalertx` as well.
## 1. Manual Updates
Use this method when you need precise control over a single container or when dealing with a broken container that needs immediate attention.
Example Commands
To manually update the `netalertx` container, stop it, delete it, remove the old image, and start a fresh one with `docker-compose`.
```bash
# Stop the container
sudo docker container stop netalertx
# Remove the container
sudo docker container rm netalertx
# Remove the old image
sudo docker image rm netalertx
# Pull and start a new container
sudo docker-compose up -d
```
### Alternative: Force Pull with Docker Compose
You can also use `--pull always` to ensure Docker pulls the latest image before starting the container:
```bash
sudo docker-compose up --pull always -d
```
## 2. Dockcheck for Bulk Container Updates
Always check the [Dockcheck](https://github.com/mag37/dockcheck) docs if encountering issues with the guide below.
Dockcheck is a useful tool if you have multiple containers to update and some flexibility for handling potential issues that might arise during mass updates. Dockcheck allows you to inspect each container and decide when to update.
### Example Workflow with Dockcheck
You might use Dockcheck to:
- Inspect container versions.
- Pull the latest images in bulk.
- Apply updates selectively.
Dockcheck can help streamline bulk updates, especially if you’re managing multiple containers.
Below is a script I use to run an update of the Dockcheck script and start a check for new containers:
```bash
cd /path/to/Docker &&
rm dockcheck.sh &&
wget https://raw.githubusercontent.com/mag37/dockcheck/main/dockcheck.sh &&
sudo chmod +x dockcheck.sh &&
sudo ./dockcheck.sh
```
## 3. Automated Updates with Watchtower
Always check the [watchtower](https://github.com/containrrr/watchtower) docs if encountering issues with the guide below.
Watchtower monitors your Docker containers and automatically updates them when new images are available. This is ideal for ongoing updates without manual intervention.
### Setting Up Watchtower
#### 1. Pull the Watchtower Image:
```bash
docker pull containrrr/watchtower
```
#### 2. Run Watchtower to update all images:
```bash
docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
containrrr/watchtower \
--interval 300 # Check for updates every 5 minutes
```
#### 3. Run Watchtower to update only NetAlertX:
You can specify which containers to monitor by listing them. For example, to monitor netalertx only:
```bash
docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
containrrr/watchtower netalertx
```
## Summary
- Manual: Ideal for individual or critical updates.
- Dockcheck: Suitable for controlled, mass updates.
- Watchtower: Fully automated, best for continuous deployment setups.
These approaches allow you to maintain flexibility in how you update Docker containers, depending on the urgency and scale of the update.