From: Giorgio Ravera Date: Sat, 24 Jan 2026 14:53:23 +0000 (+0100) Subject: Updated TODO.md and README.md X-Git-Tag: v0.0.1~27 X-Git-Url: http://git.giorgioravera.it/?a=commitdiff_plain;h=3627c1c11bb77393706e29867b98bb1915a1e835;p=network-manager.git Updated TODO.md and README.md --- diff --git a/README.md b/README.md index f974b24..144867e 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,46 @@ # Network Manager -## 🌐 Webapp di gestione rete +## 🌐 Network management web app -Una **webapp unificata per il controllo completo dell’infrastruttura di rete**, progettata come frontend integrato per **BIND** (DNS), **Kea DHCP** e con supporto automatico ai certificati **Let’s Encrypt**. +A **unified web app for complete control of your network infrastructure**, designed as an integrated frontend for **BIND** (DNS), **Kea DHCP**, and with automatic support for **Let’s Encrypt** certificates. -L’applicazione include: +The application includes: -- **Frontend integrato** -- **Autenticazione amministratore** -- **Database SQLite** semplice e leggero -- **Generazione automatica** delle configurazioni DNS e DHCP a partire da un dominio definito -- **Versioning locale** delle configurazioni, con storico modifiche e possibilità di rollback +- **Integrated frontend** +- **Administrator authentication** +- Simple and lightweight **SQLite database** +- **Automatic generation** of DNS and DHCP configurations from a defined domain +- **Local versioning** of configurations, with change history and rollback capability -Questa soluzione permette di gestire host, zone DNS, leases DHCP e certificati da un’unica interfaccia centralizzata, riducendo errori manuali e semplificando enormemente l’operatività. +This solution allows you to manage hosts, DNS zones, DHCP leases, and certificates from a single centralized interface, reducing manual errors and greatly simplifying operations. -Progettato per essere eseguito facilmente tramite **Docker** e **Docker Compose**, con configurazione tramite variabili d’ambiente. +Designed to run easily via **Docker** and **Docker Compose**, with configuration via environment variables. + +This project is currently under development. For upcoming tasks and planned improvements, please refer to the [TODO list](TODO.list) file. --- -## ✨ Caratteristiche +## ✨ Features -- Frontend statico servito dall’applicazione (`FRONTEND_DIR`) -- Database SQLite persistente (`/data/database.db`) -- Logging configurabile su console e/o file -- Protezione login con rate-limit configurabile -- Credenziali admin configurabili tramite env o Docker secrets -- Supporto per `SESSION_SECRET`: chiave personalizzata per i cookie (se mancante viene generata automaticamente) +- Static frontend served by the application (`FRONTEND_DIR`) +- Persistent SQLite database (`/data/database.db`) +- Configurable logging to console and/or file +- Login protection with configurable rate-limit +- Admin credentials configurable via env or Docker secrets +- Support for `SESSION_SECRET`: custom key for cookies (if missing, it is generated automatically) --- -## 📦 Requisiti +## 📦 Requirements - Docker = 20.x - Docker Compose = v2 --- -## 🚀 Avvio rapido +## 🚀 Quick start -### 1) Struttura consigliata +### 1) Recommended structure ``` project/ +- docker-compose.yml @@ -48,7 +50,7 @@ project/ +- data/ ``` -### 2) ⚙️ Configurazione tramite `.env` (opzionale) +### 2) ⚙️ Configuration via `.env` (optional) ```dotenv # --- Host & Web --- DOMAIN=example.com @@ -57,19 +59,19 @@ HTTP_PORT=8000 # --- Admin --- ADMIN_USER=admin ADMIN_PASSWORD=admin -# In produzione usa ADMIN_PASSWORD_HASH_FILE +# In production use ADMIN_PASSWORD_HASH_FILE # --- Login rate limit --- LOGIN_MAX_ATTEMPTS=5 LOGIN_WINDOW_SECONDS=600 # --- Log --- LOG_LEVEL=INFO LOG_TO_FILE=false -# --- Session secret (opzionale ma consigliato in produzione) --- +# --- Session secret (optional but recommended in production) --- # SESSION_SECRET=****ReplaceWithYourSecret***** ``` -Se SESSION_SECRET non è impostato, l’app genera una chiave casuale ad ogni riavvio -> le sessioni esistenti diventano invalide. +If SESSION_SECRET is not set, the app generates a random key on each restart -> existing sessions become invalid. -### 3) 🐳 `docker-compose.yml` di esempio +### 3) 🐳 Example `docker-compose.yml` ```yaml services: network-manager: @@ -114,46 +116,46 @@ secrets: --- -## 🔧 Variabili d’ambiente supportate -| Variabile | Default | Descrizione | -|----------|-------------|----------| -| `FRONTEND_DIR` | /app/frontend | Directory del frontend | -| `DB_FILE` | /data/database.db | File SQLite | -| `DB_RESET` | false | Reset DB a ogni avvio | -| `LOG_LEVEL` | info | Livello log | -| `LOG_TO_FILE` | false | Abilita logging su file | -| `LOG_FILE` | /data/app.log | File log applicativo | -| `LOG_ACCESS_FILE` | /data/access.log | Access log HTTP | -| `DOMAIN` | example.com | Dominio pubblico | -| `PUBLIC_IP` | 127.0.0.1 | IP pubblico | -| `HTTP_PORT` | 8000 | Porta HTTP interna | -| `LOGIN_MAX_ATTEMPTS` | 5 | Tentativi login | -| `LOGIN_WINDOW_SECONDS` | 600 | Finestra tentativi | -| `ADMIN_USER` | admin | Username admin | -| `ADMIN_PASSWORD` | admin | Password admin (sviluppo) | -| `ADMIN_PASSWORD_HASH_FILE` | /run/secrets/admin_password_hash | Hash password admin | -| `SESSION_SECRET` | (auto‑generata) | Secret sessione | +## 🔧 Supported environment variables +| Variable | Default | Description | +|----------|---------|-------------| +| `FRONTEND_DIR` | /app/frontend | Frontend directory | +| `DB_FILE` | /data/database.db | SQLite file | +| `DB_RESET` | false | Reset DB on every startup | +| `LOG_LEVEL` | info | Log level | +| `LOG_TO_FILE` | false | Enable file logging | +| `LOG_FILE` | /data/app.log | Application log file | +| `LOG_ACCESS_FILE` | /data/access.log | HTTP access log | +| `DOMAIN` | example.com | Public domain | +| `PUBLIC_IP` | 127.0.0.1 | Public IP | +| `HTTP_PORT` | 8000 | Internal HTTP port | +| `LOGIN_MAX_ATTEMPTS` | 5 | Login attempts | +| `LOGIN_WINDOW_SECONDS` | 600 | Attempt window | +| `ADMIN_USER` | admin | Admin username | +| `ADMIN_PASSWORD` | admin | Admin password (development) | +| `ADMIN_PASSWORD_HASH_FILE` | /run/secrets/admin_password_hash | Admin password hash | +| `SESSION_SECRET` | (auto-generated) | Session secret | --- -## 🔐 Gestione credenziali admin -### ✔ Sviluppo: usare variabili +## 🔐 Admin credential management +### ✔ Development: use variables ```bash ADMIN_USER=admin ADMIN_PASSWORD=admin ``` -### ✔ Produzione: usare Docker secrets +### ✔ Production: use Docker secrets ```bash -python - <<'PY' +python - <<‘PY’ import bcrypt -pwd = b"PasswordSicura" +pwd = b“SecurePassword” print(bcrypt.hashpw(pwd, bcrypt.gensalt()).decode()) PY ``` -Salvare l’hash in `./secrets/admin_password_hash`. +Save the hash in `./secrets/admin_password_hash`. -Docker compose lo monterà in: +Docker compose will mount it in: ``` /run/secrets/admin_password_hash ``` @@ -161,20 +163,20 @@ Docker compose lo monterà in: --- ## 🔑 SESSION_SECRET -Serve a firmare i cookie. -Se impostato, l’app genera una chiave nuova ogni volta e tutte le sessioni decadono ad ogni restart. -Genera un secret forte: +Used to sign cookies. +If set, the app generates a new key each time and all sessions expire on each restart. +Generate a strong secret: ```bash openssl rand -base64 64 ``` -Poi: -SESSION_SECRET: "incolla-il-secret-qui" +Then: +SESSION_SECRET: “paste-the-secret-here” --- -## 💾 Persistenza +## 💾 Persistence ### Database + Log -Mappare `/data` come volume: +Map `/data` as a volume: ```yaml volumes: - ./data:/data @@ -182,12 +184,12 @@ volumes: --- -## 📌 Comandi utili -Avvio normale: +## 📌 Useful commands +Normal startup: ```bash docker compose up ``` -In background: +In the background: ```bash docker compose up -d ``` @@ -195,15 +197,15 @@ Log: ```bash docker compose logs -f network-manager ``` -Ricreare il container: +Container rebuild/recreation: ```bash docker compose up -d --force-recreate ``` --- -## 🔒 Checklist Sicurezza -- Usare *ADMIN_PASSWORD_HASH_FILE* in produzione -- Disabilitare *SESSION_SECRET* per generazione automatica -- Impostare secure=True sui cookie se usi HTTPS -- Usare un reverse proxy con TLS -- Non mettere password nel repository \ No newline at end of file +## 🔒 Security Checklist +- Use *ADMIN_PASSWORD_HASH_FILE* in production +- Disable *SESSION_SECRET* for automatic generation +- Set secure=True on cookies if you use HTTPS +- Use a reverse proxy with TLS +- Do not put passwords in the repository diff --git a/TODO.md b/TODO.md index 6f976b2..4cf50c0 100644 --- a/TODO.md +++ b/TODO.md @@ -1,142 +1,142 @@ -## 📝 To‑Do List / Workflow Operativo (Estesa) +## 📝 To-Do List / Operational Workflow (Extended) --- -### 🔄 Gestione DB all’avvio +### 🔄 DB management at startup -- [ ] **Se il database è vuoto** - - Importare YAML iniziale - - Popolare il database +- [ ] **If the database is empty** + - Import initial YAML + - Populate the database -- [ ] **Se il database esiste** - - Ignorare YAML **a meno che il file del repository sia cambiato** - - Se YAML è variato → aggiornare il DB +- [ ] **If the database exists** + - Ignore YAML **unless the repository file has changed** + - If YAML has changed → update the DB --- -### 🛠️ Aggiornamenti effettuati dalla Webapp +### 🛠️ Updates made by the Webapp -- [ ] Applicare modifiche al database -- [ ] Rigenerare YAML dal DB -- [ ] Effettuare **commit + push** su Git -- [ ] Rigenerare **da zero**: - - [ ] Configurazione **BIND (DNS)** - - [ ] Configurazione **Kea (DHCP)** -- [ ] Eseguire reload dei servizi: +- [ ] Apply changes to the database +- [ ] Regenerate YAML from the DB +- [ ] Perform **commit + push** on Git +- [ ] Regenerate **from scratch**: + - [ ] **BIND (DNS)** configuration + - [ ] **Kea (DHCP)** configuration +- [ ] Reload services: - [ ] BIND - [ ] Kea --- -### 🔍 YAML ↔ DB Coerenza Periodica +### 🔍 YAML ↔ DB Periodic Consistency -- [ ] Calcolare **checksum atteso** YAML -- [ ] Confrontare con **checksum reale** -- [ ] Determinare quale elemento è variato +- [ ] Calculate YAML **expected checksum** +- [ ] Compare with **actual checksum** +- [ ] Determine which element has changed -#### Regole di sincronizzazione -- [ ] YAML cambiato → aggiornare DB -- [ ] DB cambiato → rigenerare YAML +#### Synchronization rules +- [ ] YAML changed → update DB +- [ ] DB changed → regenerate YAML --- -## 🧩 Generazione configurazioni +## 🧩 Configuration Generation ### 🧪 BIND (DNS) -- [ ] Ricostruire zone forward e reverse -- [ ] Ricostruire tutti i record (A, AAAA, CNAME) -- [ ] Validazione sintassi (`named-checkconf`, `named-checkzone`) -- [ ] Gestione rollback in caso di errori +- [ ] Rebuild forward and reverse zones +- [ ] Rebuild all records (A, AAAA, CNAME) +- [ ] Syntax validation (`named-checkconf`, `named-checkzone`) +- [ ] Rollback management in case of errors ### 🧪 Kea (DHCP) -- [ ] Rigenerare subnet, pool, opzioni globali e host reservations -- [ ] Validare config JSON (`kea-dhcp4 -t`) -- [ ] Rollback se la sintassi non è valida +- [ ] Regenerate subnets, pools, global options, and host reservations +- [ ] Validate JSON configuration (`kea-dhcp4 -t`) +- [ ] Rollback if syntax is invalid --- -## 🧭 Versioning Git +## 🧭 Git versioning -- [ ] Controllare modifiche locali (`git status`) -- [ ] Applicare commit automatico con messaggi standard -- [ ] Push verso il repository remoto -- [ ] Tenere traccia delle versioni YAML generate -- [ ] Usare Git come audit delle modifiche +- [ ] Check local changes (`git status`) +- [ ] Apply automatic commit with standard messages +- [ ] Push to remote repository +- [ ] Keep track of generated YAML versions +- [ ] Use Git as an audit of changes --- -## 🩺 Controllo Servizi (Health Check) +## 🩺 Service Check (Health Check) ### 🔎 BIND -- [ ] Controllo stato servizio -- [ ] Verifica log per errori +- [ ] Service status check +- [ ] Check logs for errors ### 🔎 Kea -- [ ] Controllo stato DHCP4/DHCP6 -- [ ] Verifica errori da log agent +- [ ] DHCP4/DHCP6 status check +- [ ] Check agent logs for errors --- -# 🔐 Hardening Sicurezza Web +# 🔐 Web Security Hardening -### 🔒 Sessioni & Cookie -- [ ] Impostare `secure=True` quando si usa HTTPS -- [ ] Impostare `httponly=True` per prevenire accesso via JS -- [ ] Impostare `samesite=Strict` o `Lax` a seconda dell’uso -- [ ] Rotazione controllata di `SESSION_SECRET` (manuale o programmata) +### 🔒 Sessions & Cookies +- [ ] Set `secure=True` when using HTTPS +- [ ] Set `httponly=True` to prevent access via JS +- [ ] Set `samesite=Strict` or `Lax` depending on use +- [ ] Controlled rotation of `SESSION_SECRET` (manual or scheduled) -### 🛡 Protezione HTTP -- [ ] Headers di sicurezza: +### 🛡 HTTP Protection +- [ ] Security headers: - [ ] `Content-Security-Policy` - [ ] `Strict-Transport-Security` - [ ] `X-Frame-Options` - [ ] `X-Content-Type-Options` - [ ] `Referrer-Policy` -- [ ] Abilitare TLS tramite reverse proxy -- [ ] Rate limiting aggiuntivo su IP e endpoint sensibili +- [ ] Enable TLS via reverse proxy +- [ ] Additional rate limiting on sensitive IPs and endpoints -### 🔥 Protezione applicativa -- [ ] Validazione input DNS/DHCP (hostname, IP, subnet) -- [ ] Sanitizzazione input contro injection YAML/XML/JSON -- [ ] Audit log delle modifiche critiche -- [ ] Protezione contro brute force (ce l’hai già 👍) +### 🔥 Application protection +- [ ] DNS/DHCP input validation (hostname, IP, subnet) +- [ ] Input sanitization against YAML/XML/JSON injection +- [ ] Audit log of critical changes +- [ ] Brute force protection (you already have this 👍) ### 🔧 Backup & Recovery -- [ ] Backup periodico del DB SQLite -- [ ] Backup del repository Git su remoto -- [ ] Backup delle configurazioni generate +- [ ] Periodic backup of SQLite DB +- [ ] Remote Git repository backup +- [ ] Backup of generated configurations --- -# 👥 Gestione Utenti (RBAC) +# 👥 User Management (RBAC) -### 🎛 Ruoli previsti -- [ ] **admin** — accesso completo a tutto -- [ ] **operator** — può modificare host/DNS/DHCP ma non gestione utenti -- [ ] **viewer** — sola lettura +### 🎛 Planned roles +- [ ] **admin** — full access to everything +- [ ] **operator** — can modify host/DNS/DHCP but not user management +- [ ] **viewer** — read-only -### 🧩 Funzionalità da implementare -- [ ] Creazione utenti -- [ ] Reset password -- [ ] Disabilitazione utenti -- [ ] Cambio password admin -- [ ] Autenticazione basata su hash (bcrypt o argon2) -- [ ] Audit log (chi ha fatto cosa, quando) -- [ ] Timeout sessioni -- [ ] Protezione contro session hijacking -- [ ] Logout globale / invalidazione sessioni +### 🧩 Features to be implemented +- [ ] User creation +- [ ] Password reset +- [ ] User disabling +- [ ] Admin password change +- [ ] Hash-based authentication (bcrypt or argon2) +- [ ] Audit log (who did what, when) +- [ ] Session timeout +- [ ] Protection against session hijacking +- [ ] Global logout / session invalidation --- -# ⭐ Checklist finale - -- [ ] Gestione DB ↔ YAML completa -- [ ] Generazione BIND/Kea con validazione & rollback -- [ ] Versioning Git -- [ ] Health-check BIND/Kea -- [ ] Hardening sicurezza web -- [ ] Gestione utenti + ruoli -- [ ] Notifiche (email/webhook) -- [ ] Backup DB + backup Git -- [ ] Test automatici +# ⭐ Final checklist + +- [ ] Complete DB ↔ YAML management +- [ ] BIND/Kea generation with validation & rollback +- [ ] Git versioning +- [ ] BIND/Kea health check +- [ ] Web security hardening +- [ ] User + role management +- [ ] Notifications (email/webhook) +- [ ] DB backup + Git backup +- [ ] Automatic tests