ja4-platform/docs/development.md

Guide de développement

Ce guide couvre la compilation, les tests, le packaging et l'extension du monorepo ja4-platform. Toutes les opérations de build et de test s'exécutent dans Docker — aucune toolchain Go, Python ou C n'est requise sur la machine hôte.

Prérequis

Outil	Version minimale	Notes
Docker	20.10+	BuildKit activé (DOCKER_BUILDKIT=1)
Docker Compose	2.x	Pour bot-detector et dashboard
make	3.81+	GNU Make
git	2.x	Pour le versioning

Aucun compilateur Go, Python ou C n'est nécessaire sur la machine hôte.

Compilation de tous les services

make build-all

Cela construit les images Docker pour :

• ja4-platform/sentinel:latest
• ja4-platform/correlator:latest
• ja4-platform/bot-detector:latest
• ja4-platform/dashboard:latest

mod-reqin-log est un module Apache et n'est construit que dans le cadre du processus RPM.

Compilation individuelle

make build-sentinel      # Binaire Go dans Docker
make build-correlator    # Binaire Go dans Docker
make build-bot-detector  # Image Python
make build-dashboard     # Image FastAPI + Jinja2

Exécution des tests

make test-all

Tests par service

Service	Commande	Détails
sentinel	make test-sentinel	Tests Go avec -race, nécessite NET_RAW/NET_ADMIN
correlator	make test-correlator	Tests Go avec seuil de couverture 80%
mod-reqin-log	make test-mod-reqin-log	Tests unitaires C (sérialisation JSON, config, headers)
bot-detector	make test-bot-detector	Suite pytest Python
dashboard	make test-dashboard	pytest pour les routes FastAPI
ja4_common (Python)	make test-ja4common-python	Tests de la librairie Python partagée

Tests d'intégration

Les tests d'intégration full-stack s'exécutent contre Docker Compose avec une instance ClickHouse réelle :

make test-integration          # 8 phases : build → start → schema → traffic → pipeline → dashboard → bot-detector → sentinel
make test-integration-keep     # idem mais laisse la stack en fonctionnement
make test-integration-down     # démontage de la stack d'intégration

La suite de tests se trouve dans tests/integration/ et réinitialise la base de données entre chaque exécution.

Construction des paquets RPM

make rpm-all

Construit les RPMs pour sentinel, correlator et mod-reqin-log ciblant Rocky Linux 8/9/10 :

make rpm-sentinel        # → services/sentinel/dist/rpm/
make rpm-correlator      # → services/correlator/dist/rpm/
make rpm-mod-reqin-log   # → services/mod-reqin-log/dist/rpm/

Chaque build RPM utilise un pipeline Docker multi-étapes :

1. L'étape builder compile le binaire (Go) ou l'objet partagé (C)
2. L'étape rpmbuild exécute rpmbuild pour chaque distro cible (el8, el9, el10)
3. L'étape de sortie copie les RPMs sur l'hôte via --output type=local

Paquets de distribution

make dist    # Alias for rpm-all
# RPMs in services/<service>/dist/rpm/el{8,9,10}/

Développement local

Services Go (sentinel, correlator)

Le fichier go.work relie les modules Go :

go 1.24.6

use (
    ./services/sentinel
    ./services/correlator
    ./shared/go/ja4common
)

Si Go 1.24+ est installé localement, le développement sans Docker est possible :

# Tests sentinel en local
cd services/sentinel && go test ./... -race -v

# Tests correlator en local
cd services/correlator && go test ./... -race -cover -v

# Compilation du binaire sentinel (nécessite libpcap-dev)
cd services/sentinel && go build -o ja4sentinel ./cmd/ja4sentinel/

Services Python (bot-detector, dashboard)

# Installer la librairie partagée en mode développement
cd shared/python/ja4_common && pip install -e .

# Lancer le bot-detector localement
cd services/bot-detector && pip install -r bot_detector/requirements.txt
python -m bot_detector

# Lancer le dashboard localement
cd services/dashboard && pip install -r backend/requirements.txt
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

Dépendances Python pour le développement local du bot-detector

Les dépendances principales sont listées dans services/bot-detector/bot_detector/requirements.txt. Les librairies ML clés sont :

Librairie	Usage
isotree	Extended Isolation Forest (scoreur principal non supervisé)
torch	Autoencoder (PyTorch, architecture n→64→32→16→32→64→n)
xgboost	Modèle supervisé (entraîné sur les labels SOC)
hdbscan	Clustering de campagnes d'attaque
shap	Explicabilité des scores d'anomalie
scikit-learn	Fallback pour Isolation Forest si isotree indisponible
clickhouse-connect	Client ClickHouse (via ja4_common)

Structure modulaire du bot-detector (11 modules)

services/bot-detector/bot_detector/
├── __init__.py          # Package init
├── __main__.py          # Point d'entrée (python -m bot_detector)
├── config.py            # Configuration (os.getenv, PAS pydantic-settings)
├── log.py               # Configuration du logging
├── infra.py             # Connexion ClickHouse, health check
├── preprocessing.py     # Feature engineering, filtrage, normalisation
├── models.py            # EIF, Autoencoder, XGBoost (entraînement + scoring)
├── scoring.py           # Ensemble triple voix, seuils adaptatifs
├── browser.py           # Détection de navigateur 5 axes multifactoriels
├── pipeline.py          # Orchestration du cycle de détection
├── cycle.py             # Boucle principale (cycle de 5 minutes)
└── tests/               # Tests pytest (self-contained, pas d'import lourd)

Module C (mod-reqin-log)

Nécessite apxs (outil d'extension Apache) et les headers de développement :

cd services/mod-reqin-log
make build    # Compile mod_reqin_log.so
make test     # Exécute les tests unitaires
make rpm      # Construit les paquets RPM

Scripts utilitaires

Les scripts dans scripts/ facilitent l'initialisation et la gestion de l'environnement de développement :

Script	Commande Make	Description
init-stack.sh	make init-stack	Initialisation complète de la stack ClickHouse (schéma + données CSV)
import-prod-data.sh	make import-prod-data	Import de données de prod avec décalage temporel
reload-prod-logs.sh	make reload-prod-logs	Export prod → réimport dev avec décalage
update-csv-data.sh	—	Téléchargement et génération de toutes les données CSV de référence

# Initialisation complète (schéma + données CSV + import prod)
make init-and-import

# Initialisation seule (schéma + CSV)
make init-stack

# Import des données prod pré-exportées
make import-prod-data

# Rechargement depuis la prod
make reload-prod-logs

Ajout d'un nouveau service

Service Go

1. Créer le répertoire du service :

   mkdir -p services/my-service/cmd/my-service
   mkdir -p services/my-service/internal
   

2. Initialiser le module Go :

   cd services/my-service
   go mod init github.com/antitbone/ja4/my-service
   

3. Ajouter au go.work :

   use (
       ./services/sentinel
       ./services/correlator
       ./services/my-service      # ← add this
       ./shared/go/ja4common
   )
   

4. Importer la librairie partagée :

   import (
       "github.com/antitbone/ja4/ja4common/logger"
       "github.com/antitbone/ja4/ja4common/config"
       "github.com/antitbone/ja4/ja4common/shutdown"
   )
   

5. Ajouter les cibles Makefile :

   build-my-service:
       docker build -f services/my-service/Dockerfile -t ja4-platform/my-service:latest .
   
   test-my-service:
       docker build -f services/my-service/Dockerfile.dev -t ja4-platform/my-service-tests:latest .
       docker run --rm ja4-platform/my-service-tests:latest
   

6. Mettre à jour les dépendances build-all et test-all.

Service Python

1. Créer le répertoire du service avec un requirements.txt ou pyproject.toml.
2. Ajouter ja4-common comme dépendance (installée depuis shared/python/ja4_common).
3. Utiliser from ja4_common.clickhouse import get_client pour l'accès ClickHouse.
4. Ajouter les cibles Makefile en suivant le modèle bot-detector/dashboard.

Workspace go.work

Le fichier go.work à la racine du dépôt relie tous les modules Go, permettant le développement cross-module sans publication :

go 1.24.6

use (
    ./services/sentinel
    ./services/correlator
    ./shared/go/ja4common
)

Lors de l'ajout d'un nouveau module Go :

1. go mod init dans le répertoire du service
2. Ajouter le chemin dans go.work
3. Référencer les packages partagés via leur chemin de module : github.com/antitbone/ja4/ja4common/...
4. Exécuter go work sync pour mettre à jour le workspace

Les deux services Go ont une directive replace dans leur go.mod pointant vers ../../shared/go/ja4common. Le workspace prend priorité en développement local ; la directive replace est nécessaire pour les builds Docker où go.work n'est pas disponible.

Package Python ja4_common

Le package Python partagé (shared/python/ja4_common) fournit :

• ClickHouseSettings — modèle pydantic-settings lisant depuis .env
• ClickHouseClient — client singleton avec reconnexion automatique
• get_client() — accesseur singleton au niveau du module

Note : le dashboard n'utilise PAS ja4_common — il possède son propre client léger clickhouse-connect dans backend/database.py.

Extension de ja4_common

1. Ajouter de nouveaux modules sous shared/python/ja4_common/ja4_common/
2. Les exporter dans __init__.py
3. Ajouter les dépendances dans pyproject.toml
4. Lancer les tests : make test-ja4common-python

Utilisation dans un nouveau service

Ajouter dans requirements.txt :

ja4-common @ file:///app/shared/python/ja4_common

Or in Docker, copy the shared library and install:

COPY shared/python/ja4_common /app/shared/python/ja4_common
RUN pip install /app/shared/python/ja4_common

Variables d'environnement

Chaque service lit sa configuration depuis des variables d'environnement et/ou des fichiers YAML. Consultez la documentation de chaque service pour la référence complète :

• Configuration du Sentinel
• Configuration du Correlator
• Configuration du Bot Detector
• Configuration du Dashboard