← Indice documentazione Guida all'architettura › sandbox

Metnos

Sandbox degli executor

Come viene contenuta un'esecuzione sul server e sui dispositivi associati.

La sandbox limita ciò che il processo di un executor può vedere e modificare. Le risorse dipendono dal manifest firmato e, quando necessario, dall'invocazione concreta. Questo livello si aggiunge al Vaglio, alla verifica dell'identità e ai controlli applicativi: non li sostituisce e non concede, da solo, l'autorizzazione a compiere un'azione.

1. Ambito

Quando un executor gira sul server Linux, runtime/sandbox.py deve anteporre bwrap al comando Python. Bubblewrap costruisce una vista separata del file system, rende privato /tmp, separa alcuni spazi dei nomi e, se l'executor non richiede la rete, aggiunge --unshare-net. Non esiste un demone separato: il profilo viene costruito per ogni invocazione.

Se il lavoro viene trasferito a un dispositivo associato, il client Rust applica invece il meccanismo disponibile su quel sistema operativo. Il server sceglie il dispositivo e verifica l'appartenenza all'utente; il client esegue il comando e restituisce anche il livello di contenimento realmente usato.

2. Interfacce del modulo

Funzione	Responsabilità
`bwrap_available`, `sandbox_disabled`	Rilevano la presenza di `bwrap` e l'eventuale disattivazione mediante `METNOS_SANDBOX`.
`wrap_command`	Restituisce il comando avvolto da `bwrap`, oppure fallisce chiuso prima del sottoprocesso. Soltanto il broker undo vincolato ai byte esatti usa il percorso diretto.
`filesystem_extras`	Risolve soltanto gli argomenti indicati da una capacità firmata `fs:read` con forma `arg:<nome>`; l'argomento può restringere l'ambito, non ampliarlo.
`undo_history_extras`	Rende scrivibile la sola cartella dei contenuti di ripristino appartenente al turno corrente, quando il manifest dichiara il modello inverso previsto.
`invocation_skills`, `skill_extras`	Individuano i fornitori necessari all'invocazione, rendono visibile la sola cartella della relativa integrazione e abilitano la rete. Per gli executor conformi l'origine è `provider:access`; i manifest precedenti conservano un percorso di compatibilità.
`mail_extras`	Per `mail:read` rende visibili in sola lettura le credenziali dei soli account richiesti e abilita la rete. Non monta l'intero deposito delle credenziali.
`dialog_extras`	Per `dialog.user_input` rende scrivibile la sola cartella del mittente autenticato.
`python_package_roots`	Individua le radici dei pacchetti usate dall'interprete corrente, senza esporre l'intera cartella personale.
`status`	Restituisce percorso, disponibilità, disattivazione e stato effettivo di `bwrap`.

3. Risorse rese visibili sul server

3.1 Base di esecuzione

Il profilo monta in sola lettura i percorsi di sistema esistenti fra /usr, /bin, /sbin, le directory delle librerie, /etc, /var/lib/python3 e /sys. Aggiunge inoltre:

/proc e un /dev minimo;
un /tmp privato;
in sola lettura, la cartella dell'executor, il runtime Metnos e l'ambiente Python effettivamente in uso;
in sola lettura, i database i18n e del lessico di riconoscimento, quando presenti.

Sono sempre richiesti --unshare-user, --unshare-ipc, --unshare-uts e --die-with-parent. Il profilo del server non aggiunge attualmente uno spazio dei nomi PID, Landlock o un filtro seccomp personalizzato.

3.2 Risorse derivate dalle capacità

Dichiarazione	Effetto sul profilo
`fs:read` / `fs:write`	Montaggio in sola lettura o in lettura e scrittura. Gli ambiti fissi in forma glob vengono ridotti alla loro radice; gli ambiti `arg:` sono risolti sul valore concreto e soltanto se il percorso esiste.
`metnos:read`, `metnos:write`, `metnos:create`	Traduzione di risorse semantiche chiuse — per esempio fogli, registro persone o proposte — nei soli percorsi canonici gestiti da Metnos.
`index:read`	Accesso in sola lettura alla radice canonica dell'indice dichiarato; un nome sconosciuto non concede nulla.
`systemd:read` e `system:read`	Visibilità limitata alle risorse note necessarie alla lettura dello stato. La richiesta delle interfacce di rete mantiene disponibile la rete dell'host.
`provider:access` o `skill:<nome>`	Cartella dell'integrazione in lettura e scrittura, necessaria anche al rinnovo OAuth, e rete dell'host.
`mail:read`	Singoli file di credenziali dell'account richiesto in sola lettura e rete dell'host.

Le capacità network:* e net:*, le integrazioni esterne e alcuni casi di lettura del sistema impediscono l'aggiunta di --unshare-net. In questo caso il processo dispone della rete dell'host: la limitazione a un dominio o a un fornitore resta compito dei controlli applicativi e delle credenziali circoscritte.

4. Bubblewrap non disponibile

Se bwrap non è nel PATH, oppure se METNOS_SANDBOX vale 0, off, no o false, wrap_command rifiuta ogni executor ordinario prima del registro di annullamento e prima di avviare il sottoprocesso. L'esito stabile è executor_os_sandbox_unavailable.

La sola eccezione diretta è undo_last_turn, riconosciuto mediante nome, origine, appartenenza, capacità, lista dei file e digest firmato esatti. Una revisione Birth successiva non eredita l'eccezione. Lo stato e il rifiuto stabile sono osservabili mediante status() e la diagnostica del servizio.

5. Integrazione nel runtime

invoke_executor è il punto comune di esecuzione. L'ordine essenziale è il seguente:

ricava attore, canale e turno dal contesto autenticato;
valuta l'eventuale collocazione remota, mostrando soltanto i dispositivi appartenenti allo stesso utente;
mantiene sul server le invocazioni che dipendono da un'integrazione esterna installata sul server;
verifica l'ambito firmato dei percorsi e poi fallisce chiuso se bwrap non è disponibile;
prepara il registro di annullamento e le sole risorse aggiuntive necessarie all'invocazione;
avvia sys.executable, cioè l'interprete dell'ambiente Metnos corrente, attraverso wrap_command.

Il punto pubblico passa inoltre dallo schedulatore centrale, che applica limiti di concorrenza senza cambiare collocazione, argomenti o contratto del risultato.

6. Autonomia e policy

Il parametro autonomy è accettato da wrap_command, ma oggi è informativo: non seleziona profili diversi. Il confinamento deriva dalle capacità del manifest e dalle risorse risolte per l'invocazione. Le decisioni su consenso, criticità e ammissibilità appartengono alla policy e al Vaglio, non alla sandbox.

7. Verifiche

I test non dipendono da un numero dichiarato nella documentazione. Le verifiche dedicate coprono i montaggi del runtime e dell'ambiente Python, i database i18n, le integrazioni esterne, le credenziali di posta e i casi di declassamento. Le principali suite sono:

tests/runtime/safety/test_sandbox_runtime_bind.py
tests/runtime/safety/test_sandbox_i18n_bind.py
tests/runtime/safety/test_sandbox_skill_backed.py

I moduli Rust contengono inoltre test vicini alle implementazioni comuni, Linux, Windows e AppContainer. Le prove che confrontano gli argomenti di bwrap possono essere eseguite anche senza avviare una sandbox reale; le prove di sistema verificano separatamente il meccanismo disponibile sulla piattaforma.

8. Diagnostica e installazione

Lo stato corrente si legge con sandbox.status(). La funzione controlla il PATH al momento della chiamata e restituisce bwrap_available, bwrap_path, disabled_via_env e active; il risultato non viene memorizzato dal modulo.

# Debian e Ubuntu
sudo apt install bubblewrap

# Fedora e RHEL
sudo dnf install bubblewrap

# Arch Linux
sudo pacman -S bubblewrap

Dopo l'installazione occorre verificare sia status() sia una vera invocazione nell'ambiente del servizio. Un PATH diverso o la variabile METNOS_SANDBOX possono produrre un esito differente da quello della sessione amministrativa.

9. Confini di sicurezza

Visibile non significa autorizzato. Un montaggio permette al processo di raggiungere una risorsa; l'identità, il consenso e la finalità dell'azione devono essere verificati prima.
Alcuni montaggi di base sono ampi. Sul server /etc e /sys sono visibili in sola lettura quando esistono. Il montaggio condiviso di /opt è stato rimosso, per impedire il riuso di una dipendenza sorella firmata ma non dichiarata.
La rete è binaria. Quando serve, viene ereditata la rete dell'host; bubblewrap non applica una lista di host ammessi.
Il profilo non usa Landlock o seccomp personalizzati e, sul server, non separa lo spazio dei nomi PID.
system:undo è un'eccezione vincolata ai byte. L'annullamento deve ricostruire dal registro risorse note soltanto al momento dell'esecuzione. Il percorso diretto richiede digest e lista dei file revisionati; ogni revisione successiva fallisce chiusa.
L'assenza di bubblewrap produce un rifiuto sul server. I controlli applicativi non sono trattati come sostituti dell'isolamento del kernel.

10. Sandbox sui dispositivi associati

Il client remoto usa un contratto di risultato comune, ma il contenimento dipende dalla piattaforma. Il campo sandbox descrive il livello realmente applicato; un eventuale sandbox_downgrade_reason spiega il passaggio a un livello meno forte.

Piattaforma	Implementazione corrente	Comportamento in caso di declassamento
Linux	Bubblewrap con spazio dei nomi dei montaggi e PID, rete separata quando non richiesta, cartella temporanea privata e gruppo di processi dedicato. Landlock e seccomp personalizzati non sono implementati.	Il server rifiuta l'esecuzione ordinaria se `bwrap` manca o è disattivato. Un client associato deve dichiarare esplicitamente ogni declassamento specifico della piattaforma.
Windows	AppContainer con concessioni derivate dalle capacità, posto a sua volta in un Job Object. AppContainer è tentato per impostazione predefinita quando supportato.	Per sottoprocessi di sistema, percorsi non ancorabili, ambiti troppo ampi o indisponibilità del contenitore, il client usa il Job Object e comunica il motivo. Se il manifest richiede AppContainer come livello minimo, l'invocazione non deve essere declassata silenziosamente.
macOS	Non esiste oggi un modulo nativo `sandbox_macos.rs`. Il percorso Unix comune non offre un equivalente operativo di bubblewrap su macOS.	L'esecuzione non va presentata come isolata: il livello effettivo è `none`, pur restando il controllo della scadenza sul gruppo di processi.

Il Job Object limita la memoria del singolo processo, il numero di processi attivi e la durata dell'albero. Il processo nasce sospeso, viene assegnato al Job Object e soltanto allora viene avviato; alla scadenza l'intero Job Object viene terminato. AppContainer aggiunge l'isolamento di file e rete mediante concessioni calcolate per l'invocazione.

Prima dell'esecuzione remota, il client verifica il pacchetto firmato e usa un interprete Python predisposto e verificato. Queste verifiche proteggono la provenienza del codice; non sostituiscono il contenimento dichiarato nel risultato.