# GastinelLMwork v0 — Noyau d'Exécution & Bac à Sable (`lmwork-exec`) `lmwork-exec` est la bibliothèque fondamentale d'exécution et de confinement sécurisé pour l'environnement agentique GastinelLMwork. Principe directeur figé : > **« L'intelligence est dans le confinement, pas dans le classifieur. »** L'analyse statique ou heuristique d'une commande shell pour déterminer sa dangerosité étant indécidable en pratique (ex. `echo | base64 -d | sh`, scripts postinstall npm, Makefiles arbitraires), la sécurité repose exclusivement sur les barrières de confinement du système d'exploitation. --- ## 1. Emplacement des artefacts compilés Après compilation via `cargo build --release` : - **Bibliothèque Rust (crate)** : `lmwork-exec/` (éditable et réutilisable dans vos applications). - **Binaire exécutable autonome (`.exe`)** : - **Chemin Release** : `target\release\lmwork-exec.exe` - **Chemin Debug** : `target\debug\lmwork-exec.exe` ### Utilisation directe en ligne de commande : ```powershell # Exécution simple avec timeout de 5 secondes .\target\release\lmwork-exec.exe --timeout 5 "echo Hello World" # Exécution avec restriction mémoire et interdiction réseau .\target\release\lmwork-exec.exe --timeout 10 --max-mem 268435456 "cmd.exe /C dir" ``` --- ## 2. Ce que fait la brique 1. **Confinement multiplateforme par l'OS** : - **Sous Linux** : Confinement via **Bubblewrap (`bwrap`)**. Isolation intégrale des espaces de noms (montages, réseau, PID, IPC, UTS, cgroups). Seuls les répertoires explicitement listés dans la politique (`writable_paths`, `readonly_paths`) sont montés dans le bac à sable. Tout le reste du système de fichiers est invisible. - **Vérification stricte de Bubblewrap** : Si `bwrap` n'est pas présent dans le système sous Linux, l'exécution **échoue immédiatement avec l'erreur `ExecError::BwrapNotFound`**. Il n'y a **jamais de repli silencieux vers une exécution non confinée**. - **Sous Windows** : Confinement via **Windows Job Object**. Contrôle strict des quotas mémoire (`max_memory_bytes`), limitation du nombre de processus concurrents (`max_processes`), et activation de `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`. 2. **Arrêt fiable des arbres de processus** : - En cas d'expiration du `timeout` ou d'appel à `kill()`, l'intégralité de l'arborescence (processus parent, enfants, petits-enfants) est immédiatement anéantie sans laisser de processus orphelins (via `TerminateJobObject` sous Windows et `--die-with-parent` sous Linux). 3. **Pseudo-Terminal natif (PTY) systématique** : - Toutes les commandes tournent dans un vrai terminal virtuel (`portable-pty` / ConPTY sous Windows, `/dev/pts` sous Linux). - Les programmes interactifs (`sudo`, `git rebase -i`, prompts de mot de passe, `Read-Host`) fonctionnent sans blocage de tubes. - Support complet de la saisie interactive utilisateur (`write_input`) et du redimensionnement dynamique de fenêtre (`resize`). - Flux d'octets brut transmis au fil de l'eau sans altération des séquences d'échappement ANSI. 4. **Journalisation structurée d'audit** : - Chaque exécution consigne un enregistrement JSON par ligne (NDJSON) : horodatage ISO-8601, commande, répertoire de travail, politique appliquée, code de retour, durée en millisecondes et avertissements éventuels. - Aucun secret ou variable d'environnement n'est consigné dans les journaux. --- ## 3. Ce que la brique NE garantit PAS (Différences et Limites) > [!WARNING] > **Limite critique connue sous Windows (Passe v0) :** > Un **Job Object Windows ne restreint pas le système de fichiers**. > Sous Windows dans cette version, une commande hostile exécutée par l'utilisateur conserve la possibilité de lire les fichiers de son profil utilisateur (ex. `type C:\Users\...\.ssh\id_ed25519`). > - La politique `writable_paths` et `readonly_paths` est acceptée par l'API pour préserver la portabilité, mais un avertissement explicite d'audit est émis : > *`Windows sandbox warning: writable_paths and readonly_paths filesystem isolation is NOT enforced on Windows in this version (Job Object isolation only).`* > - L'isolation fine des systèmes de fichiers sous Windows via des jetons restreints (`CreateRestrictedToken`) ou AppContainer est planifiée pour la passe v1. > - **Sous Linux en revanche, l'isolation du système de fichiers est totale et effective dès cette version v0 via Bubblewrap.** --- ## 4. Tableau comparatif Linux vs Windows | Caractéristique | Linux (`bwrap`) | Windows (`Job Object`) | | :--- | :--- | :--- | | **Backend de sandboxing** | Bubblewrap 0.4+ | Windows Job Object Win32 API | | **Isolation Système de fichiers** | **Absolue** (seuls les chemins de la politique sont visibles) | **Non appliquée en v0** (Job Object ne restreint pas NTFS) | | **Isolation Réseau** | **Oui** (`--unshare-net` quand `network: false`) | **Non appliquée en v0** | | **Limitation Mémoire & Processus** | Primitifs cgroup / rlimit | **Oui** (`JobMemoryLimit`, `ActiveProcessLimit`) | | **Destruction totale de l'arbre** | **Oui** (`--die-with-parent` + pid namespace) | **Oui** (`JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` + `TerminateJobObject`) | | **PTY interactif** | `/dev/pts` POSIX | Windows ConPTY avec handshake DSR | | **Comportement si outil absent** | **Échec immédiat** (`ExecError::BwrapNotFound`) | Intégré au noyau Windows NT | --- ## 5. Exemple d'intégration en bibliothèque Rust Ajoutez `lmwork-exec` à vos dépendances dans `Cargo.toml` : ```toml [dependencies] lmwork-exec = { path = "../lmwork-exec" } tokio = { version = "1.0", features = ["full"] } ``` ### Exemple de code : ```rust use lmwork_exec::{execute, ExecEvent, ExecRequest, SandboxPolicy}; use std::path::PathBuf; use std::time::Duration; #[tokio::main] async fn main() -> Result<(), Box> { let policy = SandboxPolicy { writable_paths: vec![PathBuf::from("/tmp/workspace")], readonly_paths: vec![PathBuf::from("/usr"), PathBuf::from("/bin")], network: false, allow_sudo: false, max_memory_bytes: Some(512 * 1024 * 1024), // 512 Mo max_processes: Some(32), timeout: Some(Duration::from_secs(10)), }; let request = ExecRequest { command: "cargo test".to_string(), cwd: PathBuf::from("/tmp/workspace"), policy, }; let (mut handle, mut rx) = execute(request).await?; // Écoute du flux au fil de l'eau while let Some(event) = rx.recv().await { match event { ExecEvent::Stdout(bytes) => { print!("{}", String::from_utf8_lossy(&bytes)); } ExecEvent::Exited { code } => { println!("\nProcessus terminé avec le code : {:?}", code); break; } ExecEvent::TimedOut => { eprintln!("\nTimeout dépassé : processus tué !"); } _ => {} } } Ok(()) } ``` --- ## 6. Architecture des décisions (ADR) Consultez les décisions d'architecture détaillées dans le dossier `doc/adr/` : - [`doc/adr/0001-bubblewrap-linux-sandbox.md`](doc/adr/0001-bubblewrap-linux-sandbox.md) : Choix de Bubblewrap sous Linux. - [`doc/adr/0002-windows-job-object-and-filesystem-limits.md`](doc/adr/0002-windows-job-object-and-filesystem-limits.md) : Choix des Windows Job Objects et limite assumée sur le système de fichiers. - [`doc/adr/0003-systematic-pty-portable-pty.md`](doc/adr/0003-systematic-pty-portable-pty.md) : Utilisation systématique d'un vrai PTY avec `portable-pty`.