Pular para o conteúdo principal

​
Visão geral

Claude Code apresenta sandboxing nativo para fornecer um ambiente mais seguro para execução de agentes, reduzindo a necessidade de prompts de permissão constantes. Em vez de pedir permissão para cada comando bash, o sandboxing cria limites definidos antecipadamente onde Claude Code pode trabalhar com mais liberdade e risco reduzido. A ferramenta bash em sandbox usa primitivos de nível do SO para impor isolamento tanto de sistema de arquivos quanto de rede.

​
Por que o sandboxing é importante

A segurança tradicional baseada em permissões requer aprovação constante do usuário para comandos bash. Embora isso forneça controle, pode levar a:
  • Fadiga de aprovação: Clicar repetidamente em “aprovar” pode fazer com que os usuários prestem menos atenção ao que estão aprovando
  • Produtividade reduzida: Interrupções constantes desaceleram fluxos de trabalho de desenvolvimento
  • Autonomia limitada: Claude Code não pode trabalhar com eficiência quando aguarda aprovações
O sandboxing aborda esses desafios ao:
  1. Definir limites claros: Especificar exatamente quais diretórios e hosts de rede Claude Code pode acessar
  2. Reduzir prompts de permissão: Comandos seguros dentro do sandbox não requerem aprovação
  3. Manter a segurança: Tentativas de acessar recursos fora do sandbox acionam notificações imediatas
  4. Habilitar autonomia: Claude Code pode ser executado de forma mais independente dentro de limites definidos
O sandboxing eficaz requer isolamento tanto de sistema de arquivos quanto de rede. Sem isolamento de rede, um agente comprometido poderia exfiltrar arquivos sensíveis como chaves SSH. Sem isolamento de sistema de arquivos, um agente comprometido poderia fazer backdoor de recursos do sistema para obter acesso à rede. Ao configurar o sandboxing, é importante garantir que suas configurações não criem bypasses nesses sistemas.

​
Como funciona

​
Isolamento de sistema de arquivos

A ferramenta bash em sandbox restringe o acesso ao sistema de arquivos a diretórios específicos:
  • Comportamento padrão de escrita: Acesso de leitura e escrita ao diretório de trabalho atual e seus subdiretórios
  • Comportamento padrão de leitura: Acesso de leitura a todo o computador, exceto certos diretórios negados
  • Acesso bloqueado: Não é possível modificar arquivos fora do diretório de trabalho atual sem permissão explícita
  • Configurável: Defina caminhos permitidos e negados personalizados através de configurações
Você pode conceder acesso de escrita a caminhos adicionais usando sandbox.filesystem.allowWrite em suas configurações. Essas restrições são impostas no nível do SO (Seatbelt no macOS, bubblewrap no Linux), portanto se aplicam a todos os comandos de subprocesso, incluindo ferramentas como kubectl, terraform e npm, não apenas às ferramentas de arquivo do Claude.

​
Isolamento de rede

O acesso à rede é controlado através de um servidor proxy executado fora do sandbox:
  • Restrições de domínio: Apenas domínios aprovados podem ser acessados
  • Confirmação do usuário: Novas solicitações de domínio acionam prompts de permissão (a menos que allowManagedDomainsOnly esteja habilitado, que bloqueia domínios não permitidos automaticamente)
  • Suporte a proxy personalizado: Usuários avançados podem implementar regras personalizadas no tráfego de saída
  • Cobertura abrangente: As restrições se aplicam a todos os scripts, programas e subprocessos gerados por comandos

​
Imposição no nível do SO

A ferramenta bash em sandbox aproveita primitivos de segurança do sistema operacional:
  • macOS: Usa Seatbelt para imposição de sandbox
  • Linux: Usa bubblewrap para isolamento
  • WSL2: Usa bubblewrap, igual ao Linux
WSL1 não é suportado porque bubblewrap requer recursos de kernel disponíveis apenas no WSL2. Essas restrições no nível do SO garantem que todos os processos filhos gerados pelos comandos do Claude Code herdem os mesmos limites de segurança.

​
Começando

​
Pré-requisitos

No macOS, o sandboxing funciona imediatamente usando o framework Seatbelt integrado. No Linux e WSL2, instale primeiro os pacotes necessários: 
sudo apt-get install bubblewrap socat

​
Habilitar sandboxing

Você pode habilitar o sandboxing executando o comando /sandbox: 
/sandbox
Isso abre um menu onde você pode escolher entre modos de sandbox. Se as dependências necessárias estiverem faltando (como bubblewrap ou socat no Linux), o menu exibe instruções de instalação para sua plataforma.

​
Modos de sandbox

Claude Code oferece dois modos de sandbox: Modo de permissão automática: Comandos bash tentarão ser executados dentro do sandbox e são automaticamente permitidos sem exigir permissão. Comandos que não podem ser colocados em sandbox (como aqueles que precisam de acesso à rede para hosts não permitidos) voltam ao fluxo de permissão regular. Regras explícitas de ask/deny que você configurou são sempre respeitadas. Modo de permissões regular: Todos os comandos bash passam pelo fluxo de permissão padrão, mesmo quando em sandbox. Isso fornece mais controle, mas requer mais aprovações. Em ambos os modos, o sandbox impõe as mesmas restrições de sistema de arquivos e rede. A diferença é apenas se os comandos em sandbox são aprovados automaticamente ou requerem permissão explícita.
O modo de permissão automática funciona independentemente de sua configuração de modo de permissão. Mesmo que você não esteja no modo “aceitar edições”, comandos bash em sandbox serão executados automaticamente quando a permissão automática estiver habilitada. Isso significa que comandos bash que modificam arquivos dentro dos limites do sandbox serão executados sem avisar, mesmo quando ferramentas de edição de arquivo normalmente exigiriam aprovação.

​
Configurar sandboxing

Personalize o comportamento do sandbox através de seu arquivo settings.json. Veja Settings para referência de configuração completa.

​
Concedendo acesso de escrita de subprocesso a caminhos específicos

Por padrão, comandos em sandbox podem apenas escrever no diretório de trabalho atual. Se comandos de subprocesso como kubectl, terraform ou npm precisarem escrever fora do diretório do projeto, use sandbox.filesystem.allowWrite para conceder acesso a caminhos específicos: 
{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}
Esses caminhos são impostos no nível do SO, portanto todos os comandos executados dentro do sandbox, incluindo seus processos filhos, os respeitam. Esta é a abordagem recomendada quando uma ferramenta precisa de acesso de escrita a um local específico, em vez de excluir a ferramenta do sandbox inteiramente com excludedCommands. Quando allowWrite (ou denyWrite/denyRead/allowRead) é definido em múltiplos escopos de configurações, os arrays são mesclados, significando que caminhos de cada escopo são combinados, não substituídos. Por exemplo, se as configurações gerenciadas permitem escritas em /opt/company-tools e um usuário adiciona ~/.kube em suas configurações pessoais, ambos os caminhos são incluídos na configuração final do sandbox. Isso significa que usuários e projetos podem estender a lista sem duplicar ou sobrescrever caminhos definidos por escopos de prioridade mais alta. Prefixos de caminho controlam como os caminhos são resolvidos:
PrefixoSignificadoExemplo
/Caminho absoluto da raiz do sistema de arquivos/tmp/build permanece /tmp/build
~/Relativo ao diretório home~/.kube torna-se $HOME/.kube
./ ou sem prefixoRelativo à raiz do projeto para configurações de projeto, ou a ~/.claude para configurações de usuário./output em .claude/settings.json resolve para <project-root>/output
O prefixo anterior //path para caminhos absolutos ainda funciona. Se você usou anteriormente /path esperando resolução relativa ao projeto, mude para ./path. Esta sintaxe difere das regras de permissão Read e Edit, que usam //path para absoluto e /path para relativo ao projeto. Os caminhos do sistema de arquivos do sandbox usam convenções padrão: /tmp/build é um caminho absoluto. Você também pode negar acesso de escrita ou leitura usando sandbox.filesystem.denyWrite e sandbox.filesystem.denyRead. Estes são mesclados com quaisquer caminhos das regras de permissão Edit(...) e Read(...). Para permitir novamente a leitura de caminhos específicos dentro de uma região negada, use sandbox.filesystem.allowRead, que tem precedência sobre denyRead. Quando allowManagedReadPathsOnly está habilitado em configurações gerenciadas, apenas entradas allowRead gerenciadas são respeitadas; entradas allowRead de usuário, projeto e local são ignoradas. Por exemplo, para bloquear a leitura de todo o diretório home enquanto ainda permite leituras do projeto atual, adicione isto ao .claude/settings.json do seu projeto: 
{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}
O . em allowRead resolve para a raiz do projeto porque esta configuração reside em configurações de projeto. Se você colocasse a mesma configuração em ~/.claude/settings.json, . resolveria para ~/.claude em vez disso, e arquivos do projeto permaneceriam bloqueados pela regra denyRead.
Nem todos os comandos são compatíveis com sandboxing imediatamente. Algumas notas que podem ajudá-lo a aproveitar ao máximo o sandbox:
  • Muitas ferramentas CLI requerem acesso a certos hosts. Conforme você usa essas ferramentas, elas solicitarão permissão para acessar certos hosts. Conceder permissão permitirá que elas acessem esses hosts agora e no futuro, permitindo que sejam executadas com segurança dentro do sandbox.
  • watchman é incompatível com execução no sandbox. Se você estiver executando jest, considere usar jest --no-watchman
  • docker é incompatível com execução no sandbox. Considere especificar docker em excludedCommands para forçá-lo a ser executado fora do sandbox.
Claude Code inclui um mecanismo de escape intencional que permite que comandos sejam executados fora do sandbox quando necessário. Quando um comando falha devido a restrições de sandbox (como problemas de conectividade de rede ou ferramentas incompatíveis), Claude é solicitado a analisar a falha e pode tentar novamente o comando com o parâmetro dangerouslyDisableSandbox. Comandos que usam este parâmetro passam pelo fluxo de permissões normal do Claude Code, exigindo permissão do usuário para executar. Isso permite que Claude Code lide com casos extremos onde certas ferramentas ou operações de rede não podem funcionar dentro das restrições do sandbox.Você pode desabilitar este escape hatch definindo "allowUnsandboxedCommands": false em suas configurações de sandbox. Quando desabilitado, o parâmetro dangerouslyDisableSandbox é completamente ignorado e todos os comandos devem ser executados em sandbox ou estar explicitamente listados em excludedCommands.

​
Benefícios de segurança

​
Proteção contra injeção de prompt

Mesmo que um atacante manipule com sucesso o comportamento do Claude Code através de injeção de prompt, o sandbox garante que seu sistema permaneça seguro: Proteção de sistema de arquivos:
  • Não é possível modificar arquivos de configuração críticos como ~/.bashrc
  • Não é possível modificar arquivos no nível do sistema em /bin/
  • Não é possível ler arquivos que são negados em suas configurações de permissão do Claude
Proteção de rede:
  • Não é possível exfiltrar dados para servidores controlados por atacantes
  • Não é possível baixar scripts maliciosos de domínios não autorizados
  • Não é possível fazer chamadas de API inesperadas para serviços não aprovados
  • Não é possível contatar nenhum domínio não explicitamente permitido
Monitoramento e controle:
  • Todas as tentativas de acesso fora do sandbox são bloqueadas no nível do SO
  • Você recebe notificações imediatas quando os limites são testados
  • Você pode escolher negar, permitir uma vez ou atualizar permanentemente sua configuração

​
Superfície de ataque reduzida

O sandboxing limita o dano potencial de:
  • Dependências maliciosas: Pacotes NPM ou outras dependências com código prejudicial
  • Scripts comprometidos: Scripts de compilação ou ferramentas com vulnerabilidades de segurança
  • Engenharia social: Ataques que enganam usuários para executar comandos perigosos
  • Injeção de prompt: Ataques que enganam Claude para executar comandos perigosos

​
Operação transparente

Quando Claude Code tenta acessar recursos de rede fora do sandbox:
  1. A operação é bloqueada no nível do SO
  2. Você recebe uma notificação imediata
  3. Você pode escolher:
    • Negar a solicitação
    • Permitir uma vez
    • Atualizar sua configuração de sandbox para permitir permanentemente

​
Limitações de segurança

  • Limitações de Sandboxing de rede: O sistema de filtragem de rede funciona restringindo os domínios aos quais os processos podem se conectar. Ele não inspeciona de outra forma o tráfego passando pelo proxy e os usuários são responsáveis por garantir que apenas permitam domínios confiáveis em sua política.
Os usuários devem estar cientes dos riscos potenciais que vêm de permitir domínios amplos como github.com que podem permitir exfiltração de dados. Além disso, em alguns casos pode ser possível contornar a filtragem de rede através de domain fronting.
  • Escalação de privilégio via Unix Sockets: A configuração allowUnixSockets pode inadvertidamente conceder acesso a serviços poderosos do sistema que poderiam levar a bypasses de sandbox. Por exemplo, se for usada para permitir acesso a /var/run/docker.sock, isso efetivamente concederia acesso ao sistema host através da exploração do socket docker. Os usuários são encorajados a considerar cuidadosamente quaisquer unix sockets que permitam através do sandbox.
  • Escalação de permissão de sistema de arquivos: Permissões de escrita de sistema de arquivos excessivamente amplas podem habilitar ataques de escalação de privilégio. Permitir escritas em diretórios contendo executáveis em $PATH, diretórios de configuração do sistema ou arquivos de configuração de shell do usuário (.bashrc, .zshrc) pode levar a execução de código em diferentes contextos de segurança quando outros usuários ou processos do sistema acessam esses arquivos.
  • Força do Sandbox Linux: A implementação Linux fornece isolamento forte de sistema de arquivos e rede, mas inclui um modo enableWeakerNestedSandbox que permite que funcione dentro de ambientes Docker sem namespaces privilegiados. Esta opção enfraquece consideravelmente a segurança e deve ser usada apenas em casos onde isolamento adicional é de outra forma imposto.

​
Como o sandboxing se relaciona com permissões

Sandboxing e permissões são camadas de segurança complementares que funcionam juntas:
  • Permissões controlam quais ferramentas Claude Code pode usar e são avaliadas antes de qualquer ferramenta ser executada. Elas se aplicam a todas as ferramentas: Bash, Read, Edit, WebFetch, MCP e outras.
  • Sandboxing fornece imposição no nível do SO que restringe o que comandos Bash podem acessar no nível de sistema de arquivos e rede. Aplica-se apenas a comandos Bash e seus processos filhos.
Restrições de sistema de arquivos e rede são configuradas através de configurações de sandbox e regras de permissão:
  • Use sandbox.filesystem.allowWrite para conceder acesso de escrita de subprocesso a caminhos fora do diretório de trabalho
  • Use sandbox.filesystem.denyWrite e sandbox.filesystem.denyRead para bloquear acesso de subprocesso a caminhos específicos
  • Use sandbox.filesystem.allowRead para permitir novamente a leitura de caminhos específicos dentro de uma região denyRead
  • Use regras de negação Read e Edit para bloquear acesso a arquivos ou diretórios específicos
  • Use regras de permissão/negação WebFetch para controlar acesso a domínios
  • Use allowedDomains de sandbox para controlar quais domínios comandos Bash podem alcançar
Caminhos de ambas as configurações sandbox.filesystem e regras de permissão são mesclados juntos na configuração final do sandbox. Este repositório inclui configurações de configurações iniciais para cenários de implantação comuns, incluindo exemplos específicos de sandbox. Use-os como pontos de partida e ajuste-os para suas necessidades.

​
Uso avançado

​
Configuração de proxy personalizado

Para organizações que exigem segurança de rede avançada, você pode implementar um proxy personalizado para:
  • Descriptografar e inspecionar tráfego HTTPS
  • Aplicar regras de filtragem personalizadas
  • Registrar todas as solicitações de rede
  • Integrar com infraestrutura de segurança existente
{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

​
Integração com ferramentas de segurança existentes

A ferramenta bash em sandbox funciona junto com:

​
Melhores práticas

  1. Comece restritivo: Comece com permissões mínimas e expanda conforme necessário
  2. Monitore logs: Revise tentativas de violação de sandbox para entender as necessidades do Claude Code
  3. Use configurações específicas do ambiente: Diferentes regras de sandbox para contextos de desenvolvimento vs. produção
  4. Combine com permissões: Use sandboxing junto com políticas IAM para segurança abrangente
  5. Teste configurações: Verifique se suas configurações de sandbox não bloqueiam fluxos de trabalho legítimos

​
Código aberto

O runtime do sandbox está disponível como um pacote npm de código aberto para uso em seus próprios projetos de agentes. Isso permite que a comunidade mais ampla de agentes de IA construa sistemas autônomos mais seguros e protegidos. Isso também pode ser usado para colocar em sandbox outros programas que você possa desejar executar. Por exemplo, para colocar um servidor MCP em sandbox, você poderia executar: 
npx @anthropic-ai/sandbox-runtime <command-to-sandbox>
Para detalhes de implementação e código-fonte, visite o repositório GitHub.

​
Limitações

  • Overhead de desempenho: Mínimo, mas algumas operações de sistema de arquivos podem ser ligeiramente mais lentas
  • Compatibilidade: Algumas ferramentas que requerem padrões de acesso específicos do sistema podem precisar de ajustes de configuração, ou podem até precisar ser executadas fora do sandbox
  • Suporte de plataforma: Suporta macOS, Linux e WSL2. WSL1 não é suportado. Suporte nativo do Windows está planejado.

​
O que o sandboxing não cobre

O sandbox isola subprocessos Bash. Outras ferramentas operam sob limites diferentes:
  • Ferramentas de arquivo integradas: Read, Edit e Write usam o sistema de permissão diretamente em vez de serem executadas através do sandbox. Veja permissões.
  • Uso de computador no Desktop: quando Claude abre aplicativos e controla sua tela no macOS, ele é executado em seu desktop real em vez de em um ambiente isolado. Prompts de permissão por aplicativo controlam cada aplicativo. Veja uso de computador.

​
Veja também

  • Security - Recursos de segurança abrangentes e melhores práticas
  • Permissions - Configuração de permissão e controle de acesso
  • Settings - Referência de configuração completa
  • CLI reference - Opções de linha de comando