Pular para o conteúdo principal

​
Visão Geral

Claude Code apresenta isolamento nativo em sandbox para fornecer um ambiente mais seguro para execução de agentes, reduzindo a necessidade de solicitações constantes de permissão. Em vez de pedir permissão para cada comando bash, o sandbox 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 isolamento em sandbox é 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 os fluxos de trabalho de desenvolvimento
  • Autonomia limitada: Claude Code não pode trabalhar com eficiência quando aguarda aprovações
O isolamento em sandbox aborda esses desafios por:
  1. Definir limites claros: Especifique exatamente quais diretórios e hosts de rede Claude Code pode acessar
  2. Reduzir solicitações 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. Permitir autonomia: Claude Code pode ser executado de forma mais independente dentro de limites definidos
O isolamento eficaz em sandbox requer ambos isolamento de sistema de arquivos e 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 isolamento em sandbox, é 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

​
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 solicitações de permissão
  • 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 de nível do SO

A ferramenta bash em sandbox aproveita primitivos de segurança do sistema operacional:
  • Linux: Usa bubblewrap para isolamento
  • macOS: Usa Seatbelt para imposição de sandbox
Essas restrições de nível do SO garantem que todos os processos filhos gerados pelos comandos de Claude Code herdem os mesmos limites de segurança.

​
Começando

​
Ativar isolamento em sandbox

Você pode ativar o isolamento em sandbox executando o comando de barra /sandbox: 
> /sandbox
Isso ativa a ferramenta bash em sandbox com configurações padrão, permitindo acesso ao seu diretório de trabalho atual enquanto bloqueia o acesso a locais sensíveis do sistema.

​
Configurar isolamento em sandbox

Personalize o comportamento do sandbox através do seu arquivo settings.json. Consulte Configurações para referência de configuração completa.
Nem todos os comandos são compatíveis com isolamento em sandbox 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 de 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 de sandbox.Você pode desabilitar este mecanismo de escape 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 de 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 de 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 entrar em contato com 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 isolamento em sandbox 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 Isolamento de Rede: O sistema de filtragem de rede funciona restringindo os domínios aos quais os processos podem se conectar. Ele não inspeciona 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 podem 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 permitir 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 à 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.

​
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 de 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 isolamento em sandbox 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 de 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 fazer sandbox de outros programas que você possa desejar executar. Por exemplo, para fazer sandbox de um servidor MCP, 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

  • Sobrecarga de desempenho: Mínima, 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: Atualmente suporta Linux e macOS; suporte para Windows planejado

​
Veja também

  • Segurança - Recursos de segurança abrangentes e melhores práticas
  • IAM - Configuração de permissão e controle de acesso
  • Configurações - Referência de configuração completa
  • Referência CLI - Opções de linha de comando incluindo -sb