vh/NetAlertX
1
0
Fork 0
mirror of https://github.com/jokob-sk/NetAlertX.git synced 2026-04-07 02:31:27 -07:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity
Files
5839853f69f561d172ef2c4bb7de53f813a2e11e
NetAlertX/front/plugins/fritzbox/README.md
sebingel 5839853f69 Add Fritz!Box device scanner plugin via TR-064 protocol 
NetAlertX had no native support for discovering devices connected to
Fritz!Box routers. Users relying on Fritz!Box as their primary home
router had to use generic network scanning (ARP/ICMP), missing
Fritz!Box-specific details like interface type (WiFi/LAN) and
connection status per device.

Changes:
- Add plugin implementation (front/plugins/fritzbox/fritzbox.py)
  Queries all hosts via FritzHosts TR-064 service, normalizes MACs,
  maps interface types (802.11→WiFi, Ethernet→LAN), and writes results
  to CurrentScan via Plugin_Objects. Supports filtering to active-only
  devices and optional guest WiFi monitoring via a synthetic AP device
  with a deterministic locally-administered MAC (02:xx derived from
  Fritz!Box MAC via MD5).

- Add plugin configuration (front/plugins/fritzbox/config.json)
  Defines plugin_type "device_scanner" with settings for host, port,
  credentials, guest WiFi reporting, and active-only filtering.
  Maps scan columns to CurrentScan fields (scanMac, scanLastIP, scanName,
  scanType). Default schedule: every 5 minutes.

- Add plugin documentation (front/plugins/fritzbox/README.md)
  Covers TR-064 protocol basics, quick setup guide, all settings with
  defaults, troubleshooting for common issues (connection refused, auth
  failures, no devices found), and technical details.

- Add fritzconnection>=1.15.1 dependency (requirements.txt)
  Required Python library for TR-064 communication with Fritz!Box.

- Add test suite (test/plugins/test_fritzbox.py:1-298)
  298 lines covering get_connected_devices (active filtering, MAC
  normalization, interface mapping, error resilience), check_guest_wifi_status
  (service detection, SSID-based guest detection, fallback behavior), and
  create_guest_wifi_device (deterministic MAC generation, locally-administered
  bit, fallback MAC, regression anchor with precomputed hash).

Users can now scan Fritz!Box-connected devices natively, seeing per-device
connection status and interface type directly in NetAlertX. Guest WiFi
monitoring provides visibility into guest network state. The plugin
defaults to HTTPS on port 49443 with active-only filtering enabled.
2026-04-06 07:34:14 +00:00

213 lines
9.0 KiB
Markdown
Executable File
Raw Blame History

## Overview
The Fritz!Box plugin queries connected devices from a Fritz!Box router using the **TR-064** protocol (Technical Report 064), a standardized interface for managing DSL routers and home network devices. This plugin discovers all network-connected devices and reports their MAC addresses, IP addresses, hostnames, and connection types to NetAlertX.
TR-064 is a UPnP-based protocol that provides programmatic access to Fritz!Box configuration and status information. Unlike web scraping, it offers a stable, documented API that works across Fritz!Box models.
### Features
- **Device Discovery**: Automatically detects all connected devices (WiFi 2.4GHz, WiFi 5GHz, Ethernet)
- **Real-time Status**: Reports active connection status for each device
- **Guest WiFi Monitoring**: Optional synthetic Access Point device to track guest network status
- **Flexible Filtering**: Choose to report only active devices or include disconnected devices in Fritz!Box memory
- **Secure Connection**: Supports both HTTP and HTTPS with configurable SSL verification
> [!TIP]
> TR-064 is typically enabled by default on Fritz!Box routers. If you encounter connection issues, check that it hasn't been disabled in your Fritz!Box settings under **Home Network > Network > Network Settings > Allow access for applications**.
### Quick Setup Guide
To set up the plugin correctly:
1. **Enable TR-064 on Fritz!Box** (usually already enabled):
- Log in to your Fritz!Box web interface (typically `fritz.box` or `192.168.178.1`)
- Navigate to: **Home Network > Network > Network Settings**
- Ensure **"Allow access for applications"** is checked
- Note: Some models show this as **"Allow remote access"** - enable both HTTP and HTTPS
2. **Configure Plugin in NetAlertX**:
- Head to **Settings** > **Fritz!Box Plugin**
- Set the required settings (see below)
- Choose run mode: **schedule** (recommended, runs every 5 minutes)
#### Required Settings
- **Fritz!Box Host** (`FRITZBOX_HOST`): Hostname or IP address of your Fritz!Box
- Default: `fritz.box`
- Alternative: `192.168.178.1` (or your Fritz!Box's IP)
- **TR-064 Port** (`FRITZBOX_PORT`): Port for TR-064 protocol
- Default: `49443` (HTTPS). Use `49000` if HTTPS is disabled
- **Username** (`FRITZBOX_USER`): Fritz!Box username
- Can be empty for some models when accessing from local network
- For newer models, use an admin username
- **Password** (`FRITZBOX_PASS`): Fritz!Box password
- Required: Your Fritz!Box admin password
#### Optional Settings
- **Use HTTPS** (`FRITZBOX_USE_TLS`): Enable secure HTTPS connection (default: `true`)
- Recommended for security
- Requires port `49443` instead of `49000`
- **Report Guest WiFi** (`FRITZBOX_REPORT_GUEST`): Create Access Point device for guest WiFi (default: `false`)
- When enabled, adds a synthetic "Guest WiFi Network" device to your device list
- Device appears only when guest WiFi is active
- Useful for monitoring guest network status
- **Guest WiFi Service** (`FRITZBOX_GUEST_SERVICE`): Which WLANConfiguration service is the guest network (default: `3`)
- Fritz!Box typically uses `1` for 2.4GHz, `2` for 5GHz, `3` for guest WiFi
- Only relevant when **Report Guest WiFi** is enabled
- Change this if your Fritz!Box uses a non-standard configuration
- **Active Devices Only** (`FRITZBOX_ACTIVE_ONLY`): Report only connected devices (default: `true`)
- When enabled, only currently connected devices appear
- When disabled, includes all devices stored in Fritz!Box memory (even if disconnected)
### Usage
1. Head to **Settings** > **Fritz!Box** to configure the plugin
2. Set **When to run** to **schedule** (recommended) or **once** for manual testing
3. The plugin will run every 5 minutes by default (configurable via **Schedule** setting)
4. View discovered devices in the **Devices** page
5. Check logs at `/tmp/log/plugins/script.FRITZBOX.log` for troubleshooting
### Device Information Reported
The plugin reports the following information for each device:
| Field | Description | Mapped To |
|-------|-------------|-----------|
| **MAC Address** | Device hardware address (normalized format) | `devMac` |
| **IP Address** | Current IPv4 address | `devLastIP` |
| **Hostname** | Device name from Fritz!Box | `devName` |
| **Connection Status** | "Active" or "Inactive" | `devVendor` (shown as vendor field) |
| **Interface Type** | WiFi / LAN / Guest Network | `devType` |
### Guest WiFi Feature
When **Report Guest WiFi** is enabled and guest WiFi is active on your Fritz!Box:
- A synthetic device named **"Guest WiFi Network"** appears in your device list
- Device Type: **Access Point**
- MAC Address: Locally-administered synthetic MAC derived from Fritz!Box MAC (e.g., `02:a1:b2:c3:d4:e5`)
- Status: Only appears when guest WiFi is enabled
This allows you to:
- Monitor when guest WiFi is active
- Set up notifications when guest network is enabled/disabled
- Track guest network status alongside other network devices
> [!NOTE]
> The guest WiFi device is synthetic (not a real physical device). It's created by the plugin to represent the guest network state.
### Troubleshooting
#### Connection Refused / Timeout Errors
**Symptoms**: Plugin logs show "Failed to connect to Fritz!Box" or timeout errors
**Solutions**:
1. Verify Fritz!Box is reachable:
```bash
ping fritz.box
# or
ping 192.168.178.1
```
2. Check TR-064 is enabled:
- Fritz!Box web interface > **Home Network > Network > Network Settings**
- Enable **"Allow access for applications"**
3. Verify correct port:
- HTTP: Port `49000`
- HTTPS: Port `49443`
- Match **Use HTTPS** setting with port
4. Check firewall rules (if NetAlertX runs in Docker):
- Ensure container can reach Fritz!Box network
- Use host IP instead of `fritz.box` if DNS resolution fails
#### Authentication Failed
**Symptoms**: "Authentication error" or "Invalid credentials"
**Solutions**:
1. Verify password is correct
2. Try leaving **Username** empty (some models allow this from local network)
3. Create a dedicated user in Fritz!Box:
- **System > Fritz!Box Users > Add User**
- Grant network access permissions
4. For newer Fritz!OS versions, ensure user has **"Access from home network"** permission
#### No Devices Found
**Symptoms**: Plugin runs successfully but reports 0 devices
**Solutions**:
1. Check **Active Devices Only** setting:
- If enabled, only connected devices appear
- Disable to see all devices in Fritz!Box memory
2. Verify devices are actually connected to Fritz!Box
3. Check Fritz!Box web interface > **Home Network > Mesh** to see devices
4. Increase log level to `verbose` and check `/tmp/log/plugins/script.FRITZBOX.log`
#### Guest WiFi Not Detected
**Symptoms**: Guest WiFi enabled but no Access Point device appears
**Solutions**:
1. Ensure **Report Guest WiFi** is enabled
2. Guest WiFi must be **active** (not just configured)
3. Some Fritz!Box models don't expose guest network via TR-064
4. Check plugin logs for "Guest WiFi active" message
### Limitations
- **Active-only filtering**: When `FRITZBOX_ACTIVE_ONLY` is enabled, the plugin only reports currently connected devices. Disconnected devices stored in Fritz!Box memory are ignored.
- **Guest WiFi synthetic device**: The guest WiFi Access Point is a synthetic device created by the plugin. Its MAC address is derived from the Fritz!Box MAC and doesn't represent a physical device.
- **Model differences**: Some Fritz!Box models may not expose all TR-064 services (e.g., guest WiFi detection). The plugin degrades gracefully if services are unavailable.
- **IPv6 support**: Currently reports IPv4 addresses only. IPv6 support may be added in future versions.
- **Device type detection**: Interface type (WiFi/LAN) is reported, but detailed device categorization (smartphone, laptop, etc.) is handled by NetAlertX's device type detection, not this plugin.
### Technical Details
**Protocol**: TR-064 (Technical Report 064) - UPnP-based device management protocol
**Library**: [fritzconnection](https://github.com/kbr/fritzconnection) >= 1.15.1
**Services Used**:
- `FritzHosts`: Device discovery and information
- `WLANConfiguration`: Guest WiFi status detection
- `DeviceInfo`: Fritz!Box MAC address retrieval
**Execution Schedule**: Default every 5 minutes (configurable via cron syntax)
**Timeout**: 60 seconds (configurable via `RUN_TIMEOUT`)
### Notes
- **Performance**: TR-064 queries typically complete in under 2 seconds, even with many devices
- **Security**: Passwords are stored in NetAlertX's configuration database and not logged
- **Compatibility**: Tested with Fritz!Box models running Fritz!OS 7.x and 8.x
- **Dependencies**: Requires `fritzconnection` Python library (automatically installed via requirements.txt)
### Version
- **Version**: 1.0.0
- **Author**: NetAlertX Community
- **Release Date**: January 2026
- **License**: GPL-3.0
### Support
For issues, questions, or feature requests:
- NetAlertX GitHub: [https://github.com/jokob-sk/NetAlertX](https://github.com/jokob-sk/NetAlertX)
- Fritz!Box TR-064 Documentation: [https://avm.de/service/schnittstellen/](https://avm.de/service/schnittstellen/)
Reference in New Issue View Git Blame Copy Permalink