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.
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.
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.
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.
| Opzione | Tipo | Predefinito | Descrizione |
|---|
allowed_domains | string[] | [] | Pattern di dominio consentiti tramite il proxy. Se non è vuoto, sono consentiti solo i domini corrispondenti (modalità allowlist) |
denied_domains | string[] | [] | Pattern di dominio sempre bloccati. Le regole deny hanno la precedenza sulle regole di autorizzazione |
network_mode | string | "full" | "full" consente tutti i metodi HTTP; "limited" consente solo GET/HEAD/OPTIONS |
| Pattern | Corrisponde a |
|---|
example.com | Solo corrispondenza esatta |
*.example.com | Qualsiasi sottodominio (non il dominio principale) |
**.example.com | Dominio principale e qualsiasi sottodominio |
{
"sandbox": {
"allowed_domains": [
"github.com",
"**.npmjs.org",
"**.crates.io",
"**.pypi.org"
],
"denied_domains": ["evil.example.com"],
"network_mode": "full"
}
}
Il filtraggio dei domini si applica quando la sandbox è attiva (--sandbox). Senza --sandbox, la sezione relativa alla sandbox viene ignorata.
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:
| Opzione | Tipo | Descrizione |
|---|
excluded.allow | string[] | I comandi corrispondenti vengono eseguiti automaticamente al di fuori della sandbox |
excluded.ask | string[] | I comandi corrispondenti vengono eseguiti al di fuori della sandbox dopo l’approvazione dell’utente |
excluded.deny | string[] | I comandi corrispondenti non vengono mai esclusi: restano sempre all’interno della sandbox |
{
"sandbox": {
"excluded": {
"allow": ["Exec(git status *)"],
"ask": ["Exec(git push *)"],
"deny": ["Exec(git tag *)"]
}
}
}
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
Modalità di applicazione della sandbox
--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
- 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:
| Scenario | Configurazione Enterprise | Configurazione utente | Risultato effettivo |
|---|
| L’amministratore imposta un’allowlist | allowed_domains: ["github.com"] | allowed_domains: ["npmjs.org"] | È consentito solo github.com (Enterprise sostituisce l’elenco dell’utente) |
| L’amministratore imposta una denylist | denied_domains: ["evil.com"] | denied_domains: ["risky.io"] | Sia evil.com sia risky.io sono bloccati (uniti) |
| Nessuna allowlist impostata dall’amministratore | allowed_domains: [] | allowed_domains: ["github.com"] | Viene usata l’allowlist 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
- 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):
{
"excluded": {
"deny": ["Exec(**)"],
"allow": ["Exec(gh *)"]
}
}
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.
