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), kretprobe recvfrom (L7 HTTP nginx), corrélation in-memory, insert ClickHouse	INSERT batch ClickHouse
État HTTP : ✅ HTTPS via SSL uprobes (headers complets) — ✅ HTTP nginx via kretprobe recvfrom (headers complets) — ⚠️ HTTP plain via TC (paquets bruts)
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.