f85a10b012
Correctifs pipeline L7 (uprobe SSL_read) :
- uprobe_ssl.c : ssl_set_fd ne retourne plus tôt quand fd_conn_map est
vide (accept4 non disponible en Docker). Sauvegarde ssl_ptr→{fd,0,0}
pour permettre le fallback /proc côté Go.
- main.go : consumeSSLEvents reécrit avec routeur magic-bytes complet :
* HTTP/2 preface → extraction SETTINGS + conversion correlation.HTTP2Settings
* HTTP/1.x requête → method, path, query, headers, header_order_sig
* HTTP/1.x réponse → status_code
* Fallback /proc/<tgid>/fd/<fd> quand src_ip=0 (accept4 absent)
- writer/clickhouse.go : export header_order_signature ajouté
Nouveaux packages :
- internal/parser/http1.go : parseur HTTP/1.x (IsHTTP1Request,
ParseHTTP1Request, IsHTTP1Response, ParseHTTP1Response)
- internal/parser/http1_test.go : 11 tests unitaires (28 total passent)
- internal/procutil/proc_lookup.go : résolution fd→IP via /proc avec cache
TTL 5s (FDCache). Supporte /proc/PID/net/tcp et tcp6, IPv4-mappé IPv6.
Infrastructure tests VM (tests/vm/) :
- Vagrantfile : VM Rocky Linux 9 KVM, 4 CPU / 4 GB RAM
- provision.sh : installation toolchain eBPF + Go + Docker + nginx
- run-tests-vm.sh : suite de test complète dans la VM (L3/L4+TLS+L7)
- README.md : guide d'installation et d'utilisation
- Makefile : cibles vm-up, vm-down, vm-ssh, test-vm-nginx, test-vm-all,
vm-rebuild-ja4ebpf
Corrections stack Docker :
- Dockerfiles nginx/apache/nginx-varnish/hitch-varnish : suppression des
références à shared/go/ja4common/ (répertoire supprimé)
- clickhouse-init.sh : restauré depuis git, seed anubis_ua_rules obsolète
supprimé (table REGEXP_TREE supprimée du schéma)
- traffic-gen : ajout HTTP/1.0 (http.client) et HTTP/2 (httpx)
- verify_db.py : script de vérification 35 checks (L3/L4/TLS/L7/corrélation)
- run-stack-tests.sh : phase 6 verify_db ajoutée
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.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.