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

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

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

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

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

```bash
make rpm-all
```

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

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

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

```bash
# 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)

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

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

```bash
# 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 :
   ```bash
   mkdir -p services/my-service/cmd/my-service
   mkdir -p services/my-service/internal
   ```

2. Initialiser le module Go :
   ```bash
   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 :
   ```go
   import (
       "github.com/antitbone/ja4/ja4common/logger"
       "github.com/antitbone/ja4/ja4common/config"
       "github.com/antitbone/ja4/ja4common/shutdown"
   )
   ```

5. Ajouter les cibles Makefile :
   ```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:
```dockerfile
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](services/sentinel.md#configuration-reference)
- [Configuration du Correlator](services/correlator.md#configuration-reference)
- [Configuration du Bot Detector](services/bot-detector.md#environment-variables)
- [Configuration du Dashboard](services/dashboard.md#configuration)