rmm2/Lastenheft.md

Lastenheft – OPNsense Zentralmanagement Agent

1. Zielsetzung

Ziel dieses Projektes ist die Entwicklung eines OPNsense Zentralmanagement-Agents, der es einer externen Management‑ und Monitoring‑Plattform ermöglicht, weitreichende Systeminformationen auszulesen sowie definierte Systemaktionen und Änderungen auf OPNsense‑Firewalls durchzuführen.

Da die bestehende OPNsense‑API für den vorgesehenen Funktionsumfang nicht ausreichend ist, soll ein Agent-basiertes Architekturmodell umgesetzt werden. Der Agent stellt eine sichere, persistente Verbindung zu einem zentralen Backend her und fungiert als Kontroll‑, Informations‑ und Tunnel‑Endpunkt.

Fur das frontent orientiere dich an dem vorschalg der Beispielbilder

2. Ausgangssituation

• Mehrere OPNsense‑Firewalls (verschiedene Versionen, Standorte, Kunden)

• Zentrale Verwaltungsoberfläche (ähnlich den gezeigten UI‑Mockups)

• Bestehende OPNsense‑API liefert nicht alle benötigten Informationen

• Bedarf an:

  • System‑Transparenz
  • Fernzugriff (SSH / WebUI)
  • Zentralem Backup‑ und Zertifikatsmanagement

3. Gesamtarchitektur

3.1 Komponenten

3.1.1 OPNsense Agent (pro Firewall)

• Läuft lokal auf der OPNsense (Plugin oder Service)
• Baut initiativ eine Verbindung zum Backend auf (Outbound only)
• Liefert Systemdaten
• Führt Kommandos und Aktionen kontrolliert aus

3.1.2 Backend Server (Control Plane)

• Zentrale Kommunikations‑ und Steuerinstanz
• Hält persistente Agent‑Verbindungen
• Stellt APIs für das Frontend bereit
• Baut Tunnel (SSH / HTTPS) zu den Firewalls über den Agent auf

3.1.3 Frontend Server (UI / Webinterface)

• Web‑UI für Administratoren
• Darstellung der Firewalls (Übersichten, Details, Status)
• Steuerung von Aktionen (Tunnel, Backups, Reloads)

4. Funktionale Anforderungen – Agent

4.1 Hardware‑ und Systeminformationen

Der Agent muss folgende Informationen bereitstellen:

• Hersteller
• Modell
• Seriennummer
• BIOS‑Version
• CPU (Typ, Kerne, Threads, Takt)
• RAM (gesamt, frei)
• Massenspeicher (Typ, Kapazität, Belegung)
• OPNsense‑Version
• Uptime

4.2 Dienste und Status

Der Agent muss:

• Alle Systemdienste auflisten
• Status je Dienst liefern (running / stopped)
• Dienst neu starten / stoppen / starten können (optional konfigurierbar)

Beispiele:

• configd
• dhcpd / kea
• unbound
• openvpn
• wireguard
• cron

4.3 Netzwerk‑Interfaces

Der Agent muss:

• Alle Interfaces anzeigen
• Rolle (WAN / LAN / OPT)
• IP‑Adresse(n)
• MAC‑Adresse
• RX/TX‑Traffic
• Status (up/down)

4.4 VPN‑Informationen

4.4.1 WireGuard

• Tunnelname
• Peers
• Status (up/down)
• Transferstatistiken

4.4.2 OpenVPN

• Server / Client‑Instanzen
• Verbindungsstatus
• Road‑Warrior‑Sessions

4.5 Routing

• Anzeige der Routing‑Tabelle
• Zielnetz
• Gateway
• Interface
• Typ (statisch / dynamisch)

4.6 DHCP (KEA)

• Aktive DHCP‑Instanzen
• Pools
• Leases (IPv4 / IPv6)
• Lease‑Status
• Zuordnung MAC ↔ IP

4.7 Zertifikate

• Auflistung aller Zertifikate
• Typ (CA, Server, User, ACME)
• Gültigkeitszeitraum
• Ablaufwarnungen
• Zertifikat neu laden / erneuern (optional)

4.8 Backups

Der Agent muss:

• Konfigurations‑Backups erstellen können
• Backup lokal zwischenspeichern
• Backup an Backend übertragen
• Metadaten liefern (Größe, Zeitstempel)

5. Tunnel‑Funktionalität

5.1 Ziel

Das Backend soll on‑demand Tunnel zu einer Firewall aufbauen können, ohne dass direkte eingehende Verbindungen zur Firewall notwendig sind.

5.2 Tunnelarten

• SSH‑Tunnel
• HTTPS‑Tunnel (WebUI)

5.3 Funktionsweise

• Agent hält persistente Verbindung zum Backend
• Backend fordert Tunnel an
• Agent öffnet lokalen Zielport (z. B. 127.0.0.1:22 oder 443)
• Agent erstellt Reverse‑Tunnel
• Backend stellt öffentlichen / internen Zugriffspunkt bereit

5.4 Anforderungen an Tunnel

• Vergleichbar mit stunnel

• Konfigurierbar:

  • Zielport
  • Protokoll
  • Laufzeit
  • Zugriffsbeschränkung

• Frontend zeigt klickbaren Link zum Tunnel

6. Sicherheit & Compliance

6.1 Kommunikation

• TLS‑verschlüsselt (mTLS bevorzugt)
• Agent authentifiziert sich eindeutig
• Zertifikatsbasierte Identität

6.2 Rechte & Rollen

• Agent darf nur explizit erlaubte Aktionen ausführen
• Rollenmodell im Backend (Admin, Read‑Only, Operator)

6.3 Logging & Audit

• Alle Aktionen werden protokolliert
• Tunnel‑Nutzung wird geloggt
• Konfigurationsänderungen nachvollziehbar

7. Nicht‑funktionale Anforderungen

7.1 Performance

• Geringe Last auf OPNsense
• Asynchrone Abfragen

7.2 Stabilität

• Agent überlebt OPNsense‑Updates
• Automatische Reconnect‑Logik

7.3 Skalierbarkeit

• Unterstützung für viele hundert Firewalls
• Mandantenfähigkeit (Kunden / Standorte)

8. Abgrenzung

Nicht Bestandteil dieses Lastenhefts:

• Vollständige Firewall‑Rule‑Bearbeitung
• Deep Packet Inspection
• IDS/IPS‑Regelverwaltung

9. Abnahmekriterien

• Alle genannten Informationspunkte sind im Frontend sichtbar
• Tunnel können on‑demand aufgebaut und beendet werden
• Backups sind abrufbar und wiederherstellbar
• Agent funktioniert mit mehreren OPNsense‑Versionen

---

Dieses Lastenheft basiert auf den bereitgestellten Screenshots, der beschriebenen Zielarchitektur und den funktionalen Anforderungen des Auftraggebers.