mirror of
https://github.com/jokob-sk/NetAlertX.git
synced 2026-10-11 17:54:02 -04:00
Mauricio Camayo
e543f14d08
References PR #1765. Docs: - Added PIHOLEMON to docs/PLUGINS.md and a new "Approach 4" section in docs/PIHOLE_GUIDE.md, leading with anomaly detection (the actual differentiator vs PIHOLEAPI) and explaining when to pick each plugin. - README/PLUGINS.md/config.json's UI-facing description all reordered and shortened to lead with anomaly detection instead of device import, and to drop implementation detail that belongs in the README, not the Settings page. - Trimmed the "Why not extend PIHOLEAPI" README section per feedback - useful context for a maintainer, not for an end user configuring the plugin. config.json / pihole_monitor.py: - RUN defaults to "disabled", matching every other non-core plugin. - VERIFY_SSL split into PRIMARY_VERIFY_SSL / SECONDARY_VERIFY_SSL - each instance can be http/https independently. Settings reordered so each *_VERIFY_SSL sits right under its matching *_PASSWORD. - GRAPHQL_TOKEN removed; graphql_token now reads the core API_TOKEN setting instead of a plugin-specific duplicate. - GRAPHQL_URL replaced with a GET_OWNER boolean - the endpoint is now derived from this app's own GRAPHQL_PORT (single source of truth) instead of a URL the user had to keep in sync by hand. - HISTORY_LENGTH (run count) replaced with HISTORY_DAYS (a real time window): state now stores [timestamp, delta] samples and trim_history() drops anything older than the window, so the baseline means the same thing regardless of schedule - a faster schedule adds more data points instead of shrinking the window. - STATE_FILE moved from the log folder to dbFolderPath, so the rolling anomaly baseline survives NetAlertX upgrades instead of being wiped with the logs. - netalertx_device_owner() (1 GraphQL call per device) replaced by netalertx_device_owners() (1 call per run, batched) - avoids N blocking round-trips on a large network. - Fixed a zero-baseline bug: `bool(... and baseline and ...)` silently exempted a device with an all-zero blocked-query history (0.0 is falsy in Python) from ever being flagged, even on its first real spike. Now checks `baseline is not None`. - Fixed the placeholder-MAC filter: only excluded the literal "ip-::", not Pi-hole's general "ip-<address>" placeholder pattern. Caught downstream by is_mac() either way, but now the actual placeholder check does what it looks like it does. - Fixed a cumulative-counter bug: Pi-hole's /api/stats/top_clients returns a count that's cumulative since FTL last started, not a per-interval or daily-resetting one (confirmed against FTL's own source and long-standing user reports that it doesn't reset at midnight). Comparing that raw total directly against a rolling average made any device's ordinary growing traffic look like an escalating anomaly. compute_delta() now diffs each run's raw count against the previous run's (state gained a per-key last_raw reference point alongside the delta history) - None (not 0) on the first-ever run for a device or right after a counter reset, so those runs re-anchor the reference point instead of fabricating or swallowing a delta. - RUN_SCHD default changed from every 6 hours to every 5 minutes now that the baseline window is real days, not run count, so a frequent schedule only adds data points instead of narrowing the window; also matches the default most other device-scanner plugins use. - RUN_SCHD gained the same live cron-validity checkmark ARPSCAN and other scanner plugins use (a ✓/✗ icon next to the field, validated client-side against a regex) - reuses the existing generic validateRegex() widget, nothing plugin-specific to build. Tests: 48 tests (up from 37), 99% line+branch coverage. Every fix above verified via mutation testing (deliberately broken, confirmed the relevant test fails, then restored).
NetAlertX modules
The original pilaert.py code is now moved to this new folder and split into different modules.
| Module | Description |
|---|---|
__main__.py |
The MAIN program of NetAlertX |
__init__.py |
an empty init file |
README.md |
this readme file |
../server/plugins |
a folder containing all plugins that publish notifications or scan for devices |
api.py |
updating the API endpoints with the relevant data. |
appevent.py |
TBC |
const.py |
A place to define the constants for NetAlertX like log path or config path. |
conf.py |
conf.py holds the configuration variables and makes them available for all modules. It is also the workaround for global variables that need to be resolved at some point |
database.py |
This module connects to the DB, makes sure the DB is up to date and defines some standard queries and interfaces. |
device.py |
The device module looks after the devices and saves the scan results into the devices |
flows.py |
TBC |
helper.py |
Helper as the name suggest contains multiple little functions and methods used in many of the other modules and helps keep things clean |
initialise.py |
Initiatlise sets up the environment and makes everything ready to go |
logger.py |
Logger is there the keep all the logs organised and looking identical. |
networscan.py |
Networkscan collects the scan results (maybe to merge with reporting.py) |
notification.py |
Creates and handles the notification object and generates ther HTML and text variants of the message |
plugin.py |
This is where the plugins get integrated into the backend of NetAlertX |
plugin_utils.py |
Helper utilities for plugin.py |
reporting.py |
Reporting collects the data for the notification reports |
scheduler.py |
All things scheduling |