Skip to main content
Il flag --sandbox esegue la CLI con isolamento a livello di sistema operativo, applicando a livello di sistema operativo gli ambiti di autorizzazione Read e Write attivi e, facoltativamente, limitando il traffico di rete.

​
Come funziona la sandbox

Quando la sandbox è attiva:
  • I percorsi scrivibili derivano dagli ambiti delle autorizzazioni Write(...) concessi, oltre che dalla directory del workspace
  • I percorsi leggibili derivano dagli ambiti Read(...) concessi (i percorsi predefiniti della piattaforma, come /usr/bin, sono sempre leggibili)
  • Gli ambiti concessi nel corso della sessione espandono dinamicamente la sandbox per i comandi successivi
Se la risoluzione della sandbox non riesce (ad es. gli strumenti di sandboxing non sono disponibili sulla piattaforma dell’utente), la CLI si rifiuta di avviarsi invece di avviarsi senza sandbox. Questo comportamento fail-closed si applica sia quando la sandbox è stata abilitata tramite un’impostazione del team, sia quando l’utente passa direttamente --sandbox, garantendo che l’obiettivo di sicurezza non venga mai aggirato silenziosamente.Cause comuni degli errori di risoluzione della sandbox:
  • Windows: il sandboxing a livello di sistema operativo non è attualmente supportato su Windows. Le sessioni su Windows non si avviano quando viene passato --sandbox o quando l’applicazione della sandbox è Required, incluso il caso in cui la CLI venga eseguita come server ACP all’interno di un IDE (ad es. Devin Desktop).
  • Linux: il sandboxing richiede che bubblewrap (bwrap) e socat siano installati. Se mancano, l’avvio delle sessioni non riesce e vengono mostrate le istruzioni di installazione.
  • Errori negli ambiti di autorizzazione: percorsi non validi negli ambiti di autorizzazione che non possono essere risolti.

​
Filtro di rete

Il filtro di rete del sandbox è attualmente instabile. Se hai bisogno di questa funzionalità, contatta il referente del tuo account per conoscere le tempistiche di stabilizzazione.
Configura il filtro di rete a livello di dominio per il sandbox nella sezione sandbox del file di configurazione (solo configurazione utente). Quando --sandbox è attivo e il filtraggio dei domini è configurato, viene avviato un proxy di rete gestito sull’interfaccia di loopback e il sandbox limita tutto il traffico dei processi figli a passare attraverso di esso. Sintassi dei pattern di dominio: Esempio:
Il filtraggio dei domini si applica quando la sandbox è attiva (--sandbox). Senza --sandbox, la sezione relativa alla sandbox viene ignorata.

​
Comandi esclusi

A volte un comando specifico deve essere eseguito al di fuori della sandbox, ad esempio i comandi git che devono accedere alle credenziali o gli hook bloccati dalla sandbox. La sezione di configurazione sandbox.excluded consente di escludere i comandi corrispondenti dall’isolamento della sandbox usando la stessa sintassi di regola Exec(...) di autorizzazioni: Esempio:
Risoluzione delle regole: per ogni comando, all’interno di una sorgente prevale la regola corrispondente più specifica (ad es. Exec(git push *) prevale su Exec(git *)), e quando corrispondono sia la configurazione utente sia le impostazioni del team, prevale il verdetto più restrittivo (deny > ask > allow). I comandi senza alcuna regola corrispondente — anche quando sandbox.excluded non è configurato — vengono sempre eseguiti all’interno della sandbox.
  • In sandbox.excluded sono supportate solo le regole Exec(...); qualsiasi altro tipo di regola (ad es. Read(...), Write(...)) viene ignorato con un avviso.
  • L’esclusione opera in modalità fail-closed: se un comando non può essere determinato in modo sicuro (ad es. perché non può essere analizzato), rimane all’interno della sandbox.
  • Le esclusioni si applicano al percorso exec predefinito per comando. I comandi eseguiti tramite una shell PTY persistente (sessioni interattive, oppure quando pty_for_noninteractive_exec è abilitato) rimangono sempre all’interno della sandbox.

​
Applicazione a livello Enterprise

Gli amministratori Enterprise possono controllare il comportamento della sandbox per l’intera organizzazione tramite Team Settings.

​
Modalità di applicazione della sandbox

Imposta il livello di applicazione del flag --sandbox per tutta la tua organizzazione:
  • Facoltativo (predefinito) — Gli utenti scelgono se specificare --sandbox. Nessuna imposizione.
  • Obbligatorio — Il flag --sandbox viene imposto per tutti gli utenti, anche se non lo specificano sulla riga di comando. Tutte le sessioni CLI vengono eseguite con sandboxing del file system a livello di sistema operativo, che applica gli ambiti di autorizzazione in lettura/scrittura.
Una futura modalità Strict potrebbe bloccare completamente la configurazione della sandbox, impedendo agli utenti di modificarne le impostazioni.
Assicurati che tutte le macchine di destinazione siano state predisposte prima di impostare la modalità di applicazione della sandbox su Obbligatorio per tutta la tua organizzazione. Se alcuni utenti utilizzano Windows, non potranno eseguire la CLI finché il sandboxing a livello di sistema operativo non sarà supportato su Windows o finché il criterio non verrà allentato su Facoltativo.

​
Filtraggio dei domini Enterprise

Gli amministratori possono anche configurare allowlist e denylist di domini valide per l’intera organizzazione:
  • Allowlist di domini — Se impostata, solo i domini presenti in questo elenco sono raggiungibili tramite il proxy di rete della sandbox. Questo elenco è vincolante: sostituisce completamente qualsiasi allowed_domains configurato dall’utente. Gli utenti non possono aggiungere altri domini per aggirare le restrizioni impostate dagli amministratori.
  • Denylist di domini — Domini sempre bloccati. I domini negati a livello Enterprise sono additivi: vengono uniti ai denied_domains locali dell’utente, rendendo l’elenco risultante più restrittivo.
Come interagiscono gli elenchi di domini Enterprise e quelli dell’utente:
Poiché i denied_domains locali dell’utente vengono mantenuti e uniti in modo additivo, un utente potrebbe negare un dominio presente nell’allowlist Enterprise. È intenzionale: l’effetto combinato è sempre più restrittivo, mai meno. Se questo causa problemi di accesso, l’utente deve rimuovere la voce in conflitto dalla propria configurazione locale.

​
Comandi esclusi a livello Enterprise

Gli admin possono anche impostare nelle impostazioni del team regole di comandi esclusi valide per tutta l’organizzazione:
  • Allow / ask esclusi — regole Exec(...) per i comandi che possono essere eseguiti fuori dal sandbox in tutta l’organizzazione, automaticamente o dopo una richiesta di conferma.
  • Deny esclusi — regole Exec(...) per i comandi che non devono mai essere eseguiti fuori dal sandbox. Un deny del team ha la precedenza su qualsiasi allow o ask a livello utente per i comandi corrispondenti, quindi gli utenti non possono escludere comandi che i loro admin hanno bloccato.
Le regole del team e dell’utente vengono risolte insieme: all’interno di ogni origine prevale la regola corrispondente più specifica, e tra origini prevale il verdetto più restrittivo (deny > ask > allow). Esempio: bloccare tutte le esclusioni tranne gh. Un deny wildcard con un’eccezione allow mantiene tutti i comandi all’interno del sandbox tranne gh, indipendentemente da ciò che gli utenti configurano localmente. Questi valori vanno nella configurazione excluded-commands delle impostazioni del team (non nel file di configurazione dell’utente, quindi non c’è alcuna chiave sandbox esterna):
Poiché la regola più specifica Exec(gh *) prevale sul wildcard Exec(**), i comandi gh vengono eseguiti fuori dal sandbox, mentre tutto il resto rimane all’interno — e il deny wildcard a livello di team prevale su qualsiasi regola allow o ask a livello di singolo utente per gli altri comandi.

​
Approfondimenti