# OPNsense - Brainstorming & Todo

## Brainstorming

### Contexte
L'API REST OPNsense (https://docs.opnsense.org/development/api.html) expose plus de 24 modules core et 80+ plugins.
Authentification par clé API (key + secret) en HTTPS Basic Auth.
Format d'appel : `https://<host>/api/<module>/<controller>/<command>/[<param>]`

### Endpoints API exploitables pour IPWatch

#### 1. Table ARP (enrichissement des scans)
- `GET /api/diagnostics/interface/get_arp` : table ARP complète du firewall
- `GET /api/diagnostics/interface/search_arp` : recherche dans la table ARP
- **Interet** : OPNsense voit TOUT le trafic, sa table ARP est plus complète que celle de la machine IPWatch. Permet de detecter des equipements que le scan ping ne voit pas (equipements qui ne repondent pas au ping mais passent par le firewall).

#### 2. DHCP Kea - Reservations statiques (gestion centralisee)
- `GET /api/kea/dhcpv4/search_reservation` : lister toutes les reservations
- `GET /api/kea/dhcpv4/get_reservation/{uuid}` : detail d'une reservation
- `POST /api/kea/dhcpv4/add_reservation` : creer une reservation (IP + MAC + hostname)
- `POST /api/kea/dhcpv4/set_reservation/{uuid}` : modifier une reservation
- `POST /api/kea/dhcpv4/del_reservation/{uuid}` : supprimer une reservation
- **Champs du modele reservation** : `subnet` (ref), `ip_address` (IPv4), `hw_address` (MAC), `hostname` (DNS), `description` (texte libre)
- **Reservation hors plage DHCP** : OUI, c'est meme recommande avec Kea. Les reservations doivent etre en dehors du pool dynamique pour eviter les collisions. Ex: pool=10.0.1.100-254, reservation=10.0.0.50 → OK.
- **Description "Ajout par IPWatch"** : OUI, le champ `description` est un texte libre non parse. On peut y mettre : `"Ajout par IPWatch - {nom_equipement} - {date}"` pour tracer l'origine de la reservation.
- **Interet** : Depuis IPWatch, on peut directement gerer les baux statiques DHCP. Quand un nouvel equipement est detecte, on peut lui attribuer une IP fixe en un clic, meme en dehors de la plage DHCP dynamique.

#### 3. DNS Unbound - Host overrides (resolution noms)
- `GET /api/unbound/settings/search_host_override` : lister les overrides DNS
- `POST /api/unbound/settings/add_host_override` : ajouter un override
- `POST /api/unbound/settings/set_host_override/{uuid}` : modifier
- `POST /api/unbound/settings/del_host_override/{uuid}` : supprimer
- `POST /api/unbound/service/reconfigure` : appliquer les changements
- **Interet** : Gerer la resolution DNS locale directement depuis IPWatch. Quand on nomme un equipement dans IPWatch, on peut aussi creer l'entree DNS correspondante.

#### 4. Aliases Firewall (groupes d'IP)
- `GET /api/firewall/alias/get` : lister les aliases
- `POST /api/firewall/alias/add_item` : creer un alias
- `POST /api/firewall/alias/set_item/{uuid}` : modifier
- `POST /api/firewall/alias/del_item/{uuid}` : supprimer
- `POST /api/firewall/alias/toggle_item/{uuid}` : activer/desactiver
- **Interet** : Creer/gerer des groupes d'IP depuis IPWatch (ex: "cameras", "IoT", "serveurs") qui se repercutent dans les regles firewall OPNsense.

#### 5. Regles Firewall (visibilite et gestion)
- `GET /api/firewall/filter/search_rule` : lister les regles
- `POST /api/firewall/filter/add_rule` : ajouter une regle
- `POST /api/firewall/filter/toggle_rule/{uuid}` : activer/desactiver
- `POST /api/firewall/filter/apply/{revision}` : appliquer
- **Interet** : Voir les regles associees a une IP, bloquer/debloquer un equipement directement depuis IPWatch.

#### 6. Interfaces et trafic (monitoring)
- `GET /api/diagnostics/interface/get_interface_statistics` : stats par interface
- `GET /api/diagnostics/traffic/stream` : flux temps reel
- `GET /api/diagnostics/traffic/_top` : top connexions
- `GET /api/diagnostics/interface/get_interface_config` : config interfaces
- **Interet** : Afficher dans IPWatch le trafic par equipement, detecter les anomalies de consommation, enrichir le panneau de details d'une IP.

#### 7. Systeme OPNsense (dashboard)
- `GET /api/diagnostics/system/system_information` : info systeme
- `GET /api/diagnostics/system/system_resources` : CPU/RAM
- `GET /api/diagnostics/system/system_temperature` : temperatures
- `GET /api/diagnostics/system/memory` : memoire
- **Interet** : Afficher l'etat du firewall dans le dashboard IPWatch (sante du reseau).

#### 8. VPN Status (Wireguard/OpenVPN)
- Endpoints Wireguard et OpenVPN pour voir les tunnels actifs
- **Interet** : Visualiser les connexions VPN, savoir quel equipement est connecte via VPN.

#### 9. Network Insight (analyse historique)
- `GET /api/diagnostics/networkinsight/timeserie` : donnees chronologiques
- `GET /api/diagnostics/networkinsight/top` : classement trafic
- **Interet** : Historique de trafic par IP, graphiques d'utilisation dans le detail d'un equipement.

---

### Idees d'integration UI dans IPWatch

1. **Panneau de details IP (volet gauche)** :
   - Section "OPNsense" avec : reservation DHCP, override DNS, aliases associes, regles firewall
   - Boutons d'action : "Creer reservation DHCP", "Ajouter override DNS", "Bloquer cette IP"
   - Graphique mini de trafic de cet equipement

2. **Nouveau detection (volet droit)** :
   - Quand un nouvel equipement est detecte, proposer directement : "Creer reservation DHCP statique"
   - Pre-remplir avec le MAC et proposer une IP dans la plage appropriee

3. **Dashboard / Stats systeme** :
   - Widget sante OPNsense (CPU, RAM, temp)
   - Widget trafic global
   - Widget connexions VPN actives

4. **Onglet Architecture** :
   - Afficher le firewall OPNsense comme noeud central
   - Visualiser les interfaces, VLANs, flux de trafic

5. **Configuration** :
   - Section `opnsense` dans config.yaml avec : host, api_key, api_secret, enabled, sync_interval
   - Page parametres avec test de connexion

---

### Onglet OPNsense - Tableau de bord dedie (ligne 9 amelioration.md)

Vision : un onglet `/opnsense` dans IPWatch qui offre une vue claire et pedagogique de l'etat du firewall, ses services, et ses parametrages, sans avoir besoin d'ouvrir l'interface OPNsense.

#### Section 0 : Detection automatique des services (au chargement)
Avant d'afficher l'onglet, IPWatch doit detecter quels services sont installes et actifs :
- **Endpoint** : `POST /api/core/service/search` → retourne `{id, name, running, locked, description}` pour chaque service
- **Endpoint** : `GET /api/core/firmware/info` → liste tous les paquets installes (nom, version, description)
- **Logique de detection DHCP** :
  - Si service `kea-dhcp4` present et running → utiliser les endpoints Kea (`/api/kea/dhcpv4/...`)
  - Si service `dhcpd` present et running → utiliser les endpoints ISC DHCP (+ avertir EOL)
  - Si service `dnsmasq` present et running → utiliser les endpoints Dnsmasq (`/api/dnsmasq/...`)
  - Si aucun → afficher "Aucun serveur DHCP detecte"
- **Detection generale** : stocker le resultat dans un objet `detectedServices` cote backend, reutilise partout :
  ```
  { dhcp: "kea" | "isc" | "dnsmasq" | null, dns: "unbound" | "dnsmasq" | null,
    vpn: ["wireguard", "openvpn"] | [], ids: true | false, ... }
  ```
- **Interet** : adapter dynamiquement l'UI et les endpoints selon la configuration reelle du serveur OPNsense
- **Couche d'abstraction backend** : les APIs DHCP sont tres differentes selon le service detecte :
  ```
  opnsense_client.py
    ├── dhcp_adapter.py         # Interface commune (list, add, del, get reservation)
    │   ├── kea_adapter.py      # kea/dhcpv4/*_reservation (CRUD complet, champ description)
    │   ├── dnsmasq_adapter.py  # dnsmasq/settings/*_host (CRUD complet, tags, options, ranges)
    │   └── isc_adapter.py      # dhcpv4/leases/search_lease (lecture seule, PAS d'API pour static mapping)
  ```
  - **Kea** : API complete → reservation (subnet, ip_address, hw_address, hostname, description)
  - **Dnsmasq** : API complete → hosts statiques (ip, mac, hostname) + tags + options DHCP + ranges
  - **ISC DHCP** : PAS d'API pour les static mappings (issue #4062), seulement lecture des baux. Afficher avertissement EOL + recommander migration vers Kea ou Dnsmasq
  - Le frontend appelle toujours les memes routes IPWatch (`/api/opnsense/dhcp/reservations`), le backend route vers le bon adapter

#### Section 1 : Etat des services (haut de page)
Grille de cartes affichant chaque service avec un indicateur visuel (vert/rouge/gris).
- **Endpoint** : `POST /api/core/service/search` (deja appele en Section 0)
- **Services cles a afficher** : Unbound (DNS), Kea DHCP, Firewall, OpenVPN, Wireguard, Syslog, IDS/IPS, NTP, HAProxy, etc.
- Chaque carte affiche :
  - Icone du service
  - Nom + description courte
  - Badge etat : "Actif" (vert) / "Arrete" (rouge) / "Desactive" (gris)
  - **Tooltip** : description detaillee du role du service, parametres principaux, derniere action
  - Boutons : Start / Stop / Restart (avec confirmation modale)
- **Filtres** : Tous / Actifs / Arretes / Critiques

#### Section 2 : Parametrages rapides (milieu de page)
Tableaux clairs par domaine, chaque ligne avec tooltips explicatifs :

**DHCP (Kea)** :
- Tableau des reservations statiques : IP | MAC | Hostname | Subnet | Actions
- Endpoints : `search_reservation`, `add_reservation`, `del_reservation`
- Tooltip par champ : "L'adresse MAC identifie physiquement l'equipement", etc.
- Bouton "Ajouter reservation" avec formulaire modal

**DNS (Unbound)** :
- Tableau des host overrides : Hostname | Domain | IP | Description | Actions
- Endpoints : `search_host_override`, `add_host_override`, `del_host_override`
- Tooltip : "Un host override force la resolution DNS locale d'un nom vers une IP specifique"

**Firewall - Aliases** :
- Tableau des aliases : Nom | Type | Contenu | Enabled | Actions
- Endpoints : `get`, `add_item`, `toggle_item`
- Tooltip : "Un alias regroupe des IPs/reseaux/ports pour simplifier les regles firewall"

**Firewall - Regles** :
- Tableau des regles (lecture seule recommandee) : # | Action | Interface | Source | Dest | Port | Proto | Enabled
- Endpoint : `search_rule`
- Tooltip : "Pass = autorise le trafic, Block = bloque, Reject = bloque et notifie"
- Statistiques par regle (hits) via `rule_stats`

**Interfaces** :
- Tableau des interfaces : Nom | Status | IP | Gateway | Media | Debit In/Out
- Endpoints : `get_interface_config`, `get_interface_statistics`
- Tooltip : "WAN = connexion Internet, LAN = reseau local, OPT = interface supplementaire"

**VLANs** :
- Tableau : Interface parent | VLAN ID | Description | Actions
- Endpoint : `search_item` (VlanSettingsController)

#### Section 3 : Monitoring systeme (colonne droite ou section)
Mini-dashboard de sante OPNsense :
- **CPU** : jauge + pourcentage (`system_resources`)
- **RAM** : jauge + utilise/total (`memory`)
- **Temperature** : valeur + icone couleur (`system_temperature`)
- **Disque** : barre de progression (`system_disk`)
- **Uptime** : duree depuis dernier reboot (`system_information`)
- **Version** : OPNsense version + derniere MAJ firmware

#### Section 4 : Logs et erreurs (bas de page)
Tableau de logs temps reel avec filtrage :
- **Sources de logs** :
  - `GET /api/diagnostics/log/core/firewall` : logs firewall (block/pass)
  - `GET /api/syslog/service/stats` : stats syslog
  - Logs DHCP : attributions, expirations, conflits
  - Logs IDS/IPS : alertes de securite
- **Colonnes** : Timestamp | Severite | Service | Message | IP source | IP dest
- **Filtres** :
  - Par severite : erreur (rouge), warning (orange), info (bleu), debug (gris)
  - Par service : Firewall, DHCP, DNS, VPN, IDS
  - Par IP : filtrer les logs d'un equipement specifique
  - Par periode : derniere heure, 24h, 7j
- **Recherche** : texte libre dans les messages
- **Tooltip sur les erreurs** :
  - "Block" firewall → "Le firewall a bloque ce trafic car aucune regle ne l'autorise"
  - "DHCP NAK" → "Le serveur DHCP a refuse la demande : l'IP demandee n'est pas disponible"
  - "IDS Alert" → "Le systeme de detection d'intrusion a identifie un comportement suspect"
- **Auto-refresh** : polling configurable (5s, 15s, 30s, 1min) ou WebSocket si disponible

#### Section 5 : Actions globales (header de l'onglet)
- Bouton "Test connexion API" avec indicateur vert/rouge
- Bouton "Rafraichir tout" pour recharger toutes les sections
- Indicateur "Derniere synchro : il y a X secondes"
- Lien direct vers l'interface web OPNsense (ouvre dans un nouvel onglet)

#### Design et UX
- **Theme** : Monokai coherent avec le reste d'IPWatch
- **Tooltips** : icone (i) a cote de chaque element avec description claire et accessible
  - Vocabulaire non-technique quand possible
  - Exemples concrets ("Par exemple, si vous voulez que votre NAS ait toujours l'IP 10.0.0.50...")
  - Lien vers la doc OPNsense pour approfondir
- **Responsive** : layout adaptatif (2 colonnes desktop, 1 colonne mobile)
- **Etats de chargement** : skeleton loaders pendant les appels API
- **Gestion d'erreurs** :
  - Connexion impossible → message clair + bouton "Verifier la configuration"
  - Timeout → retry automatique + notification
  - Erreur API → affichage du code erreur + explication

---

## Todo

*(deplacer ici les elements valides du brainstorming)*

- [ ] Ajouter section `opnsense` dans config.yaml (host, api_key, api_secret, enabled)
- [ ] Creer service backend `opnsense_client.py` (classe client API avec auth)
- [ ] Endpoint de test de connexion API OPNsense
- [ ] Detection auto des services installes (`core/service/search` + `core/firmware/info`) → objet `detectedServices`
- [ ] Couche d'abstraction DHCP : `dhcp_adapter.py` avec `kea_adapter`, `dnsmasq_adapter`, `isc_adapter`
- [ ] Routes IPWatch uniformes (`/api/opnsense/dhcp/reservations`) routees vers le bon adapter
- [ ] Integration table ARP OPNsense dans le scan reseau
- [ ] Lecture des reservations DHCP depuis OPNsense (Kea ou Dnsmasq selon detection)
- [ ] Bouton "Creer reservation DHCP" dans le volet details IP
- [ ] Lecture des host overrides Unbound
- [ ] Bouton "Creer override DNS" dans le volet details IP
- [ ] Afficher les aliases firewall associes a une IP
- [ ] Widget sante OPNsense dans dashboard
- [ ] Section OPNsense dans page Parametres (config + test connexion)
- [ ] Creer onglet OPNsense : vue `/opnsense` + route + lien navigation
- [ ] Section services : grille de cartes avec etat (actif/arrete) via `core/service/search`
- [ ] Section DHCP : tableau des reservations Kea avec CRUD
- [ ] Section DNS : tableau des host overrides Unbound avec CRUD
- [ ] Section Aliases : tableau des aliases firewall avec CRUD
- [ ] Section Regles Firewall : tableau lecture seule avec stats
- [ ] Section Interfaces : tableau avec stats trafic
- [ ] Section Monitoring systeme : jauges CPU/RAM/Temp/Disque
- [ ] Section Logs : tableau temps reel avec filtres severite/service/IP
- [ ] Tooltips pedagogiques sur tous les elements de l'onglet
- [ ] Gestion erreurs : connexion impossible, timeout, erreurs API
- [ ] Tuto migration ISC DHCP vers Kea : voir `tuto_migration_isc_vers_kea.md`

## Done

*(deplacer ici les elements termines)*