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

Improve Plugins README 0.1

Browse Source
This commit is contained in:
Jokob-sk
2023-04-02 10:22:22 +10:00
parent a6c2b9254b
commit 5936ba4626
3 changed files with 18 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/API.md
View File

@@ -5,12 +5,7 @@ PiAlert comes with a simple API. These API endpoints are static files, that are
### When are the endpoints updated ### When are the endpoints updated
Once you enable the API (`ENABLE_API` setting), the endpoints are updated during these events: Once you enable the API (`ENABLE_API` setting), the endpoints are updated when objects in the API endpoints are changed:
1) Always during a notification event.
2) (optional) If `API_RUN` is set to `schedule` on a specified cron-like schedule specified by the `API_RUN_SCHD` setting.
3) (optional) If `API_RUN` is set to `interval` every N seconds specified by the `API_RUN_INTERVAL` setting (minimum 5).
### Location of the endpoints ### Location of the endpoints

2
front/php/templates/language/en_us.php
View File

@@ -515,7 +515,7 @@ $lang['en_us'] = array(
'ENABLE_ARPSCAN_description' => 'Arp-scan is a command-line tool that uses the ARP protocol to discover and fingerprint IP hosts on the local network. An alternative to ARP scan is to enable the <a onclick="toggleAllSettings()" href="#PIHOLE_ACTIVE"><code>PIHOLE_ACTIVE</code>PiHole integration settings</a>.', 'ENABLE_ARPSCAN_description' => 'Arp-scan is a command-line tool that uses the ARP protocol to discover and fingerprint IP hosts on the local network. An alternative to ARP scan is to enable the <a onclick="toggleAllSettings()" href="#PIHOLE_ACTIVE"><code>PIHOLE_ACTIVE</code>PiHole integration settings</a>.',
'SCAN_SUBNETS_name' => 'Subnets to scan', 'SCAN_SUBNETS_name' => 'Subnets to scan',
'SCAN_SUBNETS_description' => ' 'SCAN_SUBNETS_description' => '
The arp-scan time itself depends on the number of IP addresses to check so set this up carefully with the appropriate network mask and interface. Check the <a href="https://github.com/jokob-sk/Pi.Alert/blob/main/docs/SUBNETS.md" target="_blank">subnets documentation</a> for details. The arp-scan time itself depends on the number of IP addresses to check so set this up carefully with the appropriate network mask and interface. Check the <a href="https://github.com/jokob-sk/Pi.Alert/blob/main/docs/SUBNETS.md" target="_blank">subnets documentation</a> for help on setting up VLANs, what VLANs are supported, or how to figure out the network mask and your interface.
', ',
'LOG_LEVEL_name' => 'Print additional logging', 'LOG_LEVEL_name' => 'Print additional logging',
'LOG_LEVEL_description' => 'This setting will enable more verbose logging. Useful for debugging events writing into the database.', 'LOG_LEVEL_description' => 'This setting will enable more verbose logging. Useful for debugging events writing into the database.',

32
front/plugins/README.md
View File

@@ -1,17 +1,9 @@
# ⚠ Disclaimer
Highly experimental feature. Follow the below very carefully and check example plugin(s). Plugin UI is not my priority right now, happy to approve PRs if you are interested in extending/improvintg the UI experience (e.g. making the tables sortable/filterable).
## ❗ Known issues:
These issues will be hopefully fixed with time, so please don't report them. Instead, if you know how, feel free to investigate and submit a PR to fix the below. Keep the PRs small as it's easier to approve them:
* Existing plugin objects sometimes not interpreted correctly and a new object is created instead, resulting in duplicate entries.
* Occasional (experienced twice) hanging of processing plugin script file.
* UI displaying outdated values until the API endpoints get refreshed.
## Overview ## Overview
| ![Screen 1][screen1] | ![Screen 2][screen2] |
|----------------------|----------------------|
| ![Screen 3][screen3] | ![Screen 4][screen4] |
PiAlert comes with a plugin system to feed events from third-party scripts into the UI and then send notifications, if desired. The highlighted functionality this plugin system supports, is dynamic creation of a simple UI to interact with the discovered objects, a mechanism to surface settings of plugins in the UI, or to import objects into existing PiAlert database tables. (Currently update/overwriting of existing objects is not supported.) PiAlert comes with a plugin system to feed events from third-party scripts into the UI and then send notifications, if desired. The highlighted functionality this plugin system supports, is dynamic creation of a simple UI to interact with the discovered objects, a mechanism to surface settings of plugins in the UI, or to import objects into existing PiAlert database tables. (Currently update/overwriting of existing objects is not supported.)
Example use cases for plugins could be: Example use cases for plugins could be:
@@ -27,6 +19,18 @@ If you wish to develop a plugin, please check the existing plugin structure. Onc
Again, please read the below carefully if you'd like to contribute with a plugin yourself. This documentation file might be outdated, so double check the sample plugins as well. Again, please read the below carefully if you'd like to contribute with a plugin yourself. This documentation file might be outdated, so double check the sample plugins as well.
## ⚠ Disclaimer
Highly experimental feature. Follow the below very carefully and check example plugin(s). Plugin UI is not my priority right now, happy to approve PRs if you are interested in extending/improvintg the UI experience (e.g. making the tables sortable/filterable).
## ❗ Known issues:
These issues will be hopefully fixed with time, so please don't report them. Instead, if you know how, feel free to investigate and submit a PR to fix the below. Keep the PRs small as it's easier to approve them:
* Existing plugin objects sometimes not interpreted correctly and a new object is created instead, resulting in duplicate entries.
* Occasional (experienced twice) hanging of processing plugin script file.
* UI displaying outdated values until the API endpoints get refreshed.
## Plugin file structure overview ## Plugin file structure overview
> Folder name must be the same as the code name value in: `"code_name": "<value>"` > Folder name must be the same as the code name value in: `"code_name": "<value>"`
@@ -436,11 +440,7 @@ The UI will adjust how columns are displayed in the UI based on the definition o
### SQL query based plugins ### SQL query based plugins
- [nmap_services (NMAPSERV) config.json](https://github.com/jokob-sk/Pi.Alert/blob/main/front/plugins/nmap_services/config.json) - [nmap_services (NMAPSERV) config.json](https://github.com/jokob-sk/Pi.Alert/blob/main/front/plugins/nmap_services/config.json)
### Screenshots
| ![Screen 1][screen1] | ![Screen 2][screen2] |
|----------------------|----------------------|
| ![Screen 3][screen3] | ![Screen 4][screen4] |
[screen1]: https://raw.githubusercontent.com/jokob-sk/Pi.Alert/main/docs/img/plugins.png "Screen 1" [screen1]: https://raw.githubusercontent.com/jokob-sk/Pi.Alert/main/docs/img/plugins.png "Screen 1"
[screen2]: https://raw.githubusercontent.com/jokob-sk/Pi.Alert/main/docs/img/plugins_settings.png "Screen 2" [screen2]: https://raw.githubusercontent.com/jokob-sk/Pi.Alert/main/docs/img/plugins_settings.png "Screen 2"