mirror/NetAlertX
1
0 Fork 0
mirror of https://github.com/jokob-sk/NetAlertX.git synced 2026-11-07 07:53:09 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
03911713bbb45d70d58ef93f3cd8cb49139ed719
NetAlertX/server/plugins/pihole_api_scan
T
History
sebingel 0aa4536983 makes PIHOLEAPI report a failed TLS certificate check as such 
With "Verify SSL" working, the login request checks the Pi-hole
certificate when that setting is on. In a live test with the setting on
and Pi-hole behind a reverse proxy with an untrusted certificate, the
login failed with "Connection error during Pi-hole auth. Check
PIHOLEAPI_URL and PIHOLEAPI_PASSWORD", although URL and password were
right. requests.exceptions.SSLError is a subclass of ConnectionError, so
the certificate error fell into that branch.

Changes:
- pihole_api_auth() catches requests.exceptions.SSLError before
  ConnectionError (server/plugins/pihole_api_scan/pihole_api_scan.py) and
  logs: "TLS certificate check failed during Pi-hole auth: <error>. Turn
  off PIHOLEAPI_VERIFY_SSL if Pi-hole uses a self-signed certificate."
- test/plugins/test_pihole_api_scan_verify_ssl.py: _login_failure() runs
  pihole_api_auth() with a failing login request.
  test_certificate_error_points_to_verify_ssl_setting checks the new
  message (fails without this change);
  test_plain_connection_error_still_points_to_url_and_password checks
  that other connection errors keep the old one.

Impact:
A user who turns on "Verify SSL" while Pi-hole uses a self-signed or
otherwise untrusted certificate gets a log line that names the cause and
the setting. Other connection errors are reported as before.
2026-11-01 09:33:41 +00:00
..
config.json
Add website monitoring plugin and update workflows configuration
2026-08-10 02:32:49 +00:00
pihole_api_scan.py
makes PIHOLEAPI report a failed TLS certificate check as such
2026-11-01 09:33:41 +00:00
README.md
fixes PIHOLEAPI's ignored VERIFY_SSL setting and checks setting keys
2026-11-01 09:32:55 +00:00

README.md

Overview - PIHOLEAPI Plugin — Pi-hole v6 Device Import

The PIHOLEAPI plugin lets NetAlertX import network devices directly from a Pi-hole v6 instance. This turns Pi-hole into an additional discovery source, helping NetAlertX stay aware of devices seen by your DNS server.

The plugin connects to your Pi-hole’s API and retrieves:

  • MAC addresses
  • IP addresses
  • Hostnames (if available)
  • Vendor info
  • Last-seen timestamps

NetAlertX then uses this information to match or create devices in your system.

See the Pi-hole guide for a walkthrough covering this plugin alongside the other Pi-hole integrations (PIHOLE, PIHOLEMON, DHCPLSS).

Quick setup guide

  • You are running Pi-hole v6 or newer.
  • The Web UI password in Pi-hole is set.
  • Local network devices appear under Settings → Network in Pi-hole.

No additional Pi-hole configuration is required.

Usage

  • Head to Settings > Plugin name to adjust the default values.
Setting Key Description
PIHOLEAPI_URL Your Pi-hole base URL.
PIHOLEAPI_PASSWORD The Web UI base64 encoded (en-/decoding handled by the app) admin password.
PIHOLEAPI_VERIFY_SSL Whether to verify HTTPS certificates. Disable only for self-signed certificates.
PIHOLEAPI_RUN_TIMEOUT Request timeout in seconds.
PIHOLEAPI_API_MAXCLIENTS Maximum number of devices to request from Pi-hole. Defaults are usually fine.
PIHOLEAPI_FAKE_MAC Generate FAKE MAC from IP.

⚠️ Troubleshooting

Below are the most common issues and how to resolve them.

❌ Authentication failed

Check the following:

  • The Pi-hole URL is correct and includes a trailing slash

    • http://192.168.1.10/ ✔
    • http://192.168.1.10/admin ❌

  • Your Pi-hole password is correct

  • You are using Pi-hole v6, not v5

  • SSL verification matches your setup (disable for self-signed certificates)

❌ Connection error

Usually caused by:

  • Wrong URL
  • Wrong HTTP/HTTPS selection
  • Timeout too low

Try:

PIHOLEAPI_URL = http://<pi-hole-ip>/
PIHOLEAPI_RUN_TIMEOUT = 60

❌ No devices imported

Check:

  • Pi-hole shows devices under Settings → Network
  • NetAlertX logs contain:
[PIHOLEAPI] Pi-hole API returned data

If nothing appears:

  • Pi-hole might be returning empty results
  • Your network interface list may be empty
  • A firewall or reverse proxy is blocking access

Try enabling debug logging:

LOG_LEVEL = debug

Then re-run the plugin.

❌ Some devices are missing

Check:

  • Pi-hole shows devices under Settings → Network
  • NetAlertX logs contain:
[PIHOLEAPI] Skipping invalid MAC (see PIHOLEAPI_FAKE_MAC setting) ...

If devices are missing:

  • The app skipps devices with invalid MACs
  • Enable PIHOLEAPI_FAKE_MAC if you want to import these devices with a fake mac and you are not concerned with data inconsistencies later on

Try enabling PIHOLEAPI_FAKE_MAC:

PIHOLEAPI_FAKE_MAC = 1

Then re-run the plugin.

❌ Wrong or missing hostnames

Pi-hole only reports names it knows from:

  • Local DNS
  • DHCP leases
  • Previously seen queries

If names are missing, confirm they appear in Pi-hole’s own UI first.

Notes

  • Additional notes, limitations, Author info.

  • Version: 1.0.0

  • Author: jokob-sk, leiweibau

  • Release Date: 11-2025

Reference in new issue View Git Blame Copy Permalink