fbsyslogsender

Dieses Projekt ermöglicht ein lückenloses Monitoring von FRITZ!Box-Systemen (DSL, VPN, WLAN, Login) via Syslog, optimiert für Graylog und Elastic.

FRITZ!Box Enterprise Monitor (Lua-Based)

Dieses Projekt ermöglicht ein lückenloses Monitoring von FRITZ!Box-Systemen (DSL, VPN, WLAN, Login) via Syslog, optimiert für Graylog und Elastic.

🛠 Features

• Lua-API statt TR-064: Umgeht das 5-Zeilen-Limit der Standard-API.
• VPN-Decoder: Übersetzt Fehler-Codes (z.B. 0x203e) in Klartext.
• Hash-Persistenz: Erkennt bereits gesendete Logs auch nach Neustart.
• JSON-Support: Strukturiertes Logging für einfache Graylog-Dashboards.
• Auto-Sync: Pusht beim ersten Start die Historie der FRITZ!Box chronologisch nach.

🚀 Deployment (Interaktiv)

Um einen neuen Standort (Satellit) aufzusetzen:

1. Skript und Dateien auf den Host kopieren.
2. Deployment starten: ./deploy-fb-monitor.sh deploy

📁 Archivierung & Backup

Sicherung des aktuellen Standorts inkl. aller Hashes: ./deploy-fb-monitor.sh backup 1.0.0 'standort-name'

⚙️ .env Parameter (Auszug)

• HASH_PERSISTENT=True: Speichert Hashes in /data/hashes.db.txt.
• HASH_BACKUP_EVERY=20: Sichert alle 20 neuen Zeilen gegen Absturz.
• SYSLOG_JSON_ONLY=True: Sendet reine JSON-Objekte an den Server.
• SEND_INITIAL_LOG=True: Erzwingt beim ersten Start einen Full-Push.

📊 Syslog Level Mapping

• Level 2 (Critical): VPN-Handshake Fehler (IKE/IPsec).
• Level 3 (Error): DynDNS-Fehler, DSL-Abbrüche, Login-Fehler.
• Level 4 (Warning): Häufungsmeldungen [X Meldungen seit...].
• Level 6 (Info): Reguläre Statusmeldungen & erfolgreiche Logins.

Übersicht

Dieses System überwacht eine FRITZ!Box (getestet mit FRITZ!OS 7.52+) auf System-Ereignisse und VPN-Statusänderungen. Da die Standard-Schnittstelle (TR-064) von AVM oft auf 5 Log-Einträge limitiert ist, nutzt dieses Skript die Lua-Sch>

Funktionsweise

Authentifizierung: Das Skript meldet sich via Challenge-Response-Verfahren an der FRITZ!Box an und erhält eine Session-ID (SID).
Log-Streaming: Das System-Log wird regelmäßig ausgelesen. Neue Einträge werden identifiziert (SHA1-Hash-Vergleich) und chronologisch an einen zentralen Syslog-Server weitergeleitet.
VPN-Monitoring: Der Status aller VPN-Verbindungen (IPSec Site-to-Site & WireGuard) wird überwacht. Änderungen (UP/DOWN) generieren sofort eine Syslog-Meldung mit entsprechendem Severity-Level (INFO/CRITICAL).
Deduplizierung: Um Log-Fluten zu vermeiden, werden bereits gesendete Zeilen im Speicher zwischengespeichert.

Voraussetzungen

FRITZ!Box-Benutzer: Ein dedizierter Benutzer mit Berechtigung für "FRITZ!Box Einstellungen" (notwendig für den Zugriff auf VPN-Daten).
Zentraler Syslog-Server: (z. B. Graylog, rsyslog oder Logstash), der UDP-Pakete auf Port 514 empfängt.

Installation & Deployment

1. Umgebungsvariablen (.env)

Erstelle eine .env Datei mit folgendem Inhalt: env

FRITZ_IP=192.168.178.1 FRITZ_USER=syslog_user FRITZ_PWD=dein_starkes_passwort

SYSLOG_SERVER=192.168.x.x SYSLOG_PORT=514 SYSLOG_SENDER_NAME=fritzbox_standort_a

CHECK_INTERVAL=60 SEND_INITIAL_LOG=True DEBUG_MODE=False

2. Docker Compose

Starten des Containers mit: bash

docker compose up -d --build

Troubleshooting ("Notfall-Guide")

Falls keine Logs mehr im Syslog-Server ankommen:

Container-Logs prüfen: docker logs -f fritz-syslog-forwarder.
SID-Fehler: Erscheint ein "Login-Fehler", prüfen ob das Passwort abgelaufen ist oder ob die FRITZ!Box eine 2FA-Bestätigung (Taste drücken) für den API-Zugriff verlangt.
Netzwerk: Testen, ob der Container den Syslog-Server pingen kann.
FRITZ!OS Update: Nach einem Firmware-Update könnte AVM die data.lua Pfade ändern. In diesem Fall muss die fetch_data Funktion im Skript geprüft werden.

Technische Details

Sprache: Python 3.11-slim
Bibliotheken: requests, python-dotenv
Authentifizierung: login_sid.lua (MD5-basiert)
Datenquelle: data.lua?page=log und data.lua?page=vpn

3. Hinweis zur Häufungserkennung

Die FRITZ!Box fasst identische Meldungen zusammen (z.B. Login-Versuche), um das Log nicht zu fluten. Durch das elif oben wird eine Zeile wie: Anmeldung des Benutzers syslog... [145 Meldungen seit 04.02.26 02:00:39] automatisch als Warning markiert. Das ist ideal für Graylog-Alerts, da du so sofort siehst, wenn ein Dienst (oder ein Angreifer) "Amok läuft". Zusammenfassung der Änderungen für deine Meta-Doku:

VPN-Fehlercodes: Werden nun mit Severity 2 (Critical) gewichtet.
Häufungserkennung: Alles innerhalb der eckigen Klammern führt zu Severity 4 (Warning).
Docker-Transparenz: Debug-Prints sind unbuffered, um "Echtzeit-Gefühl" in den Container-Logs zu haben.

Sobald du die 7.62 installierst, schau im DEBUG_MODE besonders auf die VPN-Meldungen – AVM führt dort oft neue Verschlüsselungs-Bezeichnungen ein.

4. Erklärung der erweiterten Umgebungsvariablen (.env)

Parameter Wert (Beispiel) Beschreibung SEND_INITIAL_LOG True/False Wenn True, wird beim Containerstart das gesamte vorhandene Log der FRITZ!Box gesendet. Bei False werden nur Ereignisse ab Startmoment übertragen. SYSLOG_EXTRACT_TIME True/False Extrahiert den Zeitstempel direkt aus der FRITZ!Box-Meldung (04.02.26 03:02). Garantiert sekundengenaue Logs, unabhängig von der Container-Zeit. SYSLOG_MIXED_JSON True/False Sendet eine hybride Nachricht: Erst der Klartext, dann der Trenner, dann strukturiertes JSON. Ideal für parallele Nutzung von Syslog-Viewern und Graylog. SYSLOG_JSON_ONLY True/False Sendet nach dem Syslog-Header ausschließlich das JSON-Objekt. Optimiert für Elasticsearch und Graylog (kein Parsing des Klartextes nötig). JSON_SEPARATOR " -_- " Definiert die Zeichenfolge, die bei MIXED_JSON zwischen Text und Daten steht. Dient Graylog als Anker für das Splitting. TZ Europe/Berlin Zeitzone für den Fall, dass die Zeitextraktion fehlschlägt oder VPN-Events (Echtzeit) gesendet werden. DEBUG_MODE True/False Schaltet ausführliche Ausgaben im Container-Log (docker logs) frei (Login-Status, gesendete Payloads, Hash-Checks). DEBUG2_IGNORE_CACHE True/False Vorsicht: Deaktiviert den Dubletten-Schutz. Sendet bei jedem Intervall das komplette Log erneut. Nur für kurzzeitige Fehlersuche nutzen!

5. Syslog-Prioritäten & Level-Mapping

Das Skript übersetzt FRITZ!Box-Ereignisse automatisch in standardisierte Syslog-Severities (RFC 5424). Dies ermöglicht in Graylog/Zabbix eine sofortige Alarmierung basierend auf dem Feld level oder der Priority-ID. Severity ID Level Name Trigger im Skript (Keywords) Bedeutung 2 CRITICAL 0x203e, 0x2027, ike-error Kritische VPN-Handshake-Fehler. Handlungsbedarf bei Site-to-Site. 3 ERROR Fehler, Error, Failed, Abbruch, gescheitert Fehlgeschlagene Logins, DSL-Abbrüche, Internet-Trennung. 4 WARNING [... Meldungen seit ...], Warnung, Warning, ursache Häufung von Ereignissen oder instabile Leitungen (Störsicherheit). 6 INFO Alle anderen Meldungen WLAN-Anmeldungen, reguläre Reconnects, Systemstarts.

Pro-Tipp für die Wartung:

Sollte die FRITZ!Box nach einem Update auf 7.62 oder 8.0 keine Logs mehr senden, prüfen Sie im DEBUG_MODE, ob die fetch_data Funktion noch ein gültiges JSON-Objekt von der data.lua zurückerhält. AVM neigt dazu, die Feldnamen (z.B. von vpnList zu vpn_list) bei Major-Updates leicht zu ändern.