Fichiers
lmwork/doc/adr/0001-bubblewrap-linux-sandbox.md
2026-10-11 01:56:28 +02:00

ADR 0001 : Choix de Bubblewrap (bwrap) pour le confinement sous Linux

Statut

Accepté

Contexte

GastinelLMwork nécessite un bac à sable strict sous Linux pour exécuter des commandes issues d'un modèle d'IA local. Le principe fondateur du projet stipule :

« L'intelligence est dans le confinement, pas dans le classifieur. »

Les alternatives pour le confinement sous Linux incluaient :

  1. Docker / Podman / Conteneurs OCI : Lourds, nécessitent un démon système ou des privilèges root / socket, introduisent une complexité de démarrage et de dépendances inacceptable pour une bibliothèque embarquée dans un outil de développement léger.
  2. Seccomp brut ou Chroot : chroot requiert les privilèges root (CAP_SYS_CHROOT). seccomp pur bloque les appels système mais ne gère pas les espaces de noms de chemins de fichiers ni le réseau.
  3. Landlock : Récent dans le noyau Linux (5.13+), ne gère pas nativement l'isolation de l'espace de noms réseau ni PID.
  4. Bubblewrap (bwrap) : Outil standard de sandboxing non privilégié (utilisé par Flatpak), s'appuyant sur les user namespaces du noyau Linux sans nécessiter de démon ni de droits administrateur.

Décision

Nous choisissons Bubblewrap (bwrap) comme moteur d'isolation principal sous Linux :

  • Espaces de noms isolés : --unshare-all (montage, PID, réseau, IPC, UTS, cgroup).
  • Isolation du système de fichiers stricte : Aucun chemin hôte n'est visible par défaut. Seuls les chemins listés dans policy.readonly_paths (--ro-bind) et policy.writable_paths (--bind) sont montés.
  • Réseau désactivable : --unshare-net garantit l'absence totale de connectivité quand network: false.
  • Nettoyage automatique : --die-with-parent assure que la mort du superviseur ou de bwrap tue instantanément tous les sous-processus de l'arbre.
  • Interdiction du contournement : La bibliothèque vérifie obligatoirement la présence de l'exécutable bwrap (which::which("bwrap")). Si bwrap est absent, l'exécution échoue immédiatement avec une erreur explicite ExecError::BwrapNotFound. Aucun repli silencieux vers une exécution sans confinement n'est toléré.

Conséquences

  • Avantages : Confinement robuste et éprouvé par le monde des distributions Linux (Flatpak), zéro démon, démarrage ultra-rapide (millisecondes), sécurité garantie par le noyau.
  • Limites : Les distributions très anciennes sans support des user namespaces non privilégiés (ou avec kernel.unprivileged_userns_clone = 0) nécessitent l'installation du binaire bwrap avec bit SUID ou l'activation des user namespaces.