AuditShield/plan.md

AuditShield — Plan de développement

Vue d'ensemble

Outil d'audit infrastructure et sécurité pour clients MSP. Scans réseau + vulnérabilités + pentest → rapports PDF compréhensibles pour non-techniciens.

---

✅ Phase 1 — Socle (terminée)

Branche : feature/phase-1-socle (PR ouverte, pas encore mergée dans dev)

Ce qui a été créé

Backend (FastAPI + SQLAlchemy)

• backend/core/ — config (pydantic-settings), database (SQLAlchemy 2.0), security (JWT + bcrypt)
• backend/models/ — 7 modèles : User, Client, Audit, Cible, Vulnérabilité, Action + TimestampMixin
• backend/schemas/ — Pydantic v2 : UserCreate/Read, ClientCreate/Update/Read, AuditCreate/Update/Read/Detail, CibleCreate/Read, VulnerabiliteCreate/Read, ActionCreate/Update/Read
• backend/api/auth.py — POST /register, POST /login (OAuth2), GET /me
• backend/api/clients.py — CRUD complet (GET list, POST, GET/{id}, PATCH/{id}, DELETE/{id})
• backend/api/audits.py — CRUD audit + nested : cibles (add/valider), vulnérabilités (add), actions (add/update)
• backend/main.py — FastAPI app, CORS (localhost:3000), rate limiting (slowapi), docs /api/docs en DEBUG
• backend/alembic/ — migrations configurées (env.py prêt avec models importés)
• backend/tests/test_auth.py — test async register + login avec SQLite in-memory

Frontend (Next.js 14 App Router)

• Route groups : (auth) pour login, (dashboard) pour pages protégées
• app/(auth)/login/page.tsx — formulaire login avec gestion JWT
• app/(dashboard)/layout.tsx — guard auth (redirect /login), layout sidebar + main
• app/(dashboard)/dashboard/page.tsx — 4 stat cards + 5 audits récents
• app/(dashboard)/clients/page.tsx — grille clients avec recherche
• app/(dashboard)/audits/page.tsx — liste audits avec badges statut + recherche
• components/layout/sidebar.tsx — navigation (Dashboard, Clients, Audits) + déconnexion
• components/ui/ — Button (CVA variants), Card, Input, Label, Badge (+ variantes criticité)
• lib/api.ts — client fetch générique typé : authApi, clientsApi, auditsApi
• lib/auth.ts — helpers localStorage pour token JWT

Infrastructure

• docker/docker-compose.yml — config prod : images registry + labels Traefik + Let's Encrypt (utilisé par Gitea Actions)
• docker/docker-compose.prod.yml — alias prod identique (gardé pour référence)
• backend/Dockerfile — Python 3.11-slim + WeasyPrint deps + alembic upgrade
• frontend/Dockerfile — multi-stage Node 20 (deps → builder → runner standalone)
• .env.example — toutes les variables documentées

Décisions techniques

Décision	Raison
SQLAlchemy 2.0 avec type hints Mapped[]	API moderne, meilleure inference TypeScript équivalente côté Python
Pydantic v2 séparé des modèles ORM	Découplage validation/persistance, évite circular imports
JWT HS256 + 24h expiration	Simple à implémenter, stateless, suffisant pour MVP
slowapi pour rate limiting	Compatible FastAPI/Starlette, minimal
TimestampMixin	DRY pour created_at/updated_at sur tous les modèles
Cascade delete	Intégrité référentielle (supprimer client → supprime tout)
Celery + Redis (infra seulement)	Prêt pour les jobs asynchrones de scan (Phase 2)
Next.js App Router + route groups	Layouts différents auth/dashboard sans duplication
shadcn/ui + Radix	Accessibilité, composants non-opinionnés, facilement personnalisables
JWT dans localStorage	Simple pour MVP — à migrer vers HttpOnly cookie en Phase 3
camelCase pour types TS, snake_case en DB	Convention JS vs convention Python/SQL
Rewrites next.config.mjs vers backend	Pas de CORS en prod, tout passe par Next.js

État fonctionnel

• ✅ Register/Login utilisateur avec JWT
• ✅ CRUD clients complet
• ✅ CRUD audits + cibles + vulnérabilités + actions
• ✅ Dashboard avec stats temps réel
• ✅ Pages liste clients et audits avec recherche
• ✅ Guard auth côté frontend
• ✅ Docker prod prêt (docker-compose.yml = config prod images registry + Traefik)
• ⏳ Pages de formulaire (création/édition) non créées
• ⏳ Pages détail client et audit non créées
• ⏳ Scanners : dossier vide (placeholder Phase 2)
• ⏳ Génération PDF : dossier vide (placeholder Phase 4)

---

🔲 Phase 2 — Scanners réseau (Nmap)

Branche : feature/phase-2-nmap

Objectif

Permettre le lancement d'un scan Nmap sur des cibles validées, afficher les résultats en temps réel, et les persister en base.

Tâches backend

• Celery worker — configurer backend/celery_app.py, worker Docker dans docker-compose
• Scanner Nmap — backend/scanners/nmap.py
  • Wrapper autour de python-nmap
  • Parse les résultats : ports ouverts, services, OS
  • Vérification que la cible est validee = True avant tout scan
  • Log de chaque scan en BDD (model ScanLog)
• Model ScanLog — backend/models/scan_log.py
  • audit_id, cible_id, type_scan, statut, résultat (JSON), durée
• Tâche Celery — backend/scanners/tasks.py
  • task_scan_nmap(audit_id, cible_ids) — async, met à jour statut
  • Retour des résultats via polling ou WebSocket
• Routes scan — backend/api/scans.py
  • POST /audits/{audit_id}/scans/nmap — lance le scan (en background)
  • GET /audits/{audit_id}/scans — liste les scans passés
  • GET /audits/{audit_id}/scans/{scan_id} — détail d'un scan
• Parsing Nmap → Vulnérabilités — déduire des vulnérabilités simples (ports dangereux, services obsolètes)

Tâches frontend

• Page détail audit — app/(dashboard)/audits/[id]/page.tsx
  • Affiche : infos audit, liste cibles (avec bouton "Valider"), liste vulnérabilités, liste actions
  • Bouton "Lancer un scan Nmap"
  • Statut du scan en temps réel (polling GET /scans)
• Page détail client — app/(dashboard)/clients/[id]/page.tsx
  • Infos client + liste des audits du client
  • Bouton "Nouvel audit"
• Formulaire nouveau client — app/(dashboard)/clients/nouveau/page.tsx
• Formulaire nouvel audit — app/(dashboard)/audits/nouveau/page.tsx
• Formulaire ajout cible — Modal ou inline dans détail audit
• Composant ScanStatus — affiche statut scan (en cours / terminé / erreur)
• Toast notifications — feedback utilisateur (succès, erreur)

Tâches infra

• Ajouter service worker dans docker-compose.yml (image backend + command: celery worker) — attention, c'est la config prod
• Ajouter python-nmap dans requirements.txt
• Première migration Alembic : alembic -c backend/alembic.ini revision --autogenerate -m "init"

---

🔲 Phase 3 — Vulnérabilités avancées + Actions

Branche : feature/phase-3-vulnerabilites

Objectif

Enrichissement des vulnérabilités avec CVE, scoring CVSS automatique, workflow de gestion des actions, et calcul du score global d'audit.

Tâches backend

• Intégration CVE/NVD — backend/scanners/cve.py
  • Lookup CVE via NVD API (gratuit)
  • Traduction automatique en langage clair (résumé simplifié)
  • Auto-remplissage criticité depuis CVSS score
• Calcul score global audit — méthode sur le model Audit
  • Pondération : critique × 4, important × 3, modéré × 2, faible × 1
  • Normalisé sur 10, mis à jour à chaque vulnérabilité ajoutée
• OpenVAS optionnel — backend/scanners/openvas.py
  • Wrapper GVM (Greenbone Vulnerability Management)
  • Si disponible, scan plus profond
• Notifications — model Notification, endpoint SSE ou WebSocket
  • Alertes nouvelles vulnérabilités critiques
  • Changements de statut d'action

Tâches frontend

• Page détail vulnérabilité — app/(dashboard)/audits/[id]/vulnerabilites/[vulnId]/page.tsx
  • Affiche : titre, criticité (badge coloré), CVE, CVSS, description, recommandation
  • Liste des actions liées + bouton "Ajouter une action"
  • Formulaire d'action inline
• Composant CriticiteBar — représentation visuelle du score global
• Page gestion des actions — tableau kanban simple (Ouvert → En cours → Résolu)
• Filtres et tri — sur les listes de vulnérabilités (par criticité, statut)
• Pagination — composant <Pagination> réutilisable

---

🔲 Phase 4 — Rapports PDF + Dashboard avancé

Branche : feature/phase-4-rapports

Objectif

Génération de rapports PDF professionnels compréhensibles par un dirigeant non-technique, et dashboard enrichi avec graphiques.

Tâches backend

• Moteur PDF — backend/reports/pdf.py
  • WeasyPrint + Jinja2 templates HTML
  • Template rapport : page de garde, résumé exécutif, score global, vulnérabilités par criticité, recommandations, plan d'actions
  • Langage client : pas de jargon technique, CVE traduits en langage clair
• Templates HTML — backend/reports/templates/
  • rapport_audit.html — template principal
  • _vulnerabilite.html — bloc par vulnérabilité
  • CSS intégré (compatible WeasyPrint)
• Route export — GET /audits/{audit_id}/rapport.pdf
  • Génère et streame le PDF
  • Header Content-Disposition: attachment
• Tâche Celery — génération PDF asynchrone pour audits longs

Tâches frontend

• Bouton "Exporter PDF" — dans la page détail audit
• Dashboard avancé — graphiques :
  • Répartition vulnérabilités par criticité (donut chart)
  • Évolution des audits dans le temps (line chart)
  • Taux de résolution des actions (progress bar)
  • Utiliser recharts ou chart.js
• Page rapports — app/(dashboard)/rapports/page.tsx
  • Liste des rapports générés, téléchargement
• Mode impression — CSS @media print pour la page détail audit

---

Prochaine étape

git checkout dev
git checkout -b feature/phase-2-nmap

Commencer par :

1. Configurer Celery dans docker-compose.yml (service worker)
2. Créer backend/models/scan_log.py
3. Créer backend/scanners/nmap.py
4. Générer la première migration Alembic
5. Créer les pages frontend manquantes (détail audit, formulaires)