Skip to content

Segurança ​

Como o choliba restringe o que cada agente alcança: as permissões do agent.yaml, os MCPs declarados e as regras que valem em qualquer provider.

O modelo por trás dessas regras (sujeito, ação, objeto e contexto, e onde cada regra é imposta) está em Modelo de permissões.

Os agentes rodam comandos e mexem em arquivos, então o choliba restringe o que cada um alcança, a partir do permissions do agent.yaml:

  • Negado por padrão, em qualquer lugar. O agente só lê, escreve e roda o que está em permissions.allow, no workspace ou fora dele; deny prevalece sobre allow, menos no que uma exceção (permissions.exception) tira dele. O choliba escreve as permissões no prompt e as aplica no provider. Cada execução roda numa pasta vazia, .cache/runs/<id>/, criada antes e apagada depois, porque os providers liberam tudo na pasta em que rodam. No Claude, as regras dizem exatamente onde ele lê e escreve, e ele só tem as ferramentas que as permissões pedem. No Cursor, que não trata allow como limite, o choliba gera um deny para todo o resto do disco e grava o cli.json nessa pasta da execução: é o diretório em que o cursor-agent nasce, e sem um raiz de git ele só lê o cli.json dali. O de ~/.cursor continua de base; as listas allow e deny da run substituem as dele. O mcp.json fica na raiz do workspace. O Grep e o Glob do Cursor leem o que um deny de leitura cobre, e nenhuma permissão os tira: o prompt diz ao modelo para nunca usá-los, e o choliba interrompe a execução na primeira chamada a um deles, com código 1. Limite do Cursor: um arquivo novo, criado direto numa pasta do caminho até um item liberado (a raiz do workspace, por exemplo), não é bloqueado. No Codex, o sandbox próprio fica desligado: ele roda dentro do bwrap ou do container, que só montam o que as permissões alcançam (deny.read escondido, deny.write só leitura). O Codex não limita comandos, então o choliba confere cada comando que ele roda contra permissions.execute (como o Bash(comando:*) do Claude) e interrompe a execução, com código 1, no primeiro fora dele, ou com substituição ($(…), crases). Como o Codex lê arquivos pelo shell, os comandos que só leem passam sempre: cat, head, tail, ls, wc, nl, grep, rg, find, pwd e sed -n '<início>,<fim>p', sem as opções que rodam outro programa ou gravam (find -exec, find -delete, rg --pre, rg -z); o prompt do Codex diz para ler só com eles. O que eles alcançam é o que o sandbox monta. A conferência é feita quando o comando aparece no stream, já começando a rodar. Limite do Codex: ele não recebe mensagens durante a execução, e a cópia do auth.json do codex login fica na pasta da execução, ao alcance do agente até ela ser apagada.
  • Caminhos. Caminho relativo é relativo à raiz do workspace. Um caminho sem glob é o item e tudo abaixo dele, com ou sem / no fim, em qualquer provider: o choliba entrega a cada um o glob explícito. Num glob, o Cursor libera a pasta antes dele inteira.
  • Exceções no deny. permissions.exception (ou, na forma antiga, !caminho dentro do deny) tira um caminho de um deny da mesma ação, como no .gitignore (veja Exceções no deny). Nenhum provider entende exceções, então o choliba resolve antes: o deny que contém a exceção vira tudo o que há dentro dele, menos o caminho até ela, lido do disco no começo da execução. Assim os providers recebem regras que não se contradizem e chegam ao mesmo resultado. Limite: o que for criado depois, numa dessas pastas, fica fora do deny (no Claude continua bloqueado, porque nada o libera).
  • Skills. A pasta de cada skill declarada fica liberada para leitura e é uma exceção dos deny.read do agente: declarar a skill é pedir para lê-la. Vale só para essa pasta, não para .choliba/skills/ inteira.
  • As definições não mudam numa run. Toda execução ganha deny.write e deny.delete das pastas de agentes, skills e MCPs (--agents-dir ou CHOL_AGENTS_DIR, CHOL_SKILLS_DIR, CHOL_MCPS_DIR), além do que o agente declara. O prompt, as regras do provider e o container herdam essa negação. Uma exceção de escrita ou exclusão dentro delas para a execução: nenhuma run reabre essas pastas. A leitura de cada skill declarada continua liberada. Depois do provider, o choliba compara o sha256 de cada arquivo dessas pastas com o de antes: arquivo criado, alterado ou apagado encerra a execução com código 1 e a lista dos caminhos, e nada é desfeito.
  • --add-dir <pasta> libera a leitura de uma pasta a mais só naquela execução (pode repetir), como se ela estivesse em allow.read; o deny do agente continua valendo por cima dela.
  • Execução por diretório. Os comandos rodam a partir da pasta da execução, dentro do workspace (por isso bun choliba ... funciona sem cd). Um diretório de execute fora do workspace precisa estar em allow.read, porque rodar comandos nele já dá acesso ao que há lá. Os providers aplicam em que diretórios o agente entra e quais comandos roda, mas não o vínculo "este comando só neste diretório": na prática vale a união dos dois.
  • bun choliba, nunca bunx choliba. Os agentes oficiais chamam o choliba com bun, que roda o instalado na pasta de trabalho e, sem ele, falha na hora (Script not found). O bunx, sem o choliba instalado, baixa do npm o pacote que tiver esse nome e o executa: um agente rodaria código de quem publicasse o nome. Num agente seu, use bun choliba nos steps e nas permissões de execução.
  • Ferramentas da run. O que só os agentes usam (apagar, o navegador, o leitor de trace) não é comando público do choliba: é um script que ele cria ao lado da pasta da execução, libera só para aquela sessão, nega para escrita e apaga no fim. O apagar resolve cada caminho antes de agir e recusa o que sai de allow.delete. Veja Ferramentas da run.
  • Nenhum agente delega. Nenhum agente chama um subagente nem põe outro agente para trabalhar por ele, e isso não se configura. O prompt de todo agente diz isso. No Claude, a ferramenta de subagente (Agent) nem existe na sessão. O Cursor não tem permissão que a tire, então o choliba interrompe a execução no primeiro Task, com código 1.
  • MCP só declarado. O agente só usa os servidores e as tools de mcps. O prompt diz isso, e o choliba confere cada chamada: um servidor ou uma tool fora do declarado (ou procurar tools de MCP num agente sem mcps) interrompe a execução com código 1, em qualquer provider. No Claude, a sessão só tem os servidores declarados. No Cursor, que soma os MCPs do ~/.cursor/mcp.json do usuário, o choliba também nega os que o agente não declara. O Codex recebe somente overrides para os MCPs declarados, sem o config.toml pessoal.
  • Dado não é ordem. O que um passo põe no prompt vindo de arquivos (read_files, search_files) ou do repositório (o índice do git_diff) vai dentro de <untrusted_input source="…">, e o prompt de todo agente diz que aquilo é dado, nunca instrução, mesmo que diga vir do sistema ou do usuário. Uma tag untrusted_input dentro do texto é escapada, para o dado não fechar o bloco. É uma camada a mais: o modelo ainda pode ser enganado, e quem limita o agente são as permissões e o container.
  • steps não passam pelas permissões. Os passos são executados pelo choliba, fora da sessão do modelo: um passo pode fazer o que o modelo não pode (rodar um comando que as permissões do agente negam, por exemplo). Veja Steps.

Sandbox ​

As regras acima são aplicadas pelo próprio provider, e cada um tem os limites descritos. Com CHOL_SANDBOX=docker, o provider roda num container que só enxerga o que o agente alcança, e esses limites deixam de importar. Como cada modo funciona, o que o container vê, a rede, a credencial e a imagem: Sandbox.