143 lignes
7.5 KiB
Markdown
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`.
|