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

27 lignes
2.6 KiB
Markdown

# 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.