🛡️ Bot Detector Dashboard

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

Version: 1.7.0 - Subnet Investigation + IP Reputation

🚀 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
• Des données dans la table http_logs (pour les user-agents)

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

Lancement

# 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

docker compose stop dashboard_web

Vérifier le statut

# 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
• Incidents clusterisés : Regroupement automatique par subnet /24
• Top Menaces Actives : Top 10 des IPs les plus dangereuses

Investigation Subnet /24 (NOUVEAU)

• URL: /entities/subnet/x.x.x.x_24 (ex: /entities/subnet/141.98.11.0_24)
• Stats globales : Total IPs, détections, JA4 uniques, User-Agents uniques, Hosts
• Tableau des IPs : Toutes les IPs du subnet avec leurs statistiques
• Actions par IP : Investiguer, Voir détails
• Sources : ml_detected_anomalies (détections) + view_dashboard_entities (user-agents)

Investigation IP + Réputation (NOUVEAU)

• URL: /investigation/:ip
• Panel Réputation IP :
  • Score de menace 0-100
  • Niveau: clean/low/medium/high/critical
  • Détection: Proxy, Hosting, VPN, Tor
  • Géolocalisation: Pays, Ville
  • ASN + Organisation
• Sources : IP-API.com + IPinfo.io (sans clé API)

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	/api/incidents/clusters	Incidents clusterisés par subnet /24
GET	/api/entities/subnet/{subnet}	Investigation subnet (ex: 141.98.11.0/24)
GET	/api/entities/{type}/{value}	Investigation entité (IP, JA4, UA, etc.)
GET	/api/reputation/ip/{ip}	Réputation IP (IP-API + IPinfo)
GET	/api/analysis/{ip}/subnet	Analyse subnet / ASN
GET	/api/analysis/{ip}/country	Analyse pays
GET	/api/analysis/{ip}/ja4	Analyse JA4
GET	/api/analysis/{ip}/user-agents	Analyse User-Agents
GET	/api/analysis/{ip}/recommendation	Recommandation de classification
POST	/api/analysis/classifications	Sauvegarder classification SOC
GET	/health	Health check

Exemples

# 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

# Investigation subnet (URL encode / en _24)
curl "http://localhost:3000/api/entities/subnet/141.98.11.0_24?hours=24"

# Réputation IP
curl http://localhost:3000/api/reputation/ip/141.98.11.209

# Incidents clusterisés
curl http://localhost:3000/api/incidents/clusters?limit=20

# 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 :

# 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 :

#!/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 :

chmod +x test_dashboard.sh
./test_dashboard.sh

Tests manuels de l'API

# 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

# 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

# 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

# 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

# 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)

# 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é"

# 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

# 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é

# 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)

# 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)

# 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 :

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

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

Tests unitaires (à venir)

# 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