Watchdog Docker

Docker Container für OPNsense Monitoring mit Web-Interface und E-Mail-Benachrichtigungen.

Aktuelle Version: Siehe VERSION | Changelog: CHANGELOG.md

Features

• 🔍 DHCP Lease Monitoring - Überwachung neuer IP-Vergaben
• 📱 Device Detection - Erkennung neuer Geräte via ARP (mit Abgleich bekannter Geräte)
• 🔌 Interface Monitoring - Status-Änderungen von Netzwerk-Interfaces
• 🌐 Gateway Monitoring - Überwachung von Gateway-Status
• 📧 E-Mail Benachrichtigungen - Automatische Alerts bei Events
• 🖥️ Web Dashboard - Übersichtliches Interface mit Echtzeit-Updates
• 🔐 Passwort-Schutz - Gesicherter Zugang zum Dashboard

Überwachte Events

Event-Typ	Beschreibung	Interface-Filter
DHCP Lease	Neue IP-Adresse vergeben	✓
New Device	Neues Gerät im Netzwerk erkannt	✓
Interface Status	Interface up/down Änderungen	✓
Gateway Status	Gateway Status-Änderungen	-

Voraussetzungen

• Docker & Docker Compose
• OPNsense Firewall mit aktivierter API
• SMTP Server für E-Mail-Benachrichtigungen (optional)

OPNsense API Setup

1. API Key & Secret generieren

1. In OPNsense: System → Access → Users
2. Wähle deinen Admin-User oder erstelle einen neuen
3. Scrolle zu API keys und klicke auf + (Add)
4. Notiere dir Key und Secret - sie werden nur einmal angezeigt!

2. API Zugriff testen

curl -k -u "YOUR_KEY:YOUR_SECRET" https://192.168.1.1/api/core/menu/search/

Falls erfolgreich, erhältst du JSON-Daten zurück.

Installation

1. Repository klonen

git clone <repository-url>
cd watchdog-docker

2. Konfiguration anpassen

Bearbeite config/config.yaml:

OPNsense Einstellungen

opnsense:
  host: "https://192.168.1.1"  # Deine OPNsense IP
  api_key: "YOUR_API_KEY_HERE"
  api_secret: "YOUR_API_SECRET_HERE"
  verify_ssl: false  # Auf true setzen bei gültigem Zertifikat

Admin-Passwort generieren

Passwort-Hash für das Web-Interface generieren:

from werkzeug.security import generate_password_hash

# Ersetze 'dein_passwort' mit deinem gewünschten Passwort
password = "dein_passwort"
hash = generate_password_hash(password)
print(hash)

Kopiere den generierten Hash in die config.yaml:

web:
  admin_password_hash: "scrypt:32768:8:1$..."  # Dein generierter Hash

E-Mail Konfiguration (optional)

email:
  enabled: true
  smtp_server: "mail.yourdomain.com"
  smtp_port: 587
  smtp_use_tls: true
  smtp_username: "watchdog@yourdomain.com"
  smtp_password: "YOUR_PASSWORD"
  from_address: "watchdog@yourdomain.com"
  to_addresses:
    - "admin@yourdomain.com"

Falls du keine E-Mails versenden möchtest, setze enabled: false.

Monitoring-Einstellungen

monitoring:
  polling_interval: 60  # Sekunden zwischen Checks

  # Nur bestimmte Interfaces überwachen (leer = alle)
  monitored_interfaces:
    - lan
    - wan

  # Events ein/ausschalten
  events:
    dhcp_leases: true
    new_devices: true
    interface_status: true
    gateway_status: true

3. Docker Container starten

# Container bauen und starten
docker-compose up -d

# Logs anzeigen
docker-compose logs -f

# Status prüfen
docker-compose ps

4. Web-Interface öffnen

Öffne im Browser: http://localhost:5000

• Benutzername: admin
• Passwort: Dein konfiguriertes Passwort

Verzeichnisstruktur

watchdog-docker/
├── Dockerfile                # Docker Image Definition
├── docker-compose.yml        # Docker Compose Konfiguration
├── requirements.txt          # Python Dependencies
├── README.md                 # Diese Datei
├── config/
│   └── config.yaml          # Hauptkonfiguration
├── app/
│   ├── main.py              # Flask App & Routes
│   ├── opnsense_api.py      # OPNsense API Client
│   ├── monitor.py           # Event Monitoring Logik
│   ├── database.py          # SQLite Datenbank Handler
│   ├── email_handler.py     # E-Mail Versand
│   └── templates/
│       ├── login.html       # Login-Seite
│       └── dashboard.html   # Dashboard
└── data/                     # Auto-generiert beim ersten Start
    ├── watchdog.db          # SQLite Datenbank
    └── watchdog.log         # Log-Datei

API Endpoints

Das Dashboard verwendet folgende REST-API Endpoints:

• GET /api/events - Events abrufen
  • Parameter: limit, type, interface
• GET /api/stats - Statistiken abrufen
• GET /health - Health Check

Beispiel:

curl http://localhost:5000/api/events?type=dhcp_lease&limit=10

Datenbank

Die SQLite-Datenbank wird automatisch beim ersten Start erstellt.

Tabellen

events

Spalte	Typ	Beschreibung
id	INTEGER	Primary Key
timestamp	DATETIME	Event-Zeitpunkt
type	TEXT	Event-Typ
interface	TEXT	Interface-Name
details	TEXT	Event-Details
data	JSON	Vollständige Event-Daten

known_devices

Spalte	Typ	Beschreibung
mac	TEXT	MAC-Adresse (Primary Key)
name	TEXT	Geräte-Name
first_seen	DATETIME	Erstmals gesehen
last_seen	DATETIME	Zuletzt gesehen

Datenbank-Wartung

Alte Events werden automatisch nach der konfigurierten Retention-Zeit gelöscht (Standard: 90 Tage).

E-Mail Benachrichtigungen

Event-Typen

• DHCP Lease 🔵 - Neue IP-Vergabe
• New Device 🔴 - Unbekanntes Gerät (nur bei unbekannten Geräten)
• Interface Status ⚠️ - Interface up/down
• Gateway Status ⚠️ - Gateway-Änderungen

E-Mail Beispiel

Jede E-Mail enthält:

• Event-Typ mit Icon
• Zeitpunkt
• Interface/Gateway
• IP, MAC, Hostname (bei Geräten)
• Detaillierte Beschreibung

Troubleshooting

Container startet nicht

# Logs prüfen
docker-compose logs

# Container Status
docker-compose ps

OPNsense API-Verbindung schlägt fehl

1. Prüfe ob OPNsense erreichbar ist:

   ping 192.168.1.1
   

2. Teste API manuell:

   curl -k -u "KEY:SECRET" https://192.168.1.1/api/core/menu/search/
   

3. Prüfe Firewall-Regeln auf OPNsense

Keine E-Mails werden versendet

1. Prüfe SMTP-Einstellungen in config.yaml
2. Teste SMTP-Verbindung:

   telnet mail.yourdomain.com 587
   

3. Prüfe Container-Logs auf SMTP-Fehler

Login funktioniert nicht

1. Prüfe ob Passwort-Hash korrekt generiert wurde
2. Versuche neuen Hash zu generieren:

   from werkzeug.security import generate_password_hash
   print(generate_password_hash("dein_passwort"))
   

3. Hash in config.yaml ersetzen und Container neu starten

Dashboard zeigt keine Events

1. Prüfe ob Monitoring läuft:

   docker-compose logs | grep "Monitoring started"
   

2. Prüfe ob OPNsense API antwortet:

   docker-compose logs | grep "OPNsense"
   

3. Erhöhe Log-Level auf DEBUG in config.yaml:

   logging:
     level: "DEBUG"
   

Update

# Container stoppen
docker-compose down

# Neueste Version pullen
git pull

# Container neu bauen und starten
docker-compose up -d --build

Hinweis: Die Datenbank (data/watchdog.db) bleibt bei Updates erhalten.

Backup

Datenbank sichern

# Backup erstellen
docker-compose exec watchdog sqlite3 /app/data/watchdog.db ".backup /app/data/backup.db"

# Backup aus Container kopieren
docker cp watchdog:/app/data/backup.db ./backup.db

Konfiguration sichern

# Config sichern
cp config/config.yaml config/config.yaml.backup

Sicherheitshinweise

• ⚠️ Ändere das secret_key in der config.yaml
• ⚠️ Verwende ein sicheres Admin-Passwort
• ⚠️ Aktiviere SSL-Verifizierung (verify_ssl: true) in Produktion
• ⚠️ Verwende HTTPS für das Web-Interface (z.B. mit Reverse Proxy)
• ⚠️ Speichere keine API-Secrets in Git (nutze .env Dateien)

Versionierung & Entwicklung

Versionsschema

Das Projekt folgt einem angepassten Semantic Versioning Schema:

• Große Änderungen (neue Features, Breaking Changes): +0.1

  • Beispiel: 0.1.0 → 0.2.0
  • Trigger: Neue Monitoring-Features, API-Änderungen, UI-Redesign

• Kleine Änderungen (Bugfixes, kleinere Verbesserungen): +0.0.1

  • Beispiel: 0.1.0 → 0.1.1
  • Trigger: Bugfixes, Performance-Verbesserungen, Dokumentations-Updates

• Major Release (1.x): Nur auf Anweisung

  • Production-Ready Status
  • Vollständig getestet und stabil

Git Workflow

• main - Stable Release Branch (nur getestete Versionen)
• develop - Development Branch (aktive Entwicklung)
• Feature Branches - Für größere Features (feature/feature-name)

Changelog

Alle Änderungen werden in CHANGELOG.md dokumentiert. Das Format folgt Keep a Changelog.

Entwicklung

Lokale Entwicklung ohne Docker

# Virtual Environment erstellen
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Dependencies installieren
pip install -r requirements.txt

# App starten
python app/main.py

Tests

# OPNsense API Connection testen
python -c "from app.opnsense_api import OPNsenseAPI; import yaml; config = yaml.safe_load(open('config/config.yaml')); api = OPNsenseAPI(**config['opnsense']); print(api.test_connection())"

Support

Bei Problemen oder Fragen:

1. Prüfe die Troubleshooting Sektion
2. Aktiviere DEBUG-Logging und prüfe die Logs
3. Erstelle ein Issue mit:
   • Container-Logs (docker-compose logs)
   • Konfiguration (ohne Secrets!)
   • Fehlerbeschreibung

Lizenz

MIT License

Changelog

Siehe CHANGELOG.md für vollständige Versionshistorie.