AuditShield/CLAUDE.md

AuditShield

Projet

Outil d'audit infrastructure et sécurité pour clients MSP. Permet de lancer des scans réseau, vulnérabilités et pentest automatisés, avec suivi des actions et génération de rapports exportables (PDF + dashboard web) compréhensibles pour des clients non-techniques.

Stack

• Frontend : Next.js 14 + Tailwind + shadcn/ui
• Backend : FastAPI (Python 3.11)
• Base de données : PostgreSQL
• ORM : SQLAlchemy + Alembic (migrations)
• Auth : JWT + bcrypt
• PDF : WeasyPrint
• Déploiement : Docker → Synology NAS ou VPS (rigolet.tech)

Structure

frontend/
  app/
    (auth)/login/       # Page login (pas de layout dashboard)
    (dashboard)/        # Pages protégées avec sidebar
      layout.tsx        # Guard auth + layout sidebar+main
      dashboard/        # Stats globales
      clients/          # CRUD clients
      audits/           # CRUD audits
  components/
    layout/             # Sidebar, Header
    ui/                 # shadcn/ui : Button, Card, Input, Badge, Label
  lib/
    api.ts              # Client fetch typé (authApi, clientsApi, auditsApi)
    auth.ts             # Helpers JWT localStorage
    utils.ts            # cn() (tailwind-merge + clsx)
backend/
  api/                  # Routes FastAPI (auth, clients, audits)
  core/                 # config.py, database.py, security.py
  models/               # SQLAlchemy ORM (base.py + TimestampMixin)
  schemas/              # Pydantic v2 (séparés des modèles)
  scanners/             # Placeholder Phase 2 (Nmap, OpenVAS...)
  reports/              # Placeholder Phase 4 (WeasyPrint PDF)
  tests/                # pytest async avec SQLite in-memory
  alembic/              # Migrations (env.py configuré)
  main.py               # App FastAPI : CORS, rate limiting, routers
docker/
  docker-compose.yml      # Dev : postgres, redis, backend, frontend
  docker-compose.prod.yml # Prod : images registry + labels Traefik

Commandes

# Frontend
cd frontend && npm install && npm run dev

# Backend (lancer depuis la racine du projet, pas depuis backend/)
pip install -r backend/requirements.txt
uvicorn backend.main:app --reload

# Docker complet
docker compose -f docker/docker-compose.yml up -d

# Migrations BDD (depuis la racine, pas depuis backend/)
alembic -c backend/alembic.ini upgrade head
# Créer une migration :
alembic -c backend/alembic.ini revision --autogenerate -m "description"

# Tests
pytest backend/tests/

# Typecheck frontend
cd frontend && npm run typecheck

Modèle de données

• Client : id, nom, contact, créé_le
• Audit : id, client_id, statut, date_début, date_fin, score_global
• Cible : id, audit_id, type (IP/domaine/subnet), valeur
• Vulnérabilité : id, audit_id, criticité (critique/important/modéré/faible), titre, description, recommandation
• Action : id, vulnérabilité_id, statut (ouvert/en_cours/résolu), assigné_à, note

Sécurité IMPORTANT

• Jamais de credentials dans le code, toujours via .env
• Les scans ne se lancent QUE sur des cibles validées par l'utilisateur
• Logs de toutes les actions de scan en BDD
• Rate limiting sur toutes les routes API

Code style

• ES modules (import/export), jamais CommonJS
• Functional components + hooks uniquement
• TypeScript strict sur le frontend
• Type hints Python obligatoires sur le backend
• IMPORTANT : typecheck après chaque série de modifications

Git

• Branches : main (prod) → dev → feature/xxx
• Commits : feat: / fix: / docs: / refactor: / chore:
• IMPORTANT : toujours créer une branche pour chaque tâche
• IMPORTANT : ne jamais pusher directement sur main

Déploiement

Gitea Actions → Docker → NAS ou VPS selon le client Voir @docker/docker-compose.yml et @.gitea/workflows/deploy.yml

Ce que Claude doit savoir sur CE projet

Domaine métier

• Les scans sont des opérations longues → utiliser des jobs asynchrones (Celery ou BackgroundTasks FastAPI)
• Le rapport PDF doit être compréhensible par un dirigeant non-technique
• Toujours traduire les CVE en langage clair dans les rapports
• La BDD utilise snake_case, le frontend TypeScript utilise camelCase
• Les criticités : critique (CVSS 9-10), important (7-8.9), modéré (4-6.9), faible (0-3.9)
• Un scan ne peut se lancer que sur des cibles dont validee = True (sécurité obligatoire)

Conventions de code établies en Phase 1

Backend :

• Imports toujours en backend.xxx (ex: from backend.models.user import User), jamais en relatif — le module s'appelle backend
• Uvicorn se lance avec uvicorn backend.main:app, pas uvicorn main:app
• Alembic se lance depuis la racine avec -c backend/alembic.ini
• Les enums Python sont aussi str (class Criticite(str, enum.Enum)) pour sérialisation JSON automatique
• Pydantic v2 : utiliser model_dump() (pas .dict()), model_config = {"from_attributes": True} (pas orm_mode)
• Pattern PATCH : payload.model_dump(exclude_unset=True) pour ne pas écraser les champs non fournis
• get_current_user est une dépendance FastAPI — toujours l'injecter sur les routes protégées
• selectinload() pour les relations dans les endpoints "detail" (évite le N+1)
• TimestampMixin à hériter sur tous les nouveaux modèles
• pool_pre_ping=True sur l'engine SQLAlchemy pour les connexions longues durée

Frontend :

• Les types TypeScript sont en camelCase même si l'API renvoie du snake_case (mapping à faire côté fetch)
• "use client" obligatoire sur toutes les pages/composants utilisant des hooks React ou des effets
• Guard auth dans (dashboard)/layout.tsx via useEffect + getToken() — pas de middleware Next.js
• Le client API (lib/api.ts) passe toujours le token en paramètre explicite — pas de contexte global
• Les nouvelles pages du dashboard vont dans app/(dashboard)/[section]/page.tsx
• Les nouveaux composants UI shadcn vont dans components/ui/, les composants métier dans components/
• Les rewrites next.config.ts proxifient /api/* vers le backend — en dev, définir NEXT_PUBLIC_API_URL=http://localhost:8000
• JWT stocké dans localStorage (simple pour MVP, à migrer vers HttpOnly cookie plus tard)

Infrastructure :

• Le service backend dans docker-compose dépend de postgres avec condition: service_healthy
• Le build frontend Next.js utilise output: "standalone" → le Dockerfile copie .next/standalone
• Les variables d'env préfixées NEXT_PUBLIC_ sont embarquées au build (pas au runtime)
• docker-compose.prod.yml attend des images pré-buildées depuis ${REGISTRY} — pas de build local

Pièges à éviter

• Ne pas lancer uvicorn main:app depuis backend/ — toujours depuis la racine avec le module complet
• Ne pas oublier "use client" sur les pages avec useEffect, useState, useRouter
• Ne pas utiliser .dict() Pydantic v1 — c'est .model_dump() en v2
• Ne pas faire de scans sans vérifier cible.validee == True côté backend
• Ne pas commiter .env — seulement .env.example
• Alembic env.py importe les modèles depuis backend.models — ajouter tout nouveau modèle dans backend/models/__init__.py