Proposition: WireGuard VPN par Instance SSH

Date: 27/01/2026 Priorite: HAUTE Effort estime: L (1-2 jours) Status: EN ATTENTE VALIDATION

Objectif

Permettre a chaque instance SSH de se connecter via un tunnel WireGuard, pour acceder a des machines distantes de maniere securisee (derriere NAT, reseaux prives, etc.)

Cas d'usage

Acces reseau 86000 (Raph) : Se connecter aux machines de Poitiers via VPN
Serveurs derriere NAT : Machines sans IP publique
Securite renforcee : Chiffrement supplementaire sur reseaux non fiables

Architecture

┌────────────────────────────────────────────────────────────────────────┐
│                        CONNECTORS-API CONTAINER                         │
│  ┌──────────────────┐      ┌──────────────────┐                        │
│  │   wireguard.ts   │─────►│  wireguard-go    │                        │
│  │   (service)      │      │  (userspace)     │                        │
│  └──────────────────┘      └────────┬─────────┘                        │
│                                     │ wg0 interface                    │
│                                     │ 10.0.0.x/24                      │
└─────────────────────────────────────┼──────────────────────────────────┘
                                      │
                            WireGuard │ Tunnel UDP
                              Port 51820
                                      │
                    ┌─────────────────┴─────────────────┐
                    │         SERVEUR DISTANT           │
                    │  WireGuard endpoint (peer)        │
                    │  10.0.0.1/24                      │
                    │                                   │
                    │  ┌─────────────────────────────┐  │
                    │  │  Machines internes          │  │
                    │  │  192.168.x.x (allowed_ips)  │  │
                    │  └─────────────────────────────┘  │
                    └───────────────────────────────────┘

Implementation

Phase 1: Backend - Service WireGuard

Fichier: src/services/wireguard.ts

// Structure de config VPN
interface VPNConfig {
  enabled: boolean;
  private_key_encrypted: string;  // Chiffre AES
  public_key: string;             // Pour donner au peer
  endpoint: string;               // IP:Port du serveur WG distant
  peer_public_key: string;        // Cle publique du peer
  allowed_ips: string;            // CIDR ex: "10.0.0.0/24, 192.168.1.0/24"
  address: string;                // IP locale du tunnel ex: "10.0.0.2/24"
  dns?: string;                   // DNS optionnel
  persistent_keepalive?: number;  // Keepalive (25 par defaut)
}

// Fonctions principales
generateKeyPair(): { privateKey: string, publicKey: string }
connect(instanceId: string, config: VPNConfig): Promise<void>
disconnect(instanceId: string): Promise<void>
getStatus(instanceId: string): Promise<VPNStatus>

Approche technique:

Utiliser wireguard-go en mode userspace (pas besoin de module kernel)
Generer les cles via wg genkey / wg pubkey
Creer interface avec wg-quick ou commandes manuelles
Stocker les connexions actives en Map memoire

Phase 2: Backend - Endpoints API

Fichier: src/index.ts (ajouts)

Endpoint	Description
`POST /api/instances/:id/vpn/generate-keys`	Genere paire de cles, retourne public
`PUT /api/instances/:id/vpn`	Sauvegarde config VPN
`POST /api/instances/:id/vpn/connect`	Demarre tunnel WireGuard
`POST /api/instances/:id/vpn/disconnect`	Arrete tunnel
`GET /api/instances/:id/vpn/status`	Status (connected/disconnected, stats)

Exemple reponse generate-keys:

{
  "public_key": "ABC123...",
  "message": "Cle publique a configurer sur le serveur distant"
}

Exemple reponse status:

{
  "connected": true,
  "interface": "wg-inst-abc123",
  "endpoint": "82.67.42.47:51820",
  "last_handshake": "2026-01-27T12:30:00Z",
  "transfer": {
    "rx": 12345678,
    "tx": 9876543
  }
}

Phase 3: Docker - Capabilities

Modifications conf.prod.gouroubleu.yml:

docker:
  cap_add:
    - NET_ADMIN
    - SYS_MODULE
  sysctls:
    - net.ipv4.ip_forward=1
    - net.ipv4.conf.all.src_valid_mark=1
  devices:
    - /dev/net/tun:/dev/net/tun

Alternative sidecar (si trop complexe):

Container wireguard dedie
Communication via API HTTP interne
connectors-api envoie les configs, le sidecar gere les tunnels

Phase 4: Frontend - UI

Fichier: src/routes/connectors/instance/[id]/index.tsx

Nouvelle section "VPN WireGuard" avec:

Formulaire configuration:
- Endpoint distant (IP:Port) *
- Cle publique du peer *
- Adresse tunnel (ex: 10.0.0.2/24) *
- IPs autorisees (CIDR, comma-separated) *
- DNS (optionnel)
- Keepalive (defaut: 25)
Zone cles:
- Bouton "Generer mes cles"
- Affichage cle publique (copiable)
- Message: "Configurez cette cle sur votre serveur WireGuard"
Controles:
- Toggle Connect/Disconnect
- Indicateur status (badge vert/rouge)
- Stats (RX/TX, dernier handshake)

Fichier: src/components/VpnConfig.tsx (nouveau)

Phase 5: Securite & Audit

Cles privees chiffrees AES-256-CBC (comme SSH)
Validation CIDR (pas de 0.0.0.0/0 par defaut)
Rate limiting connexions VPN (1 par instance)
Audit logs: vpn.connect, vpn.disconnect, vpn.generate_keys
Timeout inactif: deconnexion apres 1h sans trafic

Dependances

Backend

wireguard-go : A installer dans l'image Docker
Ou package npm wireguard si disponible

Frontend

Aucune nouvelle dependance

Docker

Image base doit supporter wireguard-go
Alternative: image linuxserver/wireguard comme sidecar

Plan d'execution

Etape	Description	Fichiers
1	Service wireguard.ts	connectors-api/src/services/wireguard.ts
2	Endpoints API	connectors-api/src/index.ts
3	Types & validation	connectors-api/src/types/*.ts
4	Dockerfile + capabilities	conf.prod.gouroubleu.yml, Dockerfile
5	Frontend VpnConfig	connectors-front/src/components/VpnConfig.tsx
6	Integration page instance	connectors-front/src/routes/.../index.tsx
7	Tests manuels	Tunnel vers 86000 ou VM locale
8	Documentation	memory/ssh-connector.md

Risques & Mitigations

Risque	Impact	Mitigation
Permissions Docker insuffisantes	Bloquant	Tester capabilities avant dev
wireguard-go instable	Moyen	Fallback vers sidecar container
Conflit interfaces reseau	Moyen	Nommage unique wg-inst-{id}
Fuite memoire connexions	Faible	Garbage collector + timeout

Tests prevus

[ ] Generation cles (public_key valide)
[ ] Sauvegarde config en BDD
[ ] Connexion VPN vers VM locale
[ ] Connexion SSH via tunnel VPN
[ ] Deconnexion propre
[ ] Reconnexion apres redemarrage container
[ ] Stats RX/TX correctes
[ ] Audit logs generes

Decisions validees (27/01/2026)

Approche Docker: Sidecar wireguard dedie (plus isole, plus propre)
Perimetre allowed_ips: Les deux - 0.0.0.0/0 autorise + possibilite de restreindre
Nombre max de VPN: Oui, configurable par user (defaut: 5)
Persistance: Les deux - reconnexion auto + option pour desactiver

Validation

[x] Architecture validee
[x] Questions repondues
[x] Pret pour implementation

Status: EN COURS D'IMPLEMENTATION