# Architecture de détection — logcorrelator

## Vue d'ensemble

Le système de détection est composé de **trois couches** qui s'enchaînent en pipeline :

```
Trafic HTTP/TLS capturé
        │
        ▼
┌───────────────────┐
│  ClickHouse       │  Stockage, agrégation, vues heuristiques
│  (SQL pipeline)   │
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│  bot_detector.py  │  Modèle IA (Isolation Forest, cycle 5 min)
│  (Python / ML)    │
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│ ml_detected_      │  Table de résultats (ReplacingMergeTree)
│ anomalies         │
└───────────────────┘
```

---

## 1. Ingestion des logs (`http_logs_raw` → `http_logs`)

Les logs bruts arrivent en JSON dans la table `http_logs_raw`. Une **vue matérialisée** (`mv_http_logs`) les parse en temps réel et alimente la table `http_logs`, qui contient les champs structurés suivants :

| Catégorie | Champs clés |
|---|---|
| Réseau | `src_ip`, `src_port`, `dst_ip`, `dst_port` |
| Enrichissement | `src_asn`, `src_country_code`, `src_as_name` (via dictionnaire IPLocate) |
| HTTP | `method`, `host`, `path`, `query`, `http_version` |
| Corrélation | `correlated`, `orphan_side`, `conn_id`, `keepalives` |
| Métadonnées IP | `ip_meta_ttl`, `ip_meta_id`, `ip_meta_df`, `ip_meta_total_length` |
| Métadonnées TCP | `tcp_meta_window_size`, `tcp_meta_mss`, `tcp_meta_window_scale`, `tcp_meta_options` |
| TLS / Fingerprint | `tls_version`, `tls_sni`, `tls_alpn`, `ja3`, `ja3_hash`, `ja4` |
| En-têtes HTTP | `header_user_agent`, `header_sec_ch_ua*`, `header_sec_fetch_*`, … |

L'enrichissement IP est réalisé via le dictionnaire `dict_iplocate_asn` (fichier CSV chargé en mémoire, rechargé toutes les 1-2 heures).

---

## 2. Agrégation comportementale (fenêtre horaire)

Deux tables d'agrégation `AggregatingMergeTree` sont alimentées en continu par des vues matérialisées.

### 2.1 `agg_host_ip_ja4_1h` — Comportement réseau & applicatif

Agrège par triplet **(window_start, src_ip, ja4, host)** toutes les heures :

| Métrique agrégée | Signification |
|---|---|
| `hits` | Nombre total de requêtes |
| `count_post` | Requêtes POST |
| `uniq_paths` | Chemins distincts visités |
| `uniq_query_params` | Paramètres de query distincts |
| `unique_src_ports` | Ports sources distincts |
| `unique_conn_id` | Connexions TCP distinctes |
| `max_keepalives` | Réutilisation maximale d'une connexion |
| `orphan_count` | Requêtes sans corrélation TCP complète |
| `ip_id_zero_count` | Paquets avec IP ID = 0 (spoofing potentiel) |
| `tcp_fp_raw` | Hash de l'empreinte TCP (window, MSS, scale, options) |
| `tcp_jitter_variance` | Variance du délai SYN→ClientHello (jitter TLS) |
| `total_ip_length_var` | Variance de la taille des paquets IP |
| `mss_1460_count` | Requêtes avec MSS = 1460 (signature Ethernet/desktop) |

### 2.2 `agg_header_fingerprint_1h` — Empreinte des en-têtes HTTP

Agrège par **(window_start, src_ip)** :

| Métrique | Signification |
|---|---|
| `header_order_hash` | Hash de l'ordre des en-têtes (fingerprint JA4H) |
| `header_count` | Nombre d'en-têtes distincts |
| `has_accept_language` | Présence de `Accept-Language` |
| `has_cookie` | Présence de `Cookie` |
| `has_referer` | Présence de `Referer` |
| `modern_browser_score` | Score 0/50/100 selon présence UA et `Sec-CH-UA` |
| `ua_ch_mismatch` | Incohérence entre `User-Agent` et `Sec-CH-UA-Platform` |
| `sec_fetch_mode/dest` | Contexte de navigation déclaré |

---

## 3. Exclusions (listes blanches)

Avant toute analyse, deux tables permettent d'**exclure les robots légitimes** connus :

- `bot_ip` (fichier `bot_ip.csv`) — IPs à ignorer (crawlers, monitoring…)
- `bot_ja4` (fichier `bot_ja4.csv`) — Fingerprints JA4 à ignorer
- `ref_bot_networks` — Réseaux CIDR IPv4/IPv6 catégorisés (légitimes ou malveillants)

Ces exclusions sont appliquées dans la vue `view_ai_features_1h`.

---

## 4. Vue IA : `view_ai_features_1h`

Cette vue consolidée **sur 24 heures glissantes** calcule les **28 features** passées au modèle ML. Elle joint les deux tables d'agrégation et dérive les métriques suivantes :

| Feature | Calcul | Signal détecté |
|---|---|---|
| `hit_velocity` | `hits / durée_en_secondes` | Volume de requêtes anormalement élevé |
| `fuzzing_index` | `uniq_query_params / uniq_paths` | Exploration paramétrique (fuzzing) |
| `post_ratio` | `count_post / hits` | Soumission de formulaires en masse |
| `port_exhaustion_ratio` | `unique_src_ports / hits` | Rotation de ports (scan) |
| `orphan_ratio` | `orphan_count / hits` | Requêtes sans handshake complet |
| `ip_id_zero_ratio` | `ip_id_zero_count / hits` | Spoofing d'adresse IP |
| `multiplexing_efficiency` | `hits / unique_conn_id` | Réutilisation des connexions (H2/H3) |
| `true_window_size` | `tcp_win * 2^tcp_scale` | Taille réelle de la fenêtre TCP |
| `window_mss_ratio` | `tcp_win / tcp_mss` | Cohérence TCP stack |
| `tcp_jitter_variance` | Variance SYN→ClientHello | Irrégularité du timing TLS |
| `alpn_http_mismatch` | ALPN=h2 mais HTTP/1.1 | Négociation TLS mensongère |
| `is_alpn_missing` | ALPN absent ou `00` | Client non-standard |
| `sni_host_mismatch` | SNI ≠ Host header | Proxy transparent / bot |
| `mss_mobile_mismatch` | MSS=1460 + score navigateur élevé | Client mobile simulé depuis desktop |
| `is_fake_navigation` | `sec_fetch_mode=navigate` mais `sec_fetch_dest≠document` | Navigation simulée |
| `tcp_shared_count` | Nb d'IPs partageant la même empreinte TCP | Infrastructure partagée / botnet |
| `header_order_shared_count` | Nb d'IPs partageant le même ordre d'en-têtes | Outil automatisé commun |

---

## 5. Modèle IA : Isolation Forest (`bot_detector.py`)

### Cycle d'exécution

Le service tourne en boucle avec un **cycle de 5 minutes** :

```
fetch_and_analyze()
    │
    ├─ Requête SELECT * FROM view_ai_features_1h
    │
    ├─ Nettoyage des données (fillna)
    │
    ├─ Dual-Model routing :
    │   ├─ [Complet]      correlated=1 → 23 features (réseau + TLS + headers)
    │   └─ [Applicatif]   correlated=0 → 19 features (headers + comportement)
    │
    └─ INSERT INTO ml_detected_anomalies
```

### Paramétrage du modèle

| Paramètre | Valeur | Signification |
|---|---|---|
| `n_estimators` | 200 | Nombre d'arbres d'isolation |
| `contamination` | 0.2% | Proportion de bots attendue dans le trafic |
| `seuil de score` | < -0.05 | Score en dessous duquel une session est marquée anomalie |
| `volume minimum` | 500 sessions | En dessous, le modèle est ignoré (trop peu de données) |

### Dual-Model routing

Le trafic est **séparé en deux populations** selon le champ `correlated` :

- **Modèle Complet** (`correlated=1`) : la corrélation TCP↔HTTP est disponible → les features réseau (TTL, jitter TLS, ALPN, SNI) sont fiables et ajoutées à l'analyse.
- **Modèle Applicatif** (`correlated=0`) : seule la couche HTTP est disponible → l'analyse se concentre sur le comportement applicatif (headers, paths, POST ratio…).

---

## 6. Vues heuristiques statiques

En parallèle du modèle IA, cinq vues SQL fournissent des **détections déterministes** sans ML, sur fenêtre 24h :

| Vue | Règle de détection |
|---|---|
| `view_host_ip_ja4_rotation` | IP avec ≥ 5 fingerprints JA4 distincts et > 100 requêtes → rotation d'identité |
| `view_host_ja4_anomalies` | Fingerprint JA4 vu depuis ≥ 20 IPs sur ≥ 3 hôtes → outil de scan distribué |
| `view_form_bruteforce_detected` | ≥ 10 query params distincts et ≥ 20 hits → brute-force de formulaire |
| `view_alpn_mismatch_detected` | HTTP/1.1 avec ALPN h2 ou h3 et ≥ 10 hits → négociation TLS frauduleuse |
| `view_tcp_spoofing_detected` | TTL ≤ 64 avec User-Agent Windows ou iPhone → empreinte OS incohérente |

---

## 7. Résultats : `ml_detected_anomalies`

Les anomalies détectées sont stockées dans une table `ReplacingMergeTree(detected_at)` avec **TTL 30 jours**. La clé d'ordre `(src_ip, ja4, host)` garantit que chaque triplet ne conserve que la **détection la plus récente** (dédoublonnage automatique).

Chaque enregistrement contient :
- Les scores et features ayant conduit à la détection
- Le champ `reason` : texte lisible avec score, vélocité, et indice de fuzzing
- Le champ `is_headless` : déduit de l'incohérence `sec_fetch_mode`

---

## 8. Schéma de flux complet

```
                          ┌─────────────────────────────────────┐
                          │         http_logs_raw (JSON)         │
                          └──────────────┬──────────────────────┘
                                         │ mv_http_logs (MV)
                                         ▼
                          ┌─────────────────────────────────────┐
                          │         http_logs (parsée)           │
                          └────────┬──────────────┬─────────────┘
                                   │              │
               mv_agg_host_ip_ja4  │              │  mv_agg_header_fingerprint
                                   ▼              ▼
                    ┌──────────────────┐  ┌──────────────────────────┐
                    │ agg_host_ip_ja4  │  │ agg_header_fingerprint   │
                    │ _1h              │  │ _1h                      │
                    └────────┬─────────┘  └──────────┬──────────────┘
                             │                        │
                             └──────────┬─────────────┘
                                        │ view_ai_features_1h (JOIN + calculs)
                                        ▼
                          ┌─────────────────────────────────────┐
                          │  bot_detector.py (Isolation Forest)  │
                          │  Cycle : 5 min | Fenêtre : 24h       │
                          └──────────────┬──────────────────────┘
                                         │
                                         ▼
                          ┌─────────────────────────────────────┐
                          │     ml_detected_anomalies            │
                          │     (ReplacingMergeTree, TTL 30j)    │
                          └─────────────────────────────────────┘
```