Skip to main content
A opção --sandbox executa o CLI com isolamento em nível de sistema operacional, aplicando os escopos ativos de permissão de leitura e gravação no próprio sistema operacional e, opcionalmente, restringindo o tráfego de rede.

​
Como o sandbox funciona

Quando o sandbox está ativo:
  • Os caminhos graváveis são derivados dos escopos de permissão Write(...) concedidos, mais o diretório do workspace
  • Os caminhos legíveis são derivados dos escopos Read(...) concedidos (padrões da plataforma, como /usr/bin, são sempre legíveis)
  • Escopos concedidos no meio da sessão expandem dinamicamente o sandbox para os comandos subsequentes
Se a resolução do sandbox falhar (por exemplo, se as ferramentas de sandbox não estiverem disponíveis na plataforma do usuário), a CLI se recusará a iniciar em vez de ser executada fora do sandbox. Esse comportamento de falha segura se aplica tanto quando o sandbox foi ativado por uma configuração da equipe quanto pelo usuário ao passar --sandbox diretamente, garantindo que a intenção de segurança nunca seja contornada silenciosamente.Causas comuns de falha na resolução do sandbox:
  • Windows: o sandbox em nível de SO não tem suporte no Windows no momento. As sessões no Windows falharão imediatamente quando --sandbox for passado ou quando a imposição do sandbox for obrigatória, inclusive quando a CLI for executada como um servidor ACP dentro de uma IDE (por exemplo, Devin Desktop).
  • Linux: o sandbox exige que bubblewrap (bwrap) e socat estejam instalados. As sessões falham imediatamente com instruções de instalação quando eles não estão presentes.
  • Erros de escopo de permissão: caminhos inválidos em escopos de permissão que não podem ser resolvidos.

​
Filtragem de rede

A filtragem de rede do sandbox está instável no momento. Se você precisar desse recurso, entre em contato com o representante da sua conta para saber a previsão de estabilização.
Configure a filtragem de rede em nível de domínio para o sandbox na seção sandbox do seu arquivo de configuração (apenas na configuração do usuário). Quando --sandbox está ativo e a filtragem de domínio está configurada, um proxy de rede gerenciado é iniciado na interface de loopback, e o sandbox restringe todo o tráfego dos processos filhos para passar por ele. Sintaxe de padrão de domínio: Exemplo:
A filtragem de domínio se aplica quando o sandbox está ativo (--sandbox). Sem --sandbox, a seção do sandbox é ignorada.

​
Comandos excluídos

Às vezes, um comando específico precisa ser executado fora do sandbox — por exemplo, comandos git que precisam acessar credenciais ou hooks bloqueados pelo sandbox. A seção de configuração sandbox.excluded permite excluir do isolamento do sandbox os comandos correspondentes, usando a mesma sintaxe de regra Exec(...) de permissão: Exemplo:
Resolução de regras: para cada comando, a regra correspondente mais específica prevalece dentro de uma origem (por exemplo, Exec(git push *) prevalece sobre Exec(git *)), e, quando tanto a configuração do usuário quanto as Configurações da equipe se aplicam, prevalece a decisão mais restritiva (deny > ask > allow). Comandos sem nenhuma regra correspondente — inclusive quando sandbox.excluded não está configurado — sempre são executados dentro do sandbox.
  • Somente regras Exec(...) têm suporte em sandbox.excluded; qualquer outro tipo de regra (por exemplo, Read(...), Write(...)) é ignorado com um aviso.
  • A exclusão é fail-closed: se um comando não puder ser resolvido com segurança (por exemplo, se não puder ser analisado), ele permanece dentro do sandbox.
  • As exclusões se aplicam ao caminho de execução padrão de cada comando. Comandos executados por meio de um shell PTY persistente (sessões interativas ou quando pty_for_noninteractive_exec está ativado) sempre permanecem dentro do sandbox.

​
Aplicação obrigatória no Enterprise

Os admins do Enterprise podem controlar o comportamento do sandbox em toda a organização por meio de Configurações da equipe.

​
Modo de imposição do sandbox

Defina o nível de imposição da flag --sandbox em toda a sua organização:
  • Opcional (padrão) — Os usuários escolhem se querem informar --sandbox. Sem imposição.
  • Obrigatório — A flag --sandbox é aplicada a todos os usuários, mesmo que eles não a informem na linha de comando. Todas as sessões de CLI são executadas com sandbox de sistema de arquivos em nível de SO, que aplica escopos de permissão de leitura/gravação.
No futuro, um modo Strict poderá restringir totalmente a configuração do sandbox, impedindo que os usuários modifiquem suas configurações.
Certifique-se de que todas as máquinas de destino estejam provisionadas antes de definir o modo de imposição do sandbox como Obrigatório em toda a sua organização. Se algum usuário usar Windows, não conseguirá executar a CLI até que o sandbox em nível de SO tenha suporte no Windows ou que a política seja flexibilizada para Opcional.

​
Filtragem de domínios no Enterprise

Os administradores também podem configurar listas de permissões e listas de bloqueio de domínios para toda a organização:
  • Lista de permissões de domínios — Quando definida, somente os domínios desta lista podem ser acessados pelo proxy de rede do sandbox. Esta lista é definitiva: ela substitui completamente qualquer allowed_domains configurado pelo usuário. Os usuários não podem adicionar domínios extras para contornar as restrições do administrador.
  • Lista de bloqueio de domínios — Domínios que são sempre bloqueados. Os domínios bloqueados no Enterprise são aditivos: eles são mesclados com o denied_domains local do usuário, tornando a lista combinada mais restritiva.
Como as listas de domínios do Enterprise e do usuário interagem:
Como o denied_domains local do usuário é preservado e mesclado de forma aditiva, o usuário pode bloquear um domínio que aparece na lista de permissões do Enterprise. Isso é intencional: o efeito combinado é sempre mais restritivo, nunca menos. Se isso causar problemas de acesso, o usuário deve remover a entrada conflitante da configuração local.

​
Comandos excluídos no Enterprise

Os administradores também podem definir regras de comandos excluídos para toda a organização nas Configurações da equipe:
  • Excluded allow / ask — regras Exec(...) para comandos que podem ser executados fora do sandbox em toda a organização, automaticamente ou após uma confirmação.
  • Excluded deny — regras Exec(...) para comandos que nunca devem ser executados fora do sandbox. Um deny da equipe tem precedência sobre qualquer allow ou ask em nível de usuário para comandos correspondentes, então os usuários não podem excluir comandos que seus administradores restringiram.
As regras da equipe e do usuário são avaliadas em conjunto: a regra correspondente mais específica prevalece dentro de cada origem, e a decisão mais restritiva prevalece entre as origens (deny > ask > allow). Exemplo: bloquear todas as exclusões, exceto gh. Um deny curinga com uma exceção allow mantém todos os comandos dentro do sandbox, exceto gh, independentemente do que os usuários configurarem localmente. Esses valores vão na configuração de comandos excluídos das Configurações da equipe (não no arquivo de configuração do usuário, portanto não há uma chave sandbox de nível superior):
Como a regra mais específica Exec(gh *) prevalece sobre o curinga Exec(**), os comandos gh são executados fora do sandbox, enquanto todo o restante permanece dentro — e o curinga deny no nível da equipe se sobrepõe a quaisquer regras allow ou ask no nível do usuário para outros comandos.

​
Leitura adicional