Premier commit
Cette révision appartient à :
révision
0beb92563c
7 fichiers modifiés
+1305
Aucun fichier ne correspond à votre recherche
@@ -0,0 +1,68 @@
|
|||||||
|
|
||||||
|
# --- double-push : exclusions generiques (secrets, builds, binaires, gros fichiers) ---
|
||||||
|
target/
|
||||||
|
node_modules/
|
||||||
|
build/
|
||||||
|
build-*/
|
||||||
|
dist/
|
||||||
|
out/
|
||||||
|
.gradle/
|
||||||
|
.idea/
|
||||||
|
venv/
|
||||||
|
.venv/
|
||||||
|
env/
|
||||||
|
__pycache__/
|
||||||
|
*.pyc
|
||||||
|
.cache/
|
||||||
|
.next/
|
||||||
|
.env
|
||||||
|
.env.*
|
||||||
|
!.env.example
|
||||||
|
accounts.json
|
||||||
|
Clee.API/
|
||||||
|
*.pem
|
||||||
|
*.key
|
||||||
|
*.p12
|
||||||
|
*.pfx
|
||||||
|
*.jks
|
||||||
|
*.keystore
|
||||||
|
keystore.properties
|
||||||
|
id_rsa*
|
||||||
|
id_ed25519*
|
||||||
|
*.kdbx
|
||||||
|
*.odt
|
||||||
|
*.sqlite
|
||||||
|
*.sqlite3
|
||||||
|
*.db
|
||||||
|
*.log
|
||||||
|
*.exe
|
||||||
|
*.dll
|
||||||
|
*.msi
|
||||||
|
*.jar
|
||||||
|
*.zip
|
||||||
|
*.7z
|
||||||
|
*.rar
|
||||||
|
*.tar
|
||||||
|
*.tar.gz
|
||||||
|
*.tgz
|
||||||
|
*.gguf
|
||||||
|
*.safetensors
|
||||||
|
*.onnx
|
||||||
|
*.pt
|
||||||
|
*.pth
|
||||||
|
*.bin
|
||||||
|
*.iso
|
||||||
|
*.gws
|
||||||
|
*.apk
|
||||||
|
*.aab
|
||||||
|
*.so
|
||||||
|
*.o
|
||||||
|
*.a
|
||||||
|
*.lib
|
||||||
|
*.pdb
|
||||||
|
*.mp4
|
||||||
|
*.mkv
|
||||||
|
*.wav
|
||||||
|
*.flac
|
||||||
|
# sous-depots / donnees volumineuses exclus du premier commit
|
||||||
|
/lmwork-exec/
|
||||||
Générée
+1002
Diff désactivé car ce fichier est trop long.
Voir la Diff
@@ -0,0 +1,5 @@
|
|||||||
|
[workspace]
|
||||||
|
members = [
|
||||||
|
"lmwork-exec",
|
||||||
|
]
|
||||||
|
resolver = "2"
|
||||||
+142
@@ -0,0 +1,142 @@
|
|||||||
|
# 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`.
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
# 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.
|
||||||
@@ -0,0 +1,33 @@
|
|||||||
|
# ADR 0002 : Confinement Windows via Job Objects et limite assumée sur le système de fichiers
|
||||||
|
|
||||||
|
## Statut
|
||||||
|
Accepté (V0 — limite documentée et assumée)
|
||||||
|
|
||||||
|
## Contexte
|
||||||
|
Sous Windows, confiner l'exécution d'un processus arbitraire (spécifiquement lancé dans un terminal virtuel ConPTY) impose de concilier la gestion des ressources, l'arrêt des arborescences de processus et la sécurité des accès disques.
|
||||||
|
|
||||||
|
Sous Windows, les mécanismes d'isolation incluent :
|
||||||
|
1. **Windows Job Objects** : Primitif noyau pour borner la mémoire (`ProcessMemoryLimit`, `JobMemoryLimit`), le nombre de processus (`ActiveProcessLimit`), et détruire tous les descendants lors de la clôture (`JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`).
|
||||||
|
2. **Jetons restreints (`CreateRestrictedToken`)** : Permet de supprimer des privilèges et d'ajouter des SIDs de restriction pour limiter les ACLs de fichiers.
|
||||||
|
3. **AppContainer Isolation** : Mécanisme de sandbox moderne UWP/Chromium, mais très lourd à mettre en place avec ConPTY et nécessitant des configurations d'ACLs explicites sur chaque ressource.
|
||||||
|
|
||||||
|
## Décision
|
||||||
|
Pour la passe v0 de GastinelLMwork :
|
||||||
|
1. **Implémentation de `Windows Job Object`** :
|
||||||
|
- Chaque commande est associée dès sa création à un Job Object Windows anonyme.
|
||||||
|
- Les limites de mémoire (`policy.max_memory_bytes`) et de processus (`policy.max_processes`) sont imposées au niveau du noyau via `SetInformationJobObject`.
|
||||||
|
- `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` est systématiquement activé.
|
||||||
|
- En cas de timeout ou de commande de destruction (`kill`), `TerminateJobObject` est invoqué, garantissant que tout l'arbre de processus (processus parent `cmd.exe`, `powershell.exe`, et sous-processus éventuels) est anéanti sans processus zombie.
|
||||||
|
2. **Limite connue et assumée : absence d'isolation du système de fichiers en v0** :
|
||||||
|
- Un Windows Job Object **ne restreint pas l'accès au système de fichiers NTFS**.
|
||||||
|
- Par conséquent, sur Windows dans cette passe v0, une commande de type `type C:\Users\...\.ssh\id_ed25519` ou la lecture/écriture de fichiers hors des chemins spécifiés **n'est pas bloquée par le noyau**.
|
||||||
|
- **Décision contractuelle** : L'implémentation de `CreateRestrictedToken` est reportée à la passe v1.
|
||||||
|
3. **Mesures d'atténuation en v0** :
|
||||||
|
- La politique `writable_paths` / `readonly_paths` est acceptée par l'API pour préserver la portabilité du code appelant.
|
||||||
|
- Dès qu'au moins un chemin de fichier est spécifié dans la politique sous Windows, un **avertissement clair et non équivoque** est émis dans les journaux d'audit et la console (`tracing::warn!`) :
|
||||||
|
> *« Windows sandbox warning: writable_paths and readonly_paths filesystem isolation is NOT enforced on Windows in this version (Job Object isolation only). »*
|
||||||
|
- L'architecture de la bibliothèque (`platform/windows.rs`) est isolée pour permettre le branchement de `CreateRestrictedToken` dans la passe suivante sans refactoriser l'API publique ni le moteur de PTY.
|
||||||
|
|
||||||
|
## Conséquences
|
||||||
|
- **Avantages** : Zéro fuite de processus sous Windows en cas de timeout ou d'arrêt ; respect strict des quotas mémoire et nombre de processus.
|
||||||
|
- **Risques de sécurité (assumé en v0)** : Les scripts exécutés sous Windows ont accès à l'ensemble des fichiers accessibles par l'utilisateur courant. Ne pas exécuter de commandes non fiables sous Windows sans confirmation explicite de l'humain.
|
||||||
@@ -0,0 +1,29 @@
|
|||||||
|
# ADR 0003 : Utilisation systématique d'un vrai PTY (`portable-pty`)
|
||||||
|
|
||||||
|
## Statut
|
||||||
|
Accepté
|
||||||
|
|
||||||
|
## Contexte
|
||||||
|
L'exécution de commandes dans les environnements de développement ou assistants IA souffre historiquement d'une faiblesse majeure : l'utilisation de tubes standards (`pipes` stdin/stdout/stderr via `std::process::Stdio::piped()`).
|
||||||
|
|
||||||
|
Cette approche classique échoue systématiquement sur :
|
||||||
|
1. `sudo` qui refuse de lire le mot de passe depuis un pipe (exige un vrai tty).
|
||||||
|
2. Les outils interactifs tels que `git rebase -i`, `git commit`, `nano`, `vim`, ou les prompts SSH.
|
||||||
|
3. Tout binaire vérifiant `isatty(STDIN_FILENO)` ou `_isatty()`.
|
||||||
|
4. La mise en mémoire tampon automatique de la libc (`setvbuf`), qui retarde la sortie textuelle par bloc de 4 Ko au lieu de l'émettre au fil de l'eau.
|
||||||
|
|
||||||
|
## Décision
|
||||||
|
1. **Passage systématique par un PTY natif** :
|
||||||
|
Toute commande est exécutée au travers de la bibliothèque `portable-pty` (s'appuyant sur ConPTY sous Windows et les pseudo-terminaux `/dev/pts` POSIX sous Linux).
|
||||||
|
2. **Pas d'interprétation ANSI côté moteur d'exécution** :
|
||||||
|
Le moteur lit les octets bruts du descripteur maître et les remonte tels quels sous forme d'événements `ExecEvent::Stdout(Vec<u8>)`. Le traitement et le rendu des séquences ANSI (couleurs, positions de curseur, clear screen) relèvent de la responsabilité de l'interface utilisateur frontend (xterm.js ou terminal Tauri dans une passe ultérieure).
|
||||||
|
3. **Contrôle dynamique du terminal** :
|
||||||
|
L'API expose :
|
||||||
|
- `write_input(&[u8])` pour injecter des frappes clavier au processus interactif.
|
||||||
|
- `resize(cols, rows)` pour notifier le terminal virtuel d'un changement de taille de fenêtre.
|
||||||
|
4. **Gestion de la négociation initiale ConPTY sous Windows** :
|
||||||
|
ConPTY émet par conception une séquence ANSI DSR (`\x1b[6n`) à l'initialisation pour interroger la position du curseur. Sans émulateur de terminal physique pour y répondre, `cmd.exe` peut bloquer. Notre couche PTY répond immédiatement par `\x1b[1;1R` dès l'ouverture du terminal sous Windows, éliminant tout blocage.
|
||||||
|
|
||||||
|
## Conséquences
|
||||||
|
- **Avantages** : Compatibilité totale avec les programmes interactifs, transmission immédiate et non bufférisée des caractères, comportement identique à une session terminal utilisateur.
|
||||||
|
- **Particularité** : Dans un PTY, `stdout` et `stderr` sont fusionnés par le système d'exploitation au niveau du terminal esclave. Le flux est donc unifié en `ExecEvent::Stdout`.
|
||||||
Référencer dans un nouveau ticket
Bloquer un utilisateur