watchdog-docker/README.md

# Watchdog Docker v0.1

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

## 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

```bash
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

```bash
git clone <repository-url>
cd watchdog-docker
```

### 2. Konfiguration anpassen

Bearbeite `config/config.yaml`:

#### OPNsense Einstellungen

```yaml
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:

```python
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`:

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

#### E-Mail Konfiguration (optional)

```yaml
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

```yaml
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

```bash
# 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:
```bash
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

![Email Notification](docs/email-example.png)

Jede E-Mail enthält:
- Event-Typ mit Icon
- Zeitpunkt
- Interface/Gateway
- IP, MAC, Hostname (bei Geräten)
- Detaillierte Beschreibung

## Troubleshooting

### Container startet nicht

```bash
# Logs prüfen
docker-compose logs

# Container Status
docker-compose ps
```

### OPNsense API-Verbindung schlägt fehl

1. Prüfe ob OPNsense erreichbar ist:
   ```bash
   ping 192.168.1.1
   ```

2. Teste API manuell:
   ```bash
   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:
   ```bash
   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:
   ```python
   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:
   ```bash
   docker-compose logs | grep "Monitoring started"
   ```

2. Prüfe ob OPNsense API antwortet:
   ```bash
   docker-compose logs | grep "OPNsense"
   ```

3. Erhöhe Log-Level auf DEBUG in `config.yaml`:
   ```yaml
   logging:
     level: "DEBUG"
   ```

## Update

```bash
# 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

```bash
# 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

```bash
# 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)

## Entwicklung

### Lokale Entwicklung ohne Docker

```bash
# 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

```bash
# 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](#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

### v0.1 (Initial Release)
- OPNsense Monitoring (DHCP, Devices, Interfaces, Gateways)
- Web Dashboard mit Echtzeit-Updates
- E-Mail Benachrichtigungen
- SQLite Datenbank
- Docker Support