mirror of
https://github.com/jokob-sk/NetAlertX.git
synced 2026-11-08 00:13:25 -05:00
sebingel
71efcd0ba0
main() read the setting 'PIHOLEAPI_SSL_VERIFY', but config.json defines
the function VERIFY_SSL, so the real key is PIHOLEAPI_VERIFY_SSL.
get_setting_value() returns "" for a key nobody defined, so every Pi-hole
API request got verify="": certificate checks were always off and the
InsecureRequestWarning was suppressed, even when a user had turned on
"Verify SSL". The login request sends the Pi-hole web password to
api/auth. The plugin README and docs/PIHOLE_GUIDE.md used the wrong name
too. test_plugin_conventions.py did not catch it: it only looks at
get_setting_value("X") or <literal>, and this line had no fallback.
Changes:
- test/plugins/test_plugin_conventions.py: new
test_own_setting_keys_exist_in_config. Every literal
get_setting_value('<PREFIX>_X') in a plugin's scripts must name a
setting its own config.json defines; core settings and other plugins'
keys are not checked. Before the fix it fails for exactly one of the 54
plugins: pihole_api_scan.py, get_setting_value('PIHOLEAPI_SSL_VERIFY').
- New test/plugins/test_pihole_api_scan_verify_ssl.py: runs main() with
VERIFY_SSL true and false and checks the verify= value that reaches
requests.post() for api/auth. Only the HTTP call is mocked. It fails
before the fix (verify=None).
- server/plugins/pihole_api_scan/pihole_api_scan.py: main() reads
PIHOLEAPI_VERIFY_SSL.
- server/plugins/pihole_api_scan/README.md and docs/PIHOLE_GUIDE.md name
the setting PIHOLEAPI_VERIFY_SSL.
- docs/PLUGINS_DEV.md, Conventions Checklist: read a setting under the
exact key config.json defines; names the new check.
Impact:
"Verify SSL" now works. The default stays false, so default installs
behave as before. A user who turned it on while Pi-hole uses a
self-signed certificate will now see the login fail, as the setting
description says ("Disable if you are using a self-signed certificate").
Live check against Pi-hole v6.8 behind a proxy with an untrusted
certificate: with "Verify SSL" on the fixed code refused to log in, the
old code logged in and imported 33 entries.
97 lines
7.8 KiB
Markdown
Executable File
97 lines
7.8 KiB
Markdown
Executable File
# Integration with Pi-hole
|
|
|
|
NetAlertX includes four plugins for integrating with an existing Pi-hole installation. The first plugin imports devices through the Pi-hole v6 API, the second parses the `dhcp.leases` file generated by Pi-hole, the third reads the Pi-hole SQLite database directly, and the fourth flags devices with a blocked-query spike (a common malware/compromised-device signature) and, alongside that, imports devices from one or two Pi-hole v6 instances at once. You can use any of these approaches individually or combine them with each other and other [plugins](/PLUGINS_OVERVIEW).
|
|
|
|
## Approach 1: `PIHOLEAPI` Plugin - Import devices directly from the Pi-hole v6 API
|
|
|
|
To use this approach, make sure a Web UI password is configured in **Pi-hole**.
|
|
|
|
### Settings
|
|
|
|
|
|
|
|
| Setting | Description | Recommended value |
|
|
| :------------------------- | :----------------------------------------------------------------------------------------------- | :-------------------------- |
|
|
| `PIHOLEAPI_URL` | Your Pi-hole base URL, including the port. | `http://192.168.1.82:9880/` |
|
|
| `PIHOLEAPI_RUN_SCHD` | If you run multiple device scanner plugins, configure them to use the same schedule. | `*/5 * * * *` |
|
|
| `PIHOLEAPI_PASSWORD` | The Pi-hole Web UI admin password. NetAlertX automatically handles Base64 encoding and decoding. | `passw0rd` |
|
|
| `PIHOLEAPI_VERIFY_SSL` | Whether to verify HTTPS certificates. Disable only when using self-signed certificates. | `False` |
|
|
| `PIHOLEAPI_API_MAXCLIENTS` | Maximum number of devices to request from Pi-hole. The default value is usually sufficient. | `500` |
|
|
| `PIHOLEAPI_FAKE_MAC` | Generate a deterministic fake MAC address from the IP address. | `False` |
|
|
|
|
Check the [PIHOLEAPI plugin README](https://docs.netalertx.com/plugins/pihole_api_scan) for additional details and troubleshooting.
|
|
|
|
### docker-compose changes
|
|
|
|
No changes are required.
|
|
|
|
---
|
|
|
|
## Approach 2: `DHCPLSS` Plugin - Import devices from the Pi-hole DHCP leases file
|
|
|
|
This approach requires mounting the Pi-hole DHCP leases file (`dhcp.leases`) into the NetAlertX container. This is straightforward when both applications run on the same host. If they run on different hosts, you'll need to synchronize the file or use the `PIHOLEAPI` plugin instead.
|
|
|
|
### Settings
|
|
|
|
|
|
|
|
| Setting | Description | Recommended value |
|
|
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------- |
|
|
| `DHCPLSS_RUN` | When the plugin should run. | `schedule` |
|
|
| `DHCPLSS_RUN_SCHD` | If you run multiple device scanner plugins, configure them to use the same schedule. | `*/5 * * * *` |
|
|
| `DHCPLSS_paths_to_check` | Path to the mapped `dhcp.leases` file inside the container. The path must include `pihole` so the plugin can identify it as a Pi-hole leases file. | `['/etc/pihole/dhcp.leases']` |
|
|
|
|
Check the [DHCPLSS plugin README](https://docs.netalertx.com/plugins/dhcp_leases#overview) for additional details.
|
|
|
|
### docker-compose changes
|
|
|
|
| Path | Description |
|
|
| :------------------------- | :--------------------------------------------------------------------------------------------- |
|
|
| `:/etc/pihole/dhcp.leases` | Mount Pi-hole's `dhcp.leases` file. This path must match an entry in `DHCPLSS_paths_to_check`. |
|
|
|
|
---
|
|
|
|
## Approach 3: `PIHOLE` Plugin - Import devices directly from the Pi-hole database
|
|
|
|
This approach requires mounting the Pi-hole database file into the NetAlertX container. This is straightforward when both applications run on the same host. If Pi-hole is running on a different host, you'll need to synchronize the database file into the NetAlertX container. In that scenario, the `PIHOLEAPI` or `DHCPLSS` plugins are usually simpler.
|
|
|
|
### Settings
|
|
|
|
|
|
|
|
| Setting | Description | Recommended value |
|
|
| :---------------- | :----------------------------------------------------------------------------------- | :-------------------------- |
|
|
| `PIHOLE_RUN` | When the plugin should run. | `schedule` |
|
|
| `PIHOLE_RUN_SCHD` | If you run multiple device scanner plugins, configure them to use the same schedule. | `*/5 * * * *` |
|
|
| `PIHOLE_DB_PATH` | Path to the mapped Pi-hole database file inside the container. | `/etc/pihole/pihole-FTL.db` |
|
|
|
|
Check the [PIHOLE plugin README](https://docs.netalertx.com/plugins/pihole_scan) for additional details.
|
|
|
|
### docker-compose changes
|
|
|
|
| Path | Description |
|
|
| :--------------------------- | :--------------------------------------------- |
|
|
| `:/etc/pihole/pihole-FTL.db` | Mount Pi-hole's `pihole-FTL.db` database file. |
|
|
|
|
---
|
|
|
|
## Approach 4: `PIHOLEMON` Plugin - Blocked-query anomaly detection (plus device import from one or two Pi-hole v6 instances)
|
|
|
|
This plugin's main job is different from the other three above: it watches each device's own blocked-query count and flags it when that count spikes well above its recent average - a common signature of malware or a compromised device beaconing out to blocklisted domains, not just device discovery. Bundled into the same connection is a second job, the same idea as `PIHOLEAPI`'s device import, extended to a primary **and** an optional secondary/failover Pi-hole instance under one set of settings.
|
|
|
|
**How it differs from `PIHOLEAPI`:**
|
|
|
|
* **Anomaly detection is the point, not a bonus.** `PIHOLEAPI` only imports devices. This plugin's reason to exist is watching a device you *already* know for a sudden change in its own behavior - device import is the second, supporting job, not the main one.
|
|
* **Two Pi-hole instances, not one.** A primary and an optional secondary/failover are both checked and their results combined under one set of settings - useful if you run more than one Pi-hole (e.g. two resolvers for redundancy) and want a single device list and a single anomaly baseline across both, instead of a blind spot on whichever instance isn't being watched.
|
|
* **Choose `PIHOLEAPI`** if you only run one Pi-hole and just want device import - it's the simpler, more focused option. **Choose `PIHOLEMON`** if you want the anomaly detection, or run two Pi-holes needing one configuration, or both.
|
|
|
|
Check the [PIHOLEMON plugin README](https://docs.netalertx.com/plugins/pihole_monitor) for the full settings reference, the `http://` vs `https://` trade-off, and troubleshooting.
|
|
|
|
### docker-compose changes
|
|
|
|
No changes are required - this plugin only talks to Pi-hole's API, the same as `PIHOLEAPI`.
|
|
|
|
---
|
|
|
|
Explore other [plugins](./PLUGINS_OVERVIEW.md) to discover additional information about your network, or learn how to scan [remote networks](./REMOTE_NETWORKS.md).
|