c60ce97f23
Implement offline profile building (profile_builder.py) and real-time dynamic scoring (browser_matcher_dynamic.py) using HDBSCAN-based browser fingerprint clustering. Add ClickHouse materialized view (13_h2_profiling.sql) for h2_profile_stats aggregation. Update thesis and project documentation to cover the new dynamic profiling architecture. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
ja4-platform
ja4-platform est un pipeline de sécurité monorepo pour le fingerprinting TLS (JA4/JA3) et la détection de bots HTTP. Un agent unique basé sur eBPF observe passivement le trafic réseau de manière non-intrusive, reconstruit les sessions TCP/TLS/HTTP en mémoire, et alimente une base ClickHouse pour la détection d'anomalies par apprentissage automatique et la présentation dans un tableau de bord SOC.
Pipeline Overview
+-----------------------------------------------------------------------+
| Linux Server (Apache / Nginx / Varnish / Hitch) |
| |
| +-------------------------------------------------------------+ |
| | ja4ebpf (agent eBPF GO) | |
| | | |
| | Hook TC ingress (L3/L4/L5 - passif) : | |
| reseau| SYN -> TTL, DF, IP-ID, MSS, Window, Scale | |
| ----->| TLS -> ClientHello : JA4, ALPN, SNI, extensions | |
| XDP/TC| HTTP -> payload port 80/8080 (magic bytes router) | |
| | | |
| uprobe| Hook SSL_read (L7 - trafic dechiffre) : | |
| ----->| HTTP/1.1 -> methode, path, headers (ordre exact) | |
| | HTTP/2 -> SETTINGS, WINDOW_UPDATE, pseudo-headers | |
| | | |
| | Correlation in-memory src_ip:src_port | |
| | 256 shards . timeout 500ms . GC 100ms | |
| +----------------------------+---------------------------------+ |
+-----------------------------------------------------------------------+
| INSERT batch (Native TCP :9000)
v
+------------------------------------------+
| ClickHouse 24.8 |
| |
| ja4_logs ja4_processing |
| +-----------+ +--------------+ |
| |_raw -> MV |------->| agg_* (x6) | |
| |-> http_logs | ml_* (x2) | |
| +-----------+ | views, dicts | |
+------+---------------------------+----+
| |
+--------+ +----------+
v v
+--------------------+ +--------------------+
| bot-detector | | dashboard |
| Python 3.11 | | FastAPI + Jinja2 |
| EIF + AE + XGBoost| | htmx + Chart.js |
| HDBSCAN . SHAP | | SOC analyst UI |
+--------------------+ +--------------------+
Services
| Service | Langage | Description | Interface |
|---|---|---|---|
| ja4ebpf | Go 1.24 + C eBPF (CO-RE) | Agent eBPF passif : TC ingress (L3/L4/L5), uprobe SSL_read (L7 HTTPS), TC port 80/8080 (HTTP clair), corrélation in-memory, insert ClickHouse | INSERT batch ClickHouse |
| bot-detector | Python 3.11 | Ensemble ML triple-voix (EIF+AE+XGB), clustering HDBSCAN, explicabilité SHAP | ClickHouse read/write, HTTP :8080 |
| dashboard | Python 3.11 | Tableau de bord SOC : 9 endpoints JSON, 8 pages HTML | HTTP :8000 |
Bibliothèques partagées
| Bibliothèque | Langage | Description |
|---|---|---|
| go/ja4common | Go | Logger, config loader, graceful shutdown handler, IP filter |
| python/ja4_common | Python | ClickHouseClient singleton, ClickHouseSettings (pydantic-settings) |
Quickstart
Prérequis
- Docker (avec BuildKit) et Docker Compose
make- Aucune toolchain Go, Python, C ou eBPF n'est requise sur la machine hôte — tous les builds s'exécutent dans Docker Rocky Linux.
Build de tous les services
make build-all
Exécution de tous les tests
make test-all
Build des paquets RPM
make rpm-ja4ebpf
# RPMs écrits dans services/ja4ebpf/dist/rpm/el{8,9,10}/
Tests d'intégration
Tests full-stack avec Docker Compose et une vraie instance ClickHouse :
make test-integration # stack Apache référence (8 phases)
make test-nginx # stack nginx + ja4ebpf
make test-nginx-varnish # nginx + Varnish + ja4ebpf
make test-hitch-varnish # hitch (TLS) + Varnish + ja4ebpf
make test-all-stacks # les 3 stacks serveur en séquence
make test-integration-keep # laisse la stack en fonctionnement
make test-integration-down # démontage de la stack
La suite de tests se trouve dans tests/integration/ et réinitialise la base entre chaque exécution.
Scripts
| Script | Description |
|---|---|
init-stack.sh |
Initialisation complète du schéma ClickHouse + chargement CSV |
import-prod-data.sh |
Import de données de production avec décalage temporel |
reload-prod-logs.sh |
Export prod -> réimport dev avec décalage |
update-csv-data.sh |
Génération des CSV de référence (bot IPs, signatures JA4, ASN) |
Cibles Makefile correspondantes :
make init-stack # schéma + CSV
make import-prod-data # données prod
make init-and-import # init-stack + import-prod-data
make reload-prod-logs # rechargement depuis la prod
Go Workspace
Le workspace go.work lie les modules Go du dépôt :
go 1.24.6
use (
./shared/go/ja4common
./services/ja4ebpf
)
ja4ebpf utilise une directive replace dans son go.mod vers ../../shared/go/ja4common. Le workspace prend priorité en développement local ; la directive replace est nécessaire pour les builds Docker.
Documentation
| Document | Description |
|---|---|
| Architecture | Architecture système, flux de données, interactions entre composants |
| Deployment | Guide de déploiement en production |
| Development | Build, test, packaging et extension de la plateforme |
| Database Schema | Tables, vues, dictionnaires et vues matérialisées ClickHouse |
| Database Migrations | Ordre de migration, application, vérification et rollback |
| Commenting Standard | Conventions de commentaires (commentaires français, identifiants anglais) |
| Thesis Reference | Référence académique : techniques de détection du trafic HTTP |
| Audit vs Thesis | Comparaison entre l'implémentation et les techniques de la thèse |
Documentation des services
- ja4ebpf — Agent eBPF CO-RE (Go + C), capture réseau passive multi-couches
- Bot Detector — Détection ML d'anomalies triple-voix (Python)
- Dashboard — Tableau de bord SOC et API (FastAPI)
Documentation des bibliothèques partagées
- go-ja4common — Bibliothèque Go partagée (logger, config, shutdown, ipfilter)
- python-ja4common — Bibliothèque Python partagée (client ClickHouse, settings)
License
Voir les répertoires des services individuels pour les informations de licence.