Configurar a ferramenta Bash em sandbox

​

Get started

/sandbox

​

Set up Linux and WSL2

• bubblewrap: a ferramenta de sandboxing sem privilégios que impõe isolamento de sistema de arquivos
• socat: o relay usado para rotear tráfego de rede através do proxy de sandbox

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF

sudo systemctl reload apparmor

​

Sandbox modes

• Deny rules explícitas são sempre respeitadas
• Comandos rm ou rmdir que visam /, seu diretório home ou outros caminhos críticos do sistema ainda acionam um prompt de permissão
• Ask rules com escopo de conteúdo como Bash(git push *) ainda forçam um prompt mesmo para comandos em sandbox
• Uma regra ask Bash simples, ou o formulário equivalente Bash(*), é ignorada para comandos executados em sandbox; ainda se aplica a comandos que voltam ao fluxo de permissão regular

​

Configure sandboxing

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

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

​

Protect credentials

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

​

Como o sandboxing funciona

​

Isolamento do sistema de arquivos

• Comportamento padrão de escrita: acesso de leitura e escrita ao diretório de trabalho atual e seus subdiretórios, além do diretório temporário da sessão para o qual $TMPDIR aponta
• Comportamento padrão de leitura: acesso de leitura a todo o computador, exceto certos diretórios negados. Observe que esse padrão ainda permite ler arquivos de credenciais como ~/.aws/credentials e ~/.ssh/. Use sandbox.credentials para bloquear leituras desses arquivos e desconfigurar variáveis de ambiente secretas, ou adicione os caminhos a denyRead.
• Acesso bloqueado: não é possível modificar arquivos fora do diretório de trabalho atual e do diretório temporário da sessão sem permissão explícita, incluindo arquivos de configuração de shell como ~/.bashrc e binários do sistema em /bin/
• Git worktrees: quando o diretório de trabalho é um git worktree vinculado, o sandbox também permite escritas no diretório .git compartilhado do repositório principal para que comandos como git commit possam atualizar refs e o índice. As escritas em hooks/ e config dentro desse diretório permanecem negadas.
• Configurável: defina caminhos permitidos e negados personalizados através de configurações

​

Isolamento de rede

• Restrições de domínio: nenhum domínio é pré-permitido. Na primeira vez que um comando precisa de um novo domínio, Claude Code solicita aprovação. A partir da v2.1.191, escolher Sim permite o host para o resto da sessão atual, portanto conexões posteriores ao mesmo host não solicitam novamente. Pré-permita domínios com allowedDomains para evitar o prompt inteiramente.
• Managed lockdown: se allowManagedDomainsOnly estiver definido em configurações gerenciadas, domínios não permitidos são bloqueados automaticamente em vez de solicitar, e apenas allowedDomains de configurações gerenciadas são honrados.
• 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

• macOS: usa Seatbelt para imposição de sandbox
• Linux: usa bubblewrap para isolamento
• WSL2: usa bubblewrap, igual ao Linux

​

Como sandboxing se relaciona com permissões e modos de permissão

​

Regras de permissão

• Regras de permissão 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.

​

Modos de permissão

​

Configure the sandbox for your organization

​

Enforce sandboxing with managed settings

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

• failIfUnavailable: uma dependência faltante como bubblewrap no Linux bloqueia Claude Code de iniciar em vez de mostrar um aviso e voltar a execução sem sandbox
• allowUnsandboxedCommands: false: o escape hatch dangerouslyDisableSandbox é ignorado, portanto comandos que falham sob o sandbox não podem ser retentados fora dele

​

Keep developers from widening the policy

​

Custom proxy configuration

• 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
    }
  }
}

​

Troubleshooting

• Comandos falham com um erro host-not-allowed: muitas ferramentas CLI precisam alcançar hosts específicos. Conceder permissão quando solicitado adiciona o host à sua lista de permitidos para que a ferramenta seja executada dentro do sandbox no futuro.
• jest trava ou falha: watchman é incompatível com o sandbox. Execute jest --no-watchman em vez disso.
• CLIs baseadas em Go falham na verificação TLS no macOS: ferramentas como gh, gcloud e terraform podem falhar na verificação TLS sob Seatbelt. Liste essas ferramentas em excludedCommands para executá-las fora do sandbox. Se você estiver usando httpProxyPort com um proxy MITM e CA personalizado, defina enableWeakerNetworkIsolation como true em vez disso.
• open, osascript, ou fluxos de autenticação baseados em navegador falham com erro -600 no macOS: o sandbox bloqueia Apple Events por padrão. Defina allowAppleEvents como true em suas configurações de usuário, gerenciadas ou CLI para permitir. As configurações do projeto são ignoradas para esta chave. Habilitá-lo remove o isolamento de execução de código, pois comandos em sandbox podem então iniciar outras aplicações sem sandbox sem prompt do usuário e enviar comandos AppleScript para aplicações em execução, sujeito ao prompt de consentimento de automação do macOS (TCC). Alternativamente, adicione o comando a excludedCommands para executá-lo fora do sandbox.
• Comandos docker falham: docker é incompatível com o sandbox. Adicione docker * a excludedCommands para executá-lo fora do sandbox.
• Bubblewrap falha ao iniciar dentro de um container: em um container sem privilégios, bubblewrap não consegue montar um sistema de arquivos /proc fresco. Defina enableWeakerNestedSandbox como true para que o sandbox interno faça bind-mount do /proc existente do container em vez disso. Use esta configuração apenas quando o container externo já fornece o limite de isolamento que você precisa, pois expõe informações de processo a comandos em sandbox que uma montagem /proc fresca ocultaria.
• Filtro seccomp no Linux: o filtro seccomp é necessário para bloquear sockets de domínio Unix. A aba Dependencies em /sandbox mostra se está disponível. Se estiver faltando, execute npm install -g @anthropic-ai/sandbox-runtime para instalar o helper.
• --dangerously-skip-permissions falha como root: este sinalizador é bloqueado ao executar como root ou via sudo no Linux e macOS, porque acesso root combinado com nenhum prompt de permissão pode modificar qualquer arquivo ou serviço no sistema. A verificação é ignorada automaticamente dentro de um sandbox reconhecido. Para executar autonomamente em um container, use a configuração dev container, que executa Claude Code como um usuário não-root.

​

Limitações

​

Limitações de segurança

• Filtragem de rede: o sistema de filtragem de rede funciona restringindo os domínios aos quais os processos podem se conectar. O proxy integrado não termina ou realiza inspeção TLS no tráfego de saída, portanto o conteúdo de conexões criptografadas não é examinado. Você é responsável por garantir que apenas domínios confiáveis sejam permitidos em sua política.

• 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, permitir acesso a /var/run/docker.sock efetivamente concede acesso ao sistema host através do socket Docker. Considere cuidadosamente quaisquer Unix sockets que você permita 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 como .bashrc ou .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 o habilita a funcionar dentro de ambientes Docker sem namespaces privilegiados, ou em hosts Linux onde namespaces de usuário sem privilégios são desabilitados por sysctl. Esta opção enfraquece consideravelmente a segurança e deve ser usada apenas quando isolamento adicional é de outra forma imposto.
• Apple Events no macOS: o sandbox macOS bloqueia Apple Events por padrão. A configuração allowAppleEvents remove essa restrição para que ferramentas como open e osascript funcionem, mas remove isolamento de execução de código: comandos em sandbox podem iniciar outras aplicações sem sandbox sem nenhum prompt do usuário, e podem enviar comandos AppleScript para aplicações em execução, sujeito ao prompt de consentimento de automação macOS por aplicativo (TCC). Isso é apenas honrado a partir de configurações de usuário, gerenciadas ou CLI. Configurações de projeto não podem habilitá-lo.
• Arquivos de configurações protegidos: o sandbox automaticamente nega acesso de escrita aos arquivos settings.json do Claude Code em cada escopo e ao diretório de configurações gerenciadas, portanto um comando em sandbox não pode modificar sua própria política.

​

Compatibilidade de plataforma e ferramentas

• Suporte de plataforma: suporta macOS, Linux e WSL2. WSL1 e Windows nativo não são suportados.
• Overhead de desempenho: mínimo, mas algumas operações de sistema de arquivos podem ser ligeiramente mais lentas.
• Compatibilidade de ferramentas: algumas ferramentas que exigem padrões de acesso específicos do sistema podem precisar de ajustes de configuração, ou podem precisar ser executadas fora do sandbox.

​

Escopo

• Ferramentas de arquivo integradas: Read, Edit e Write usam o sistema de permissão diretamente em vez de serem executadas através do sandbox. Consulte permissions.
• Computer use: quando Claude abre aplicativos e controla sua tela, ele é executado em seu desktop real em vez de em um ambiente isolado. Prompts de permissão por aplicativo controlam cada aplicativo. Consulte computer use in the CLI ou computer use in Desktop.
• Variáveis de ambiente: comandos Bash em sandbox herdam o ambiente do processo pai por padrão, incluindo quaisquer credenciais definidas lá. Use sandbox.credentials para remover variáveis específicas para comandos em sandbox, ou defina CLAUDE_CODE_SUBPROCESS_ENV_SCRUB para remover credenciais do Anthropic e do provedor de nuvem de todos os subprocessos.
• Subagents: subagents são executados no mesmo processo que a sessão pai e usam a mesma configuração de sandbox. Comandos Bash dentro de um subagent são colocados em sandbox quando sandboxing está habilitado na sessão pai.

​

Veja também

• Sandbox environments: compare o sandbox integrado com dev containers, containers e VMs
• 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