7.5 KiB
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> | 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
- Chemin Release :
Utilisation directe en ligne de commande :
# 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
- 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
bwrapn'est pas présent dans le système sous Linux, l'exécution échoue immédiatement avec l'erreurExecError::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 deJOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE.
- Sous Linux : Confinement via Bubblewrap (
- Arrêt fiable des arbres de processus :
- En cas d'expiration du
timeoutou d'appel àkill(), l'intégralité de l'arborescence (processus parent, enfants, petits-enfants) est immédiatement anéantie sans laisser de processus orphelins (viaTerminateJobObjectsous Windows et--die-with-parentsous Linux).
- En cas d'expiration du
- Pseudo-Terminal natif (PTY) systématique :
- Toutes les commandes tournent dans un vrai terminal virtuel (
portable-pty/ ConPTY sous Windows,/dev/ptssous 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.
- Toutes les commandes tournent dans un vrai terminal virtuel (
- 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_pathsetreadonly_pathsest 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 :
[dependencies]
lmwork-exec = { path = "../lmwork-exec" }
tokio = { version = "1.0", features = ["full"] }
Exemple de code :
use lmwork_exec::{execute, ExecEvent, ExecRequest, SandboxPolicy};
use std::path::PathBuf;
use std::time::Duration;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
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: Choix de Bubblewrap sous Linux.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: Utilisation systématique d'un vrai PTY avecportable-pty.