3b047b680a
- Use two separate //go:generate directives (Ja4Tc for tc_capture.c, Ja4Ssl
for uprobe_ssl.c) to avoid duplicate LICENSE symbol and multi-file clang issue
- Update loader.go to hold tcObjs/sslObjs separately with correct field names:
UprobeSslSetFd, UprobeSslReadEntry, UretprobeSslReadExit,
KprobeAccept4Entry, KretprobeAccept4Exit
- Add systemd-rpm-macros to all three RPM build stages (el8/el9/el10)
so that %{_unitdir} macro resolves correctly
- RPMs now build successfully for el8, el9, el10
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
167 lines
7.8 KiB
Markdown
167 lines
7.8 KiB
Markdown
# 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), TC port 80/8080 (HTTP clair), corrélation in-memory, insert ClickHouse | INSERT batch ClickHouse |
|
|
| [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.
|