Initial commit: Bot Detector Dashboard for SOC Incident Response
🛡️ Dashboard complet pour l'analyse et la classification des menaces Fonctionnalités principales: - Visualisation des détections en temps réel (24h) - Investigation multi-entités (IP, JA4, ASN, Host, User-Agent) - Analyse de corrélation pour classification SOC - Clustering automatique par subnet/JA4/UA - Export des classifications pour ML Composants: - Backend: FastAPI (Python) + ClickHouse - Frontend: React + TypeScript + TailwindCSS - 6 routes API: metrics, detections, variability, attributes, analysis, entities - 7 types d'entités investigables Documentation ajoutée: - NAVIGATION_GRAPH.md: Graph complet de navigation - SOC_OPTIMIZATION_PROPOSAL.md: Proposition d'optimisation pour SOC • Réduction de 7 à 2 clics pour classification • Nouvelle vue /incidents clusterisée • Panel latéral d'investigation • Quick Search (Cmd+K) • Timeline interactive • Graph de corrélations Sécurité: - .gitignore configuré (exclut .env, secrets, node_modules) - Credentials dans .env (à ne pas committer) ⚠️ Audit sécurité réalisé - Voir recommandations dans SOC_OPTIMIZATION_PROPOSAL.md Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
This commit is contained in:
SOC Analyst
503
README.md
Normal file
503
README.md
Normal file
@ -0,0 +1,503 @@
|
||||
# 🛡️ 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
|
||||
Reference in New Issue
Block a user