SpyBara
Go Premium

sandboxing.md 2026-05-02 18:14 UTC to 2026-05-04 22:58 UTC

329 added, 0 removed.

2026
Sun 31 06:39 Sat 30 06:23 Fri 29 06:38 Thu 28 06:37 Wed 27 06:42 Tue 26 06:33 Sun 24 06:25 Sat 23 06:18 Fri 22 06:33 Thu 21 06:36 Wed 20 06:35 Tue 19 06:34 Mon 18 23:59 Sun 17 01:01 Fri 15 22:58 Thu 14 17:02 Wed 13 23:01 Tue 12 22:57 Mon 11 23:00 Sun 10 23:03 Sat 9 04:57 Fri 8 22:00 Thu 7 22:59 Tue 5 23:00 Mon 4 22:58 Sat 2 18:14 Fri 1 18:19

Sandboxing

Scopri come lo strumento bash in sandbox di Claude Code fornisce isolamento del filesystem e della rete per un'esecuzione dell'agente più sicura e autonoma.

Panoramica

Claude Code include il sandboxing nativo per fornire un ambiente più sicuro per l'esecuzione dell'agente, riducendo la necessità di prompt di autorizzazione costanti. Invece di chiedere autorizzazione per ogni comando bash, il sandboxing crea confini definiti in anticipo dove Claude Code può lavorare più liberamente con rischio ridotto.

Lo strumento bash in sandbox utilizza primitive a livello del sistema operativo per applicare sia l'isolamento del filesystem che della rete.

Perché il sandboxing è importante

La sicurezza tradizionale basata su autorizzazioni richiede l'approvazione costante dell'utente per i comandi bash. Sebbene questo fornisca controllo, può portare a:

  • Affaticamento da approvazione: Fare clic ripetutamente su "approva" può causare agli utenti di prestare meno attenzione a ciò che stanno approvando
  • Produttività ridotta: Le interruzioni costanti rallentano i flussi di lavoro di sviluppo
  • Autonomia limitata: Claude Code non può lavorare in modo efficiente quando è in attesa di approvazioni

Il sandboxing affronta queste sfide:

  1. Definendo confini chiari: Specifica esattamente quali directory e host di rete Claude Code può accedere
  2. Riducendo i prompt di autorizzazione: I comandi sicuri all'interno della sandbox non richiedono approvazione
  3. Mantenendo la sicurezza: I tentativi di accedere a risorse al di fuori della sandbox attivano notifiche immediate
  4. Abilitando l'autonomia: Claude Code può funzionare più indipendentemente entro limiti definiti

Come funziona

Isolamento del filesystem

Lo strumento bash in sandbox limita l'accesso al file system a directory specifiche:

  • Comportamento di scrittura predefinito: Accesso in lettura e scrittura alla directory di lavoro corrente e alle sue sottodirectory
  • Comportamento di lettura predefinito: Accesso in lettura all'intero computer, ad eccezione di determinate directory negate
  • Accesso bloccato: Non è possibile modificare file al di fuori della directory di lavoro corrente senza autorizzazione esplicita
  • Configurabile: Definisci percorsi consentiti e negati personalizzati tramite le impostazioni

È possibile concedere l'accesso in scrittura a percorsi aggiuntivi utilizzando sandbox.filesystem.allowWrite nelle impostazioni. Queste restrizioni sono applicate a livello del sistema operativo (Seatbelt su macOS, bubblewrap su Linux), quindi si applicano a tutti i comandi dei sottoprocessi, inclusi strumenti come kubectl, terraform e npm, non solo agli strumenti di file di Claude.

Isolamento della rete

L'accesso alla rete è controllato tramite un server proxy in esecuzione al di fuori della sandbox:

  • Restrizioni di dominio: Solo i domini approvati possono essere accessibili
  • Conferma dell'utente: Le nuove richieste di dominio attivano prompt di autorizzazione (a meno che allowManagedDomainsOnly non sia abilitato, che blocca automaticamente i domini non consentiti)
  • Supporto proxy personalizzato: Gli utenti avanzati possono implementare regole personalizzate sul traffico in uscita
  • Copertura completa: Le restrizioni si applicano a tutti gli script, programmi e sottoprocessi generati dai comandi

Applicazione a livello del sistema operativo

Lo strumento bash in sandbox sfrutta le primitive di sicurezza del sistema operativo:

  • macOS: Utilizza Seatbelt per l'applicazione della sandbox
  • Linux: Utilizza bubblewrap per l'isolamento
  • WSL2: Utilizza bubblewrap, come Linux

WSL1 non è supportato perché bubblewrap richiede funzionalità del kernel disponibili solo in WSL2.

Queste restrizioni a livello del sistema operativo assicurano che tutti i processi figlio generati dai comandi di Claude Code ereditino gli stessi confini di sicurezza.

Iniziare

Prerequisiti

Su macOS, il sandboxing funziona subito utilizzando il framework Seatbelt integrato.

Su Linux e WSL2, installa prima i pacchetti richiesti:

sudo apt-get install bubblewrap socat

WSL1 non supporta il sandboxing perché manca dei primitivi dello spazio dei nomi Linux richiesti. Se vedi Sandboxing requires WSL2, aggiorna la tua distribuzione a WSL2 o esegui Claude Code senza sandboxing.

Su WSL2, i comandi sandboxati non possono avviare binari Windows come cmd.exe, powershell.exe, o qualsiasi cosa sotto /mnt/c/. WSL li passa all'host Windows su un socket Unix, che la sandbox blocca. Se un comando ha bisogno di invocare un binario Windows, aggiungilo a excludedCommands in modo che venga eseguito al di fuori della sandbox.

Abilita il sandboxing

È possibile abilitare il sandboxing eseguendo il comando /sandbox:

/sandbox

Questo apre un menu in cui è possibile scegliere tra le modalità sandbox. Se le dipendenze richieste sono mancanti (come bubblewrap o socat su Linux), il menu visualizza le istruzioni di installazione per la piattaforma.

Per impostazione predefinita, se la sandbox non può avviarsi (dipendenze mancanti o piattaforma non supportata), Claude Code mostra un avviso ed esegue i comandi senza sandboxing. Per rendere questo un errore grave, imposta sandbox.failIfUnavailable su true. Questo è destinato a distribuzioni gestite che richiedono il sandboxing come gate di sicurezza.

Modalità sandbox

Claude Code offre due modalità sandbox:

Modalità auto-allow: I comandi Bash tenteranno di eseguire all'interno della sandbox e sono automaticamente consentiti senza richiedere autorizzazione. I comandi che non possono essere sandboxati (come quelli che necessitano di accesso alla rete a host non consentiti) ricadono nel flusso di autorizzazione regolare. Le regole di negazione esplicita sono sempre rispettate, e i comandi rm o rmdir che puntano a /, alla tua directory home o ad altri percorsi critici del sistema attivano comunque una richiesta di autorizzazione. Le regole Ask si applicano solo ai comandi che ricadono nel flusso di autorizzazione regolare.

Modalità autorizzazioni regolari: Tutti i comandi bash passano attraverso il flusso di autorizzazione standard, anche quando sandboxati. Questo fornisce più controllo ma richiede più approvazioni.

In entrambe le modalità, la sandbox applica le stesse restrizioni di filesystem e rete. La differenza è solo se i comandi sandboxati sono auto-approvati o richiedono autorizzazione esplicita.

Configura il sandboxing

Personalizza il comportamento della sandbox tramite il file settings.json. Vedi Settings per il riferimento di configurazione completo.

Concessione dell'accesso in scrittura dei sottoprocessi a percorsi specifici

Per impostazione predefinita, i comandi sandboxati possono scrivere solo nella directory di lavoro corrente. Se i comandi dei sottoprocessi come kubectl, terraform o npm devono scrivere al di fuori della directory del progetto, utilizza sandbox.filesystem.allowWrite per concedere l'accesso a percorsi specifici:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

Questi percorsi sono applicati a livello del sistema operativo, quindi tutti i comandi in esecuzione all'interno della sandbox, inclusi i loro processi figlio, li rispettano. Questo è l'approccio consigliato quando uno strumento ha bisogno di accesso in scrittura a una posizione specifica, piuttosto che escludere completamente lo strumento dalla sandbox con excludedCommands.

Quando allowWrite (o denyWrite/denyRead/allowRead) è definito in più ambiti di impostazioni, gli array sono uniti, il che significa che i percorsi da ogni ambito sono combinati, non sostituiti. Ad esempio, se le impostazioni gestite consentono scritture in /opt/company-tools e un utente aggiunge ~/.kube nelle sue impostazioni personali, entrambi i percorsi sono inclusi nella configurazione finale della sandbox. Ciò significa che gli utenti e i progetti possono estendere l'elenco senza duplicare o sovrascrivere i percorsi impostati da ambiti con priorità più alta.

I prefissi di percorso controllano come i percorsi vengono risolti:

Prefisso Significato Esempio
/ Percorso assoluto dalla radice del filesystem /tmp/build rimane /tmp/build
~/ Relativo alla directory home ~/.kube diventa $HOME/.kube
./ o nessun prefisso Relativo alla radice del progetto per le impostazioni del progetto, o a ~/.claude per le impostazioni dell'utente ./output in .claude/settings.json si risolve in <project-root>/output

Il prefisso precedente //path per i percorsi assoluti funziona ancora. Se in precedenza hai utilizzato /path aspettandoti una risoluzione relativa al progetto, passa a ./path. Questa sintassi differisce dalle regole di autorizzazione Read e Edit, che utilizzano //path per assoluto e /path per relativo al progetto. I percorsi del filesystem della sandbox utilizzano convenzioni standard: /tmp/build è un percorso assoluto.

È inoltre possibile negare l'accesso in scrittura o lettura utilizzando sandbox.filesystem.denyWrite e sandbox.filesystem.denyRead. Questi vengono uniti con qualsiasi percorso dalle regole di autorizzazione Edit(...) e Read(...). Per ri-consentire la lettura di percorsi specifici all'interno di una regione negata, utilizza sandbox.filesystem.allowRead, che ha la precedenza su denyRead. Quando allowManagedReadPathsOnly è abilitato nelle impostazioni gestite, solo le voci allowRead gestite sono rispettate; le voci allowRead dell'utente, del progetto e locali vengono ignorate. denyRead continua a unirsi da tutte le fonti.

Ad esempio, per bloccare la lettura dall'intera directory home consentendo comunque letture dal progetto corrente, aggiungi questo al .claude/settings.json del tuo progetto:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

Il . in allowRead si risolve nella radice del progetto perché questa configurazione si trova nelle impostazioni del progetto. Se hai posizionato la stessa configurazione in ~/.claude/settings.json, . si risolverebbe in ~/.claude invece, e i file del progetto rimarrebbero bloccati dalla regola denyRead.

Vantaggi della sicurezza

Protezione contro l'iniezione di prompt

Anche se un attaccante manipola con successo il comportamento di Claude Code attraverso l'iniezione di prompt, la sandbox assicura che il sistema rimanga sicuro:

Protezione del filesystem:

  • Non è possibile modificare file di configurazione critici come ~/.bashrc
  • Non è possibile modificare file a livello di sistema in /bin/
  • Non è possibile leggere file che sono negati nelle impostazioni di autorizzazione di Claude

Protezione della rete:

  • Non è possibile esfiltare dati a server controllati dall'attaccante
  • Non è possibile scaricare script dannosi da domini non autorizzati
  • Non è possibile effettuare chiamate API inaspettate a servizi non approvati
  • Non è possibile contattare alcun dominio non esplicitamente consentito

Monitoraggio e controllo:

  • Tutti i tentativi di accesso al di fuori della sandbox sono bloccati a livello del sistema operativo
  • Ricevi notifiche immediate quando i confini vengono testati
  • È possibile scegliere di negare, consentire una volta o aggiornare permanentemente la configurazione

Superficie di attacco ridotta

Il sandboxing limita il danno potenziale da:

  • Dipendenze dannose: Pacchetti NPM o altre dipendenze con codice dannoso
  • Script compromessi: Script di compilazione o strumenti con vulnerabilità di sicurezza
  • Ingegneria sociale: Attacchi che ingannano gli utenti nel far eseguire comandi pericolosi
  • Iniezione di prompt: Attacchi che ingannano Claude nel far eseguire comandi pericolosi

Funzionamento trasparente

Quando Claude Code tenta di accedere a risorse di rete al di fuori della sandbox:

  1. L'operazione viene bloccata a livello del sistema operativo
  2. Ricevi una notifica immediata
  3. È possibile scegliere di:
    • Negare la richiesta
    • Consentirla una volta
    • Aggiornare la configurazione della sandbox per consentirla permanentemente

Limitazioni della sicurezza

  • Limitazioni del sandboxing della rete: Il sistema di filtraggio della rete funziona limitando i domini a cui i processi possono connettersi. Non ispeziona altrimenti il traffico che passa attraverso il proxy e gli utenti sono responsabili di assicurarsi che consentano solo domini affidabili nella loro politica.
  • Escalation dei privilegi tramite Unix Sockets: La configurazione allowUnixSockets può inavvertitamente concedere l'accesso a potenti servizi di sistema che potrebbero portare a bypass della sandbox. Ad esempio, se viene utilizzato per consentire l'accesso a /var/run/docker.sock questo concederebbe effettivamente l'accesso al sistema host sfruttando il socket docker. Gli utenti sono incoraggiati a considerare attentamente qualsiasi socket unix che consentono attraverso la sandbox.
  • Escalation dei permessi del filesystem: I permessi di scrittura del filesystem eccessivamente ampi possono abilitare attacchi di escalation dei privilegi. Consentire scritture a directory contenenti eseguibili in $PATH, directory di configurazione di sistema o file di configurazione della shell dell'utente (.bashrc, .zshrc) può portare all'esecuzione di codice in diversi contesti di sicurezza quando altri utenti o processi di sistema accedono a questi file.
  • Forza della sandbox Linux: L'implementazione Linux fornisce un forte isolamento del filesystem e della rete ma include una modalità enableWeakerNestedSandbox che le consente di funzionare all'interno di ambienti Docker senza namespace privilegiati. Questa opzione indebolisce considerevolmente la sicurezza e dovrebbe essere utilizzata solo nei casi in cui l'isolamento aggiuntivo è altrimenti applicato.

Come il sandboxing si relaziona alle autorizzazioni

Il sandboxing e le autorizzazioni sono livelli di sicurezza complementari che funzionano insieme:

  • Autorizzazioni controllano quali strumenti Claude Code può utilizzare e vengono valutate prima che qualsiasi strumento venga eseguito. Si applicano a tutti gli strumenti: Bash, Read, Edit, WebFetch, MCP e altri.
  • Sandboxing fornisce l'applicazione a livello del sistema operativo che limita ciò che i comandi Bash possono accedere a livello di filesystem e rete. Si applica solo ai comandi Bash e ai loro processi figlio.

Le restrizioni di filesystem e rete sono configurate sia tramite le impostazioni della sandbox che le regole di autorizzazione:

  • Utilizza sandbox.filesystem.allowWrite per concedere l'accesso in scrittura dei sottoprocessi a percorsi al di fuori della directory di lavoro
  • Utilizza sandbox.filesystem.denyWrite e sandbox.filesystem.denyRead per bloccare l'accesso dei sottoprocessi a percorsi specifici
  • Utilizza sandbox.filesystem.allowRead per ri-consentire la lettura di percorsi specifici all'interno di una regione denyRead
  • Utilizza le regole di negazione Read e Edit per bloccare l'accesso a file o directory specifici
  • Utilizza le regole di consentimento/negazione WebFetch per controllare l'accesso al dominio
  • Utilizza la sandbox allowedDomains per controllare quali domini i comandi Bash possono raggiungere
  • Utilizza la sandbox deniedDomains per bloccare domini specifici anche quando un wildcard allowedDomains più ampio altrimenti li permetterebbe

I percorsi dalle impostazioni sandbox.filesystem e dalle regole di autorizzazione vengono uniti insieme nella configurazione finale della sandbox.

Questo repository include configurazioni di impostazioni iniziali per scenari di distribuzione comuni, inclusi esempi specifici della sandbox. Utilizzali come punti di partenza e adattali alle tue esigenze.

Utilizzo avanzato

Configurazione proxy personalizzata

Per le organizzazioni che richiedono una sicurezza di rete avanzata, è possibile implementare un proxy personalizzato per:

  • Decrittare e ispezionare il traffico HTTPS
  • Applicare regole di filtraggio personalizzate
  • Registrare tutte le richieste di rete
  • Integrarsi con l'infrastruttura di sicurezza esistente
{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

Integrazione con gli strumenti di sicurezza esistenti

Lo strumento bash in sandbox funziona insieme a:

Best practice

  1. Inizia restrittivo: Inizia con autorizzazioni minime e espandi secondo le necessità
  2. Monitora i log: Rivedi i tentativi di violazione della sandbox per comprendere le esigenze di Claude Code
  3. Utilizza configurazioni specifiche dell'ambiente: Diverse regole sandbox per contesti di sviluppo rispetto a produzione
  4. Combina con autorizzazioni: Utilizza il sandboxing insieme alle politiche IAM per una sicurezza completa
  5. Testa le configurazioni: Verifica che le impostazioni della sandbox non blocchino i flussi di lavoro legittimi

Open source

Il runtime della sandbox è disponibile come pacchetto npm open source per l'uso nei tuoi progetti di agente. Ciò consente alla comunità più ampia degli agenti AI di costruire sistemi autonomi più sicuri. Questo può anche essere utilizzato per sandboxare altri programmi che potresti desiderare di eseguire. Ad esempio, per sandboxare un server MCP potresti eseguire:

npx @anthropic-ai/sandbox-runtime <command-to-sandbox>

Per i dettagli di implementazione e il codice sorgente, visita il repository GitHub.

Limitazioni

  • Overhead di prestazioni: Minimo, ma alcune operazioni del filesystem potrebbero essere leggermente più lente
  • Compatibilità: Alcuni strumenti che richiedono modelli di accesso al sistema specifici potrebbero necessitare di regolazioni di configurazione, o potrebbero anche dover essere eseguiti al di fuori della sandbox
  • Supporto della piattaforma: Supporta macOS, Linux e WSL2. WSL1 non è supportato. Il supporto nativo di Windows è pianificato.

Cosa il sandboxing non copre

La sandbox isola i sottoprocessi Bash. Altri strumenti operano sotto confini diversi:

  • Strumenti di file integrati: Read, Edit e Write utilizzano il sistema di autorizzazione direttamente piuttosto che eseguire attraverso la sandbox. Vedi autorizzazioni.
  • Utilizzo del computer: quando Claude apre app e controlla lo schermo, viene eseguito sul tuo desktop effettivo piuttosto che in un ambiente isolato. I prompt di autorizzazione per app gating ogni applicazione. Vedi utilizzo del computer nella CLI o utilizzo del computer in Desktop.

Vedi anche

  • Security - Funzionalità di sicurezza complete e best practice
  • Permissions - Configurazione delle autorizzazioni e controllo dell'accesso
  • Settings - Riferimento di configurazione completo
  • CLI reference - Opzioni della riga di comando