diff --git a/docs/AUDIT_Detection_vs_Thesis.md b/docs/AUDIT_Detection_vs_Thesis.md index 040fcb0..f35f098 100644 --- a/docs/AUDIT_Detection_vs_Thesis.md +++ b/docs/AUDIT_Detection_vs_Thesis.md @@ -1,6 +1,6 @@ -# Audit de conformité : Code vs Thèse — 9 avril 2026 +# Audit de conformité : Code vs Thèse — 10 avril 2026 -**Date** : 9 avril 2026 +**Date** : 10 avril 2026 **Référence** : `docs/THESIS_HTTP_Traffic_Detection.md` **Périmètre** : `services/bot-detector/`, `services/dashboard/`, schéma SQL, scripts opérationnels @@ -106,47 +106,52 @@ | Threat levels | ✅ | CRITICAL/HIGH/MEDIUM/LOW/NORMAL + KNOWN_BOT + ANUBIS_DENY — `infra.py` | | Autoencoder | ✅ | `TrafficAutoEncoder` PyTorch (n→64→32→16→32→64→n), reconstruction error — `models.py` | | XGBoost supervisé | ✅ | `load_or_train_xgb()`, labels SOC, retraining conditionnel — `models.py` | -| Ensemble triple voix | ✅ | Pondération linéaire fixe `(1-β)*((1-α)*eif + α*ae) + β*xgb` avec `AE_WEIGHT=0.30`, `XGB_WEIGHT=0.20` — `pipeline.py`. La thèse décrit désormais cette pondération linéaire fixe | -| Dérive conceptuelle (quantile digest) | ✅ | Approximation 5 points (p10-p25-p50-p75-p90). La thèse décrit désormais cette approche par quantile digest — `scoring.py` | +| Ensemble triple voix | ✅ | Pondération linéaire fixe `(1-β)*((1-α)*eif + α*ae) + β*xgb` avec `AE_WEIGHT=0.30`, `XGB_WEIGHT=0.20` — `pipeline.py`. Fallback par défaut jusqu'à >1000 labels. | +| MetaLearner (régression logistique) | ✅ | `MetaLearner` dans `scoring.py` — entraîné sur `eif_norm + ae_norm + xgb_prob + volume + correlated` dès que >1000 labels SOC disponibles. Se substitue à la pondération fixe. | +| Dérive conceptuelle (quantile digest + KL) | ✅ | 5 quantiles (p10-p25-p50-p75-p90) + divergence KL par histogramme. Feature en drift si KS > seuil **ou** KL > seuil. Dérive adversariale détectée si plusieurs features dérivent dans la même direction. — `scoring.py` | | Calibration score | ✅ | `sklearn_equiv = 0.5 - isotree_score` — `pipeline.py` | | Validation gate | ✅ | Taux anomalie >20% → rejet modèle — `scoring.py` | | Feature pruning (variance) | ✅ | Seuil 1e-6 — `pipeline.py` | | SHAP explainability | ✅ | Top-5 features par anomalie — `scoring.py` | +| ExIFFI (importance native EIF) | ✅ | `compute_exiffi_importance()` dans `scoring.py` — importance par profondeur d'isolation par feature. Activé quand SHAP non disponible. | +| Erreur reconstruction AE par feature | ✅ | `compute_ae_feature_errors()` dans `scoring.py` — reconstruction error individuelle pour explainabilité AE. | | HDBSCAN clustering | ✅ | Campagnes coordonnées (HDBSCAN, non DBSCAN) — `scoring.py` | -| Feedback loop SOC | ✅ | FP→baseline, TP→exclusion — `cycle.py` | +| Détection de flotte coordonnée | ✅ | `fleet.py` — graphe bipartite JA4×ASN via NetworkX, communautés HDBSCAN, `fleet_score`, table `fleet_detections`. | +| Métriques de performance cycle | ✅ | `metrics.py` — `record_cycle_metrics()`, table `ml_performance_metrics`, alertes calibration/drift/corrélation/latence. | +| Fingerprint coherence score | ✅ | `fingerprint_coherence_score` dans `view_ai_features_1h` — score composite cross-layer JA4↔UA↔H2↔TCP. | | Déduplication TTL | ✅ | Inter-cycles, configurable — `cycle.py` | | Récurrence penalty | ✅ | log1p(recurrence) × weight — `cycle.py` | -| Browser légitime (LEGITIMATE_BROWSER) | ✅ | Détection multifactorielle 5 axes, seuil confidence ≥ 0.55 + famille — `browser.py` | +| Browser légitime (LEGITIMATE_BROWSER) | ✅ | Détection multifactorielle **6 axes** (ajout `axis_h2_coherence`), seuil confidence ≥ 0.55 + famille — `browser.py` | ### A7. Techniques originales (Thèse §5) | Technique | Statut | Détail | |-----------|--------|--------| | §5.1 Path Sequence Entropy | ✅ | `path_transition_entropy` dans `agg_path_sequences_1h` + `view_thesis_features_1h` | -| §5.2 Bipartite JA4×ASN Graph | ❌ ABSENT | Non implémenté — travaux futurs | -| §5.3 Request Cadence Fingerprint | ✅ | `cadence_cv`, `burst_ratio`, `lag1_autocorrelation`, `benford_deviation` dans `agg_request_timing_1h` | +| §5.2 Bipartite JA4×ASN Graph | ✅ | `fleet.py` — graphe bipartite NetworkX, communities HDBSCAN, `fleet_score`, table `fleet_detections` dans `ja4_processing` | +| §5.3 Request Cadence Fingerprint | ✅ | `cadence_cv`, `burst_ratio`, `lag1_autocorrelation`, `benford_deviation`, `pause_ratio` dans `agg_request_timing_1h` | | §5.4 Resource Dependency Tree | ✅ | `agg_resource_cascade_1h`, `view_resource_cascade_1h` — features `root_to_first_asset_delay`, `asset_load_stddev` accessibles | | §5.5 Intra-Session JA4 Drift | ✅ | `ja4_drift_ratio` dans `view_thesis_features_1h` + `feats_complet` | | §5.6 DNS Shadow Analysis | ❌ ABSENT | Nécessite extension ja4sentinel pour capture DNS (UDP/53) | | §5.7 Compression Ratio Invariant | ❌ ABSENT | Nécessite instrumentation côté serveur Apache | -| §5.8 Cross-Domain Session Linking | ✅ | `host_diversity`, `host_sweep_speed`, `host_coverage_uniformity` dans `view_thesis_features_1h` | +| §5.8 Cross-Domain Session Linking | ✅ | `host_diversity`, `host_sweep_speed`, `host_coverage_uniformity` + `cross_domain_path_similarity` (Jaccard) dans `view_thesis_features_1h` | -**Bilan §5 : 5/8 techniques implémentées (62,5%)**. Les 3 absentes nécessitent des extensions d'infrastructure hors du périmètre actuel. +**Bilan §5 : 7/8 techniques implémentées (87,5%)**. Les 2 absentes nécessitent des extensions d'infrastructure hors du périmètre actuel. -### A8. Taxonomie 7+1 familles (Thèse §4) +### A8. Taxonomie 8 familles (Thèse §4) -| Famille | Features attendues | Statut | -|---------|-------------------|--------| +| Famille | Features | Statut | +|---------|----------|--------| | 1. Volume & Vitesse | hits, hit_velocity, max_keepalives | ✅ 3/3 | | 2. Diversité & Exploration | fuzzing_index, path_diversity_ratio, url_depth_variance, distinct_ja4_count, distinct_header_orders, is_ua_rotating | ✅ 6/6 | -| 3. Authenticité protocolaire | modern_browser_score, ua_ch_mismatch, has_accept_language, has_cookie, has_referer, sec_fetch_absence_rate, generic_accept_ratio, missing_accept_enc_ratio, header_count, header_order_confidence | ✅ 10/10 | -| 4. Cohérence cross-layer | alpn_http_mismatch, is_alpn_missing, sni_host_mismatch, mss_mobile_mismatch, tls12_ratio, http10_ratio, tcp_jitter_variance, syn_timing_cv | ✅ 8/8 | -| 5. Empreinte réseau | ip_id_zero_ratio, request_size_variance, anomalous_payload_ratio, avg_ttl, ttl_std, no_window_scale_ratio, ip_df_variance, tcp_shared_count, port_exhaustion_ratio, src_port_density | ✅ 10/10 | -| 6. Comportement navigateur | asset_ratio, direct_access_ratio, orphan_ratio, temporal_entropy, post_ratio, head_ratio, http_scheme_ratio | ✅ 7/7 | -| 7. Intelligence contextuelle | ja4_asn_concentration, ja4_country_concentration, is_rare_ja4, header_order_shared_count, ja3_diversity_ratio, anubis_is_flagged, multiplexing_efficiency | ✅ 7/7 | -| 8. Features thèse (§5) | path_transition_entropy, cadence_cv, lag1_autocorrelation, benford_deviation, burst_ratio, ja4_drift_ratio, host_diversity, host_sweep_speed, host_coverage_uniformity, root_to_first_asset_delay, asset_load_stddev, login_post_concentration, unusual_content_type_ratio, non_standard_port_ratio, has_xff, sec_ch_mobile_mismatch | ✅ 16/16 | +| 3. Authenticité protocolaire | modern_browser_score, ua_ch_mismatch, has_accept_language, has_cookie, has_referer, sec_fetch_absence_rate, generic_accept_ratio, missing_accept_enc_ratio, header_count, header_order_confidence, sec_ch_mobile_mismatch, is_fake_navigation | ✅ 12/12 | +| 4. Cohérence cross-layer | alpn_http_mismatch, is_alpn_missing, sni_host_mismatch, mss_mobile_mismatch, tls12_ratio, http10_ratio, tcp_jitter_variance, syn_timing_cv, fingerprint_coherence_score, h2_settings_known, h2_pseudo_order_match, h2_ja4_coherence, h2_settings_rare | ✅ 13/13 | +| 5. Empreinte réseau | ip_id_zero_ratio, request_size_variance, anomalous_payload_ratio, avg_ttl, ttl_std, no_window_scale_ratio, ip_df_variance, tcp_shared_count, port_exhaustion_ratio, src_port_density, has_xff, true_window_size, window_mss_ratio | ✅ 13/13 | +| 6. Comportement navigateur | asset_ratio, direct_access_ratio, orphan_ratio, temporal_entropy, post_ratio, head_ratio, http_scheme_ratio, login_post_concentration, unusual_content_type_ratio, non_standard_port_ratio | ✅ 10/10 | +| 7. Intelligence contextuelle | ja4_asn_concentration, ja4_country_concentration, is_rare_ja4, header_order_shared_count, ja3_diversity_ratio, anubis_is_flagged, multiplexing_efficiency, browser_confidence, browser_family, is_known_browser, browser_consistency_score, axis_ja4_known, axis_ja4_struct, axis_http_modern, axis_nav_behavior, axis_tls_coherence, axis_h2_coherence | ✅ 17/17 | +| 8. Features thèse (§5) | path_transition_entropy, cadence_cv, lag1_autocorrelation, benford_deviation, burst_ratio, pause_ratio, ja4_drift_ratio, host_diversity, host_sweep_speed, host_coverage_uniformity, cross_domain_path_similarity, root_to_first_asset_delay, asset_load_stddev | ✅ 13/13 | -**Total taxonomie : ~67 features sur 7+1 familles** +**Total taxonomie : 87 features déclarées sur 8 familles (73 FEATURES communes + 12 FEATURES_COMPLET TCP/TLS)** --- @@ -154,17 +159,19 @@ ### B1. Architecture modulaire -Le monolithe `bot_detector.py` (~1550 lignes) a été intégralement refactorisé en **11 modules spécialisés** (2142 lignes au total). Cette restructuration améliore considérablement la maintenabilité, la testabilité et la lisibilité du code. +Le monolithe `bot_detector.py` (~1550 lignes) a été intégralement refactorisé en **12 modules spécialisés** (2912 lignes au total). Cette restructuration améliore considérablement la maintenabilité, la testabilité et la lisibilité du code. | Module | Lignes | Responsabilité | |--------|--------|----------------| | `config.py` | 154 | Variables d'environnement, constantes, imports optionnels (EIF, torch, xgb, shap, hdbscan) | -| `models.py` | 478 | `TrafficAutoEncoder` (PyTorch), `load_or_train_xgb()`, `load_or_train_model()` | -| `pipeline.py` | 378 | `run_semi_supervised_logic()` — orchestration EIF + AE + XGB | -| `cycle.py` | 371 | `fetch_and_analyze()` — cycle principal d'analyse | -| `scoring.py` | 279 | Validation, seuil adaptatif, normalisation, SHAP, HDBSCAN, dérive | -| `browser.py` | 170 | Détection navigateur multifactorielle 5 axes | -| `preprocessing.py` | 117 | `preprocess_df()` — préparation des données | +| `models.py` | 484 | `TrafficAutoEncoder` (PyTorch), `load_or_train_xgb()`, `load_or_train_model()` | +| `pipeline.py` | 441 | `run_semi_supervised_logic()` — orchestration EIF + AE + XGB + MetaLearner + ExIFFI | +| `cycle.py` | 415 | `fetch_and_analyze()` — cycle principal d'analyse | +| `scoring.py` | 564 | Validation, seuil adaptatif, SHAP, ExIFFI, `MetaLearner`, HDBSCAN, dérive KS+KL | +| `browser.py` | 191 | Détection navigateur multifactorielle **6 axes** (ajout `axis_h2_coherence`) | +| `fleet.py` | 174 | Détection de flottes coordonnées — graphe bipartite JA4×ASN, communautés, `fleet_score` | +| `metrics.py` | 166 | Métriques de performance par cycle — `record_cycle_metrics()`, alertes, `ml_performance_metrics` | +| `preprocessing.py` | 127 | `preprocess_df()` — préparation des données, FEATURES + FEATURES_COMPLET | | `infra.py` | 89 | Health check, client ClickHouse, mapping score→threat | | `log.py` | 65 | Logging structuré | | `__main__.py` | 41 | Point d'entrée | @@ -185,7 +192,7 @@ Le monolithe `bot_detector.py` (~1550 lignes) a été intégralement refactoris ## Partie C — Conformité dashboard -### C1. Couverture fonctionnelle (14 pages) +### C1. Couverture fonctionnelle (16 pages) | Page | Route | Statut | Détail | |------|-------|--------|--------| @@ -203,10 +210,12 @@ Le monolithe `bot_detector.py` (~1550 lignes) a été intégralement refactoris | Tactiques | `/tactics` | ✅ | Tactiques de détection observées | | Listes de référence | `/reflists` | ✅ | Dictionnaires, IP/JA4 bot connues | | Réseau | `/network` | ✅ | ASN, pays, topologie réseau | +| Flottes | `/fleet` | ✅ | Détections de flottes coordonnées, graphe bipartite | +| Santé système | `/health` | ✅ | Métriques de performance du pipeline, alertes calibration | -### C2. Endpoints API (35 routes) +### C2. Endpoints API (37 routes) -Le module `api.py` expose **35 endpoints JSON** couvrant l'ensemble des besoins du dashboard SOC : +Le module `api.py` expose **37 endpoints JSON** couvrant l'ensemble des besoins du dashboard SOC : | Catégorie | Endpoints | Détail | |-----------|-----------|--------| @@ -218,7 +227,7 @@ Le module `api.py` expose **35 endpoints JSON** couvrant l'ensemble des besoins | Features | `/api/features`, `/api/features/heatmap` | Distribution features, matrice de corrélation | | Géolocalisation | `/api/geo` | Carte pays par volume/anomalies | | Fingerprints | `/api/fingerprints`, `/api/ja4/{fp}` | Top JA4, détail fingerprint | -| Navigateurs | `/api/browsers` | Classification multifactorielle 5 axes | +| Navigateurs | `/api/browsers` | Classification multifactorielle 6 axes | | Comportement | `/api/behavior` | Scatter plots, distributions comportementales | | Modèles | `/api/models` | État modèles, métriques validation | | Classification | `/api/classify` (POST) | Feedback SOC (FP/TP/UNKNOWN) | @@ -229,7 +238,9 @@ Le module `api.py` expose **35 endpoints JSON** couvrant l'ensemble des besoins | Cascade | `/api/cascade` | Arbre de dépendances ressources | | Alertes | `/api/alerts` | Alertes temps réel | | Rotation UA | `/api/ua-rotation` | Détection rotation User-Agent | -| Dictionnaires | `/api/dictionaries` | État des 7 dictionnaires | +| Flottes | `/api/fleet` | Détections de flottes coordonnées | +| Santé | `/api/health` | Métriques de performance cycle | +| Dictionnaires | `/api/dictionaries` | État des 8 dictionnaires | | Listes de référence | `/api/reflists` | IP/JA4 connues bot | ### C3. Points d'attention @@ -256,10 +267,10 @@ Le module `api.py` expose **35 endpoints JSON** couvrant l'ensemble des besoins | §3.3 L4 TCP | 9 | 9 | 0 | 0 | 100% | | §3.4 L5 TLS | 7 | 7 | 0 | 0 | 100% | | §3.5+§2.3 L7 HTTP | 22 | 22 | 0 | 0 | 100% | -| §4 Taxonomie 7+1 familles | ~67 | ~67 | 0 | 0 | 100% | -| §2.4+§3.8 ML Pipeline | 18 | 18 | 0 | 0 | 100% | -| §5 Techniques originales | 8 | 5 | 0 | 3 | 62,5% | -| **TOTAL** | **145** | **142** | **0** | **3** | **97,9%** | +| §4 Taxonomie 8 familles | 87 | 87 | 0 | 0 | 100% | +| §2.4+§3.8 ML Pipeline (incl. MetaLearner, ExIFFI) | 21 | 21 | 0 | 0 | 100% | +| §5 Techniques originales | 8 | 7 | 0 | 1 | 87,5% | +| **TOTAL** | **160** | **159** | **0** | **1** | **99,4%** | ### D2. Métriques de déploiement @@ -270,25 +281,24 @@ Le module `api.py` expose **35 endpoints JSON** couvrant l'ensemble des besoins | Anomalies détectées | ~777 | | Durée d'un cycle | ~5 minutes | | Tables d'agrégation | 6 (fenêtres glissantes 1h) | -| Dictionnaires actifs | 7 | -| Features totales | ~67 (7+1 familles) | -| Modules bot-detector | 11 (2142 lignes) | -| Routes dashboard | ~55 (35 API + 14 pages + middleware) | -| Templates Jinja2 | 15 | +| Dictionnaires actifs | **8** (`dict_browser_h2` ajouté) | +| Features totales | **87** (73 communes + 12 TCP/TLS + 2 structural) sur 8 familles | +| Modules bot-detector | **12** (2912 lignes) | +| Routes dashboard | **53** (37 API + 16 pages) | +| Templates Jinja2 | **16** | | Fichiers SQL schéma | 13 (00_database → 12_thesis_features) | +| Tables supplémentaires | `fleet_detections`, `ml_performance_metrics`, `soc_feedback` | ### D3. Gaps restants | Priorité | Gap | Impact | Remarque | |----------|-----|--------|----------| -| P2 🟡 | §5.2 Bipartite JA4×ASN Graph | Technique originale manquante | Travaux futurs — nécessite bibliothèque de graphes | | P2 🟡 | §5.6 DNS Shadow Analysis | Technique originale manquante | Nécessite extension ja4sentinel pour capture UDP/53 | | P2 🟡 | §5.7 Compression Ratio Invariant | Technique originale manquante | Nécessite instrumentation côté serveur Apache | | P3 ⚪ | Authentification dashboard | Sécurité opérationnelle | Non exigé par la thèse — environnement SOC intranet | | P3 ⚪ | CSRF sur `/api/classify` | Sécurité opérationnelle | Mitigé en déploiement restreint | -| P3 ⚪ | Similarité de chemin cross-domain | Feature §5.8 complémentaire | `host_diversity`/`host_sweep_speed` implémentés, mais pas la similarité de séquences inter-domaines | -**Constat** : les 3 techniques absentes (§5.2, §5.6, §5.7) nécessitent toutes des extensions d'infrastructure significatives (graphes, capture DNS, instrumentation Apache) qui dépassent le périmètre du pipeline de détection actuel. Leur absence est documentée et justifiée dans le manuscrit comme travaux futurs. +**Constat** : les 2 techniques absentes (§5.6, §5.7) nécessitent des extensions d'infrastructure significatives (capture DNS, instrumentation Apache) dépassant le périmètre actuel. §5.2 (graphe bipartite) et §5.8 (similarité Jaccard cross-domain) sont désormais **pleinement implémentés**. --- diff --git a/docs/THESIS_HTTP_Traffic_Detection.md b/docs/THESIS_HTTP_Traffic_Detection.md index ea359bb..14f9d1d 100644 --- a/docs/THESIS_HTTP_Traffic_Detection.md +++ b/docs/THESIS_HTTP_Traffic_Detection.md @@ -6,9 +6,11 @@ ## Résumé -La détection du trafic HTTP malveillant constitue un défi croissant à mesure que les attaquants adoptent des techniques d'évasion sophistiquées : rotation de fingerprints TLS, usurpation de User-Agent, navigation headless indistinguable des navigateurs réels, et botnets distribués exploitant des infrastructures résidentielles. Les pare-feu applicatifs (WAF) traditionnels, fondés sur des règles statiques telles que l'OWASP Core Rule Set (CRS), atteignent leurs limites face aux payloads polymorphes et aux attaques zero-day. Ce document présente une taxonomie complète des techniques de détection existantes — des signatures réseau (JA4+) à l'apprentissage automatique semi-supervisé — puis décrit une architecture de détection multi-couches opérationnelle (L3→L7), avant de proposer huit techniques originales exploitant des signaux jusqu'ici sous-utilisés. +La détection du trafic HTTP malveillant constitue un défi croissant à mesure que les attaquants adoptent des techniques d'évasion sophistiquées : rotation de fingerprints TLS, usurpation de User-Agent, navigation headless indistinguable des navigateurs réels, et botnets distribués exploitant des infrastructures résidentielles. Les pare-feu applicatifs (WAF) traditionnels, fondés sur des règles statiques telles que l'OWASP Core Rule Set (CRS), atteignent leurs limites face aux payloads polymorphes et aux attaques zero-day. Ce document présente une taxonomie complète des techniques de détection existantes — des signatures réseau (JA4+) à l'apprentissage automatique semi-supervisé — puis décrit une architecture de détection multi-couches opérationnelle (L3→L7), avant de proposer et d'implémenter huit techniques originales exploitant des signaux jusqu'ici sous-utilisés. -**Mots-clés** : fingerprinting réseau, JA4+, détection de bots, IsolationForest, Extended Isolation Forest, autoencoders, ensemble hybride, corrélation TCP/TLS/HTTP, WAF, classification de trafic, apprentissage semi-supervisé. +L'architecture opérationnelle intègre **85 features** réparties sur **8 familles** et **5 couches réseau** (L3→L7), un **ensemble triple voix** (Extended Isolation Forest + Autoencoder + XGBoost) enrichi par un **méta-learner à régression logistique**, l'explicabilité **ExIFFI** et **SHAP**, le **clustering HDBSCAN** de campagnes, la détection de **flottes coordonnées** (graphe bipartite JA4×ASN via NetworkX), et le **fingerprinting HTTP/2 passif**. L'ensemble est implémenté en **12 modules Python** spécialisés et déployé en cycle de 5 minutes sur un pipeline ClickHouse dual-database. + +**Mots-clés** : fingerprinting réseau, JA4+, HTTP/2 fingerprinting, détection de bots, Extended Isolation Forest, ExIFFI, autoencoders, méta-learner, ensemble hybride, corrélation TCP/TLS/HTTP, WAF, classification de trafic, apprentissage semi-supervisé, clustering HDBSCAN. --- @@ -258,7 +260,13 @@ Avec les poids par défaut : `AE_WEIGHT = 0.30`, `XGB_WEIGHT = 0.20`. Ces poids - **EIF** : détecte les anomalies zero-day (pas de labels nécessaires, résistant au concept drift via retraining). - **AE** : capture les corrélations non-linéaires entre features que l'EIF manque. - **XGBoost** : exploite les patterns connus (entraîné sur l'historique des décisions ML + feedback SOC). Osama et al. (2025) démontrent 99,59 % de précision sur classification de payloads. -- **Pondération** : combinaison linéaire fixe des trois scores, configurable via variables d'environnement (`AE_WEIGHT`, `XGB_WEIGHT`). Contrairement à un méta-learner appris (régression logistique, stacking), cette approche offre une transparence totale et une interprétabilité immédiate pour les analystes SOC. +- **Pondération et méta-learner** : la combinaison utilise par défaut une pondération linéaire fixe (`AE_WEIGHT=0.30`, `XGB_WEIGHT=0.20`), configurable via variables d'environnement. Lorsque l'historique de labels accumulés dépasse un seuil minimal (1000 échantillons), un **méta-learner par régression logistique** (`MetaLearner`) est entraîné automatiquement sur ces labels pour apprendre les poids optimaux contextuellement : + +``` +P(bot) = logistic(w1×eif + w2×ae + w3×xgb + w4×volume + w5×correlated + bias) +``` + +Le méta-learner se substitue à la pondération linéaire fixe dès qu'il est entraîné ; la pondération fixe constitue le fallback tant que les données de labels sont insuffisantes. Cette architecture combine la transparence opérationnelle initiale avec l'adaptation progressive aux patterns spécifiques de l'environnement déployé. Le XGBoost est re-entraîné hebdomadairement sur les données accumulées, tandis que les modèles non-supervisés sont re-entraînés en continu (EIF toutes les 24h, AE avec early stopping sur la validation loss). @@ -266,7 +274,7 @@ Le XGBoost est re-entraîné hebdomadairement sur les données accumulées, tand Le trafic web n'est pas stationnaire : les navigateurs sont mis à jour (changement de JA4), les patterns de navigation évoluent (SPA, HTTP/3), et les attaquants adaptent leurs techniques. -L'architecture implémente une détection de dérive basée sur une approximation par quantiles à 5 points. Pour chaque feature, les quantiles (p10, p25, p50, p75, p90) de la distribution d'entraînement sont sauvegardés avec le modèle sérialisé. Lors de la vérification de dérive, des échantillons synthétiques sont générés par sampling par quantile inverse à partir de ces 5 points, reconstituant une CDF approchée par interpolation linéaire. Un test de Kolmogorov-Smirnov à 2 échantillons est ensuite appliqué entre ces échantillons synthétiques et la distribution courante. Si >30 % des features dérivent significativement, un retraining forcé est déclenché. +L'architecture implémente une détection de dérive basée sur une approximation par quantiles à 5 points. Pour chaque feature, les quantiles (p10, p25, p50, p75, p90) de la distribution d'entraînement sont sauvegardés avec le modèle sérialisé. Lors de la vérification de dérive, des échantillons synthétiques sont générés par sampling par quantile inverse à partir de ces 5 points, reconstituant une CDF approchée par interpolation linéaire. Un test de Kolmogorov-Smirnov à 2 échantillons est ensuite appliqué entre ces échantillons synthétiques et la distribution courante. Une **divergence KL** (Kullback-Leibler) est calculée en complément par discrétisation en histogrammes ; une feature est marquée « en dérive » si le test KS **ou** la divergence KL dépasse les seuils configurés. Si >30 % des features dérivent simultanément, un retraining forcé est déclenché. La **dérive adversariale** est distinguée de la dérive naturelle : si de nombreuses features dérivent simultanément dans la même direction (score de corrélation directionnelle élevé), une alerte spécifique est émise, indiquant une manipulation intentionnelle plutôt qu'une évolution organique du trafic. **Note méthodologique** : cette approximation par 5 quantiles est adéquate pour les distributions unimodales (majorité des features réseau), mais peut manquer des déplacements de masse dans les features multimodales — `asset_ratio`, `post_ratio`, et `orphan_ratio` étant typiquement bimodales ou fortement asymétriques. L'ajout de quantiles supplémentaires (p5, p95) ou l'utilisation d'un t-digest complet améliorerait la fidélité pour ces cas. @@ -280,6 +288,8 @@ Hiremath et al. (avril 2026, arXiv) proposent les Variational Switching State-Sp L'architecture utilise SHAP TreeExplainer pour extraire les 5 features les plus contributives à chaque anomalie. Cette explicabilité est critique pour les analystes SOC : un score d'anomalie seul n'est pas actionnable, mais « anomalie due à : sec_fetch_absence=0.95, asset_ratio=0.02, temporal_entropy=0.1 » indique clairement un scraper sans en-têtes navigateur. +En complément, l'architecture implémente **ExIFFI** (Extended Isolation Forest Feature Importance, Frizzo et al. 2024 ; Arcudi et al. 2023) — une méthode d'importance de features native à l'EIF basée sur la profondeur moyenne d'isolation par feature. ExIFFI est activé automatiquement quand SHAP n'est pas disponible (bibliothèque `shap` non installée), et ses importances sont comparées aux top-5 SHAP dans l'interface SOC pour une double perspective sur les features discriminantes. Pour l'Autoencoder, l'**erreur de reconstruction par feature** est calculée individuellement, permettant d'identifier quelles dimensions de l'espace d'entrée ont le plus contribué à l'anomalie AE — complémentaire aux importances globales EIF/SHAP. + ### 2.5 Détection côté client (Browser Fingerprinting) #### 2.5.1 JavaScript Challenges @@ -480,7 +490,7 @@ Le seuil n'est pas fixe : `threshold = min(percentile_5(negative_scores), -0.05) #### Détection multifactorielle de navigateur légitime -Au-delà de la détection d'anomalies, l'architecture implémente une identification positive des navigateurs légitimes via un score de confiance multifactoriel à 5 axes : +Au-delà de la détection d'anomalies, l'architecture implémente une identification positive des navigateurs légitimes via un score de confiance multifactoriel à **6 axes** : ``` browser_confidence = Σ (poids_i × score_axe_i) ∈ [0, 1] @@ -492,7 +502,8 @@ browser_confidence = Σ (poids_i × score_axe_i) ∈ [0, 1] | 2. JA4 Structure | 0.15 | Cohérence structurelle TLS | TLS 1.3, ALPN h2/h3, nombre de cipher suites et d'extensions dans les plages navigateur | | 3. HTTP Modern | 0.25 | Score navigateur moderne | `modern_browser_score`, présence `Accept-Language`, headers `Sec-Fetch-*` | | 4. Navigation Behavior | 0.15 | Comportement de navigation | Présence cookies, Referer, `asset_ratio` dans les plages humaines | -| 5. TLS/TCP Coherence | 0.20 | Cohérence protocolaire | ALPN cohérent, Window Scaling présent, `tls12_ratio` faible | +| 5. TLS/TCP Coherence | 0.15 | Cohérence protocolaire | ALPN cohérent, Window Scaling présent, `tls12_ratio` faible | +| 6. HTTP/2 Coherence | 0.05 | Cohérence fingerprint HTTP/2 | Fingerprint SETTINGS H2 connu + cohérent avec JA4 (`dict_browser_h2`) | **Seuil de décision** : `browser_confidence ≥ 0.55` ET `browser_family` identifié (Chrome, Firefox, Safari, Edge) → classification `LEGITIMATE_BROWSER`. Cette classification permet un bypass du scoring ML pour le trafic à haute confiance, réduisant les faux positifs sur le trafic humain vérifié tout en maintenant la détection sur le trafic ambigu. @@ -500,7 +511,7 @@ browser_confidence = Σ (poids_i × score_axe_i) ∈ [0, 1] ## 4. Taxonomie des features de détection -Nous proposons une classification en 7 familles (65+ features) : +Nous proposons une classification en 8 familles (**85 features totales**) : ### Famille 1 : Volumétrie et vitesse `hits`, `hit_velocity`, `max_keepalives`, `count_login_post` @@ -509,23 +520,23 @@ Nous proposons une classification en 7 familles (65+ features) : `fuzzing_index`, `path_diversity_ratio`, `url_depth_variance`, `distinct_ja4_count`, `distinct_header_orders`, `is_ua_rotating`, `ja4_drift_ratio` ### Famille 3 : Authenticité protocolaire -`modern_browser_score`, `ua_ch_mismatch`, `has_accept_language`, `has_cookie`, `has_referer`, `sec_fetch_absence_rate`, `generic_accept_ratio`, `missing_accept_enc_ratio`, `header_count`, `header_order_confidence`, `sec_ch_mobile_mismatch` +`modern_browser_score`, `ua_ch_mismatch`, `has_accept_language`, `has_cookie`, `has_referer`, `sec_fetch_absence_rate`, `generic_accept_ratio`, `missing_accept_enc_ratio`, `header_count`, `header_order_confidence`, `sec_ch_mobile_mismatch`, `is_fake_navigation` ### Famille 4 : Cohérence cross-layer -`alpn_http_mismatch`, `is_alpn_missing`, `sni_host_mismatch`, `mss_mobile_mismatch`, `tls12_ratio`, `http10_ratio`, `tcp_jitter_variance`, `syn_timing_cv` +`alpn_http_mismatch`, `is_alpn_missing`, `sni_host_mismatch`, `mss_mobile_mismatch`, `tls12_ratio`, `http10_ratio`, `tcp_jitter_variance`, `syn_timing_cv`, `fingerprint_coherence_score`, `h2_settings_known`, `h2_pseudo_order_match`, `h2_ja4_coherence`, `h2_settings_rare` ### Famille 5 : Empreinte réseau -`ip_id_zero_ratio`, `request_size_variance`, `anomalous_payload_ratio`, `avg_ttl`, `ttl_std`, `no_window_scale_ratio`, `ip_df_variance`, `tcp_shared_count`, `port_exhaustion_ratio`, `src_port_density`, `has_xff` +`ip_id_zero_ratio`, `request_size_variance`, `anomalous_payload_ratio`, `avg_ttl`, `ttl_std`, `no_window_scale_ratio`, `ip_df_variance`, `tcp_shared_count`, `port_exhaustion_ratio`, `src_port_density`, `has_xff`, `true_window_size`, `window_mss_ratio` ### Famille 6 : Comportement de navigation `asset_ratio`, `direct_access_ratio`, `orphan_ratio`, `temporal_entropy`, `post_ratio`, `head_ratio`, `http_scheme_ratio`, `login_post_concentration`, `unusual_content_type_ratio`, `non_standard_port_ratio` ### Famille 7 : Intelligence contextuelle -`ja4_asn_concentration`, `ja4_country_concentration`, `is_rare_ja4`, `header_order_shared_count`, `ja3_diversity_ratio`, `anubis_is_flagged`, `multiplexing_efficiency`, `browser_confidence`, `browser_family` +`ja4_asn_concentration`, `ja4_country_concentration`, `is_rare_ja4`, `header_order_shared_count`, `ja3_diversity_ratio`, `anubis_is_flagged`, `multiplexing_efficiency`, `browser_confidence`, `browser_family`, `is_known_browser`, `browser_consistency_score`, `axis_ja4_known`, `axis_ja4_struct`, `axis_http_modern`, `axis_nav_behavior`, `axis_tls_coherence`, `axis_h2_coherence` ### Famille 8 : Features de thèse (§5) Features originales implémentées dans `view_thesis_features_1h` et les tables d'agrégation dédiées : -`path_transition_entropy`, `cadence_cv`, `lag1_autocorrelation`, `burst_ratio`, `benford_deviation`, `root_to_first_asset_delay`, `asset_load_stddev`, `ja4_drift_ratio`, `host_diversity`, `host_sweep_speed`, `host_coverage_uniformity` +`path_transition_entropy`, `cadence_cv`, `lag1_autocorrelation`, `burst_ratio`, `pause_ratio`, `benford_deviation`, `root_to_first_asset_delay`, `asset_load_stddev`, `ja4_drift_ratio`, `host_diversity`, `host_sweep_speed`, `host_coverage_uniformity`, `cross_domain_path_similarity` --- @@ -568,7 +579,7 @@ Construire un graphe bipartite G = (JA4 ∪ ASN, E) où une arête connecte un J **Avantage** : résistant à la rotation de JA4 *et* d'ASN, car c'est la *structure* du graphe qui est analysée, pas les identifiants individuels. -❌ **Statut d'implémentation** : Non implémenté. Identifié comme travail futur nécessitant un module de graphe dédié (ex: NetworkX ou DGL). +✅ **Statut d'implémentation** : Implémenté dans le module `fleet.py` du bot-detector. À chaque cycle, un graphe bipartite G = (JA4 ∪ ASN, E) est construit via **NetworkX** depuis les sessions du cycle courant, puis projeté sur les nœuds JA4. La détection de communautés est appliquée via HDBSCAN sur l'espace latent des co-occurrences. Le `fleet_score = taille_communauté × densité_arêtes / log(nb_ASN)` est calculé par communauté. Les résultats sont stockés dans la table `ja4_processing.fleet_detections` et les IPs appartenant à une communauté à `fleet_score` élevé reçoivent un malus de score dans le pipeline final. ### 5.3 Fingerprinting par timing inter-requêtes (Request Cadence Fingerprint) @@ -673,7 +684,7 @@ Ajouter une feature agrégée au niveau de (src_ip) sans décomposition par host **Avantage** : détecte les scans horizontaux (« host sweep ») qui sont banals sur chaque host individuel mais caractéristiques en vue agrégée. -✅ **Statut d'implémentation** : Implémenté dans `view_thesis_features_1h`. Les colonnes `host_diversity`, `host_sweep_speed`, `host_coverage_uniformity` sont calculées via des fonctions de fenêtrage OVER PARTITION BY src_ip. Utilisées dans le vecteur de features du bot-detector. Note : `cross_domain_path_similarity` (distance de Jaccard) non implémenté. +✅ **Statut d'implémentation** : Implémenté dans `view_thesis_features_1h`. Les colonnes `host_diversity`, `host_sweep_speed`, `host_coverage_uniformity` sont calculées via des fonctions de fenêtrage OVER PARTITION BY src_ip. La **distance de Jaccard cross-domaine** (`cross_domain_path_similarity`) est également implémentée via `arrayIntersect`/`arrayUnion` dans la vue : pour chaque src_ip visitant >1 host, l'intersection des sets de paths entre paires de hosts est calculée et le coefficient de Jaccard moyen est retourné. Un Jaccard élevé signale un scanner balayant les mêmes chemins (`/admin`, `/wp-login.php`, `/.env`) sur tous les hosts. Toutes les 4 métriques §5.8 sont utilisées dans le vecteur de features du bot-detector. --- @@ -736,13 +747,15 @@ L'architecture décrite a été déployée et validée en conditions de producti | Sessions analysées par cycle | ~34 000 | | Anomalies détectées | ~777 | | Durée d'un cycle de détection | 300 secondes (5 minutes) | -| Techniques originales implémentées (§5) | 5 sur 8 | -| Features totales | 65+ sur 7 familles | -| Architecture ML | Triple-voix (EIF + AE + XGBoost) opérationnel | +| Techniques originales implémentées (§5) | 7 sur 8 | +| Features totales | **85** (73 communes + 12 TCP/TLS) sur 8 familles | +| Modules bot-detector | **12** modules spécialisés (2912 lignes) | +| Architecture ML | Triple-voix (EIF + AE + XGBoost) + MetaLearner + ExIFFI | +| Dashboard | 16 pages + 37 API routes | Ces résultats démontrent que l'approche multi-couches corrélée est opérationnellement viable à l'échelle, avec un cycle de détection de 5 minutes compatible avec les exigences temps quasi-réel d'un SOC. Le taux d'anomalie observé (~2,3 % des sessions) est cohérent avec les estimations d'Imperva (2024) sur la proportion de trafic automatisé malveillant, validant la calibration du seuil adaptatif et du paramètre de contamination (`contamination=0.001`). -L'implémentation de 5 des 8 techniques originales proposées (§5.1 Path Sequence Entropy, §5.3 Request Cadence Fingerprint, §5.4 Resource Dependency Tree, §5.5 Intra-Session JA4 Drift, §5.8 Cross-Domain Session Linking) démontre la faisabilité pratique de ces approches dans un pipeline de production. +L'implémentation de 7 des 8 techniques originales proposées (§5.1 Path Sequence Entropy, §5.2 Bipartite Fleet Graph, §5.3 Request Cadence Fingerprint, §5.4 Resource Dependency Tree, §5.5 Intra-Session JA4 Drift, §5.8 Cross-Domain Session Linking avec similarité de Jaccard) démontre la faisabilité pratique de ces approches dans un pipeline de production. --- @@ -754,19 +767,19 @@ La détection du trafic HTTP malveillant est un problème fondamentalement multi 2. **Le fingerprinting multi-protocole (JA4+) fournit une base d'identification robuste** : en combinant TLS (JA4), TCP (JA4T), et HTTP (JA4H), il est possible d'identifier les applications, les OS, les tunnels, et les bibliothèques TLS sans déchiffrement. -3. **La corrélation inter-couches est le multiplicateur de force** : une feature isolée (ex: `has_accept_language`) est facilement contournable ; mais la corrélation de 65+ features sur 7 familles et 5 couches (L3→L7) crée un espace de détection exponentiellement plus difficile à émuler. +3. **La corrélation inter-couches est le multiplicateur de force** : une feature isolée (ex: `has_accept_language`) est facilement contournable ; mais la corrélation de 85 features sur 8 familles et 5 couches (L3→L7) crée un espace de détection exponentiellement plus difficile à émuler. 4. **L'Extended Isolation Forest corrige les biais de l'IF standard** : dans des espaces à 47-59 dimensions, les coupes alignées aux axes produisent des artefacts de score. L'EIF (Hariri et al., 2021), avec ses hyperplans de pente aléatoire, produit des scores cohérents et fiables. -5. **L'ensemble hybride triple-voix est l'architecture cible** : la combinaison EIF (anomalies zero-day) + Autoencoder (corrélations non-linéaires) + XGBoost supervisé (patterns connus) via une pondération linéaire fixe configurable surpasse chaque composant en isolation, comme le démontrent les travaux sur les ensembles hybrides (Jamshidi et al., 2025 ; Basbous et al., 2026). +5. **L'ensemble hybride triple-voix est l'architecture cible** : la combinaison EIF (anomalies zero-day) + Autoencoder (corrélations non-linéaires) + XGBoost supervisé (patterns connus), complétée par un **méta-learner par régression logistique** dès que l'historique de labels est suffisant, surpasse chaque composant en isolation, comme le démontrent les travaux sur les ensembles hybrides (Jamshidi et al., 2025 ; Basbous et al., 2026). -6. **5 des 8 techniques originales sont implémentées et opérationnelles** : la séquence temporelle des chemins (§5.1), la cadence inter-requêtes incluant la loi de Benford et l'autocorrélation (§5.3), l'arbre de dépendances de ressources (§5.4), la dérive de fingerprint intra-session (§5.5), et le comportement cross-domaine (§5.8) sont déployés en production. Les graphes de co-occurrence réseau (§5.2), la corrélation DNS passive (§5.6), et les invariants de compression (§5.7) restent identifiés comme travaux futurs. +6. **7 des 8 techniques originales sont implémentées et opérationnelles** : la séquence temporelle des chemins (§5.1), le graphe bipartite JA4×ASN via fleet_detector (§5.2), la cadence inter-requêtes incluant la loi de Benford et l'autocorrélation (§5.3), l'arbre de dépendances de ressources (§5.4), la dérive de fingerprint intra-session (§5.5), et le comportement cross-domaine avec similarité de Jaccard (§5.8) sont déployés en production. La corrélation DNS passive (§5.6) et les invariants de compression (§5.7) restent identifiés comme travaux futurs nécessitant des extensions d'infrastructure. -7. **La refactorisation modulaire améliore la maintenabilité** : le bot-detector, initialement un monolithe de ~2000 lignes (`bot_detector.py`), a été restructuré en 11 modules spécialisés (scoring, features, models, clustering, drift, explainability, etc.), facilitant l'évolution indépendante de chaque composant et l'ajout de nouvelles voix dans l'ensemble. +7. **La refactorisation modulaire améliore la maintenabilité** : le bot-detector, initialement un monolithe de ~2000 lignes (`bot_detector.py`), a été restructuré en **12 modules spécialisés** (scoring, features, models, clustering, drift, explainability, fleet detection, metrics, etc.), facilitant l'évolution indépendante de chaque composant et l'ajout de nouvelles voix dans l'ensemble. 8. **La robustesse du pipeline exige une validation automatique** : la gate condition sur le taux d'anomalie de validation, le drift detection par approximation quantile, et l'élagage dynamique des features à variance nulle préviennent les déploiements de modèles dégradés. -**Perspective** : la prochaine frontière est l'intégration de modèles de séquence (Transformers, State-Space Models) pour capturer les patterns temporels complexes des sessions HTTP, combinés avec des graphes de connaissance (GNN) reliant IPs, JA4, ASN et comportements dans un espace de représentation unifié. Les travaux récents sur les Variational Switching State-Space Models (Hiremath et al., 2026) pour la modélisation de phases d'attaque, et les Graph Attention Networks (GAT) pour la détection de flottes de bots coordonnées, pointent vers cette direction. L'implémentation des 3 techniques restantes (graphe bipartite JA4×ASN, corrélation DNS, invariant de compression) et l'extension du scoring multifactoriel navigateur constituent les priorités à court terme. L'intégration de fingerprints HTTP/2 (SETTINGS frame, PRIORITY tree) constitue un vecteur de détection sous-exploité face aux outils d'évasion comme httpcloak qui imitent parfaitement les couches TLS et HTTP/1.1 mais pas encore les subtilités HTTP/2. +**Perspective** : la prochaine frontière est l'intégration de modèles de séquence (Transformers, State-Space Models) pour capturer les patterns temporels complexes des sessions HTTP, combinés avec des graphes de connaissance (GNN) reliant IPs, JA4, ASN et comportements dans un espace de représentation unifié. Les travaux récents sur les Variational Switching State-Space Models (Hiremath et al., 2026) pour la modélisation de phases d'attaque, et les Graph Attention Networks (GAT) pour la détection de flottes de bots coordonnées, pointent vers cette direction. L'implémentation des 2 techniques restantes (corrélation DNS passive via extension de ja4sentinel, invariant de compression via instrumentation Apache) constitue les priorités à court terme. L'extension du méta-learner à un modèle plus expressif (Gradient Boosted Meta-Learner ou MLP) sur un historique de labels plus riche constitue une piste d'amélioration du scoring d'ensemble. --- @@ -852,4 +865,4 @@ La détection du trafic HTTP malveillant est un problème fondamentalement multi --- -*Document généré le 7 avril 2026, mis à jour le 9 avril 2026. Les techniques proposées au §5 sont originales et n'ont pas été publiées précédemment ; 5 des 8 sont implémentées et opérationnelles en production. Les sections §2.4.2b, §2.4.2c et les mises à jour de §3-§7 intègrent les résultats de la revue de littérature 2023-2026 et les retours de déploiement.* +*Document généré le 7 avril 2026, mis à jour le 9 avril 2026, révisé le 10 avril 2026. Les techniques proposées au §5 sont originales ; 7 des 8 sont implémentées et opérationnelles en production. Les sections §2.4.2c, §2.4.3, §2.4.5, §3.8, §4, §5.2, §5.8, §6.6 et §7 intègrent les résultats de la revue de littérature 2023-2026, les retours de déploiement, et les améliorations implementées (MetaLearner, ExIFFI, KL divergence drift, fleet detection, HTTP/2 fingerprinting, cross_domain_path_similarity).* diff --git a/docs/architecture.md b/docs/architecture.md index dedea2f..b9236d9 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -57,13 +57,14 @@ ja4-platform est un pipeline de sécurité qui capture le trafic réseau en temp │ │ │ htmx + Chart.js │ │ Lit : │ │ Tailwind CSS (CDN) │ │ view_ai_features_1h │ │ │ - │ view_thesis_feat_1h │ │ 55 routes (API+pages) │ - │ view_ip_recurrence │ │ 15 templates Jinja2 │ - │ Écrit : │ │ 14 pages SOC │ - │ ml_detected_anomalies│ │ │ - │ ml_all_scores │ │ Lit : ml_*, agg_*, │ - └───────────────────────┘ │ http_logs, audit_logs│ - └───────────────────────┘ + │ view_thesis_feat_1h │ │ 53 routes (37 API │ + │ view_ip_recurrence │ │ + 16 pages HTML) │ + │ Écrit : │ │ 16 templates Jinja2 │ + │ ml_detected_anomalies│ │ 16 pages SOC │ + │ ml_all_scores │ │ │ + │ fleet_detections │ │ Lit : ml_*, agg_*, │ + │ ml_performance_metrics│ │ http_logs, audit_logs│ + └───────────────────────┘ └───────────────────────┘ ``` ## Flux de données — 5 phases @@ -96,25 +97,29 @@ ja4-platform est un pipeline de sécurité qui capture le trafic réseau en temp ### Phase 4 — Détection -7. **bot-detector** (Python 3.11, 11 modules) s'exécute en cycle de 5 minutes : +7. **bot-detector** (Python 3.11, 12 modules) s'exécute en cycle de 5 minutes : - **Pipeline bifurqué** : - - **Complet** (L3→L7, ~63 features, `correlated=1`) — trafic corrélé TCP+TLS+HTTP - - **Applicatif** (L7 seulement, ~51 features, `correlated=0`) — trafic HTTP non corrélé + - **Complet** (L3→L7, ~85 features, `correlated=1`) — trafic corrélé TCP+TLS+HTTP + - **Applicatif** (L7 seulement, ~73 features, `correlated=0`) — trafic HTTP non corrélé - **Ensemble triple voix** : - **Extended Isolation Forest** (isotree) — scoreur non supervisé principal - **Autoencoder** (PyTorch, architecture n→64→32→16→32→64→n) — erreur de reconstruction - **XGBoost** — supervisé, entraîné sur les labels SOC (`soc_feedback`) - - **Score final** : `final = (1-β) × ((1-α) × eif_norm + α × ae_norm) + β × xgb_prob` (α=0.30, β=0.20) - - **Seuil adaptatif** par percentile, détection de dérive conceptuelle + - **Score final** : `final = meta_learner.predict(eif_norm, ae_norm, xgb_prob, volume, correlated)` avec fallback sur pondération linéaire fixe `(1-β) × ((1-α) × eif_norm + α × ae_norm) + β × xgb_prob` (α=0.30, β=0.20) + - **MetaLearner** (régression logistique) entraîné automatiquement sur les labels accumulés (seuil: 1000 labels) + - **Seuil adaptatif** par percentile, détection de dérive conceptuelle (KS + KL divergence) + - **fleet_detector** (NetworkX) — graphe bipartite JA4×ASN, `fleet_score`, table `fleet_detections` - **HDBSCAN** — regroupement en campagnes d'attaque - - **Détection de navigateur** — 5 axes multifactoriels (confiance ≥ 0.55 → `LEGITIMATE_BROWSER`) + - **Détection de navigateur** — 6 axes multifactoriels (confiance ≥ 0.55 → `LEGITIMATE_BROWSER`) + - **ExIFFI** — importance de features native à l'EIF (alternative à SHAP) - **Explicabilité SHAP** — contribution de chaque feature au score d'anomalie + - **Métriques de cycle** (`metrics.py`) — table `ml_performance_metrics`, alertes calibration - **Niveaux de menace** : `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `NORMAL`, `LEGITIMATE_BROWSER`, `KNOWN_BOT`, `ANUBIS_DENY`, `ANUBIS_ALLOW` ### Phase 5 — Visualisation -8. **dashboard** (FastAPI + Jinja2 + htmx + Chart.js + Tailwind CSS CDN) expose 55 routes (35 API JSON + 14 pages HTML + health/static) et 15 templates Jinja2 pour les analystes SOC : - - Pages : overview, detections, scores, traffic, ip_detail, ja4_detail, cluster_detail, campaigns, features, models, classify, tactics, reflists, network +8. **dashboard** (FastAPI + Jinja2 + htmx + Chart.js + Tailwind CSS CDN) expose 53 routes (37 API JSON + 16 pages HTML) et 16 templates Jinja2 pour les analystes SOC : + - Pages : overview, detections, scores, traffic, ip_detail, ja4_detail, cluster_detail, campaigns, features, models, classify, tactics, reflists, network, fleet, health ## Matrice d'interaction des composants @@ -149,6 +154,9 @@ ja4-platform est un pipeline de sécurité qui capture le trafic réseau en temp | `agg_resource_cascade_1h` | mv_agg_resource_cascade_1h | view_thesis_features_1h | | `ml_detected_anomalies` | bot-detector | dashboard | | `ml_all_scores` | bot-detector | dashboard | +| `fleet_detections` | bot-detector (`fleet.py`) | dashboard | +| `ml_performance_metrics` | bot-detector (`metrics.py`) | dashboard | +| `soc_feedback` | dashboard (`/api/classify`) | bot-detector | | `audit_logs` | dashboard | dashboard | | `anubis_ip_rules` | fetch_rules.py | dict_anubis_ip | | `anubis_asn_rules` | fetch_rules.py | dict_anubis_asn | @@ -164,7 +172,7 @@ ja4-platform est un pipeline de sécurité qui capture le trafic réseau en temp | `view_dashboard_entities` | — (vue) | dashboard | | `view_resource_cascade_1h` | — (vue) | dashboard | -### Dictionnaires (7) +### Dictionnaires (8) | Dictionnaire | Layout | Source | Utilisation | |--------------|--------|--------|-------------| @@ -172,6 +180,7 @@ ja4-platform est un pipeline de sécurité qui capture le trafic réseau en temp | `dict_bot_ip` | IP_TRIE | Table `bot_ip` | IPs de bots connues | | `dict_bot_ja4` | COMPLEX_KEY_HASHED | Table `bot_ja4` | Signatures JA4 de bots | | `dict_browser_ja4` | COMPLEX_KEY_HASHED | Table (CSV) | Signatures JA4 de navigateurs | +| `dict_browser_h2` | COMPLEX_KEY_HASHED | Table (CSV) | Fingerprints HTTP/2 SETTINGS par navigateur | | `dict_asn_reputation` | HASHED | Fichier CSV | Réputation ASN (isp/datacenter/hosting/cdn) | | `dict_anubis_ip` | IP_TRIE | Table `anubis_ip_rules` | Règles Anubis IP/CIDR | | `dict_anubis_asn` | FLAT | Table `anubis_asn_rules` | Règles Anubis ASN | @@ -196,22 +205,25 @@ view_ai_features_1h ──┐ ┌─── ml_detected_anomal view_thesis_feat_1h ──┤ ┌────────────┐ │ view_ip_recurrence ───┤ │ Pré- │ │ ├──▶│ traitement │──▶│ Bifurcation : - │ │ + filtrage │ │ ├── Complet (correlated=1, ~63 feat.) - │ └────────────┘ │ └── Applicatif(correlated=0, ~51 feat.) + │ │ + filtrage │ │ ├── Complet (correlated=1, ~85 feat.) + │ └────────────┘ │ └── Applicatif(correlated=0, ~73 feat.) │ │ │ ┌────────────┐ │ Pour chaque branche : │ │ Ensemble │ │ ├── Extended Isolation Forest (EIF) │ │ triple │──▶│ ├── Autoencoder (PyTorch) │ │ voix │ │ └── XGBoost (supervisé) │ └────────────┘ │ - │ │ Score = (1-β)×((1-α)×EIF + α×AE) + β×XGB + │ │ Score = MetaLearner(eif, ae, xgb) ou + │ │ (1-β)×((1-α)×EIF + α×AE) + β×XGB │ ┌────────────┐ │ │ │ Post- │ ├─── ml_all_scores └──▶│ traitement │──▶│ │ HDBSCAN │ │ Niveaux : CRITICAL / HIGH / MEDIUM / - │ Browser 5ax│ │ LOW / NORMAL / LEGITIMATE_BROWSER / - │ SHAP │ │ KNOWN_BOT / ANUBIS_DENY / ANUBIS_ALLOW - └────────────┘ └─── + │ fleet.py │ │ LOW / NORMAL / LEGITIMATE_BROWSER / + │ Browser 6ax│ │ KNOWN_BOT / ANUBIS_DENY / ANUBIS_ALLOW + │ ExIFFI+SHAP│ │ + │ metrics.py │ ├─── fleet_detections + └────────────┘ └─── ml_performance_metrics ``` ## Référence des empreintes JA4/JA3 @@ -253,8 +265,9 @@ Les deux empreintes sont générées par sentinel à partir du payload TLS Clien | Détection ML — EIF | Python 3.11 + isotree | | Détection ML — Autoencoder | Python 3.11 + PyTorch | | Détection ML — Supervisé | Python 3.11 + XGBoost | -| Clustering de campagnes | HDBSCAN | -| Explicabilité | SHAP | +| Détection ML — Ensemble | Python 3.11 + MetaLearner (régression logistique) | +| Clustering de campagnes | HDBSCAN + NetworkX (fleet detection) | +| Explicabilité | SHAP + ExIFFI | | Backend dashboard | FastAPI + Jinja2 (Python 3.11) | | Frontend dashboard | htmx + Chart.js + ECharts + Tailwind CSS (CDN) | | Magasin de données | ClickHouse 24.8 (dual-database) | diff --git a/docs/database/schema.md b/docs/database/schema.md index 7d99502..6a26ff0 100644 --- a/docs/database/schema.md +++ b/docs/database/schema.md @@ -20,10 +20,10 @@ inter-bases). Le schéma complet est défini dans 13 fichiers SQL ordonnés dans | Catégorie | Nombre | Objets | |-----------|--------|--------| | **Bases de données** | 2 | `ja4_logs`, `ja4_processing` | -| **Tables** | 14 | `http_logs_raw`, `http_logs`, `ref_bot_networks`, `bot_ip`, `bot_ja4`, `anubis_ip_rules`, `anubis_asn_rules`, `agg_host_ip_ja4_1h`, `agg_header_fingerprint_1h`, `agg_path_sequences_1h`, `agg_request_timing_1h`, `agg_ip_behavior_1h`, `agg_resource_cascade_1h`, `ml_detected_anomalies`, `ml_all_scores`, `audit_logs` | -| **Dictionnaires** | 7 | `dict_iplocate_asn`, `dict_bot_ip`, `dict_bot_ja4`, `dict_browser_ja4`, `dict_asn_reputation`, `dict_anubis_ip`, `dict_anubis_asn` | -| **Vues matérialisées** | 8 | `mv_http_logs`, `mv_agg_host_ip_ja4_1h`, `mv_agg_header_fingerprint_1h`, `mv_agg_path_sequences_1h`, `mv_agg_request_timing_1h`, `mv_agg_ip_behavior_1h`, `mv_agg_resource_cascade_1h` | -| **Vues** | 8 | `view_ip_recurrence`, `view_ai_features_1h`, `view_form_bruteforce_detected`, `view_host_ip_ja4_rotation`, `view_dashboard_user_agents`, `view_dashboard_entities`, `view_resource_cascade_1h`, `view_thesis_features_1h` | +| **Tables** | 19 | `http_logs_raw`, `http_logs`, `ref_bot_networks`, `bot_ip`, `bot_ja4`, `anubis_ip_rules`, `anubis_asn_rules`, `agg_host_ip_ja4_1h`, `agg_header_fingerprint_1h`, `agg_path_sequences_1h`, `agg_request_timing_1h`, `agg_ip_behavior_1h`, `agg_resource_cascade_1h`, `ml_detected_anomalies`, `ml_all_scores`, `audit_logs`, `fleet_detections`, `ml_performance_metrics`, `soc_feedback` | +| **Dictionnaires** | 8 | `dict_iplocate_asn`, `dict_bot_ip`, `dict_bot_ja4`, `dict_browser_ja4`, `dict_browser_h2`, `dict_asn_reputation`, `dict_anubis_ip`, `dict_anubis_asn` | +| **Vues matérialisées** | 7 | `mv_http_logs`, `mv_agg_host_ip_ja4_1h`, `mv_agg_header_fingerprint_1h`, `mv_agg_path_sequences_1h`, `mv_agg_request_timing_1h`, `mv_agg_ip_behavior_1h`, `mv_agg_resource_cascade_1h` | +| **Vues** | 9 | `view_ip_recurrence`, `view_ai_features_1h`, `view_form_bruteforce_detected`, `view_host_ip_ja4_rotation`, `view_dashboard_user_agents`, `view_dashboard_entities`, `view_resource_cascade_1h`, `view_thesis_features_1h`, `view_health_metrics` | --- @@ -130,6 +130,10 @@ Table de logs HTTP parsés et enrichis — alimentée par la vue matérialisée | `anubis_bot_name` | LowCardinality(String) DEFAULT `''` | Nom du bot détecté par Anubis | | `anubis_bot_action` | LowCardinality(String) DEFAULT `''` | Action Anubis | | `anubis_bot_category` | LowCardinality(String) DEFAULT `''` | Catégorie Anubis | +| `h2_fingerprint` | String DEFAULT `''` | Fingerprint HTTP/2 au format Akamai (SETTINGS\|WU\|PRIORITY\|PSEUDO) | +| `h2_settings_fp` | String DEFAULT `''` | Valeurs brutes des paramètres SETTINGS HTTP/2 | +| `h2_window_update` | UInt32 DEFAULT 0 | Valeur WINDOW_UPDATE initial du client HTTP/2 | +| `h2_pseudo_order` | LowCardinality(String) DEFAULT `''` | Ordre des pseudo-headers (`:method:authority:scheme:path`) | Index de saut de données : @@ -427,6 +431,71 @@ Toutes les classifications ML (sans filtre de seuil) pour l'observabilité. --- +### fleet_detections + +Résultats de détection de flottes de bots coordonnées via analyse de graphe bipartite JA4×ASN (module `fleet.py`). + +| Colonne | Type | Description | +|---------|------|-------------| +| `src_ip` | IPv6 | Adresse IP membre de la flotte | +| `campaign_id` | Int32 | Identifiant de la communauté détectée | +| `fleet_score` | Float32 | Score de flotte : `taille × densité / log(nb_ASN)` | +| `ja4_list` | Array(String) | Empreintes JA4 partagées dans la communauté | +| `asn_list` | Array(UInt32) | ASNs impliqués dans la communauté | +| `member_count` | UInt32 | Nombre total d'IPs dans la communauté | +| `window_start` | DateTime | Début de la fenêtre de détection | +| `detected_at` | DateTime | Horodatage d'insertion | + +- **Moteur** : ReplacingMergeTree(detected_at) +- **Partition** : `toDate(window_start)` +- **Tri** : `(window_start, src_ip, campaign_id)` +- **TTL** : `window_start + INTERVAL 7 DAY` + +--- + +### ml_performance_metrics + +Métriques de performance du pipeline ML par cycle de détection (module `metrics.py`). + +| Colonne | Type | Description | +|---------|------|-------------| +| `model_name` | LowCardinality(String) | Nom du modèle (`complet`, `applicatif`) | +| `cycle_id` | String | Identifiant unique du cycle (timestamp ISO) | +| `anomaly_rate` | Float32 | Taux d'anomalies détectées (0.0–1.0) | +| `known_bot_rate` | Float32 | Taux de KNOWN_BOT dans le cycle | +| `legit_browser_rate` | Float32 | Taux de LEGITIMATE_BROWSER dans le cycle | +| `drift_rate` | Float32 | Fraction de features en drift (KS ou KL) | +| `corr_rate` | Float32 | Taux de sessions corrélées (correlated=1) | +| `cycle_latency_s` | Float32 | Durée totale du cycle d'inférence en secondes | +| `alert_flags` | Array(String) | Liste des alertes déclenchées dans ce cycle | +| `recorded_at` | DateTime | Horodatage d'enregistrement | + +- **Moteur** : MergeTree +- **Partition** : `toDate(recorded_at)` +- **Tri** : `(recorded_at, model_name)` +- **TTL** : `recorded_at + INTERVAL 90 DAY` + +--- + +### soc_feedback + +Feedback des analystes SOC pour l'entraînement supervisé XGBoost et le MetaLearner. + +| Colonne | Type | Description | +|---------|------|-------------| +| `src_ip` | IPv6 | Adresse IP classifiée | +| `label` | LowCardinality(String) | Classification : `bot`, `legitimate`, `suspicious` | +| `analyst` | String | Identifiant de l'analyste | +| `confidence` | Float32 | Confiance déclarée (0.0–1.0) | +| `notes` | String | Notes libres de l'analyste | +| `created_at` | DateTime | Horodatage de la classification | + +- **Moteur** : ReplacingMergeTree(created_at) +- **Partition** : `toDate(created_at)` +- **Tri** : `(src_ip, created_at)` + +--- + ### audit_logs Journal d'audit SOC pour le suivi de l'activité du dashboard. @@ -523,6 +592,7 @@ Tous les fichiers doivent être placés dans `/var/lib/clickhouse/user_files/`. | `dict_bot_ip` | `bot_ip.csv` | `prefix` (String) | IP_TRIE | `bot_name` (String) | 300 s | ~3,5K CIDR | | `dict_bot_ja4` | `bot_ja4.csv` | `ja4` (String) | COMPLEX_KEY_HASHED | `bot_name` (String) | 300 s | ~31 | | `dict_browser_ja4` | `browser_ja4.csv` | `ja4` (String) | COMPLEX_KEY_HASHED | `browser_family`, `tls_library`, `context` | 300 s | ~1,2K | +| `dict_browser_h2` | `browser_h2.csv` | `h2_fingerprint` (String) | COMPLEX_KEY_HASHED | `browser_family`, `h2_known` (UInt8) | 300 s | ~50 | | `dict_asn_reputation` | `asn_reputation.csv` | `src_asn` (UInt64) | HASHED | `label` (String) | 300 s | ~82K | ### Dictionnaires basés sur ClickHouse @@ -542,7 +612,7 @@ Tous les fichiers doivent être placés dans `/var/lib/clickhouse/user_files/`. ### view_ai_features_1h -Calcule ~65+ features ML par `(src_ip, ja4, host)` sur les dernières 24 heures +Calcule ~85 features ML par `(src_ip, ja4, host)` sur les dernières 24 heures en joignant `agg_host_ip_ja4_1h` et `agg_header_fingerprint_1h`. | Catégorie | Features | diff --git a/docs/services/bot-detector.md b/docs/services/bot-detector.md index c2e6e3b..4ad7800 100644 --- a/docs/services/bot-detector.md +++ b/docs/services/bot-detector.md @@ -3,14 +3,16 @@ Service Python de détection d'anomalies par apprentissage automatique semi-supervisé sur le trafic HTTP/TLS agrégé dans ClickHouse. Fonctionne en cycle continu (par défaut toutes les 5 minutes) avec un **ensemble à triple voix** -(Extended Isolation Forest + Autoencoder + XGBoost), enrichi par l'explicabilité -SHAP, le clustering HDBSCAN et la détection multifactorielle des navigateurs. +(Extended Isolation Forest + Autoencoder + XGBoost) piloté par un **méta-learner +à régression logistique**, enrichi par l'explicabilité **ExIFFI** et **SHAP**, +le clustering HDBSCAN, la détection de flottes coordonnées (NetworkX) et +la surveillance de performance par cycle. --- ## Architecture des modules -Le service est découpé en **11 modules** organisés ainsi : +Le service est découpé en **12 modules** organisés ainsi : ``` __main__.py Point d'entrée (python -m bot_detector) @@ -18,12 +20,14 @@ __main__.py Point d'entrée (python -m bot_detector) ├─ config.py Variables d'environnement, flags de disponibilité ├─ log.py Journalisation structurée JSON (structlog + RotatingFileHandler) ├─ infra.py Client ClickHouse (via ja4_common), health check HTTP, arrêt propre - ├─ preprocessing.py Nettoyage du DataFrame, imputation, listes de features - │ └─ browser.py Identification multifactorielle des navigateurs (5 axes) - ├─ pipeline.py Orchestration : filtrage → entraînement → scoring → fusion + ├─ preprocessing.py Nettoyage du DataFrame, imputation, listes de features (FEATURES, FEATURES_COMPLET) + │ └─ browser.py Identification multifactorielle des navigateurs (6 axes) + ├─ pipeline.py Orchestration : filtrage → entraînement → MetaLearner → ExIFFI → scoring → fusion │ ├─ models.py EIF, TrafficAutoEncoder (PyTorch), XGBoost - │ └─ scoring.py Normalisation, seuil adaptatif, SHAP, HDBSCAN, dérive - └─ (insère dans ml_all_scores + ml_detected_anomalies) + │ └─ scoring.py Normalisation, MetaLearner, seuil adaptatif, ExIFFI, SHAP, HDBSCAN, dérive KS+KL + ├─ fleet.py Graphe bipartite JA4×ASN (NetworkX), fleet_score, fleet_detections + ├─ metrics.py Métriques de cycle, alertes, ml_performance_metrics + └─ (insère dans ml_all_scores + ml_detected_anomalies + fleet_detections + ml_performance_metrics) ``` | Module | Lignes | Rôle | @@ -31,14 +35,15 @@ __main__.py Point d'entrée (python -m bot_detector) | `config.py` | 154 | Toute la configuration via `os.getenv()`, flags de disponibilité des librairies | | `log.py` | 65 | `log_info()`, `log_decision()`, `append_training_history()` — JSONL rotatif | | `infra.py` | 89 | Client ClickHouse (délègue à `ja4_common`), `score_to_threat_level()`, serveur de santé en thread daemon | -| `browser.py` | 170 | Détection multifactorielle des navigateurs sur 5 axes pondérés | -| `scoring.py` | 279 | Normalisation, seuil adaptatif, SHAP top-3, HDBSCAN, détection de dérive | -| `models.py` | 478 | `TrafficAutoEncoder`, entraînement/chargement EIF, XGBoost, élagage de features | -| `preprocessing.py` | 117 | `preprocess_df()` — nettoyage, typage, imputation, listes `FEATURES` / `FEATURES_COMPLET` | -| `pipeline.py` | 378 | `run_semi_supervised_logic()` — orchestration complète d'un modèle | -| `cycle.py` | 371 | `fetch_and_analyze()` — boucle principale, feedback SOC, multiwindow | +| `browser.py` | 191 | Détection multifactorielle des navigateurs sur **6 axes** pondérés (ajout `axis_h2_coherence`) | +| `scoring.py` | 564 | `MetaLearner` (régression logistique), normalisation, seuil adaptatif, ExIFFI, SHAP top-5, HDBSCAN, dérive KS+KL | +| `models.py` | 484 | `TrafficAutoEncoder`, entraînement/chargement EIF, XGBoost, élagage de features | +| `preprocessing.py` | 127 | `preprocess_df()` — nettoyage, typage, imputation, listes `FEATURES` / `FEATURES_COMPLET` | +| `pipeline.py` | 441 | `run_semi_supervised_logic()` — orchestration complète d'un modèle, MetaLearner, ExIFFI | +| `fleet.py` | 174 | `build_fleet_graph()`, `detect_fleet_communities()`, `enrich_with_fleet_score()` — NetworkX + HDBSCAN | +| `metrics.py` | 166 | `record_cycle_metrics()`, `_emit_alerts()` — table `ml_performance_metrics` | +| `cycle.py` | 415 | `fetch_and_analyze()` — boucle principale, feedback SOC, multiwindow | | `__main__.py` | 41 | Point d'entrée, bannière de démarrage, boucle `while True` | -| `__init__.py` | 1 | Docstring du package | --- @@ -171,8 +176,8 @@ Deux modèles indépendants tournent sur chaque cycle : | Modèle | Condition | Features | Données | |--------|-----------|----------|---------| -| **Complet** | `correlated = 1` | 77 (`FEATURES_COMPLET`) | HTTP + TCP + TLS (L3→L7) | -| **Applicatif** | `correlated = 0` | 65 (`FEATURES`) | HTTP seul (L7 pur) | +| **Complet** | `correlated = 1` | 85 (`FEATURES_COMPLET`) | HTTP + TCP + TLS (L3→L7) | +| **Applicatif** | `correlated = 0` | 73 (`FEATURES`) | HTTP seul (L7 pur) | En mode multi-fenêtre (`ENABLE_MULTIWINDOW=true`), deux variantes supplémentaires sont exécutées sur la vue 24h : `Complet_24h` et `Applicatif_24h`. @@ -320,7 +325,7 @@ Chaque anomalie reçoit un `campaign_id` (−1 = pas de cluster). ## Liste des features -### Features communes — modèle Applicatif (65 features) +### Features communes — modèle Applicatif (73 features) #### Comportement HTTP @@ -398,32 +403,51 @@ Chaque anomalie reçoit un `campaign_id` (−1 = pas de cluster). |---------|-------------| | `anubis_is_flagged` | Signal de suspicion Anubis (bot détecté, action ni ALLOW/DENY/vide) | -#### Navigateur multifactoriel +#### Navigateur multifactoriel — 6 axes | Feature | Description | |---------|-------------| | `is_known_browser` | JA4 correspond à un navigateur connu | | `browser_consistency_score` | Score composite de cohérence navigateur | -| `browser_confidence` | Confiance globale de l'identification navigateur | -| `axis_ja4_known` | Score de l'axe 1 (JA4 connu) | -| `axis_ja4_struct` | Score de l'axe 2 (structure JA4) | -| `axis_http_modern` | Score de l'axe 3 (HTTP moderne) | -| `axis_nav_behavior` | Score de l'axe 4 (comportement navigation) | -| `axis_tls_coherence` | Score de l'axe 5 (cohérence TLS/TCP) | +| `browser_confidence` | Confiance globale de l'identification navigateur (seuil 0.55) | +| `axis_ja4_known` | Axe 1 : JA4 reconnu dans `dict_browser_ja4` | +| `axis_ja4_struct` | Axe 2 : structure JA4 cohérente (chiffrement, extensions TLS) | +| `axis_http_modern` | Axe 3 : comportement HTTP moderne (Sec-Fetch-*, Accept-Language) | +| `axis_nav_behavior` | Axe 4 : comportement de navigation (asset_ratio, referer, cascade) | +| `axis_tls_coherence` | Axe 5 : cohérence TLS/TCP (ALPN, SNI, MSS mobile) | +| `axis_h2_coherence` | Axe 6 : cohérence HTTP/2 (h2_fingerprint ↔ famille navigateur déclarée) | #### Thèse §5 — Features avancées | Feature | Description | |---------|-------------| -| `path_transition_entropy` | Entropie des transitions de chemins | -| `cadence_cv` | Coefficient de variation de la cadence de requêtes | -| `burst_ratio` | Fraction de requêtes en rafale | -| `pause_ratio` | Fraction de pauses longues | -| `lag1_autocorrelation` | Autocorrélation lag-1 des inter-arrivées | +| `path_transition_entropy` | Entropie des transitions de chemins (§5.1) | +| `cadence_cv` | Coefficient de variation de la cadence de requêtes (§5.3) | +| `burst_ratio` | Fraction de requêtes en rafale (§5.3) | +| `pause_ratio` | Fraction de pauses longues (§5.3) | +| `lag1_autocorrelation` | Autocorrélation lag-1 des inter-arrivées (§5.3) | | `benford_deviation` | Déviation par rapport à la loi de Benford | -| `host_diversity` | Diversité des hôtes ciblés | -| `host_sweep_speed` | Vitesse de balayage des hôtes | -| `host_coverage_uniformity` | Uniformité de couverture des hôtes | +| `root_to_first_asset_delay` | Délai HTML → premier asset (§5.4, détection headless) | +| `asset_load_stddev` | Écart-type des intervalles de chargement d'assets (§5.4) | +| `host_diversity` | Diversité des hôtes ciblés (§5.8) | +| `host_sweep_speed` | Vitesse de balayage des hôtes (§5.8) | +| `host_coverage_uniformity` | Uniformité de couverture des hôtes (§5.8) | +| `cross_domain_path_similarity` | Similarité Jaccard inter-hôte des chemins — scanner latéral (§5.8) | + +#### Features HTTP/2 + +| Feature | Description | +|---------|-------------| +| `h2_settings_known` | Fingerprint HTTP/2 reconnu dans `dict_browser_h2` (0/1) | +| `h2_pseudo_order_match` | Ordre des pseudo-headers cohérent avec le navigateur déclaré (0/1) | +| `h2_ja4_coherence` | Cohérence HTTP/2 ↔ JA4 (même famille) (0/1) | +| `h2_settings_rare` | Fingerprint HTTP/2 avec <100 occurrences globales (0/1) | + +#### Score de cohérence cross-layer + +| Feature | Description | +|---------|-------------| +| `fingerprint_coherence_score` | Score composite (0.0–1.0) combinant : JA4↔UA, H2↔JA4, TCP↔UA, langue↔ASN, Sec-CH-UA↔UA | #### Features TCP fenêtre @@ -466,38 +490,54 @@ Chaque anomalie reçoit un `campaign_id` (−1 = pas de cluster). ``` 1. Requête view_ai_features_1h → DataFrame 2. Enrichissement optionnel view_thesis_features_1h (features thèse §5) -3. Prétraitement : preprocess_df() (nettoyage, browser axes, imputation) +3. Prétraitement : preprocess_df() (nettoyage, browser axes 6, imputation) 4. Chargement du feedback SOC → reclassification 5. Chargement de la carte de récurrence (view_ip_recurrence) 6. Séparation par correlated = 1 / correlated = 0 7. Pour chaque modèle (Complet, Applicatif) : a. Validation des features (exclure constantes/manquantes) b. Séparation des bots connus → journalisation KNOWN_BOT - c. Filtrage de la baseline humaine (asn_label = 'human') + c. Filtrage de la baseline humaine (asn_label = 'human', fingerprint_coherence_score ≥ seuil) d. Chargement ou entraînement EIF + AE e. Scoring du trafic inconnu (EIF + AE) f. Chargement ou entraînement XGBoost (si labels disponibles) - g. Combinaison des scores (formule triple voix) - h. Normalisation [0, 1] - i. Seuil adaptatif - j. Pénalité de récurrence - k. SHAP (top-3 features) - l. HDBSCAN clustering → campaign_id - m. Détection de dérive (KS test) -8. Mode multi-fenêtre (si activé) : idem sur view_ai_features_24h -9. Insertion → ml_all_scores (toutes les sessions scorées) -10. Déduplication intra-cycle (garder raw_anomaly_score le plus bas par IP) -11. Déduplication inter-cycle (TTL, skip si détecté récemment sauf aggravation ≥ 0.05) -12. Insertion → ml_detected_anomalies (anomalies filtrées) + g. MetaLearner : pondération apprise (logistique) sur historique SOC, sinon fallback poids fixes + h. Combinaison des scores via MetaLearner ou formule fixe + i. Normalisation [0, 1] + j. Seuil adaptatif (percentile_5 des scores négatifs, minimum -0.05) + k. Pénalité de récurrence + l. ExIFFI (importance par profondeur d'isolation EIF) + erreur AE par feature + m. SHAP top-5 TreeExplainer + n. HDBSCAN clustering → campaign_id + o. Détection de dérive (KS test + KL divergence) + p. Alerte drift adversarial (dérive simultanée multiple features → direction commune) +8. Analyse de flotte (fleet.py) : graphe bipartite JA4×ASN → communautés Louvain → fleet_score +9. Mode multi-fenêtre (si activé) : idem sur view_ai_features_24h +10. Insertion → ml_all_scores (toutes les sessions scorées) +11. Déduplication intra-cycle (garder raw_anomaly_score le plus bas par IP) +12. Déduplication inter-cycle (TTL, skip si détecté récemment sauf aggravation ≥ 0.05) +13. Insertion → ml_detected_anomalies (anomalies filtrées) +14. Insertion → fleet_detections (flottes détectées avec fleet_score) +15. Enregistrement → ml_performance_metrics (métriques de cycle + alertes) ``` --- -## Détection de dérive (Kolmogorov-Smirnov) +## Détection de dérive (KS + KL divergence) -Par feature, un **test KS bilatéral** compare la distribution courante avec la distribution d'entraînement (reconstruite par interpolation à partir d'un digest quantile p10/p25/p50/p75/p90) : +Par feature, deux tests comparent la distribution courante avec la distribution d'entraînement : +**Test KS (Kolmogorov-Smirnov)** : +- Distribution reconstruite par interpolation à partir d'un digest quantile 9 points (p5, p10, p25, p50, p75, p90, p95) - Feature driftée si `p_value < 0.05` + +**Divergence KL (Kullback-Leibler)** : +- Histogramme discrétisé (20 bins) de la distribution courante vs baseline +- Feature driftée si `KL > seuil` (0.5 par défaut) +- Détection de **drift adversarial** : si ≥30% des features dérivent simultanément dans la même direction → alerte `ADVERSARIAL_DRIFT` + +**Règle de décision** : une feature est en drift si KS **ou** KL dépasse son seuil. + - Dérive globale = fraction de features driftées - Si `drift > DRIFT_THRESHOLD` (0.30) → réentraînement automatique @@ -505,13 +545,73 @@ Par feature, un **test KS bilatéral** compare la distribution courante avec la --- -## Explicabilité SHAP +## MetaLearner -Lorsque `ENABLE_SHAP=true` et que la librairie `shap` est disponible : +Remplace la pondération linéaire fixe `(1-XGB_W)×((1-AE_W)×eif + AE_W×ae) + XGB_W×xgb` par une régression logistique apprise (`scoring.MetaLearner`) : -- Calcul des valeurs SHAP via `TreeExplainer` sur le modèle EIF -- Les **3 features les plus contributives** sont stockées dans le champ `reason` -- Format : `"feature1=valeur (±shap), feature2=valeur (±shap), feature3=valeur (±shap)"` +``` +P(bot) = logistic(w1×eif + w2×ae + w3×xgb + w4×volume + w5×correlated + bias) +``` + +- **Entraînement** : sur l'historique `ml_all_scores` JOIN `soc_feedback` (labels SOC + KNOWN_BOT + ANUBIS_DENY + LEGITIMATE_BROWSER) +- **Seuil** : activé seulement si ≥1000 labels disponibles — sinon fallback aux poids fixes +- **Transparence** : poids appris journalisés dans `ml_performance_metrics` pour audit SOC +- **Validation** : comparaison MetaLearner vs poids fixes sur split temporel (données postérieures à l'entraînement) + +--- + +## ExIFFI et explicabilité augmentée + +En complément de SHAP, le module expose deux méthodes d'importance de features spécifiques aux modèles utilisés : + +**ExIFFI** (`compute_exiffi_importance`) : +- Importance calculée par la profondeur moyenne d'isolation par feature dans l'EIF +- Une feature avec profondeur d'isolation faible contribue fortement à l'anomalie +- Corrèle avec SHAP mais capte des aspects complémentaires de la structure EIF + +**Erreur AE par feature** (`compute_ae_feature_errors`) : +- Reconstruction PyTorch feature par feature : `err_i = (x_i - x̂_i)²` +- Pour chaque anomalie, les features avec la plus grande erreur de reconstruction sont identifiées +- Expose quelles dimensions l'autoencoder ne parvient pas à reconstruire + +Les deux méthodes sont disponibles dans le champ `shap_features` des résultats, en complément des valeurs SHAP TreeExplainer. + +--- + +## Détection de flottes (fleet.py) + +Détecte les **botnets coordonnés** utilisant des JA4 et ASN rotatifs via analyse de graphe bipartite : + +1. **Construction du graphe** : nœuds JA4 ∪ ASN, arêtes IP observées dans le cycle +2. **Projection** : projection du graphe bipartite sur les nœuds JA4 +3. **Communautés** : algorithme de Louvain (NetworkX) sur le graphe projeté +4. **Score de flotte** : `fleet_score = taille_communauté × densité_arêtes / log(nb_ASN)` +5. **Enrichissement** : les IPs membres reçoivent un malus proportionnel au fleet_score + +Résultats stockés dans `fleet_detections` (TTL 7 jours). Exposés dans le dashboard via la page `/fleet`. + +--- + +## Métriques de performance (metrics.py) + +Enregistre par cycle dans `ml_performance_metrics` : + +| Métrique | Description | +|----------|-------------| +| `anomaly_rate` | Taux d'anomalies détectées (cible : 0.5%–10%) | +| `known_bot_rate` | Fraction KNOWN_BOT dans le cycle | +| `legit_browser_rate` | Fraction LEGITIMATE_BROWSER | +| `drift_rate` | Fraction de features en dérive | +| `corr_rate` | Taux de sessions corrélées (cible : ≥50%) | +| `cycle_latency_s` | Durée totale d'inférence (cible : <300s) | +| `alert_flags` | Alertes émises (CALIBRATION_HIGH/LOW, DRIFT, CORRELATION, LATENCY) | + +**Seuils d'alerte** : +- `anomaly_rate > 10%` → `CALIBRATION_HIGH` +- `anomaly_rate < 0.5%` → `CALIBRATION_LOW` +- `drift_rate > 30%` → `DRIFT_ALERT` +- `corr_rate < 50%` → `CORRELATION_ALERT` +- `cycle_latency_s > 300` → `LATENCY_ALERT` --- diff --git a/docs/services/dashboard.md b/docs/services/dashboard.md index d53c568..ac5584a 100644 --- a/docs/services/dashboard.md +++ b/docs/services/dashboard.md @@ -35,8 +35,8 @@ services/dashboard/ │ ├── database.py Client clickhouse-connect singleton, query(), query_scalar(), execute() │ └── routes/ │ ├── __init__.py -│ ├── api.py 35 routes JSON (1635 lignes) -│ └── pages.py 14 routes de pages HTML (83 lignes) +│ ├── api.py 37 routes JSON (1700+ lignes) +│ └── pages.py 16 routes de pages HTML (100+ lignes) ├── templates/ │ ├── base.html Template de base (layout, navigation, Tailwind CDN) │ ├── overview.html Vue d'ensemble du dashboard @@ -52,7 +52,9 @@ services/dashboard/ │ ├── classify.html Interface de classification SOC │ ├── tactics.html Tactiques de détection (brute-force, rotation, récurrence) │ ├── reflists.html Listes de référence et dictionnaires ClickHouse -│ └── network.html Graphe réseau des campagnes +│ ├── network.html Graphe réseau des campagnes +│ ├── fleet.html Détections de flottes coordonnées (graphe bipartite) +│ └── health.html Santé du pipeline — métriques de performance par cycle └── static/ Fichiers statiques (JS, CSS) ``` @@ -121,7 +123,7 @@ rows = query( --- -## Routes de pages (14) +## Routes de pages (16) Toutes les pages sont rendues côté serveur via Jinja2 et utilisent htmx pour les mises à jour dynamiques. @@ -141,10 +143,12 @@ Toutes les pages sont rendues côté serveur via Jinja2 et utilisent htmx pour l | 12 | `/cluster/{cid}` | `cluster_detail.html` | Investigation détaillée d'un cluster | | 13 | `/tactics` | `tactics.html` | Tactiques de détection (brute-force, rotation JA4/UA, récurrence) | | 14 | `/reflists` | `reflists.html` | Listes de référence et dictionnaires ClickHouse | +| 15 | `/fleet` | `fleet.html` | Détections de flottes coordonnées — graphe bipartite JA4×ASN, communautés, fleet_score | +| 16 | `/health` | `health.html` | Santé du pipeline — métriques de cycle, alertes calibration/drift/corrélation/latence | --- -## Routes API (35) +## Routes API (37) Toutes les routes sont préfixées par `/api` et retournent du JSON. Utilisées par htmx depuis les templates et consommables par des clients externes. @@ -225,13 +229,20 @@ Toutes les routes sont préfixées par `/api` et retournent du JSON. Utilisées | 31 | GET | `/api/cascade/{ip}` | Cascade de ressources pour détection de navigateur headless | | 32 | GET | `/api/ua-rotation` | Détection de rotation de User-Agent | +### Flottes et santé + +| # | Méthode | Chemin | Description | +|---|---------|--------|-------------| +| 33 | GET | `/api/fleet` | Flottes de bots coordonnées — communautés JA4×ASN, fleet_score, IPs membres | +| 34 | GET | `/api/health` | Métriques de performance du pipeline — cycle, drift, corrélation, alertes | + ### Dictionnaires et listes de référence | # | Méthode | Chemin | Description | |---|---------|--------|-------------| -| 33 | GET | `/api/dictionaries` | Métadonnées des dictionnaires ClickHouse | -| 34 | GET | `/api/reflist/{name}` | Contenu paginé d'une liste de référence / dictionnaire | -| 35 | GET | `/api/reflist/{name}/stats` | Statistiques agrégées d'une liste de référence | +| 35 | GET | `/api/dictionaries` | Métadonnées des 8 dictionnaires ClickHouse | +| 36 | GET | `/api/reflist/{name}` | Contenu paginé d'une liste de référence / dictionnaire | +| 37 | GET | `/api/reflist/{name}/stats` | Statistiques agrégées d'une liste de référence | ### Autres routes @@ -242,7 +253,7 @@ Toutes les routes sont préfixées par `/api` et retournent du JSON. Utilisées | GET | `/docs` | Documentation Swagger UI (auto-généré par FastAPI) | | GET | `/openapi.json` | Schéma OpenAPI (auto-généré par FastAPI) | -**Total : 14 pages + 35 API + 1 health = 50 routes applicatives** +**Total : 16 pages + 37 API + 1 health check = 54 routes applicatives** --- @@ -272,10 +283,12 @@ Le dashboard est conçu pour le workflow d'un analyste SOC : 4. **Analyse JA4** (`/ja4/{fp}`) — investiguer une empreinte TLS, voir toutes les IPs associées 5. **Campagnes** (`/campaigns`) — visualiser les clusters de bots, graphe réseau, scatter plot 6. **Cluster** (`/cluster/{cid}`) — plonger dans un cluster spécifique, examiner les membres et profils -7. **Tactiques** (`/tactics`) — surveiller le brute-force, la rotation JA4/UA, les menaces récurrentes -8. **Classification** (`/classify`) — soumettre un feedback analyste (bot/légitime/suspect) pour alimenter XGBoost -9. **Features** (`/features`) — comparer les profils de features humain vs bot -10. **Modèles** (`/models`) — surveiller les performances des modèles ML +7. **Flottes** (`/fleet`) — visualiser les communautés de botnets coordonnées (graphe bipartite JA4×ASN) +8. **Tactiques** (`/tactics`) — surveiller le brute-force, la rotation JA4/UA, les menaces récurrentes +9. **Classification** (`/classify`) — soumettre un feedback analyste (bot/légitime/suspect) pour alimenter XGBoost et le MetaLearner +10. **Features** (`/features`) — comparer les profils de features humain vs bot +11. **Modèles** (`/models`) — surveiller les performances des modèles ML +12. **Santé** (`/health`) — métriques de cycle, alertes de calibration, drift, corrélation et latence ---