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

docs
Some checks failed
Code checks / check-url-paths (push) Has been cancelled
Details
docker / docker_dev (push) Has been cancelled
Details
Deploy MkDocs / deploy (push) Has been cancelled
Details

Browse Source
This commit is contained in:
jokob-sk
2025-08-24 12:57:36 +10:00
parent 3ad7b59c84
commit df9a17ed85
13 changed files with 1703 additions and 324 deletions
Download Patch File Download Diff File Expand all files Collapse all files

353
docs/API.md
View File

@@ -1,6 +1,6 @@
# API endpoints
# NetAlertX API Documentation
NetAlertX comes with a couple of API endpoints. All requests need to be authorized (executed in a logged in browser session) or you have to pass the value of the `API_TOKEN` settings as authorization bearer, for example:
This API provides programmatic access to **devices, events, sessions, metrics, network tools, and sync** in NetAlertX. It is implemented as a **REST and GraphQL server**. All requests require authentication via **API Token** (`API_TOKEN` setting) unless explicitly noted.
```graphql
curl 'http://host:GRAPHQL_PORT/graphql' \
@@ -21,347 +21,56 @@ curl 'http://host:GRAPHQL_PORT/graphql' \
}'
```
## API Endpoint: GraphQL
It runs on `0.0.0.0:<graphql_port>` with **CORS enabled** for all main endpoints.
- Endpoint URL: `php/server/query_graphql.php`
- Host: `same as front end (web ui)`
- Port: `20212` or as defined by the `GRAPHQL_PORT` setting
---
### Example Query to Fetch Devices
## Authentication
First, let's define the GraphQL query to fetch devices with pagination and sorting options.
All endpoints require an API token provided in the HTTP headers:
```graphql
query GetDevices($options: PageQueryOptionsInput) {
devices(options: $options) {
devices {
rowid
devMac
devName
devOwner
devType
devVendor
devLastConnection
devStatus
}
count
}
}
```http
Authorization: Bearer <API_TOKEN>
```
See also: [Debugging GraphQL issues](./DEBUG_GRAPHQL.md)
### `curl` Command
You can use the following `curl` command to execute the query.
```sh
curl 'http://host:GRAPHQL_PORT/graphql' -X POST -H 'Authorization: Bearer API_TOKEN' -H 'Content-Type: application/json' --data '{
"query": "query GetDevices($options: PageQueryOptionsInput) { devices(options: $options) { devices { rowid devMac devName devOwner devType devVendor devLastConnection devStatus } count } }",
"variables": {
"options": {
"page": 1,
"limit": 10,
"sort": [{ "field": "devName", "order": "asc" }],
"search": "",
"status": "connected"
}
}
}'
```
### Explanation:
1. **GraphQL Query**:
- The `query` parameter contains the GraphQL query as a string.
- The `variables` parameter contains the input variables for the query.
2. **Query Variables**:
- `page`: Specifies the page number of results to fetch.
- `limit`: Specifies the number of results per page.
- `sort`: Specifies the sorting options, with `field` being the field to sort by and `order` being the sort order (`asc` for ascending or `desc` for descending).
- `search`: A search term to filter the devices.
- `status`: The status filter to apply (valid values are `my_devices` (determined by the `UI_MY_DEVICES` setting), `connected`, `favorites`, `new`, `down`, `archived`, `offline`).
3. **`curl` Command**:
- The `-X POST` option specifies that we are making a POST request.
- The `-H "Content-Type: application/json"` option sets the content type of the request to JSON.
- The `-d` option provides the request payload, which includes the GraphQL query and variables.
### Sample Response
The response will be in JSON format, similar to the following:
If the token is missing or invalid, the server will return:
```json
{
"data": {
"devices": {
"devices": [
{
"rowid": 1,
"devMac": "00:11:22:33:44:55",
"devName": "Device 1",
"devOwner": "Owner 1",
"devType": "Type 1",
"devVendor": "Vendor 1",
"devLastConnection": "2025-01-01T00:00:00Z",
"devStatus": "connected"
},
{
"rowid": 2,
"devMac": "66:77:88:99:AA:BB",
"devName": "Device 2",
"devOwner": "Owner 2",
"devType": "Type 2",
"devVendor": "Vendor 2",
"devLastConnection": "2025-01-02T00:00:00Z",
"devStatus": "connected"
}
],
"count": 2
}
}
}
```
## API Endpoint: JSON files
This API endpoint retrieves static files, that are periodically updated.
- Endpoint URL: `php/server/query_json.php?file=<file name>`
- Host: `same as front end (web ui)`
- Port: `20211` or as defined by the $PORT docker environment variable (same as the port for the web ui)
### When are the endpoints updated
The endpoints are updated when objects in the API endpoints are changed.
### Location of the endpoints
In the container, these files are located under the `/app/api/` folder. You can access them via the `/php/server/query_json.php?file=user_notifications.json` endpoint.
### Available endpoints
You can access the following files:
| File name | Description |
|----------------------|----------------------|
| `notification_json_final.json` | The json version of the last notification (e.g. used for webhooks - [sample JSON](https://github.com/jokob-sk/NetAlertX/blob/main/front/report_templates/webhook_json_sample.json)). |
| `table_devices.json` | All of the available Devices detected by the app. |
| `table_plugins_events.json` | The list of the unprocessed (pending) notification events (plugins_events DB table). |
| `table_plugins_history.json` | The list of notification events history. |
| `table_plugins_objects.json` | The content of the plugins_objects table. Find more info on the [Plugin system here](https://github.com/jokob-sk/NetAlertX/tree/main/docs/PLUGINS.md)|
| `language_strings.json` | The content of the language_strings table, which in turn is loaded from the plugins `config.json` definitions. |
| `table_custom_endpoint.json` | A custom endpoint generated by the SQL query specified by the `API_CUSTOM_SQL` setting. |
| `table_settings.json` | The content of the settings table. |
| `app_state.json` | Contains the current application state. |
### JSON Data format
The endpoints starting with the `table_` prefix contain most, if not all, data contained in the corresponding database table. The common format for those is:
```JSON
{
"data": [
{
"db_column_name": "data",
"db_column_name2": "data2"
},
{
"db_column_name": "data3",
"db_column_name2": "data4"
}
]
}
```
Example JSON of the `table_devices.json` endpoint with two Devices (database rows):
```JSON
{
"data": [
{
"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"
},
{
"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"
}
]
}
```
## API Endpoint: Prometheus Exporter
* **Endpoint URL**: `/metrics`
* **Host**: (where NetAlertX exporter is running)
* **Port**: as configured in the `GRAPHQL_PORT` setting (`20212` by default)
---
### Example Output of the `/metrics` Endpoint
Below is a representative snippet of the metrics you may find when querying the `/metrics` endpoint for `netalertx`. It includes both aggregate counters and `device_status` labels per device.
```
netalertx_connected_devices 31
netalertx_offline_devices 54
netalertx_down_devices 0
netalertx_new_devices 0
netalertx_archived_devices 31
netalertx_favorite_devices 2
netalertx_my_devices 54
netalertx_device_status{device="Net - Huawei", mac="Internet", ip="1111.111.111.111", vendor="None", first_connection="2021-01-01 00:00:00", last_connection="2025-08-04 17:57:00", dev_type="Router", device_status="Online"} 1
netalertx_device_status{device="Net - USG", mac="74:ac:74:ac:74:ac", ip="192.168.1.1", vendor="Ubiquiti Networks Inc.", first_connection="2022-02-12 22:05:00", last_connection="2025-06-07 08:16:49", dev_type="Firewall", device_status="Archived"} 1
netalertx_device_status{device="Raspberry Pi 4 LAN", mac="74:ac:74:ac:74:74", ip="192.168.1.9", vendor="Raspberry Pi Trading Ltd", first_connection="2022-02-12 22:05:00", last_connection="2025-08-04 17:57:00", dev_type="Singleboard Computer (SBC)", device_status="Online"} 1
...
{ "error": "Forbidden" }
```
---
### Metrics Explanation
## Base URL
#### 1. Aggregate Device Counts
Metric names prefixed with `netalertx_` provide aggregated counts by device status:
* `netalertx_connected_devices`: number of devices currently connected
* `netalertx_offline_devices`: devices currently offline
* `netalertx_down_devices`: down/unreachable devices
* `netalertx_new_devices`: devices recently detected
* `netalertx_archived_devices`: archived devices
* `netalertx_favorite_devices`: user-marked favorite devices
* `netalertx_my_devices`: devices associated with the current user context
These numeric values give a high-level overview of device distribution.
#### 2. Per‑Device Status with Labels
Each individual device is represented by a `netalertx_device_status` metric, with descriptive labels:
* `device`: friendly name of the device
* `mac`: MAC address (or placeholder)
* `ip`: last recorded IP address
* `vendor`: manufacturer or "None" if unknown
* `first_connection`: timestamp when the device was first observed
* `last_connection`: most recent contact timestamp
* `dev_type`: device category or type
* `device_status`: current status (Online / Offline / Archived / Down / ...)
The metric value is always `1` (indicating presence or active state) and the combination of labels identifies the device.
```
http://<server>:<GRAPHQL_PORT>/
```
---
### How to Query with `curl`
## Endpoints
To fetch the metrics from the NetAlertX exporter:
* [Device API Endpoints](API_DEVICE.md) – Manage individual devices
* [Devices Collection](API_DEVICES.md) – Bulk operations on multiple devices
* [Events](API_EVENTS.md) – Device event logging and management
* [Sessions](API_SESSIONS.md) – Connection sessions and history
* [Metrics](API_METRICS.md) – Prometheus metrics and per-device status
* [Network Tools](API_NETTOOLS.md) – Utilities like Wake-on-LAN, traceroute, nslookup, nmap, and internet info
* [Online History](API_ONLINEHISTORY.md) – Online/offline device records
* [GraphQL](API_GRAPHQL.md) – Advanced queries and filtering
* [Sync](API_SYNC.md) – Synchronization between multiple NetAlertX instances
```sh
curl 'http://<server_ip>:<GRAPHQL_PORT>/metrics' \
-H 'Authorization: Bearer <API_TOKEN>' \
-H 'Accept: text/plain'
```
Replace:
* `<server_ip>`: IP or hostname of the NetAlertX server
* `<GRAPHQL_PORT>`: port specified in your `GRAPHQL_PORT` setting (default: `20212`)
* `<API_TOKEN>` your Bearer token from the `API_TOKEN` setting
See [Testing](API_TESTS.md) for example requests and usage.
---
### Summary
## Notes
* **Endpoint**: `/metrics` provides both summary counters and per-device status entries.
* **Aggregate metrics** help monitor overall device states.
* **Detailed metrics** expose each device’s metadata via labels.
* **Use case**: feed into Prometheus for scraping, monitoring, alerting, or charting dashboard views.
### Prometheus Scraping Configuration
```yaml
scrape_configs:
- job_name: 'netalertx'
metrics_path: /metrics
scheme: http
scrape_interval: 60s
static_configs:
- targets: ['<server_ip>:<GRAPHQL_PORT>']
authorization:
type: Bearer
credentials: <API_TOKEN>
```
### Grafana template
Grafana template sample: [Download json](./samples/API/Grafana_Dashboard.json)
## API Endpoint: /log files
This API endpoint retrieves files from the `/app/log` folder.
- Endpoint URL: `php/server/query_logs.php?file=<file name>`
- Host: `same as front end (web ui)`
- Port: `20211` or as defined by the $PORT docker environment variable (same as the port for the web ui)
| File | Description |
|--------------------------|---------------------------------------------------------------|
| `IP_changes.log` | Logs of IP address changes |
| `app.log` | Main application log |
| `app.php_errors.log` | PHP error log |
| `app_front.log` | Frontend application log |
| `app_nmap.log` | Logs of Nmap scan results |
| `db_is_locked.log` | Logs when the database is locked |
| `execution_queue.log` | Logs of execution queue activities |
| `plugins/` | Directory for temporary plugin-related files (not accessible) |
| `report_output.html` | HTML report output |
| `report_output.json` | JSON format report output |
| `report_output.txt` | Text format report output |
| `stderr.log` | Logs of standard error output |
| `stdout.log` | Logs of standard output |
* All endpoints enforce **Bearer token authentication**.
* Errors return JSON with `success: False` and an error message.
* GraphQL is available for advanced queries, while REST endpoints cover structured use cases.
* Endpoints run on `0.0.0.0:<GRAPHQL_PORT>` with **CORS enabled**.
* Use consistent API tokens and node/plugin names when interacting with `/sync` to ensure data integrity.
## API Endpoint: /config files
To retrieve files from the `/app/config` folder.
- Endpoint URL: `php/server/query_config.php?file=<file name>`
- Host: `same as front end (web ui)`
- Port: `20211` or as defined by the $PORT docker environment variable (same as the port for the web ui)
| File | Description |
|--------------------------|--------------------------------------------------|
| `devices.csv` | Devices csv file |
| `app.conf` | Application config file |