Fichiers
2026-10-11 01:56:28 +02:00

143 lignes
7.5 KiB
Markdown

# 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`
### 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<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`](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`.