dashboard/README.md

# 🛡️ Bot Detector Dashboard

Dashboard web interactif pour visualiser et investiguer les décisions de classification du Bot Detector IA.

## 🚀 Démarrage Rapide

### Prérequis

- Docker et Docker Compose
- Le service `clickhouse` déjà déployé
- Des données dans la table `ml_detected_anomalies`

> **Note:** Le dashboard peut fonctionner indépendamment de `bot_detector_ai`. Il lit les données déjà détectées dans ClickHouse.

### Lancement

```bash
# 1. Vérifier que .env existe
cp .env.example .env  # Si ce n'est pas déjà fait

# 2. Lancer le dashboard (avec Docker Compose v2)
docker compose up -d dashboard_web

# Ou avec l'ancienne syntaxe
docker-compose up -d dashboard_web

# 3. Ouvrir le dashboard
# http://localhost:3000
```

### Arrêt

```bash
docker compose stop dashboard_web
```

### Vérifier le statut

```bash
# Voir les services en cours d'exécution
docker compose ps

# Voir les logs en temps réel
docker compose logs -f dashboard_web
```

## 📊 Fonctionnalités

### Dashboard Principal
- **Métriques en temps réel** : Total détections, menaces, bots connus, IPs uniques
- **Répartition par menace** : Visualisation CRITICAL/HIGH/MEDIUM/LOW
- **Évolution temporelle** : Graphique des détections sur 24h

### Liste des Détections
- **Tableau interactif** : Tri, pagination, filtres
- **Recherche** : Par IP, JA4, Host
- **Filtres** : Par niveau de menace, modèle, pays, ASN

### Investigation (Variabilité)
- **Vue détails** : Cliquez sur une IP/JA4/pays/ASN pour investiguer
- **Variabilité des attributs** :
  - User-Agents associés (avec pourcentages)
  - JA4 fingerprints
  - Pays de provenance
  - ASN
  - Hosts contactés
  - Niveaux de menace
- **Insights automatiques** : Détection de comportements suspects
- **Navigation enchaînable** : Cliquez sur un attribut pour creuser

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    Docker Compose                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐ │
│  │  ClickHouse │  │ bot_detector│  │  dashboard_web  │ │
│  │  :8123      │  │  (existant) │  │  :3000 (web)    │ │
│  │  :9000      │  │             │  │  :8000 (API)    │ │
│  └──────┬──────┘  └──────┬──────┘  └────────┬────────┘ │
│         └────────────────┴───────────────────┘          │
└─────────────────────────────────────────────────────────┘
```

### Composants

| Composant | Technologie | Port | Description |
|-----------|-------------|------|-------------|
| **Frontend** | React + TypeScript + Tailwind | 3000 | Interface utilisateur |
| **Backend API** | FastAPI (Python) | 8000 | API REST |
| **Database** | ClickHouse (existant) | 8123 | Base de données |

## 📁 Structure

```
dashboard/
├── Dockerfile              # Image Docker multi-stage
├── requirements.txt        # Dépendances Python
├── backend/
│   ├── main.py            # Application FastAPI
│   ├── config.py          # Configuration
│   ├── database.py        # Connexion ClickHouse
│   ├── models.py          # Modèles Pydantic
│   └── routes/
│       ├── metrics.py     # Endpoint /api/metrics
│       ├── detections.py  # Endpoint /api/detections
│       ├── variability.py # Endpoint /api/variability
│       └── attributes.py  # Endpoint /api/attributes
└── frontend/
    ├── package.json       # Dépendances Node
    ├── src/
    │   ├── App.tsx        # Composant principal
    │   ├── components/
    │   │   ├── DetectionsList.tsx
    │   │   ├── DetailsView.tsx
    │   │   └── VariabilityPanel.tsx
    │   ├── hooks/
    │   │   ├── useMetrics.ts
    │   │   ├── useDetections.ts
    │   │   └── useVariability.ts
    │   └── api/
    │       └── client.ts  # Client API
```

## 🔌 API

### Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/metrics` | Métriques globales |
| GET | `/api/metrics/threats` | Distribution par menace |
| GET | `/api/detections` | Liste des détections |
| GET | `/api/detections/{id}` | Détails d'une détection |
| GET | `/api/variability/{type}/{value}` | Variabilité d'un attribut |
| GET | `/api/attributes/{type}` | Liste des valeurs uniques |
| GET | `/health` | Health check |

### Exemples

```bash
# Métriques globales
curl http://localhost:3000/api/metrics

# Détections avec filtres
curl "http://localhost:3000/api/detections?threat_level=CRITICAL&page=1"

# Variabilité d'une IP
curl http://localhost:3000/api/variability/ip/192.168.1.100

# Liste des pays
curl http://localhost:3000/api/attributes/country
```

## ⚙️ Configuration

### Variables d'Environnement

| Variable | Défaut | Description |
|----------|--------|-------------|
| `CLICKHOUSE_HOST` | `clickhouse` | Hôte ClickHouse |
| `CLICKHOUSE_DB` | `mabase_prod` | Base de données |
| `CLICKHOUSE_USER` | `admin` | Utilisateur |
| `CLICKHOUSE_PASSWORD` | `` | Mot de passe |
| `API_PORT` | `8000` | Port de l'API |

Ces variables sont lues depuis le fichier `.env` à la racine du projet.

## 🔍 Workflows d'Investigation

### Exemple 1: Investiguer une IP suspecte

1. **Dashboard** → Voir une IP classifiée 🔴 CRITICAL
2. **Clic sur l'IP** → Ouvre la vue détails
3. **Observer User-Agents** → 3 UA différents détectés
4. **Clic sur "python-requests"** → Voir toutes les IPs avec cet UA
5. **Découvrir 12 IPs** → Possible botnet
6. **Action** → Noter pour blacklist

### Exemple 2: Analyser un ASN

1. **Filtre** → ASN: OVH (AS16276)
2. **Voir 523 détections** → Beaucoup d'activité
3. **Variabilité** → 89 IPs différentes, 15 pays
4. **Insight** → "ASN de type hosting → Souvent utilisé pour des bots"
5. **Conclusion** → Activité normale pour un hébergeur

## 🎨 Thème

Le dashboard utilise un **thème sombre** optimisé pour la sécurité :

- **Background** : Slate 900/800/700
- **Menaces** : Rouge (CRITICAL), Orange (HIGH), Jaune (MEDIUM), Vert (LOW)
- **Accents** : Blue (primaire), Emerald (succès)

## 📝 Logs

Les logs du dashboard sont accessibles via Docker :

```bash
# Logs du container
docker logs dashboard_web

# Logs en temps réel
docker logs -f dashboard_web
```

## 🧪 Tests et Validation

### Script de test rapide

Créez un fichier `test_dashboard.sh` :

```bash
#!/bin/bash
echo "=== Test Dashboard Bot Detector ==="

# 1. Health check
echo -n "1. Health check... "
curl -s http://localhost:3000/health > /dev/null && echo "✅ OK" || echo "❌ ÉCHOUÉ"

# 2. API Metrics
echo -n "2. API Metrics... "
curl -s http://localhost:3000/api/metrics | jq -e '.summary' > /dev/null && echo "✅ OK" || echo "❌ ÉCHOUÉ"

# 3. API Detections
echo -n "3. API Detections... "
curl -s http://localhost:3000/api/detections | jq -e '.items' > /dev/null && echo "✅ OK" || echo "❌ ÉCHOUÉ"

# 4. Frontend
echo -n "4. Frontend HTML... "
curl -s http://localhost:3000 | grep -q "Bot Detector" && echo "✅ OK" || echo "❌ ÉCHOUÉ"

echo "=== Tests terminés ==="
```

Rendez-le exécutable et lancez-le :

```bash
chmod +x test_dashboard.sh
./test_dashboard.sh
```

### Tests manuels de l'API

```bash
# 1. Health check
curl http://localhost:3000/health

# 2. Métriques globales
curl http://localhost:3000/api/metrics | jq

# 3. Liste des détections (page 1, 25 items)
curl "http://localhost:3000/api/detections?page=1&page_size=25" | jq

# 4. Filtrer par menace CRITICAL
curl "http://localhost:3000/api/detections?threat_level=CRITICAL" | jq '.items[].src_ip'

# 5. Distribution par menace
curl http://localhost:3000/api/metrics/threats | jq

# 6. Liste des IPs uniques (top 10)
curl "http://localhost:3000/api/attributes/ip?limit=10" | jq

# 7. Variabilité d'une IP (remplacer par une IP réelle)
curl http://localhost:3000/api/variability/ip/192.168.1.100 | jq

# 8. Variabilité d'un pays
curl http://localhost:3000/api/variability/country/FR | jq

# 9. Variabilité d'un ASN
curl http://localhost:3000/api/variability/asn/16276 | jq
```

### Test du Frontend

```bash
# Vérifier que le HTML est servi
curl -s http://localhost:3000 | head -20

# Ou ouvrir dans le navigateur
# http://localhost:3000
```

### Scénarios de test utilisateur

1. **Navigation de base**
   - Ouvrir http://localhost:3000
   - Vérifier que les métriques s'affichent
   - Cliquer sur "📋 Détections"

2. **Recherche et filtres**
   - Rechercher une IP : `192.168`
   - Filtrer par menace : CRITICAL
   - Changer de page

3. **Investigation (variabilité)**
   - Cliquer sur une IP dans le tableau
   - Vérifier la section "User-Agents" (plusieurs valeurs ?)
   - Cliquer sur un User-Agent pour investiguer
   - Utiliser le breadcrumb pour revenir en arrière

4. **Insights**
   - Trouver une IP avec plusieurs User-Agents
   - Vérifier que l'insight "Possible rotation/obfuscation" s'affiche

### Vérifier les données ClickHouse

```bash
# Compter les détections (24h)
docker compose exec clickhouse clickhouse-client -d mabase_prod -q \
  "SELECT count() FROM ml_detected_anomalies WHERE detected_at >= now() - INTERVAL 24 HOUR"

# Voir un échantillon
docker compose exec clickhouse clickhouse-client -d mabase_prod -q \
  "SELECT src_ip, threat_level, model_name, detected_at FROM ml_detected_anomalies ORDER BY detected_at DESC LIMIT 5"

# Vérifier les vues du dashboard
docker compose exec clickhouse clickhouse-client -d mabase_prod -q \
  "SELECT * FROM view_dashboard_summary"
```

---

## 🐛 Dépannage

### Diagnostic rapide

```bash
# 1. Vérifier que les services tournent
docker compose ps

# 2. Vérifier les logs du dashboard
docker compose logs dashboard_web | tail -50

# 3. Tester la connexion ClickHouse depuis le dashboard
docker compose exec dashboard_web curl -v http://clickhouse:8123/ping
```

### Le dashboard ne démarre pas

```bash
# Vérifier les logs
docker compose logs dashboard_web

# Erreur courante: Port déjà utilisé
# Solution: Changer le port dans docker-compose.yml

# Erreur courante: Image non construite
docker compose build dashboard_web
docker compose up -d dashboard_web
```

### Aucune donnée affichée (dashboard vide)

```bash
# 1. Vérifier qu'il y a des données dans ClickHouse
docker compose exec clickhouse clickhouse-client -d mabase_prod -q \
  "SELECT count() FROM ml_detected_anomalies WHERE detected_at >= now() - INTERVAL 24 HOUR"

# Si le résultat est 0:
# - Lancer bot_detector_ai pour générer des données
docker compose up -d bot_detector_ai
docker compose logs -f bot_detector_ai

# - Ou importer des données manuellement
```

### Erreur "Connexion ClickHouse échoué"

```bash
# 1. Vérifier que ClickHouse est démarré
docker compose ps clickhouse

# 2. Tester la connexion
docker compose exec clickhouse clickhouse-client -q "SELECT 1"

# 3. Vérifier les credentials dans .env
cat .env | grep CLICKHOUSE

# 4. Redémarrer le dashboard
docker compose restart dashboard_web

# 5. Vérifier les logs d'erreur
docker compose logs dashboard_web | grep -i error
```

### Erreur 404 sur les routes API

```bash
# Vérifier que l'API répond
curl http://localhost:3000/health
curl http://localhost:3000/api/metrics

# Si 404, redémarrer le dashboard
docker compose restart dashboard_web
```

### Port 3000 déjà utilisé

```bash
# Option 1: Changer le port dans docker-compose.yml
# Remplacer: - "3000:8000"
# Par: - "8080:8000"

# Option 2: Trouver et tuer le processus
lsof -i :3000
kill <PID>

# Puis redémarrer
docker compose up -d dashboard_web
```

### Frontend ne se charge pas (page blanche)

```bash
# 1. Vérifier la console du navigateur (F12)
# 2. Vérifier que le build frontend existe
docker compose exec dashboard_web ls -la /app/frontend/dist

# 3. Si vide, reconstruire l'image
docker compose build --no-cache dashboard_web
docker compose up -d dashboard_web
```

### Logs d'erreur courants

| Erreur | Cause | Solution |
|--------|-------|----------|
| `Connection refused` | ClickHouse pas démarré | `docker compose up -d clickhouse` |
| `Authentication failed` | Mauvais credentials | Vérifier `.env` |
| `Table doesn't exist` | Vues non créées | Lancer `deploy_views.sql` |
| `No data available` | Pas de données | Lancer `bot_detector_ai` |

---

## 🔒 Sécurité

- **Pas d'authentification** : Dashboard conçu pour un usage local
- **CORS restreint** : Seulement localhost:3000
- **Rate limiting** : 100 requêtes/minute
- **Credentials** : Via variables d'environnement (jamais en dur)

## 📊 Performances

- **Temps de chargement** : < 2s (avec données)
- **Requêtes ClickHouse** : Optimisées avec agrégations
- **Rafraîchissement auto** : 30 secondes (métriques)

## 🧪 Développement

### Build local (sans Docker)

```bash
# Backend
cd dashboard
pip install -r requirements.txt
python -m uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

# Frontend (dans un autre terminal)
cd dashboard/frontend
npm install
npm run dev  # http://localhost:5173
```

### Documentation API interactive

L'API inclut une documentation Swagger interactive :

```bash
# Ouvrir dans le navigateur
http://localhost:3000/docs

# Ou directement sur le port API
http://localhost:8000/docs
```

### Tests unitaires (à venir)

```bash
# Backend (pytest)
cd dashboard
pytest backend/tests/

# Frontend (jest)
cd dashboard/frontend
npm test
```

## 📄 License

Même license que le projet principal Bot Detector.

---

## 📞 Support

Pour toute question ou problème :

1. Vérifier la section **🐛 Dépannage** ci-dessus
2. Consulter les logs : `docker compose logs dashboard_web`
3. Vérifier que ClickHouse contient des données
4. Ouvrir une issue sur le dépôt