ja4-platform/README.md

# 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](docs/services/ja4ebpf.md) | 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](docs/services/bot-detector.md) | Python 3.11 | Ensemble ML triple-voix (EIF+AE+XGB), clustering HDBSCAN, explicabilité SHAP | ClickHouse read/write, HTTP `:8080` |
| [dashboard](docs/services/dashboard.md) | 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](docs/shared/go-ja4common.md) | Go | Logger, config loader, graceful shutdown handler, IP filter |
| [python/ja4_common](docs/shared/python-ja4common.md) | 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

```bash
make build-all
```

### Exécution de tous les tests

```bash
make test-all
```

### Build des paquets RPM

```bash
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 :

```bash
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 :

```bash
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](docs/architecture.md) | Architecture système, flux de données, interactions entre composants |
| [Deployment](docs/deployment.md) | Guide de déploiement en production |
| [Development](docs/development.md) | Build, test, packaging et extension de la plateforme |
| [Database Schema](docs/database/schema.md) | Tables, vues, dictionnaires et vues matérialisées ClickHouse |
| [Database Migrations](docs/database/migrations.md) | Ordre de migration, application, vérification et rollback |
| [Commenting Standard](docs/commenting-standard.md) | Conventions de commentaires (commentaires français, identifiants anglais) |
| [Thesis Reference](docs/THESIS_HTTP_Traffic_Detection.md) | Référence académique : techniques de détection du trafic HTTP |
| [Audit vs Thesis](docs/AUDIT_Detection_vs_Thesis.md) | Comparaison entre l'implémentation et les techniques de la thèse |

### Documentation des services

- [ja4ebpf](docs/services/ja4ebpf.md) — Agent eBPF CO-RE (Go + C), capture réseau passive multi-couches
- [Bot Detector](docs/services/bot-detector.md) — Détection ML d'anomalies triple-voix (Python)
- [Dashboard](docs/services/dashboard.md) — Tableau de bord SOC et API (FastAPI)

### Documentation des bibliothèques partagées

- [go-ja4common](docs/shared/go-ja4common.md) — Bibliothèque Go partagée (logger, config, shutdown, ipfilter)
- [python-ja4common](docs/shared/python-ja4common.md) — Bibliothèque Python partagée (client ClickHouse, settings)

## License

Voir les répertoires des services individuels pour les informations de licence.