Skip to content

Modelo de permissões ​

Quem pode fazer o quê, sobre o quê e em que situação: a mesma regra em qualquer sandbox, imposta em níveis.

Esta página define o modelo de permissões do choliba. Ele é o alvo: o código chega a ele em etapas. Onde o comportamento de hoje ainda é diferente, a página diz isso. Para o que vale hoje regra por regra, veja Segurança e Sandbox.

A pergunta ​

Toda permissão responde à mesma pergunta: este sujeito pode fazer esta ação neste objeto, neste contexto? É o modelo ABAC do NIST (SP 800-162), na forma que o Cedar usa (principal, ação, recurso, contexto). O choliba adota a forma, não a linguagem do Cedar.

  • Negado por padrão. Só é permitido o que uma regra allow libera.
  • deny vence allow.
  • Uma exceção tira um caminho de um deny da mesma ação e não libera nada sozinha: o caminho ainda precisa de um allow. A exceção é declarada num campo próprio, permissions.exception. O prefixo ! no caminho continua aceito como a forma antiga do mesmo campo.

Sujeitos ​

SujeitoQuem éDe onde vem a política
agenta sessão de um agente (agent.id)o agent.yaml, mais as regras que o choliba põe em todo agente
stepuma ação de steps (run, git_diff…)o código da ação; pode o que o agente não pode
scriptquem usa o choliba/sandbox diretoa política que o próprio script passa

Os três passam pela mesma decisão. A política de um step não herda a do agente: um step existe justamente para fazer o que o agente não faz. A do run, que executa um comando escrito pelo próprio usuário no agent.yaml, é a pasta de trabalho inteira, com leitura e escrita. Hoje os steps rodam fora das permissões.

Objetos ​

ObjetoIdentificado por
caminhocaminho absoluto, ou um glob
comandoa pasta onde roda e o argv
ferramentao nome e o subcomando; um MCP é uma ferramenta (servidor e tool)
rederede desligada, ou um destino
variávelo nome da variável de ambiente

Um caminho sem glob vale para ele e tudo abaixo.

Um MCP sem tool vale para todas as tools dele. Uma ferramenta sem servidor é do próprio provider (Read, Task) e não se confunde com a tool de um MCP que tenha o mesmo nome.

Ações ​

AçãoObjetoEquivale a
readcaminholer um arquivo
listcaminholistar uma pasta
createcaminhocriar arquivo ou pasta
editcaminhoalterar um arquivo existente
deletecaminhoapagar arquivo ou pasta
invocarcomando, ferramentarodar o comando ou a ferramenta (o subcomando é atributo)
connectredeabrir conexão
bindredeaceitar conexão

Mover é derivado: delete na origem e create no destino. Salvar um arquivo trocando-o por um temporário, como faz o provider, pede create, edit e delete na pasta dele.

Contexto ​

O contexto muda a decisão sem mudar a regra:

  • Modo. Em plan e ask, create, edit e delete são negados, mesmo com allow. invocar uma ferramenta não é bloqueado pelo modo: o que ela fizer num caminho é decidido à parte.
  • Projeto e ticket da execução.

Duas concessões valem só para uma execução:

  • --add-dir soma uma pasta à leitura.
  • A pasta da execução (.cache/runs/<id>/), onde o provider nasce e grava os próprios arquivos, tem escrita, é declarada (não implícita) e é a pasta de trabalho em qualquer sandbox.

Quem decide e quem impõe ​

Um único ponto decide: o sandbox. Ele responde allow ou deny a cada pedido. A execução do agente escreve a política e traduz o que o provider faz (uma chamada de ferramenta no stream) em pedidos; ela não decide. A decisão é imposta em camadas, e cada decisão diz onde foi imposta:

NívelQuem impõe
enforcedo sistema: o kernel ou o container
delegatedo provider (as regras do Claude, o cli.json do Cursor)
guardedo choliba, que interrompe a execução ao ver a violação no stream
advisorysó o prompt pediu

advisory não é limite: é o registro de que ninguém impôs aquela regra.

O piso de cada ação ​

AçãoNível mínimo
read, escrita e deny em caminhoenforced
argv de um comandodelegated ou guarded
invocar ferramenta ou MCPdelegated ou guarded
redeenforced para rede desligada

Abaixo do piso de uma ação, o choliba recusa o comando ou a regra, nunca a sessão inteira, e nunca alarga a permissão.

Arredondar só para o lado restrito ​

Um sandbox que não exprime uma regra exata arredonda para o lado mais restrito e informa; nunca para o mais permissivo. Um mount, por exemplo, só sabe nada, leitura, escrita ou oculto: dentro de um mount já imposto, list, create, edit e delete são apertados pelo provider (delegated) ou pelo choliba (guarded). Se nenhum dos dois consegue apertar, a regra é recusada. Um create sem delete não vira um mount de escrita.

A única exceção nomeada: um arquivo com escrita abre a pasta dele, porque o provider salva trocando o arquivo por um temporário, e o resto da pasta fica só leitura. O provider limita a escrita ao arquivo.

Exceções conhecidas ​

  • A credencial do provider é legível pelo agente, dentro e fora do container: o provider precisa dela.
  • Pedir a uma pessoa no meio da execução não existe: o provider roda em modo não interativo (-p).
  • Rede por domínio exige um proxy; o Landlock só cobre portas TCP. A saída do provider para a API do modelo e o acesso à aplicação do projeto ficam advisory até haver proxy ou controle de porta. Outra regra de rede que o sandbox não imponha é recusada.

Do agent.yaml para o modelo ​

No agent.yamlNo modelo
permissions.allow.readallow de read e list
permissions.allow.writeallow de create e edit
permissions.allow.deleteallow de delete
permissions.deny.<ação>deny das mesmas ações
permissions.exception.<ação>exception das mesmas ações
!caminho num deny (forma antiga)exception daquela ação
permissions.allow.executeinvocar comando: pasta e prefixo do argv
permissions.allow.tools/.deny.toolsinvocar ferramenta, com os subcomandos
mcpsinvocar ferramenta: servidor e tool
modescontexto modo
pastas de agentes, skills e MCPsdeny de create, edit e delete, em todo agente
delegar a um subagentedeny de invocar, em todo agente

A tradução não alarga nem estreita o que cada agente alcança hoje.

Por sandbox ​

O nível que cada objeto alcança. Para o que muda na prática entre local e docker, veja Sandbox.

Objetolocal, hojelocal, no modelo (bwrap)docker
caminho: leitura, escrita, denyenforced (bwrap); sem bwrap, recusadoenforced; sem bwrap, recusadoenforced (mounts)
caminho: list, create, edit, delete dentro de um mountdelegateddelegated ou guardeddelegated ou guarded
comando: argvdelegateddelegated ou guardeddelegated ou guarded
ferramenta e MCPdelegated e guardeddelegated e guardeddelegated e guarded
rede desligadanão existeenforced (--unshare-net)enforced (--network none); hoje só há isolated e host
saída para a API e a aplicaçãosem limiteadvisory (exceção conhecida)hoje sem limite (a bridge não filtra saída); no modelo, advisory
pasta de trabalhoa pasta da execução (bwrap --chdir)a pasta da execução (--chdir)a pasta da execução (--workdir)

No modelo, o local isola desde o início, como qualquer outro sandbox: sem bwrap, uma regra de caminho é recusada, com a instrução de como instalá-lo. Não existe modo sem isolamento.

Casos ​

CasoHojeNo modelo
Um script roda rm com CHOL_SANDBOX=local e policy: 'read-only'sem bwrap, recusado; com bwrap, o caminho é só leitura e o rm falhasem bwrap, recusado; com bwrap, o caminho é só leitura e o rm falha
Um script aponta a pasta da execução para uma pasta do usuário, em read-onlyo docker a monta com escritaela é uma concessão declarada da execução, com escrita; nunca uma pasta com dados do usuário
Um script roda o mesmo plano em local e em dockerpwd é a pasta da execução nos doispwd é a pasta da execução nos dois
O provider salva o ticket trocando-o por um temporárioresolvido: o arquivo com escrita abre a pasta, o resto fica só leituraigual: a exceção nomeada do arredondamento
O agente chama um MCP que não declarouo choliba interrompe (guarded); no Claude a sessão nem tem o servidor (delegated)igual, com a decisão vinda do sandbox
O agente chama um subagenteno Claude a ferramenta não existe (delegated); no Cursor o choliba interrompe no primeiro Task (guarded)igual: um deny de invocar que vale para todo agente