From 58eaa33f39850cfe13965c1985cd47af49779fb3 Mon Sep 17 00:00:00 2001 From: jokob-sk Date: Mon, 6 Jan 2025 09:22:34 +1100 Subject: [PATCH] GraphQL and API docs #933 + create /plugins log folder #921 --- docker-compose.yml | 2 +- dockerfiles/setup.sh | 2 + docs/API.md | 171 +++++++++++++++++++++++++++++++- front/css/dark-patch.css | 4 +- front/css/system-dark-patch.css | 4 +- front/settings.php | 9 +- install/start.debian.sh | 2 + 7 files changed, 185 insertions(+), 9 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index e6ccc9cd..ca180001 100755 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -15,7 +15,7 @@ services: # - ${APP_DATA_LOCATION}/netalertx_dev/db:/app/db - ${APP_DATA_LOCATION}/netalertx/db:/app/db # (optional) useful for debugging if you have issues setting up the container - - ${DEV_LOCATION}/log:/app/log + - ${APP_DATA_LOCATION}/netalertx/log:/app/log # (API: OPTION 1) use for performance - type: tmpfs target: /app/api diff --git a/dockerfiles/setup.sh b/dockerfiles/setup.sh index b572379a..b98f841b 100755 --- a/dockerfiles/setup.sh +++ b/dockerfiles/setup.sh @@ -108,6 +108,8 @@ fi # Create the execution_queue.log and app_front.log files if they don't exist touch "${INSTALL_DIR}"/log/{app.log,execution_queue.log,app_front.log,app.php_errors.log,stderr.log,stdout.log,db_is_locked.log} touch "${INSTALL_DIR}"/api/user_notifications.json +# Create plugins sub-directory if it doesn't exist in case a custom log folder is used +mkdir -p "${INSTALL_DIR}"/log/plugins echo "[INSTALL] Fixing permissions after copied starter config & DB" chown -R nginx:www-data "${INSTALL_DIR}"/{config,log,db,api} diff --git a/docs/API.md b/docs/API.md index 49aa3462..552ebdaa 100755 --- a/docs/API.md +++ b/docs/API.md @@ -1,7 +1,134 @@ -## API endpoints +# API endpoints -NetAlertX comes with a simple API. These API endpoints are static files, that are periodically updated based on your settings. +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: +```graphql +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" + } + } + }' +``` + +## API Endpoint: GraphQL + +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 + +First, let's define the GraphQL query to fetch devices with pagination and sorting options. + +```graphql +query GetDevices($options: PageQueryOptionsInput) { + devices(options: $options) { + devices { + rowid + devMac + devName + devOwner + devType + devVendor + devLastConnection + devStatus + } + count + } +} +``` + +### `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: + +```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 + +These API endpoint are static files, that are periodically updated. + +Endpoint URL: `php/server/query_json.php?file=` +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 @@ -9,7 +136,7 @@ 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 acces sthem via the `/php/server/query_json.php?file=user_notifications.json` endpoint. +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 @@ -95,3 +222,41 @@ Example JSON of the `table_devices.json` endpoint with two Devices (database row ``` +## API Endpoint: /log files + +To retrieve files from the `/app/log` folder. + +Endpoint URL: `php/server/query_logs.php?file=` +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 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 | + + +## API Endpoint: /config files + +To retrieve files from the `/app/config` folder. + +Endpoint URL: `php/server/query_config.php?file=` +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 | + diff --git a/front/css/dark-patch.css b/front/css/dark-patch.css index 9c15bbc3..c522742b 100755 --- a/front/css/dark-patch.css +++ b/front/css/dark-patch.css @@ -17,9 +17,9 @@ html { background-color: #353c42; } -body { +/* body { background-image: url('../img/boxed-bg-dark.png') !important; -} +} */ body, .bg-yellow, .callout.callout-warning, .alert-warning, .label-warning, .modal-warning .modal-body { diff --git a/front/css/system-dark-patch.css b/front/css/system-dark-patch.css index 9d804f79..85c45b84 100755 --- a/front/css/system-dark-patch.css +++ b/front/css/system-dark-patch.css @@ -19,9 +19,9 @@ background-color: #353c42; } - body { + /* body { background-image: url('../img/boxed-bg-dark.png') !important; - } + } */ body, .bg-yellow, .callout.callout-warning, .alert-warning, .label-warning, .modal-warning .modal-body { diff --git a/front/settings.php b/front/settings.php index b5c0b065..6c67f8d7 100755 --- a/front/settings.php +++ b/front/settings.php @@ -225,8 +225,15 @@ $settingsJSON_DB = json_encode($settings, JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX pluginsData = res["data"]; - // Sort settingsData alphabetically based on the "setGroup" property + // Sort settingsData alphabetically, ensuring "General" is always first settingsData.sort((a, b) => { + if (a["setGroup"] === "General") { + return -1; // Place "General" first + } + if (b["setGroup"] === "General") { + return 1; // Place "General" first + } + // For other values, sort alphabetically if (a["setGroup"] < b["setGroup"]) { return -1; } diff --git a/install/start.debian.sh b/install/start.debian.sh index 8aa16e2a..4a88d509 100755 --- a/install/start.debian.sh +++ b/install/start.debian.sh @@ -100,6 +100,8 @@ fi # Create the execution_queue.log file if it doesn't exist touch "${INSTALL_DIR}"/log/{app.log,execution_queue.log,app_front.log,app.php_errors.log,stderr.log,stdout.log,db_is_locked.log} touch "${INSTALL_DIR}"/api/user_notifications.json +# Create plugins sub-directory if it doesn't exist in case a custom log folder is used +mkdir -p "${INSTALL_DIR}"/log/plugins # Fixing file permissions echo "[INSTALL] Fixing file permissions"