diff --git a/projet_web_ui_passerelle_reseau_synthese_complete.md b/projet_web_ui_passerelle_reseau_synthese_complete.md new file mode 100644 index 0000000..f0568d0 --- /dev/null +++ b/projet_web_ui_passerelle_reseau_synthese_complete.md @@ -0,0 +1,249 @@ +# PROJET WEBUI PASSERELLE RÉSEAU – SYNTHÈSE COMPLÈTE + +Ce document reprend **l’intégralité de la discussion**, structurée et consolidée, sur la conception et le développement d’une **WebUI d’administration réseau** destinée à une **VM Debian 13 (Trixie)** jouant le rôle de **passerelle LAN → Internet**. + +--- + +## 1. OBJECTIF GÉNÉRAL + +Créer une **application Web d’administration réseau**, installée dans une **machine virtuelle Debian 13**, permettant de configurer et superviser : + +- le réseau local (LAN) +- l’accès Internet (WAN) +- l’attribution d’adresses IP (DHCP) +- la résolution de noms (DNS) +- le pare-feu et le partage de connexion (NAT) +- les services réseau associés + +Contraintes clés : +- uniquement **outils réseau standards Debian 13** (aucun dépôt tiers) +- **WebUI simple et pédagogique**, adaptée à des utilisateurs novices +- libellés clairs, textes explicatifs, info-bulles, **pas d’acronymes non expliqués** +- accès WebUI limité au **réseau local** +- architecture modulaire (services activables/installables) + +--- + +## 2. ARCHITECTURE GÉNÉRALE + +### 2.1 Schéma fonctionnel + +Navigateur → HTTPS → Nginx → API backend (non root) → scripts contrôlés → services système Debian + +### 2.2 Composants + +- **Frontend** : HTML/CSS/JavaScript léger (onglets + formulaires) +- **Serveur Web** : Nginx +- **Backend** : Python (API REST) +- **Services système** : configurés via fichiers standards Debian +- **Contrôle système** : systemctl, journalctl, nftables, kea, unbound + +### 2.3 Sécurité + +- WebUI accessible uniquement depuis le LAN +- utilisateur système dédié pour l’application +- droits permissifs en phase V1 (sudo large), durcissement ultérieur +- aucune modification appliquée sans validation explicite + +--- + +## 3. MACHINE VIRTUELLE (PROXMOX) + +### 3.1 Paramétrage recommandé + +- Type : VM Linux +- Machine : q35 +- BIOS : OVMF (UEFI) +- CPU : 1 socket / 2 à 4 cœurs / type host +- RAM : 4 Go (ballooning désactivé) +- Disque : 32 Go, VirtIO SCSI, iothread activé +- Réseau : + - 2 cartes VirtIO + - 1 WAN (Internet) + - 1 LAN (réseau local) +- Pare-feu Proxmox : désactivé +- Watchdog : activé + +### 3.2 Rôle de la VM + +- passerelle LAN → Internet +- serveur DHCP principal +- serveur DNS local +- point central d’observation du trafic + +--- + +## 4. SERVICES UTILISÉS (STANDARD DEBIAN 13) + +### 4.1 Services cœur (V1) + +- Gestion réseau : systemd-networkd +- Pare-feu / NAT : nftables +- DHCPv4 : kea-dhcp4-server +- DNS local : unbound +- Logs : systemd-journald +- Connexions réseau : conntrack + +### 4.2 Services optionnels (V2/V3) + +- Découverte réseau : avahi-daemon (LAN uniquement) +- VPN : wireguard +- QoS : tc +- IDS/IPS : suricata (non V1) + +--- + +## 5. WEBUI – ORGANISATION DES PAGES (V1) + +### 5.1 Tableau de bord + +- état WAN / LAN +- état des services +- alertes simples + +### 5.2 Réseau + +- côté Internet : adresse automatique ou fixe +- côté réseau local : adresse de la passerelle, domaine + +### 5.3 Pare-feu et partage de connexion + +- interrupteurs simples +- règles prédéfinies compréhensibles + +### 5.4 Attribution d’adresses (DHCP) + +- plages dynamiques +- réservations fixes +- liste des appareils connectés + +### 5.5 Noms (DNS) + +- serveurs amont +- domaine local +- entrées fixes nom → adresse + +### 5.6 Services + +- installation via apt (liste blanche) +- démarrage / arrêt / activation au boot +- état en temps réel + +### 5.7 Journaux + +- lecture des logs par service +- filtres (date, texte, niveau) + +### 5.8 Activité réseau + +- connexions LAN → Internet +- requêtes DNS +- événements du pare-feu + +--- + +## 6. MÉTHODOLOGIE DE TEST ET DÉPLOIEMENT + +### 6.1 Phase 0 – Développement hors réseau + +- DHCP désactivé +- pare-feu non bloquant +- génération et validation de configuration uniquement + +### 6.2 Phase 1 – Intégration passive + +- VM connectée au LAN +- observation uniquement (logs, trafic) + +### 6.3 Phase 2 – Test DHCP contrôlé + +- arrêt temporaire de l’ancien DHCP +- activation du nouveau +- tests sur un ou deux clients +- rollback immédiat possible + +### 6.4 Phase 3 – Remplacement définitif + +- bascule complète +- surveillance + +--- + +## 7. MIGRATION DES ADRESSES IP EXISTANTES + +### 7.1 Principe + +- conserver les adresses IP actuelles +- éviter toute reconfiguration côté clients + +### 7.2 Méthode retenue (recommandée) + +**Import des baux DHCP existants** depuis l’ancien serveur + +### 7.3 Sources supportées + +- OPNsense : + - CSV (baux DHCP) + - XML (config complète) +- Fichier JSON générique + +### 7.4 Format JSON canonique interne + +{ + "source": "opnsense", + "interface": "lan", + "reservations": [ + { + "nom": "nas", + "adresse_ip": "10.0.0.10", + "adresse_materielle": "AA:BB:CC:DD:EE:01" + } + ] +} + +Tous les imports sont normalisés vers ce format. + +### 7.5 Processus WebUI + +- import fichier +- analyse et validation +- prévisualisation +- génération réservations DHCP +- aucune application automatique + +--- + +## 8. PHILOSOPHIE DU PROJET + +- sécurité avant automatisation +- aucune action irréversible sans confirmation +- priorité à la lisibilité et à la pédagogie +- architecture modulaire +- pas de dépendance externe + +--- + +## 9. PÉRIMÈTRE V1 VALIDÉ + +Modules inclus : +1. Réseau WAN/LAN +2. Pare-feu + NAT +3. DHCPv4 (Kea) +4. DNS (Unbound) +5. Services +6. Journaux +7. Activité réseau + +--- + +## 10. ÉTAPES SUIVANTES POSSIBLES + +- création du canevas de projet (arborescence + fichiers) +- écrans WebUI détaillés +- moteur d’import OPNsense (CSV/XML → JSON) +- génération automatique des configurations Kea / Unbound / nftables + +--- + +FIN DU DOCUMENT + diff --git a/prompt.md b/prompt.md new file mode 100644 index 0000000..679918d --- /dev/null +++ b/prompt.md @@ -0,0 +1,248 @@ +# prompt.md — Développement NetUI (Debian 13 / Passerelle LAN→Internet) + +## Contexte + +Tu es un assistant de développement (compatible Codex et Claude Code). Tu m’aides à construire une application **NetUI** : une **WebUI** d’administration réseau pour une **VM Debian 13 (Trixie)** jouant le rôle de **passerelle LAN → Internet** (NAT + pare-feu + DHCP + DNS). + +Le serveur est une VM Proxmox nommée côté hyperviseur `mon-reseau`, mais **le nom système Debian** est : +- **hostname** : `server-home` +- **domaine** : `home` +- **FQDN** : `server-home.home` + +Je me connecte en **SSH via VS Code** sur la VM. + +### Contraintes impératives + +1) **Aucun dépôt tiers** : uniquement les paquets des dépôts officiels Debian 13. +2) L’application doit utiliser **uniquement les outils réseau standard Debian**. +3) La WebUI est en **français**, pensée pour des **utilisateurs novices** : + - libellés explicites + - explications claires en info-bulles (tooltips) + - **éviter les acronymes** ; si un terme technique est nécessaire, l’expliquer en toutes lettres. +4) L’application est servie via **Nginx**. +5) L’accès WebUI est **limité au réseau local (LAN)**. +6) Au début (V1), on accepte une approche **permissive** sur les droits (sudo large), puis on durcira. +7) L’utilisateur système est **`gilles`** (ne pas créer de nouvel utilisateur). +8) Le dépôt Git est sur mon Gitea : `https://gitea.maison43.duckdns.org/gilles/netui.git` + +--- + +## Périmètre fonctionnel V1 (à livrer) + +NetUI V1 est composée de modules/pages : + +1) **Réseau** (WAN/LAN) + - afficher l’état : adresses, routes, passerelle, serveurs de noms + - configurer WAN (adresse automatique ou fixe) + - configurer LAN (adresse fixe, domaine local) + +2) **Pare-feu et partage de connexion** + - configuration **nftables** : règles de base + NAT + - mode novice : interrupteurs simples et règles prédéfinies compréhensibles + +3) **Attribution d’adresses (DHCP)** + - serveur DHCP : **Kea DHCPv4** + - plages dynamiques, exclusions, réservations (adresse fixe par appareil) + - liste des appareils connectés (baux) + +4) **Noms (DNS)** + - serveur DNS local : **Unbound** + - serveurs amont, entrées locales (nom → adresse) + +5) **Services** + - page dédiée pour : installer (via `apt`), activer au démarrage, démarrer/arrêter + - services concernés V1 : nftables, kea-dhcp4-server, unbound, chrony + +6) **Journaux (Logs)** + - afficher les logs des services avec filtres (date, texte, niveau) + - source : `journalctl` + +7) **Activité réseau** + - afficher connexions actives (LAN → Internet) en langage clair + - afficher activité DNS (qui demande quel nom) + - afficher événements pare-feu (autorisé / bloqué) + - sources : `conntrack`, logs Unbound, logs nftables + +8) **Migration DHCP sans casser le réseau** + - fonction d’import **depuis OPNsense** (CSV et XML) et **JSON** + - tout est normalisé vers un **format JSON canonique interne** + - génération de réservations DHCP à partir de l’import + - aucune application automatique sans validation + +--- + +## Paquets Debian (référence) + +Paquets attendus (installation manuelle possible) : +- WebUI/Backend : `nginx`, `python3`, `python3-venv`, `python3-pip` +- Réseau : `iproute2`, `systemd-networkd`, `systemd-resolved` +- Pare-feu/NAT : `nftables` +- Connexions : `conntrack` +- DHCP : `kea-dhcp4-server` +- DNS : `unbound` +- Temps : `chrony` +- Logs/diag : `rsyslog`, `tcpdump`, `ethtool` +- Dev : `git` + +--- + +## Architecture technique souhaitée + +### Serveur web +- Nginx sert le **frontend statique** et reverse-proxy `/api/` vers le backend. +- Le backend écoute sur `127.0.0.1:8000`. +- Nginx est configuré pour autoriser uniquement le réseau LAN (allow/deny). + +### Backend +- Langage : **Python** +- Framework : **FastAPI** +- Validation : Pydantic +- Génération de configuration : templates + rendu +- Stockage config : fichier unique **source de vérité** : `/etc/netui/config.yaml` + +### Frontend +- Simple : HTML/CSS/JS (pas de SPA lourde) +- Interface par **onglets** +- Style : **Gruvbox dark seventies** (contraste élevé, lisible) + +### Exécution et droits (V1) +- Le backend est lancé sous l’utilisateur `gilles`. +- Les opérations système se font via `sudo` (V1 permissif). +- Ne pas activer automatiquement les services réseau tant que l’utilisateur n’a pas cliqué « Appliquer ». + +--- + +## Exigences UX (très important) + +- Tout champ de formulaire doit avoir : + - un libellé clair + - un exemple + - une info-bulle expliquant « à quoi ça sert » +- Bannière « Mode test » si la configuration n’est pas appliquée. +- Boutons distincts : + - **Générer** (préparer fichiers sans appliquer) + - **Tester** (vérifier syntaxe/cohérence) + - **Appliquer** (écrire + recharger services) +- Messages d’erreur en français, orientés solution. + +--- + +## Règles de sécurité et de robustesse + +1) **Jamais deux serveurs DHCP actifs** sur le LAN. +2) Appliquer une configuration en deux phases : + - écrire dans un répertoire de staging + - tester : + - Kea : validation de config + - nftables : validation (`nft -c`) + - unbound : validation (`unbound-checkconf`) + - basculer et recharger +3) Toujours prévoir un rollback (V2), mais en V1 au minimum : sauvegarde du dernier état avant « Appliquer ». +4) Journaliser toute action (qui / quoi / quand). + +--- + +## Imports DHCP depuis OPNsense + +### Objectif +Conserver les adresses IP existantes en important des réservations/baux puis en générant des réservations DHCP Kea. + +### Sources d’import +- **OPNsense CSV** (baux ou réservations) +- **OPNsense XML** (export config) +- **JSON** (format pivot) + +### Format JSON canonique interne (à utiliser partout) + +```json +{ + "source": "opnsense", + "interface": "lan", + "reservations": [ + { + "nom": "nas", + "adresse_ip": "10.0.0.10", + "adresse_materielle": "AA:BB:CC:DD:EE:01" + } + ] +} +``` + +Exigences import : +- mapping automatique des colonnes quand possible +- affichage d’une prévisualisation +- validation : doublons IP, doublons MAC, IP hors réseau + +--- + +## Plan de développement (ordre recommandé) + +1) **Squelette repo** + README installation +2) Backend FastAPI minimal : + - `/health` + - `/system/info` (hostname, FQDN, interfaces) +3) Page **Services** : + - détecter installé / actif / en cours + - start/stop/enable/disable +4) Page **Journaux** : + - lecture via `journalctl` + filtres +5) Page **Réseau (lecture seule)** : IP, routes, DNS +6) Module **Pare-feu/NAT** : générer ruleset minimal + test + apply +7) Module **DHCP Kea** : génération config minimale + apply + liste baux +8) Module **DNS Unbound** : config minimale + apply + overrides +9) Module **Activité réseau** : connexions + DNS + pare-feu +10) Module **Import OPNsense** : CSV/XML/JSON → canonique → réservations + +--- + +## Ce que tu dois produire (attendu de l’assistant) + +Quand je te demande de développer, tu dois : + +1) Proposer une arborescence claire (si nécessaire). +2) Écrire du code complet et exécutable. +3) Ajouter des validations et messages d’erreurs clairs. +4) Indiquer exactement quelles commandes exécuter. +5) Fournir des fichiers prêts à coller : + - Nginx site + - systemd service (optionnel en dev) + - scripts d’application (même permissifs en V1) + +--- + +## Règles de style (documentation et UI) + +- Tout est en français. +- Aucun acronyme sans explication (ex : « passerelle (routeur) »). +- Ton ton doit être direct, structuré, et orienté actions. + +--- + +## Commandes utiles (référence) + +- État réseau : `ip -4 a`, `ip route` +- Services : `systemctl status ` +- Logs : `journalctl -u --since ...` +- nftables (test) : `nft -c -f ` +- unbound (test) : `unbound-checkconf ` +- Connexions : `conntrack -L` + +--- + +## Questions à ne PAS poser (déjà tranché) + +- Pas de dépôt tiers. +- Debian 13. +- Nginx obligatoire. +- Modules V1 validés. +- Utilisateur unique : `gilles`. + +--- + +## Démarrage immédiat + +Commence par vérifier l’état du dépôt (arborescence actuelle) et propose : +- un premier commit « squelette backend + frontend + nginx » +- une commande unique de lancement en mode développement +- une première page WebUI (onglets) et une API `/health`. + diff --git a/specification_technique.md b/specification_technique.md new file mode 100644 index 0000000..d7ae92b --- /dev/null +++ b/specification_technique.md @@ -0,0 +1,204 @@ +# Spécification technique – WebUI Passerelle Réseau (V1) + +## 1. Objet du document + +Ce document décrit **la spécification technique détaillée** de la WebUI de passerelle réseau basée sur **Debian 13 (Trixie)**. +Il sert de référence pour le développement, l’architecture logicielle et les choix techniques. + +--- + +## 2. Contexte et périmètre + +### 2.1 Rôle de la VM + +- Passerelle réseau LAN → Internet +- Serveur DHCP principal du réseau local +- Serveur DNS local +- Pare-feu et traduction d’adresses (NAT) +- Point central de supervision réseau + +### 2.2 Contraintes + +- Debian 13 Trixie uniquement +- Dépôts officiels Debian uniquement +- Aucun conteneur +- WebUI accessible uniquement depuis le réseau local +- Architecture modulaire +- Pas d’automatisation dangereuse + +--- + +## 3. Architecture générale + +### 3.1 Vue d’ensemble + +Navigateur → HTTPS → Nginx → API Backend → Scripts système → Services Debian + +### 3.2 Composants + +- Frontend : HTML / CSS / JavaScript (léger) +- Serveur Web : Nginx +- Backend : Python (API REST) +- Services système : systemd +- Journalisation : journald + +--- + +## 4. Machine virtuelle (Proxmox) + +### 4.1 Ressources + +- CPU : 2 à 4 cœurs (type host) +- RAM : 4 Go (ballooning désactivé) +- Disque : 32 Go (VirtIO SCSI) +- Réseau : + - 1 interface WAN + - 1 interface LAN + +### 4.2 Règles importantes + +- Pare-feu Proxmox désactivé +- Pare-feu unique géré dans la VM + +--- + +## 5. Gestion réseau Debian + +### 5.1 Outils retenus + +- systemd-networkd : configuration des interfaces +- nftables : pare-feu et NAT +- conntrack : suivi des connexions + +### 5.2 Fonctions réseau + +- Routage IPv4 +- Traduction d’adresses (NAT) +- Séparation WAN / LAN + +--- + +## 6. Services réseau (V1) + +### 6.1 DHCP + +- Service : kea-dhcp4-server +- Fonctions : + - plages dynamiques + - réservations fixes + - options DHCP (routeur, DNS, serveur de temps) + +### 6.2 DNS + +- Service : unbound +- Fonctions : + - cache DNS + - serveurs amont configurables + - entrées statiques nom → adresse + +### 6.3 Pare-feu + +- Service : nftables +- Fonctions : + - protection de la VM + - autorisation LAN → Internet + - blocage administration depuis Internet + +### 6.4 Services annexes + +- chrony : synchronisation de l’heure + +--- + +## 7. Backend API + +### 7.1 Principes + +- Backend non exécuté en root +- Utilisateur système dédié +- Appels système via sudo (phase V1 permissive) + +### 7.2 Responsabilités + +- Lecture / écriture de la configuration centrale +- Génération des fichiers de configuration système +- Validation avant application +- Application contrôlée des changements + +--- + +## 8. Configuration centrale + +### 8.1 Source de vérité + +- Fichier unique : /etc/netui/config.yaml + +### 8.2 Contenu + +- paramètres réseau WAN / LAN +- configuration DHCP +- configuration DNS +- état des services + +--- + +## 9. WebUI + +### 9.1 Organisation + +- Onglets +- Formulaires simples +- Textes explicatifs sous chaque champ +- Info-bulles détaillées + +### 9.2 Pages V1 + +- Tableau de bord +- Réseau +- Pare-feu / Partage de connexion +- Attribution d’adresses (DHCP) +- Noms (DNS) +- Services +- Journaux +- Activité réseau + +--- + +## 10. Import des adresses existantes + +### 10.1 Objectif + +- Conserver les adresses IP existantes lors du remplacement DHCP + +### 10.2 Sources supportées + +- OPNsense CSV +- OPNsense XML +- Fichier JSON + +### 10.3 Format interne + +- Normalisation vers un format JSON canonique + +--- + +## 11. Sécurité + +- Accès WebUI limité au LAN +- Authentification locale +- Validation stricte des données +- Aucune application automatique + +--- + +## 12. Évolutions prévues (hors V1) + +- VPN WireGuard +- QoS / limitation de débit +- Découverte réseau (mDNS) +- Historique et rollback avancé + +--- + +Fin de la spécification technique + diff --git a/todo.md b/todo.md new file mode 100644 index 0000000..4319a3d --- /dev/null +++ b/todo.md @@ -0,0 +1,142 @@ +# TODO – WebUI Passerelle Réseau (V1) + +Ce fichier liste les **tâches à réaliser**, dans l’ordre recommandé, pour développer la version V1 du projet. + +--- + +## 1. Préparation + +- [ ] Créer le dépôt Git du projet +- [ ] Définir l’arborescence (frontend / backend / deploy) +- [ ] Créer l’utilisateur système dédié à l’application + +--- + +## 2. Infrastructure de base + +- [ ] Installer Debian 13 dans la VM +- [ ] Installer Nginx +- [ ] Installer Python et environnement virtuel +- [ ] Configurer Nginx (accès LAN uniquement) +- [ ] Créer le service systemd du backend + +--- + +## 3. Backend – Squelette API + +- [ ] Créer l’API (endpoint /health) +- [ ] Mettre en place l’authentification simple +- [ ] Restreindre l’accès par adresse IP LAN +- [ ] Mettre en place la lecture des états systemd + +--- + +## 4. Page Services + +- [ ] Détection des paquets installés +- [ ] Installation contrôlée via apt (liste blanche) +- [ ] Démarrage / arrêt / activation des services +- [ ] Affichage clair de l’état + +--- + +## 5. Journaux + +- [ ] Lecture des journaux via journalctl +- [ ] Filtrage par service +- [ ] Filtrage par période +- [ ] Recherche texte + +--- + +## 6. Réseau (lecture seule – phase initiale) + +- [ ] Afficher interfaces WAN / LAN +- [ ] Afficher adresses IP et routes +- [ ] Vérifier connectivité Internet + +--- + +## 7. Pare-feu et partage de connexion + +- [ ] Générer un ruleset nftables minimal +- [ ] Tester la configuration (mode test) +- [ ] Appliquer le pare-feu +- [ ] Activer le NAT LAN → Internet + +--- + +## 8. DHCP (Kea) + +- [ ] Générer configuration DHCP minimale +- [ ] Tester la configuration DHCP +- [ ] Activer le service Kea +- [ ] Afficher les baux DHCP actifs + +--- + +## 9. DNS (Unbound) + +- [ ] Générer configuration DNS minimale +- [ ] Tester la configuration Unbound +- [ ] Activer le service +- [ ] Lire les journaux DNS + +--- + +## 10. Import des adresses existantes + +- [ ] Import CSV OPNsense +- [ ] Import XML OPNsense +- [ ] Import JSON générique +- [ ] Normalisation interne +- [ ] Validation et prévisualisation +- [ ] Génération réservations DHCP + +--- + +## 11. WebUI + +- [ ] Créer la structure des onglets +- [ ] Implémenter les formulaires réseau +- [ ] Ajouter textes explicatifs et info-bulles +- [ ] Afficher les messages d’erreur clairs + +--- + +## 12. Activité réseau + +- [ ] Afficher connexions actives (conntrack) +- [ ] Associer connexions aux appareils DHCP +- [ ] Afficher requêtes DNS +- [ ] Afficher événements du pare-feu + +--- + +## 13. Sécurité et validation + +- [ ] Vérifier aucune action automatique dangereuse +- [ ] Ajouter confirmations avant application +- [ ] Sauvegarde automatique avant modification + +--- + +## 14. Tests + +- [ ] Test en mode passif +- [ ] Test DHCP en fenêtre contrôlée +- [ ] Test remplacement DHCP +- [ ] Test rollback + +--- + +## 15. Documentation + +- [ ] Compléter la documentation utilisateur +- [ ] Ajouter captures d’écran +- [ ] Rédiger guide de migration DHCP + +--- + +Fin du TODO V1 +