# Stack de Test et Build — ja4-platform

## Vue d'ensemble

La plateforme ja4 utilise une infrastructure de tests multi-niveaux :
- **Docker** : Build et tests unitaires
- **VM Vagrant** : Tests d'intégration eBPF sur kernel réel
- **RPMs** : Packaging multi-distro (el8/el9/el10)

```
┌─────────────────────────────────────────────────────────────────┐
│                    Host Ubuntu (libvirt/KVM)                     │
│                                                                   │
│  ┌──────────────────┐  ┌──────────────────┐  ┌─────────────────┐│
│  │   centos8 VM     │  │   rocky9 VM      │  │   rocky10 VM    ││
│  │  (kernel 4.18)   │  │  (kernel 5.14)   │  │  (kernel 6.12)  ││
│  │  IP: DHCP        │  │  IP: DHCP        │  │  IP: DHCP       ││
│  └──────────────────┘  └──────────────────┘  └─────────────────┘│
│                                                                  │
│  ┌──────────────────┐  ┌──────────────────┐                      │
│  │   traffic VM     │  │  analysis VM     │                      │
│  │  (curl-impersonate)│ │ (ClickHouse + ML)│                      │
│  │  IP: DHCP        │  │  IP: 192.168.42.10│                      │
│  └──────────────────┘  └──────────────────┘                      │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │               Docker (build/tests)                      │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐         │   │
│  │  │ ja4ebpf    │  │bot-detector│  │ dashboard  │         │   │
│  │  └────────────┘  └────────────┘  └────────────┘         │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
```

## Réseau privé

**Nom du réseau** : `ja4-e2e` (libvirt)
**Plage d'adresses** : 192.168.42.0/24 (DHCP)
**Routeur** : Libvirt NAT vers host

| VM | IP | Rôle |
|----|----|----|
| analysis | 192.168.42.10 | ClickHouse + bot-detector + dashboard |
| centos8 | DHCP (192.168.42.x) | Tests eBPF kernel 4.18 |
| rocky9 | DHCP (192.168.42.x) | Tests eBPF kernel 5.14 (défaut) |
| rocky10 | DHCP (192.168.42.x) | Tests eBPF kernel 6.12 |
| traffic | DHCP (192.168.42.x) | Générateur de trafic |

## VMs de Test

### 1. centos8 (CentOS 8 Stream)

**Box Vagrant** : `centos/8`
**Kernel** : 4.18.0-240.el8_3.x86_64
**Mémoire** : 2 Go RAM, 2 CPU
**Rôle** : Tests eBPF sur kernel 4.18 (RHEL 8 minimal)

**Services installés** :
- nginx (port 80/443)
- Apache httpd (port 8080/8443)
- ja4ebpf (service systemd)
- ClickHouse (Docker)

**Commandes** :
```bash
make vm-up              # Démarrer centos8
vagrant ssh centos8     # Connexion SSH
make test-vm-centos8    # Tests complets
```

### 2. rocky9 (Rocky Linux 9) — VM par défaut

**Box Vagrant** : `generic/rocky9`
**Kernel** : 5.14.0-427.el9.x86_64
**Mémoire** : 2 Go RAM, 2 CPU
**Rôle** : Tests eBPF principaux (défaut)

**Services installés** :
- nginx (port 80/443)
- Apache httpd (port 8080/8443)
- Varnish (port 6081)
- Hitch (port 8443)
- ja4ebpf (service systemd)
- ClickHouse (Docker)

**Commandes** :
```bash
make vm-up              # Démarrer rocky9
make vm-ssh             # Connexion SSH
make test-vm-nginx      # Test nginx
make test-vm-apache     # Test Apache
make test-vm-all        # Tous les tests
```

### 3. rocky10 (Rocky Linux 10 / AlmaLinux 10)

**Box Vagrant** : `almalinux/10`
**Kernel** : 6.12.0-124.el10_1.x86_64
**Mémoire** : 2 Go RAM, 2 CPU
**Rôle** : Tests eBPF sur kernel récent (6.12+)

**Services installés** :
- nginx (port 80/443)
- Apache httpd (port 8080/8443)
- ja4ebpf (service systemd)
- ClickHouse (Docker)

**Commandes** :
```bash
vagrant up rocky10      # Démarrer rocky10
vagrant ssh rocky10     # Connexion SSH
make test-vm-rocky10    # Tests complets
```

### 4. analysis (VM centralisée)

**Box Vagrant** : `generic/rocky9`
**IP fixe** : 192.168.42.10
**Mémoire** : 8 Go RAM (torch + isotree build), 2 CPU
**Rôle** : Serveur central pour tests E2E distribués

**Services Docker** :
- **ClickHouse** (ports 9000, 8123) : Base de données temps réel
- **bot-detector** (port 8080) : ML Python pour détection de bots
- **dashboard** (port 8000) : Interface web Flask

**Réception des logs** :
- Les VMs centos8/rocky9/rocky10 envoient leurs logs ja4ebpf vers 192.168.42.10:9000
- ClickHouse agrège les données de tous les endpoints

**Commandes** :
```bash
make e2e-up             # Démarrer analysis + endpoints
make test-e2e           # Test E2E complet
make test-e2e-quick     # Test E2E rapide
```

### 5. traffic (Générateur de trafic)

**Box Vagrant** : `generic/rocky9`
**Mémoire** : 1 Go RAM, 2 CPU
**Rôle** : Génération de trafic réaliste vers endpoints

**Outils installés** :
- curl-impersonate : TLS fingerprints réalistes (Chrome, Firefox, Safari...)
- httpx : HTTP/2, HTTP/3, HEADERS optimisés
- Scripts de génération de trafic

**Commandes** :
```bash
vagrant up traffic      # Démarrer traffic
vagrant ssh traffic     # Connexion SSH
./generate-traffic.sh   # Générer du trafic vers endpoints
```

## Build Docker

### Image de production ja4ebpf

**Dockerfile** : `services/ja4ebpf/Dockerfile`
**Base image** : `alpine:3.19` (dynamique)
**Builder** : `rockylinux:9` (compilation eBPF)

**Étapes de build** :
```bash
# 1. Génération bytecode eBPF (requiert clang + bpf2go)
make generate

# 2. Build image Docker
make build

# Sortie : antitbone/ja4ebpf:dev
```

**Variables de build** :
- `BUILD_VERSION` : Version du binaire (défaut: dev)
- `GO_VERSION` : Version Go (défaut: 1.24.3)

### Image de tests

**Dockerfile** : `services/ja4ebpf/Dockerfile.tests`
**Base image** : `rockylinux:9` (clang + Go)

**Commandes** :
```bash
make test               # Lance les tests unitaires Go
```

### Image multi-distro RPM

**Dockerfile** : `services/ja4ebpf/Dockerfile.package`
**Cible** : RPMs el8, el9, el10

**Stages** :
1. **go-builder** : Rocky Linux 9 + clang + Go
2. **rpm-el8** : AlmaLinux 8 + rpmbuild
3. **rpm-el9** : Rocky Linux 9 + rpmbuild
4. **rpm-el10** : AlmaLinux 10 + rpmbuild
5. **output** : Collecte tous les RPMs

**Commandes** :
```bash
make rpm-ja4ebpf       # Construit les 3 RPMs
make dist              # Copie RPMs dans dist/

# Sortie :
# services/ja4ebpf/dist/el8/ja4ebpf-0.3.0-1.el8.x86_64.rpm
# services/ja4ebpf/dist/el9/ja4ebpf-0.3.0-1.el9.x86_64.rpm
# services/ja4ebpf/dist/el10/ja4ebpf-0.3.0-1.el10.x86_64.rpm
```

## Services Docker (VM analysis)

### Stack complète

**Fichier** : `tests/vm/analysis/docker-compose.yml`

**Services** :

#### 1. ClickHouse

- **Image** : `clickhouse/clickhouse-server:24.8`
- **Ports** : 9000 (native), 8123 (HTTP)
- **Volumes** :
  - Schéma SQL (12 fichiers)
  - Données CSV (dictionnaires, browser_h2)
  - Scripts d'initialisation
- **Healthcheck** : `clickhouse-client --query "SELECT 1"`

#### 2. bot-detector

- **Build** : `services/bot-detector/bot_detector/Dockerfile`
- **Port** : 8080
- **Dépendances** : ClickHouse
- **Variables** :
  - Cycle accéléré : 30s (production: 300s)
  - ML : isolation_forest, XGBoost
  - Logs : JSONL dans volume

#### 3. dashboard

- **Build** : `services/dashboard/Dockerfile`
- **Port** : 8000
- **Dépendances** : ClickHouse
- **Framework** : Flask + Plotly

## Commandes principales

### VMs (Vagrant)

```bash
# Création
make vm-up              # rocky9 seulement (défaut)
make vm-up-all          # centos8 + rocky9 + rocky10

# Gestion
make vm-ssh             # Connexion rocky9
vagrant ssh centos8     # Connexion centos8
make vm-down            # Détruire rocky9
make vm-down-all        # Détruire toutes les VMs

# Provisionnement
make vm-reprovision     # Re-provisionner toutes les VMs
vagrant provision centos8  # Re-provisionner centos8
```

### Tests VM

```bash
# Tests simples (host → VM)
make test-vm-nginx      # nginx sur rocky9
make test-vm-apache     # Apache sur rocky9
make test-vm-hitch-varnish  # hitch+varnish sur rocky9
make test-vm-all        # Tous les stacks sur rocky9

# Tests multi-distros
make test-vm-centos8    # Tous les stacks sur centos8
make test-vm-rocky10    # Tous les stacks sur rocky10
make test-vm-matrix     # 3 stacks × 3 distros (9 tests)

# Tests unitaires Go dans VMs
make test-vm-all-distros    # Tests Go sur centos8 + rocky9 + rocky10
```

### Build et Packaging

```bash
# Docker
make generate            # Génération bytecode eBPF
make build               # Build image Docker
make test                # Tests unitaires Docker

# RPMs
make rpm-ja4ebpf        # RPMs el8 + el9 + el10
make dist               # Copie RPMs → dist/
```

### Tests E2E

```bash
make e2e-up             # Démarrer analysis + endpoints
make test-e2e           # Test complet (trafic → capture → ML → dashboard)
make test-e2e-quick     # Test rapide (1 cycle ML)
make e2e-down           # Arrêter analysis + endpoints
```

## Flux de test typique

### Développement itératif

```bash
# 1. Modifier code Go/C sur host
vim services/ja4ebpf/internal/loader/loader.go

# 2. Synchroniser + recompiler dans VM
make vm-rebuild-ja4ebpf

# 3. Lancer les tests
make test-vm-nginx

# 4. Vérifier les logs
vagrant ssh -- -t 'sudo journalctl -u ja4ebpf -n 50'
```

### Test multi-kernel

```bash
# 1. Démarrer toutes les VMs
make vm-up-all

# 2. Lancer la matrice de tests
make test-vm-matrix

# Résultat attendu :
# - centos8: nginx ✅ apache ✅ hitch-varnish ✅
# - rocky9:  nginx ✅ apache ✅ hitch-varnish ✅
# - rocky10: nginx ✅ apache ✅ hitch-varnish ✅
```

### Build RPM pour production

```bash
# 1. Builder les RPMs multi-distro
make rpm-ja4ebpf

# 2. Vérifier les RPMs créés
find services/ja4ebpf/dist -name '*.rpm'

# 3. Tester un RPM sur VM
vagrant ssh rocky9 -- 'sudo rpm -Uvh /vagrant/dist/el9/ja4ebpf-*.rpm'
```

## Dépannage

### VM ne démarre pas

```bash
# Vérifier libvirt
sudo systemctl status libvirtd
virsh list --all

# Vérifier réseau
virsh net-list --all
virsh net-info ja4-e2e
```

### Tests échouent

```bash
# Vérifier que ja4ebpf tourne
vagrant ssh -- 'systemctl status ja4ebpf'

# Vérifier les logs
vagrant ssh -- 'sudo journalctl -u ja4ebpf -n 100 -f'

# Vérifier ClickHouse
vagrant ssh -- 'docker ps | grep clickhouse'
vagrant ssh -- 'docker exec clickhouse clickhouse-client --query "SELECT 1"'
```

### Build échoue

```bash
# Vérifier Docker
docker ps
docker images

# Nettoyer et recommencer
docker system prune -a
make generate
```

## Références

- **Vagrantfile** : `tests/vm/Vagrantfile`
- **Docker Compose analysis** : `tests/vm/analysis/docker-compose.yml`
- **RPM spec** : `services/ja4ebpf/packaging/rpm/ja4ebpf.spec`
- **Makefile principal** : `Makefile`
- **Scripts de test** : `tests/vm/*.sh`