O sandbox de comandos

Bolhas com a ferramenta Executar comandos podem executar comandos no seu projeto: instalar pacotes, executar compilações e testes. Três camadas decidem o que realmente é executado.

1. O que uma bolha pode fazer

Cada papel possui um conjunto fixo de ferramentas. Um Coder pode escrever arquivos e executar comandos; um Revisor pode executar comandos, mas não escrever arquivos; um Researcher não pode fazer nenhum dos dois. As ferramentas de um papel integrado são fixas. Para escolher as suas próprias, crie uma bolha personalizada.

As ferramentas de arquivo sempre mantêm um loop vinculado à sua pasta. Seus comandos ficam restritos a ela pelo sistema operacional apenas com Sandbox de comandos de agente ativado (abaixo). Sem o sandbox, um comando que mencione um arquivo fora da pasta é recusado, mas um script, uma compilação ou um gerenciador de pacotes iniciado por um comando ainda pode escrever em qualquer lugar do projeto.

2. A proteção de comandos

Cada comando é lido antes de ser executado e recebe uma de três respostas.

Recusado, sempre:

• executar um shell diretamente (bash, sh, cmd, powershell, wsl) e qualquer coisa que altere o próprio shell;
• acesso remoto (ssh, scp, rsync e similares), encerramento de processos, alteração de permissões;
• git destrutivo (reset --hard, clean -f, push com force, comandos interativos) e publicação de pacotes;
• qualquer caminho fora do projeto e qualquer arquivo que pareça um segredo (.env, chaves, certificados);
• um endereço web que não seja um registro de pacotes, GitHub, Docker Hub ou sua própria máquina;
• qualquer coisa que nunca encerre, como um servidor de desenvolvimento ou um modo de monitoramento. Esses itens pertencem a um terminal.

Perguntar, a menos que você tenha ativado o Full Auto:

• commits, pushes, merges, rebases, checkouts de git e similares;
• exclusão de arquivos dentro da pasta do loop;
• execução de código em linha (node -e, python -c e similares).

Permitido: todo o resto, como npm install ou npm test.

Os comandos são executados sem nenhuma variável de ambiente cujo nome contenha KEY, SECRET, TOKEN, PASSWORD, CREDENTIAL ou PRIVATE. Um comando tem dois minutos, ou dez para gerenciadores de pacotes, compiladores e executores de teste. Quando o tempo se esgota, toda a árvore de processos é encerrada.

Perguntas e Full Auto

Quando um comando precisa da sua autorização, o aplicativo pergunta: Permitir uma vez, Permitir sempre nesta sessão (para esse tipo de comando neste quadro, até que o gateway seja reiniciado) ou Negar. Se nenhuma janela estiver aberta para perguntar, ou se ninguém responder a tempo, o comando é recusado.

O Full Auto transforma cada “perguntar” em “permitir” para um quadro. Ele não altera mais nada: comandos recusados, permissões de ferramentas e pastas continuam se aplicando. Ele permanece ativado até que você o desative.

3. O sandbox

A proteção lê um comando e recusa o que consegue ver. Um script de compilação ou a etapa de instalação de um pacote ainda pode escrever arquivos cujos nomes não apareçam como argumentos. O recurso Sandbox de comandos de agente (Configurações, desativado por padrão) faz com que o sistema operacional também imponha restrições às pastas:

• o projeto é somente leitura, a pasta do próprio loop tem permissão de escrita, as pastas de outros loops dentro dele são somente leitura e a pasta do próprio aplicativo é somente leitura;
• não há acesso à rede de dentro do sandbox.

Sistema	Como
Linux	bubblewrap (bwrap)
macOS	sandbox-exec
Windows	WSL com bubblewrap (o padrão) ou Docker

Com o sandbox ativado, um comando que não pode ser confinado no sandbox é recusado e nunca é executado sem ele. Se um backend não estiver pronto, as Configurações mostram a única etapa para corrigir isso, com o comando exato para copiar, por exemplo a instalação do bubblewrap dentro do WSL.

O Perfica nunca instala um sandbox para você. A imagem do Docker é baixada apenas após você confirmar uma caixa de diálogo que informa o seu tamanho.

Windows, loops na raiz do projeto

No Windows, o projeto é acessado por meio do compartilhamento de arquivos do WSL, onde os nomes não diferenciam maiúsculas de minúsculas. Para um loop cuja pasta é o projeto inteiro, um comando que digite o nome da pasta do aplicativo com letras maiúsculas ou minúsculas diferentes ainda pode gravar nela. Loops que possuem uma subpasta não são afetados.

O terminal

O painel do terminal na parte inferior do aplicativo é o seu próprio shell (Bash, PowerShell ou CMD), e não o dos agentes. A proteção não se aplica a ele. Executar no terminal coloca um comando de uma resposta de chat ou de uma entrada de log na linha de entrada do terminal; ele nunca pressiona Enter por você.