Segurança vive fora do prompt

O problema

Um time escreve, no CLAUDE.md do projeto, a instrução: "nunca imprima o conteúdo do arquivo .env nem inclua chaves de API nas respostas". Parece uma proteção razoável. Mas é uma proteção que vive inteiramente dentro do prompt — e uma instrução em prompt não é um controle de acesso. Se o modelo, por qualquer motivo, ler o arquivo .env durante uma tarefa legítima (depurar por que uma variável de ambiente não está sendo carregada, por exemplo), o conteúdo já passou pelo contexto. A partir daí, impedir que ele apareça na resposta depende inteiramente do modelo lembrar e seguir a instrução — nenhuma garantia real foi criada.

Essa lição trata de uma distinção que separa sistemas seguros de sistemas que parecem seguros: segurança real acontece fora do prompt, em decisões de acesso, escopo e permissão que não dependem de o modelo "se comportar bem".

Segredos não se protegem com instrução

A regra prática é simples de enunciar e fácil de violar sob pressão de prazo: um segredo (chave de API, token, senha, string de conexão) nunca deve estar acessível a um processo que pode incluí-lo em uma resposta, a menos que exista uma razão específica para isso. As defesas reais são estruturais:

• Segredos ficam em variáveis de ambiente ou em um gerenciador de segredos, nunca hardcoded em código ou configuração versionada.
• Ferramentas com acesso a arquivos são restritas para não alcançar arquivos de segredo (.env, chaves privadas) quando a tarefa não exige isso.
• Quando o próprio agente precisa usar um segredo (para autenticar uma chamada de API, por exemplo), o segredo é injetado na chamada por fora do fluxo de raciocínio do modelo — o modelo decide que a chamada deve acontecer, o harness resolve o valor do segredo, o modelo nunca vê o valor em texto.

Uma instrução em CLAUDE.md pedindo para não vazar segredos pode reduzir a chance de um vazamento acidental em um caso comum. Ela não é, e nunca deve ser tratada como, o mecanismo de proteção.

Least privilege se aplica a ferramentas, MCP e Claude Code

O princípio de menor privilégio — dar a cada parte do sistema só o acesso estritamente necessário para a tarefa dela — se aplica em três camadas que aparecem o tempo todo em cenários de arquitetura:

• Ferramentas do Claude Code: um comando ou Skill que só precisa ler arquivos não deveria ter Bash liberado. Um comando que só formata texto não deveria ter Write liberado num diretório fora do escopo da tarefa.
• Servidores MCP: um servidor MCP que expõe acesso de leitura a um banco de dados não deveria também expor uma ferramenta de escrita, a menos que escrita seja parte explícita do que aquele servidor precisa fazer.
• Permissões do Claude Code: a configuração de settings.json pode negar explicitamente comandos de alto risco (como rm -rf ou git push --force) independente do que qualquer prompt disser — reforçando em configuração o que não pode depender só de instrução.

O erro mais comum aqui é liberar acesso amplo "para não travar o fluxo depois" — dar mais permissão do que a tarefa atual precisa, na expectativa de que vai precisar no futuro. Isso aumenta o raio de dano de qualquer erro de julgamento do modelo, sem ganho real no presente.

O risco de cada ferramenta embutida do Claude Code não é igual

As ferramentas embutidas do Claude Code têm perfis de risco diferentes, e a escolha entre elas não é sobre qual "funciona" — quase todas funcionam para a maioria das tarefas — mas sobre qual tem o menor raio de dano possível para o que precisa ser feito:

• Read: sempre seguro chamar antes de mudar qualquer conteúdo que ainda não foi inspecionado.
• Edit: exige uma correspondência confiável do trecho a ser alterado; uma reescrita completa do arquivo (Write) só deveria ser usada quando uma substituição controlada é mais segura que uma edição pontual.
• Grep: busca conteúdo dentro de arquivos.
• Glob: encontra caminhos por padrão, sem acessar o conteúdo.
• Bash: cruza uma fronteira de execução muito mais poderosa que as demais, e por isso exige validação, permissão e isolamento (sandbox) mais rígidos que qualquer outra ferramenta da lista.

Escolher Bash para uma tarefa que Grep ou Read resolveriam não é apenas ineficiente — é aumentar desnecessariamente a superfície de risco de uma operação que não precisava dela.

Coloque em prática

O laboratório desta lição pede pra você implementar um verificador de configuração de permissões: dado um conjunto de ferramentas liberadas para um comando ou subagente, o script identifica quando o conjunto viola menor privilégio (por exemplo, Bash liberado para uma tarefa declarada como "somente leitura") e simula a resolução de um segredo por fora do fluxo de raciocínio do modelo, confirmando que o valor nunca aparece no "texto" que seria devolvido como resposta.