# 🗺️ Graph de Navigation du Dashboard Bot Detector

## Vue d'ensemble

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                           BOT DETECTOR DASHBOARD                                 │
│                           (Page d'accueil / Dashboard)                           │
└─────────────────────────────────────────────────────────────────────────────────┘
                                         │
         ┌───────────────────────────────┼───────────────────────────────┐
         │                               │                               │
         ▼                               ▼                               ▼
┌─────────────────┐            ┌─────────────────┐            ┌─────────────────┐
│   📊 Dashboard  │            │  📋 Détections  │            │  ⚙️ API /docs   │
│   (Accueil)     │───────────▶│   (Liste)       │            │  (Swagger)      │
└─────────────────┘            └─────────────────┘            └─────────────────┘
         │                               │
         │                               │
         │                               ▼
         │                     ┌─────────────────────────────────────────┐
         │                     │   FILTRES & RECHERCHE                   │
         │                     │  • Recherche: IP, JA4, Host             │
         │                     │  • Modèle: Complet / Applicatif         │
         │                     │  • Niveau menace: CRITICAL/HIGH/MEDIUM/ │
         │                     │  • Pays, ASN                            │
         │                     │  • Tri: Score, Date, IP, ASN, etc.      │
         │                     │  • Toggle: Grouper par IP / Individuel  │
         │                     └─────────────────────────────────────────┘
         │                               │
         │                               │ (Clic sur ligne)
         │                               ▼
         │                     ┌─────────────────────────────────────────┐
         │                     │  🔍 DETAILS VIEW                        │
         │                     │  /detections/:type/:value               │
         │                     │                                         │
         │                     │  Types supportés:                       │
         │                     │  • ip                                   │
         │                     │  • ja4                                  │
         │                     │  • country                              │
         │                     │  • asn                                  │
         │                     │  • host                                 │
         │                     │  • user_agent                           │
         │                     │                                         │
         │                     │  Affiche:                               │
         │                     │  • Stats (total, IPs uniques, dates)    │
         │                     │  • Insights (auto-générés)              │
         │                     │  • Variabilité des attributs            │
         │                     └─────────────────────────────────────────┘
         │                               │
         │           ┌───────────────────┼───────────────────┐
         │           │                   │                   │
         │           ▼                   ▼                   ▼
         │   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
         │   │ Investigation│   │ Investigation│   │  Entity      │
         │   │ IP           │   │ JA4          │  │  Investigation│
         │   │              │   │              │  │              │
         │   │ /investigati │   │ /investigati │  │ /entities/:t │
         │   │ on/:ip       │   │ on/ja4/:ja4  │  │ ype/:value   │
         │   └──────────────┘   └──────────────┘  └──────────────┘
         │
         │
         │ (Accès rapide depuis Dashboard)
         │
         ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                         ACCÈS RAPIDE (Dashboard)                                │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐              │
│  │ Voir détections  │  │ Menaces          │  │ Modèle Complet   │              │
│  │ → /detections    │  │ Critiques        │  │ → /detections?   │              │
│  │                  │  │ → /detections?   │  │   model_name=    │              │
│  │                  │  │   threat_level=  │  │   Complet        │              │
│  │                  │  │   CRITICAL       │  │                  │              │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘              │
└─────────────────────────────────────────────────────────────────────────────────┘
```

---

## 📊 ARBORESCENCE COMPLÈTE

### Niveau 1 - Pages Principales

```
/ (Dashboard)
├── /detections (Liste des détections)
│   ├── Filtres: ?threat_level=CRITICAL
│   ├── Filtres: ?model_name=Complet
│   ├── Filtres: ?country_code=FR
│   ├── Filtres: ?asn_number=16276
│   ├── Recherche: ?search=192.168.1.1
│   └── Tri: ?sort_by=anomaly_score&sort_order=desc
│
├── /docs (Swagger UI - API documentation)
└── /health (Health check endpoint)
```

### Niveau 2 - Vues de Détails

```
/detections/:type/:value
├── /detections/ip/192.168.1.100
├── /detections/ja4/t13d190900_...
├── /detections/country/FR
├── /detections/asn/16276
├── /detections/host/example.com
└── /detections/user_agent/Mozilla/5.0...
```

### Niveau 3 - Investigations

```
/detections/ip/:ip
└── → /investigation/:ip (Investigation complète)

/detections/ja4/:ja4
└── → /investigation/ja4/:ja4 (Investigation JA4)

/detections/:type/:value
└── → /entities/:type/:value (Investigation entité)
    ├── /entities/ip/192.168.1.100
    ├── /entities/ja4/t13d190900_...
    ├── /entities/user_agent/Mozilla/5.0...
    ├── /entities/client_header/Accept-Language
    ├── /entities/host/example.com
    ├── /entities/path/api/login
    └── /entities/query_param/token,userId
```

---

## 🔍 INVESTIGATION IP - SOUS-PANELS

```
/investigation/:ip
│
├── Panel 1: SUBNET / ASN ANALYSIS
│   ├── Calcul subnet /24
│   ├── Liste IPs du subnet
│   ├── ASN number & org
│   └── Total IPs dans l'ASN
│
├── Panel 2: COUNTRY ANALYSIS
│   ├── Pays de l'IP
│   └── Répartition autres pays du même ASN
│
├── Panel 3: JA4 ANALYSIS
│   ├── JA4 fingerprint de l'IP
│   ├── IPs partageant le même JA4
│   ├── Top subnets pour ce JA4
│   └── Autres JA4 pour cette IP
│
├── Panel 4: USER-AGENT ANALYSIS
│   ├── User-Agents de l'IP
│   ├── Classification (normal/bot/script)
│   └── Pourcentage bots
│
└── Panel 5: CORRELATION SUMMARY + CLASSIFICATION
    ├── Indicateurs de corrélation
    │   ├── subnet_ips_count
    │   ├── asn_ips_count
    │   ├── ja4_shared_ips
    │   ├── bot_ua_percentage
    │   └── user_agents_count
    │
    ├── Recommandation auto
    │   ├── label: legitimate/suspicious/malicious
    │   ├── confidence: 0-1
    │   ├── suggested_tags: []
    │   └── reason: string
    │
    └── Formulaire classification SOC
        ├── Sélection label (3 boutons)
        ├── Tags prédéfinis (20 tags)
        ├── Commentaire libre
        ├── Sauvegarder → classifications table
        └── Export ML → JSON
```

---

## 🔍 INVESTIGATION JA4 - SOUS-PANELS

```
/investigation/ja4/:ja4
│
├── Stats principales
│   ├── Total détections (24h)
│   ├── IPs uniques
│   ├── Première détection
│   ├── Dernière détection
│   └── Nombre User-Agents
│
├── Panel 1: TOP IPs
│   └── Liste IPs utilisant ce JA4 (top 10)
│
├── Panel 2: TOP Pays
│   └── Répartition géographique
│
├── Panel 3: TOP ASN
│   └── ASNs utilisant ce JA4
│
├── Panel 4: TOP Hosts
│   └── Hosts ciblés avec ce JA4
│
└── Panel 5: USER-AGENTS + CLASSIFICATION
    ├── Liste User-Agents
    ├── Classification (normal/bot/script)
    └── JA4CorrelationSummary
```

---

## 📋 ENTITÉ INVESTIGATION - SOUS-PANELS

```
/entities/:type/:value
│
├── Stats générales
│   ├── Total requêtes
│   ├── IPs uniques
│   ├── Première détection
│   └── Dernière détection
│
├── Panel 1: IPs Associées
│   └── Top 20 IPs + navigation
│
├── Panel 2: JA4 Fingerprints
│   └── Top 10 JA4 + investigation
│
├── Panel 3: User-Agents
│   ├── Top 10 UAs
│   ├── Count & percentage
│   └── Tronqué (150 chars)
│
├── Panel 4: Client Headers
│   ├── Top 10 headers
│   ├── Count & percentage
│   └── Format mono
│
├── Panel 5: Hosts Ciblés
│   └── Top 15 hosts
│
├── Panel 6: Paths
│   ├── Top 15 paths
│   └── Count & percentage
│
├── Panel 7: Query Params
│   ├── Top 15 query params
│   └── Count & percentage
│
└── Panel 8: ASNs & Pays
    ├── Top 10 ASNs
    └── Top 10 Pays (avec drapeaux)
```

---

## 🎯 WORKFLOWS SOC TYPIQUES

### Workflow 1: Investigation d'une IP suspecte

```
1. Dashboard
   └── Voir métriques (CRITICAL: 45, HIGH: 120)
   
2. Clic sur "Menaces Critiques"
   └── /detections?threat_level=CRITICAL
   
3. Repérer IP: 192.168.1.100 (Score: -0.95)
   └── Clic sur ligne IP
   
4. Details View: /detections/ip/192.168.1.100
   ├── Stats: 250 détections, 1 UA, 1 JA4
   ├── Insight: "1 User-Agent → Possible script"
   └── Bouton: "🔍 Investigation complète"
   
5. Investigation: /investigation/192.168.1.100
   ├── Panel 1: 15 IPs du subnet /24 ⚠️
   ├── Panel 2: Pays: CN (95%)
   ├── Panel 3: JA4 unique, 50 IPs partagent
   ├── Panel 4: 100% bot UA (python-requests)
   └── Panel 5: Classification
       ├── Label: MALICIOUS (auto)
       ├── Tags: scraping, bot-network, hosting-asn
       ├── Comment: "Bot de scraping distribué"
       └── Action: 💾 Sauvegarder + 📤 Export ML
```

### Workflow 2: Analyse d'un JA4 fingerprint

```
1. Dashboard
   └── Voir série temporelle (pic à 14:00)
   
2. /detections
   └── Tri par JA4 (groupé)
   
3. Repérer JA4: t13d190900_9dc949149365_...
   └── Clic: /detections/ja4/:ja4
   
4. Details View JA4
   ├── Stats: 1500 détections, 89 IPs
   ├── Insight: "89 IPs différentes → Infrastructure distribuée"
   └── Bouton: "🔍 Investigation JA4"
   
5. Investigation JA4: /investigation/ja4/:ja4
   ├── Panel 1: Top 10 IPs (CN: 45%, US: 30%)
   ├── Panel 2: Top Pays (CN, US, DE, FR)
   ├── Panel 3: Top ASN (OVH, Amazon, Google)
   ├── Panel 4: Top Hosts (api.example.com)
   └── Panel 5: User-Agents
       ├── 60% curl/7.68.0 (script)
       ├── 30% python-requests (script)
       └── 10% Mozilla (normal)
```

### Workflow 3: Investigation par ASN

```
1. /detections?asn_number=16276 (OVH)
   └── 523 détections en 24h
   
2. Clic sur ASN dans tableau
   └── /detections/asn/16276
   
3. Details View ASN
   ├── Stats: 523 détections, 89 IPs
   ├── Variabilité:
   │   ├── 15 User-Agents différents
   │   ├── 8 JA4 fingerprints
   │   ├── 12 pays
   │   └── 45 hosts ciblés
   └── Insights:
       ├── "ASN de type hosting/cloud"
       └── "12 pays → Distribution géographique large"
   
4. Navigation enchaînable
   └── Clic sur User-Agent "python-requests"
       └── /entities/user_agent/python-requests/2.28.0
           ├── 250 IPs utilisent cet UA
           ├── Top paths: /api/login, /api/users
           └── Query params: token, userId, action
```

---

## 📡 API ENDPOINTS UTILISÉS

```
GET /api/metrics
└── Résumé + timeseries + distribution

GET /api/detections
├── page, page_size
├── threat_level, model_name
├── country_code, asn_number
├── search, sort_by, sort_order
└── items[], total, page, total_pages

GET /api/detections/:id
└── Détails complets d'une détection

GET /api/variability/:type/:value
├── type: ip, ja4, country, asn, host
├── Stats globales
├── attributes:
│   ├── user_agents[]
│   ├── ja4[]
│   ├── countries[]
│   ├── asns[]
│   └── hosts[]
└── insights[]

GET /api/variability/:type/:value/ips
└── Liste des IPs associées

GET /api/variability/:type/:value/attributes
├── target_attr: user_agents, ja4, countries, asns, hosts
└── items[] avec count, percentage

GET /api/variability/:type/:value/user_agents
└── User-Agents avec classification

GET /api/attributes/:type
└── Liste des valeurs uniques (top 100)

GET /api/entities/:type/:value
├── type: ip, ja4, user_agent, client_header, host, path, query_param
├── stats: EntityStats
├── related: EntityRelatedAttributes
├── user_agents[]
├── client_headers[]
├── paths[]
└── query_params[]

GET /api/analysis/:ip/subnet
└── Subnet /24 + ASN analysis

GET /api/analysis/:ip/country
└── Pays + répartition ASN

GET /api/analysis/:ip/ja4
└── JA4 fingerprint analysis

GET /api/analysis/:ip/user-agents
└── User-Agents + classification

GET /api/analysis/:ip/recommendation
├── Indicateurs de corrélation
├── label, confidence
├── suggested_tags[]
└── reason

POST /api/analysis/classifications
└── Sauvegarde classification SOC
```

---

## 🎨 COMPOSANTS UI

```
App.tsx
├── Navigation (Navbar)
│   ├── Logo: "Bot Detector"
│   ├── Link: Dashboard
│   └── Link: Détections
│
├── Dashboard (Page d'accueil)
│   ├── MetricCard[] (4 cartes)
│   │   ├── Total Détections
│   │   ├── Menaces (CRITICAL+HIGH)
│   │   ├── Bots Connus
│   │   └── IPs Uniques
│   │
│   ├── ThreatBar[] (4 barres)
│   │   ├── CRITICAL
│   │   ├── HIGH
│   │   ├── MEDIUM
│   │   └── LOW
│   │
│   ├── TimeSeriesChart
│   └── Accès Rapide (3 liens)
│
├── DetectionsList
│   ├── Header
│   │   ├── Toggle: Grouper par IP
│   │   ├── Sélecteur colonnes
│   │   └── Recherche
│   │
│   ├── Filtres
│   │   ├── Modèle (dropdown)
│   │   └── Effacer filtres
│   │
│   └── Tableau
│       ├── Colonnes:
│       │   ├── IP / JA4
│       │   ├── Host
│       │   ├── Client Headers
│       │   ├── Modèle
│       │   ├── Score
│       │   ├── Hits
│       │   ├── Velocity
│       │   ├── ASN
│       │   ├── Pays
│       │   └── Date
│       │
│       └── Pagination
│
├── DetailsView
│   ├── Breadcrumb
│   ├── Header (type + value)
│   ├── Stats rapides (4 boxes)
│   ├── Insights[]
│   ├── VariabilityPanel
│   └── Bouton retour
│
├── InvestigationView (IP)
│   ├── SubnetAnalysis
│   ├── CountryAnalysis
│   ├── JA4Analysis
│   ├── UserAgentAnalysis
│   └── CorrelationSummary
│
├── JA4InvestigationView
│   ├── Stats principales
│   ├── Top IPs
│   ├── Top Pays
│   ├── Top ASN
│   ├── Top Hosts
│   ├── User-Agents
│   └── JA4CorrelationSummary
│
└── EntityInvestigationView
    ├── Stats générales
    ├── Panel 1: IPs Associées
    ├── Panel 2: JA4 Fingerprints
    ├── Panel 3: User-Agents
    ├── Panel 4: Client Headers
    ├── Panel 5: Hosts
    ├── Panel 6: Paths
    ├── Panel 7: Query Params
    └── Panel 8: ASNs & Pays
```

---

## 🔣 ÉTATS & DONNÉES

### Hooks React

```
useMetrics()
├── data: MetricsResponse
├── loading: boolean
├── error: Error | null
└── refresh: 30s auto

useDetections(params)
├── params: {
│   ├── page, page_size
│   ├── threat_level
│   ├── model_name
│   ├── country_code
│   ├── asn_number
│   ├── search
│   ├── sort_by, sort_order
│ }
├── data: DetectionsListResponse
├── loading: boolean
└── error: Error | null

useVariability(type, value)
├── type: string
├── value: string
├── data: VariabilityResponse
├── loading: boolean
└── error: Error | null
```

---

## 📊 MODÈLES DE DONNÉES

```typescript
MetricsResponse {
  summary: MetricsSummary {
    total_detections: number
    critical_count: number
    high_count: number
    medium_count: number
    low_count: number
    known_bots_count: number
    anomalies_count: number
    unique_ips: number
  }
  timeseries: TimeSeriesPoint[]
  threat_distribution: Record<string, number>
}

Detection {
  detected_at: datetime
  src_ip: string
  ja4: string
  host: string
  bot_name: string
  anomaly_score: float
  threat_level: string
  model_name: string
  recurrence: int
  asn_number: string
  asn_org: string
  country_code: string
  hits: int
  hit_velocity: float
  fuzzing_index: float
  post_ratio: float
  reason: string
}

VariabilityResponse {
  type: string
  value: string
  total_detections: number
  unique_ips: number
  date_range: { first_seen, last_seen }
  attributes: VariabilityAttributes {
    user_agents: AttributeValue[]
    ja4: AttributeValue[]
    countries: AttributeValue[]
    asns: AttributeValue[]
    hosts: AttributeValue[]
  }
  insights: Insight[]
}

ClassificationRecommendation {
  label: 'legitimate' | 'suspicious' | 'malicious'
  confidence: float (0-1)
  indicators: CorrelationIndicators {
    subnet_ips_count: int
    asn_ips_count: int
    ja4_shared_ips: int
    bot_ua_percentage: float
    user_agents_count: int
  }
  suggested_tags: string[]
  reason: string
}
```

---

## 🚀 POINTS D'ENTRÉE POUR SOC

### Scénarios de démarrage rapide

```
1. URGENCE: Pic d'activité suspecte
   → / (Dashboard)
   → Voir pic dans TimeSeries
   → Clic sur "Menaces Critiques"
   → Identifier pattern
   → Investigation

2. ALERT: IP blacklistée
   → /detections?search=<IP>
   → Voir historique
   → /investigation/<IP>
   → Analyser corrélations
   → Classifier + Export ML

3. INVESTIGATION: Nouveau botnet
   → /detections?threat_level=CRITICAL
   → Trier par ASN
   → Identifier cluster
   → /investigation/ja4/<JA4>
   → Cartographier infrastructure

4. REVIEW: Classification SOC
   → /entities/ip/<IP>
   → Vue complète activité
   → Décider classification
   → Sauvegarder
```

---

## 📝 NOTES

- **Navigation principale:** Dashboard → Détections → Détails → Investigation
- **Navigation secondaire:** Investigation → Entités → Investigation croisée
- **Breadcrumb:** Présent sur toutes les pages de détails
- **Retour:** Bouton "← Retour" sur chaque page d'investigation
- **URL state:** Tous les filtres sont dans l'URL (partageable)
- **Auto-refresh:** Dashboard rafraîchi toutes les 30s
- **Grouping:** Option "Grouper par IP" pour vue consolidée