# Audit de conformité : Code vs Thèse — 9 avril 2026

**Date** : 9 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

---

## Légende

| Statut | Signification |
|--------|---------------|
| ✅ CONFORME | Implémenté conformément à la thèse |
| ⚠️ PARTIEL | Implémenté mais incomplet ou dégradé |
| ❌ ABSENT | Décrit dans la thèse, non implémenté |
| 🔄 DIVERGENT | Implémenté différemment de ce que décrit la thèse |

---

## Partie A — Conformité bot-detector vs Thèse

### A1. Architecture multi-couches (Thèse §3)

| Composant thèse | Statut | Détail |
|-----------------|--------|--------|
| Pipeline L3-L5 (ja4sentinel) | ✅ | TTL, IP-ID, DF, TCP win/mss/scale, JA4/JA3, ALPN, SNI |
| Pipeline L7 (mod_reqin_log) | ✅ | Headers, méthode, path, query, timestamps ns |
| Corrélation (logcorrelator) | ✅ | Clé `src_ip:src_port`, Keep-Alive, orphelins |
| Enrichissement ASN | ✅ | `dict_iplocate_asn` (714K CIDRs, 4 colonnes) |
| Enrichissement Anubis | ✅ | Simplifié à `COALESCE(IP, ASN)` — 2 dictionnaires (`dict_anubis_ip` IP_TRIE, `dict_anubis_asn`) |
| Agrégation 1h | ✅ | 6 tables : `agg_host_ip_ja4_1h`, `agg_header_fingerprint_1h`, `agg_ip_behavior_1h`, `agg_request_timing_1h`, `agg_path_sequences_1h`, `agg_resource_cascade_1h` |
| Vue features | ✅ | `view_ai_features_1h` + `view_thesis_features_1h` |
| Bifurcation Complet/Applicatif | ✅ | 2 modèles par cycle : Complet (~45 features L3→L7, `correlated=1`) + Applicatif (~35 features L7, `correlated=0`) |

### A2. Features L3 IP (Thèse §3.2)

| Feature thèse | Statut | Colonne SQL / Python |
|--------------|--------|---------------------|
| avg_ttl | ✅ | `avg_ttl` dans `view_ai_features_1h` |
| ttl_std | ✅ | `ttl_std` |
| ip_id_zero_ratio | ✅ | `ip_id_zero_ratio` |
| ip_df_variance | ✅ | `ip_df_variance` |
| request_size_variance | ✅ | `request_size_variance` |
| anomalous_payload_ratio | ✅ | `anomalous_payload_ratio` |

### A3. Features L4 TCP (Thèse §3.3)

| Feature thèse | Statut | Détail |
|--------------|--------|--------|
| true_window_size | ✅ | Calculé dans SQL, utilisé dans `feats_complet` |
| window_mss_ratio | ✅ | Calculé dans SQL, utilisé dans `feats_complet` |
| mss_mobile_mismatch | ✅ | Dans `feats_complet` |
| no_window_scale_ratio | ✅ | Dans `feats_complet` |
| tcp_shared_count | ✅ | Dans `feats` |
| tcp_jitter_variance | ✅ | Dans `feats_complet` |
| src_port_density | ✅ | Dans `feats` |
| port_exhaustion_ratio | ✅ | Dans `feats` |
| max_keepalives | ✅ | Dans `feats` |

### A4. Features L5 TLS (Thèse §3.4)

| Feature thèse | Statut | Détail |
|--------------|--------|--------|
| JA4 fingerprint | ✅ | Clé de corrélation + feature |
| is_rare_ja4 | ✅ | Dans `feats_complet` |
| ja3_diversity_ratio | ✅ | Dans `feats_complet` |
| is_alpn_missing | ✅ | Dans `feats_complet` |
| sni_host_mismatch | ✅ | Dans `feats_complet` |
| tls12_ratio | ✅ | Dans `feats_complet` |
| alpn_http_mismatch | ✅ | Dans `feats_complet` |

### A5. Features L7 HTTP (Thèse §3.5 + §2.3)

| Feature thèse | Statut | Détail |
|--------------|--------|--------|
| hits, hit_velocity | ✅ | |
| fuzzing_index | ✅ | |
| post_ratio, head_ratio | ✅ | |
| asset_ratio, direct_access_ratio | ✅ | |
| modern_browser_score | ✅ | 0/50/100 |
| 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 | ✅ | |
| temporal_entropy | ✅ | Shannon entropie |
| path_diversity_ratio, url_depth_variance | ✅ | |
| http10_ratio, http_scheme_ratio | ✅ | |
| orphan_ratio | ✅ | |
| is_ua_rotating | ✅ | |
| login_post_concentration | ✅ | Détection brute-force (concentration POST login) — `preprocessing.py` |
| unusual_content_type_ratio | ✅ | Ratio content-types non standards — `preprocessing.py` |
| non_standard_port_ratio | ✅ | Ratio ports non conventionnels — `preprocessing.py` |
| has_xff | ✅ | Présence du header X-Forwarded-For — `preprocessing.py` |
| sec_ch_mobile_mismatch | ✅ | Incohérence Sec-CH-UA-Mobile vs UA — `preprocessing.py` |

### A6. ML Pipeline (Thèse §2.4 + §3.8)

| Élément thèse | Statut | Détail |
|---------------|--------|--------|
| Extended Isolation Forest (EIF) | ✅ | `isotree` lib, ntrees=300, contamination=0.001 — `pipeline.py` |
| Bifurcation Complet/Applicatif | ✅ | Deux modèles par cycle — `cycle.py` |
| Baseline ISP (humaine) | ✅ | `asn_label == 'isp'` — `cycle.py` |
| Seuil adaptatif | ✅ | `min(percentile_5, -0.05)` — `scoring.py` |
| 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` |
| 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` |
| HDBSCAN clustering | ✅ | Campagnes coordonnées (HDBSCAN, non DBSCAN) — `scoring.py` |
| Feedback loop SOC | ✅ | FP→baseline, TP→exclusion — `cycle.py` |
| 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` |

### 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.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` |

**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.

### A8. Taxonomie 7+1 familles (Thèse §4)

| Famille | Features attendues | 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 |

**Total taxonomie : ~67 features sur 7+1 familles**

---

## Partie B — Qualité du code bot-detector

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

| 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 |
| `infra.py` | 89 | Health check, client ClickHouse, mapping score→threat |
| `log.py` | 65 | Logging structuré |
| `__main__.py` | 41 | Point d'entrée |

**Évaluation** : la séparation des responsabilités est propre et conforme aux bonnes pratiques. Chaque composant du pipeline ML (modèles, scoring, prétraitement, détection navigateur) dispose de son propre module, facilitant l'évolution indépendante de chaque sous-système.

### B2. Points d'attention restants

| # | Sévérité | Description | Localisation |
|---|----------|-------------|-------------|
| B2.1 | 🟡 | Valeurs hardcodées non configurables (min baseline=500, ntrees=300, XGB limit=50000, seuils threat, batch_size AE=256) — concentrées dans `config.py` mais pas toutes exposées en env vars | `config.py` |
| B2.2 | 🟡 | Tests réimplémentent la logique au lieu d'importer les vraies fonctions — les tests peuvent passer même si le code réel diverge | `test_detector.py` |
| B2.3 | ⚪ | `joblib` utilisé mais non déclaré en dépendance directe (transitif via sklearn) | `requirements.txt` |

**Note** : la majorité des bugs identifiés lors de l'audit du 8 avril (campaign_id non inséré, raw_anomaly_score absent, AE broadcast error, log_decision argument swap, worst_score inversé, etc.) ont été corrigés lors de la refactorisation modulaire.

---

## Partie C — Conformité dashboard

### C1. Couverture fonctionnelle (14 pages)

| Page | Route | Statut | Détail |
|------|-------|--------|--------|
| Vue d'ensemble | `/overview` | ✅ | Stats agrégées, top IPs, top JA4, tendances |
| Détections | `/detections` | ✅ | Tri, filtres, pagination, détail anomalie |
| Scores ML | `/scores` | ✅ | Toutes les sessions scorées, filtrage par threat level |
| Trafic brut | `/traffic` | ✅ | Navigation, filtres, export |
| Détail IP | `/ip/<ip>` | ✅ | Historique complet, détections, scores, trafic |
| Détail JA4 | `/ja4/<fingerprint>` | ✅ | Analyse fingerprint, IPs associées |
| Détail cluster | `/cluster/<id>` | ✅ | Membres du cluster, caractéristiques |
| Campagnes | `/campaigns` | ✅ | Clusters HDBSCAN, campagnes coordonnées |
| Features avancées | `/features` | ✅ | Heatmap, distributions, corrélations |
| Modèles ML | `/models` | ✅ | État des modèles, historique entraînement |
| Classification SOC | `/classify` | ✅ | Feedback loop analyste (FP/TP) |
| 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 |

### C2. Endpoints API (35 routes)

Le module `api.py` expose **35 endpoints JSON** couvrant l'ensemble des besoins du dashboard SOC :

| Catégorie | Endpoints | Détail |
|-----------|-----------|--------|
| Vue d'ensemble | `/api/overview` | Stats agrégées multi-requêtes |
| Détections | `/api/detections` | Liste paginée, filtres threat level |
| Scores | `/api/scores` | Tous les scores ML avec métadonnées |
| Trafic | `/api/traffic` | Logs HTTP bruts paginés |
| Détail IP | `/api/ip/{ip}`, `/api/ip/{ip}/timeline`, `/api/ip/{ip}/radar` | Profil complet, historique temporel, radar de risque |
| 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 |
| 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) |
| Campagnes | `/api/campaigns`, `/api/cluster/{id}` | Clusters HDBSCAN, détail campagne |
| Brute-force | `/api/brute-force` | Détection concentration POST login |
| Rotation JA4 | `/api/ja4-rotation` | IPs avec rotation de fingerprints |
| Récurrence | `/api/recurrence` | Analyse récurrence IP |
| 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 |
| Listes de référence | `/api/reflists` | IP/JA4 connues bot |

### C3. Points d'attention

| # | Sévérité | Description | Remarque |
|---|----------|-------------|----------|
| C3.1 | 🟡 | Aucune authentification sur les endpoints | Préoccupation opérationnelle, non liée à la conformité thèse |
| C3.2 | 🟡 | CORS `allow_origins=["*"]` | Configuration à restreindre en production |
| C3.3 | ⚪ | Pas de protection CSRF sur `/api/classify` (POST) | Mitigé en environnement intranet SOC |
| C3.4 | ⚪ | Erreurs internes potentiellement exposées en 500 | À durcir pour la production |

**Note** : ces points sont des préoccupations de sécurité opérationnelle, **pas des écarts de conformité vis-à-vis de la thèse**. L'architecture fonctionnelle du dashboard couvre l'ensemble des besoins décrits dans le manuscrit.

---

## Partie D — Synthèse quantitative

### D1. Conformité thèse

| Section thèse | Éléments | Conformes | Partiels | Absents | Score |
|--------------|----------|-----------|----------|---------|-------|
| §3 Architecture | 8 | 8 | 0 | 0 | 100% |
| §3.2 L3 IP | 6 | 6 | 0 | 0 | 100% |
| §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%** |

### D2. Métriques de déploiement

| Métrique | Valeur |
|----------|--------|
| Volume de logs traités | 3M+ entrées |
| Sessions par cycle | ~34 000 |
| 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 |
| Fichiers SQL schéma | 13 (00_database → 12_thesis_features) |

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

---

## Partie E — Scripts et outillage opérationnel

### E1. Scripts de déploiement et exploitation

| Script | Localisation | Rôle |
|--------|-------------|------|
| `init-stack.sh` | Racine | Initialisation complète de la stack Docker (ClickHouse, services, schéma) |
| `import-prod-data.sh` | Racine | Import de données de production dans l'environnement de développement |
| `reload-prod-logs.sh` | Racine | Rechargement des logs de production (mise à jour incrémentale) |
| `update-csv-data.sh` | Racine | Mise à jour des données CSV de référence (ASN, bots connus, etc.) |

### E2. Infrastructure SQL et déploiement

- **13 fichiers SQL ordonnés** (`shared/clickhouse/00_database.sql` → `12_thesis_features.sql`) couvrant la totalité du schéma
- **`deploy_schema.sh`** : déploiement automatisé avec substitution des noms de bases depuis les variables d'environnement (`CLICKHOUSE_DB_LOGS`, `CLICKHOUSE_DB_PROCESSING`)
- **Dual database** : `ja4_logs` (logs bruts, enrichis, MV) + `ja4_processing` (agrégations, ML, vues, dictionnaires, audit)
- **7 dictionnaires** : `dict_iplocate_asn`, `dict_bot_ip`, `dict_bot_ja4`, `dict_browser_ja4`, `dict_asn_reputation`, `dict_anubis_ip`, `dict_anubis_asn`
- **Migrations post-déploiement** : `services/correlator/sql/migrations/` (ALTER TABLE pour déploiements existants)

### E3. Pipeline de build et tests

- **Docker-first** : chaque service dispose de `Dockerfile` (prod), `Dockerfile.dev` ou `Dockerfile.tests` (tests), et `Dockerfile.package` (RPM) pour les services Go/C
- **Tests d'intégration** : suite complète en 8 phases (build → start → schema → traffic → pipeline → dashboard → bot-detector → sentinel) via `make test-integration`
- **Couverture** : tests Go (80% gate pour le correlator), tests Python (pytest pour bot-detector, dashboard, ja4_common), tests C (cmocka pour mod_reqin_log)
- **RPM packaging** : 3 distributions (el8/el9/el10) via Rocky Linux / AlmaLinux