Injeção por ficheiro de instruções: como AGENTS.md e CLAUDE.md desviam o teu agente

O que é a injeção por ficheiro de instruções?

A injeção por ficheiro de instruções é um ataque de prompt injection indireto em que a carga vive num ficheiro do repositório que o agente de código carrega como orientação de projeto de confiança, e não como entrada não fiável. O atacante nunca fala com o modelo. Faz um commit, e o agente lê-o em teu nome, na tua máquina, com as tuas credenciais.

Vale a pena ser preciso sobre por que razão isto é uma classe diferente do prompt injection que todos já conhecem. A injeção indireta clássica esconde instruções em conteúdo que o modelo vai buscar: uma página web, um ticket do Jira, o corpo de uma issue. Supõe-se que o modelo trate isso como dados, e a falha é tratá-lo às vezes como instrução. A injeção por ficheiro de instruções inverte o enquadramento. Estes ficheiros são concebidos para serem instruções. Carregá-los como política não é um bug, é a funcionalidade documentada. CLAUDE.md existe para que um repositório possa explicar ao agente como o projeto funciona. AGENTS.md existe para que o agente recolha as convenções sem que ninguém lhe diga. Toda a proposta de valor é o agente obedecer ao ficheiro.

A vulnerabilidade não é, portanto, "o modelo confundiu dados com instruções". A vulnerabilidade é que o ficheiro tem autoridade e a sua autoria não é verificada. A Cloud Security Alliance escreveu-o preto no branco na sua nota de investigação de março de 2026 sobre injeção via README: estes ficheiros são carregados no arranque da sessão e tratados com um nível de confiança que se aproxima da autoridade do prompt de sistema, pelo que um adversário capaz de os modificar controla de facto a política de comportamento do agente em todas as interações seguintes nesse repositório.

“

Uma dependência tem de ser instalada para te fazer mal. Um ficheiro de instruções só tem de ser lido.

Essa assimetria é o que torna o ataque barato. Os ataques à supply chain de pacotes precisam de um registo, de uma subida de versão, de um passo de instalação e normalmente de um script de ciclo de vida. A injeção por ficheiro de instruções precisa de um ficheiro de texto e de alguém que abra a pasta. Não há nada para detetar na instalação porque nada é instalado. Não há nada para apanhar no grafo de dependências porque nenhuma dependência mudou. E muitas vezes também não há nada no diff, porque num clone novo não existe diff.

Os ficheiros que carregam autoridade de prompt de sistema

O primeiro gesto defensivo é conhecer a tua própria superfície de instruções. A maioria das equipas subestima-a por um fator de cinco, porque pensa "o CLAUDE.md que escrevemos" e esquece o ficheiro de settings, a pasta de skills, a configuração MCP e as substituições por subdiretório.

Duas linhas merecem um segundo olhar.

A linha do .claude/settings.json não é uma metáfora. Os hooks são comandos de shell que o agente executa em torno das suas próprias chamadas a tools, e são definidos num ficheiro que vive no repositório. É por isso que existe a CVE-2025-59536: no Claude Code anterior à versão 1.0.111, era possível executar código antes de o utilizador aceitar a caixa de diálogo de confiança do arranque, através de hooks de projeto não fiáveis definidos em .claude/settings.json. Pontuação CVSS v4.0 de 8.7. A correção chegou na 1.0.111, e a lição sobreviveu ao patch: um ficheiro JSON num repositório era uma primitiva de execução remota de código porque o agente foi concebido para executar o que esse ficheiro declarava.

A última linha é a que não para de crescer. Cada superfície que um agente lê durante o trabalho normal é um canal candidato, e os investigadores encontram novos sem parar. A Cloud Security Alliance documentou prompt injection a chegar ao claude-code-action através do GitHub Actions, e a investigação GitInject, publicada em junho de 2026, catalogou casos reais de prompt injection em pipelines de CI/CD conduzidos por IA. Se o agente o lê, um atacante pode escrevê-lo.

Por que razão a caixa de diálogo de confiança não é uma fronteira de segurança

Todos os agentes sérios mostram hoje um pedido de consentimento na primeira vez que abres uma pasta desconhecida. É um controlo genuinamente útil, e é também o pior compreendido da categoria, por causa do que realmente pergunta.

Pergunta se confias no diretório. Não diz nada, nem pode dizer, sobre o conteúdo dos ficheiros de instruções lá dentro. O consentimento é concedido à granularidade de uma pasta e depois aplicado a uma quantidade arbitrária de texto de política controlado pelo atacante. Fazem-te uma pergunta, uma única vez, e respondes antes de teres lido uma única regra.

A demonstração mais nítida desta falha veio do Hookify, um plugin distribuído pelo marketplace oficial do Claude Code da Anthropic. O Hookify é um motor de regras: lê ficheiros de regras do diretório do projeto, expressos em Markdown com front matter YAML, e injeta o seu conteúdo no canal de mensagens de sistema de confiança do subsistema de hooks. Os investigadores da Pluto Security reportaram que um atacante que deixe um desses ficheiros num repositório obtém assim um canal de condução para o modelo, para qualquer utilizador que tenha o Hookify instalado e abra esse repositório. Contra o Claude Opus 4.6, cinco cargas comportamentais apresentadas como inócuas convenções de projeto bastaram para o modelo revelar variáveis de ambiente e segredos locais.

A resposta da Anthropic é a parte a interiorizar. O relatório foi fechado como Informative, working as designed: a caixa de diálogo de confiança do diretório é a fronteira de segurança, e uma vez aceite, a configuração de projeto sob .claude/, incluindo CLAUDE.md, os hooks de projeto e a configuração de plugins como os ficheiros de regras do Hookify, é carregada intencionalmente.

Essa resposta defende-se nos seus próprios termos. E é também um enunciado muito preciso do risco residual que passa a ser teu.

É também por isso que "basta ler os ficheiros antes de aceitar" falha na prática. A superfície de instruções está espalhada por um ficheiro de settings, uma pasta de regras, uma convenção Markdown por subdiretório, uma pasta de skills e uma configuração MCP. As cargas escondem-se em comentários HTML que não renderizam nada. E assim que clonas um monorepo, a árvore pode conter uma dúzia de ficheiros de instruções encadeados, e qualquer um deles pode substituir os de cima.

Anatomia do ataque: um minuto e cinquenta e um

O teste técnico envenenado documentado pela Mitiga em junho de 2026 é o exemplo público mais limpo, porque as marcas temporais mostram exatamente o pouco tempo que um humano tem para intervir.

Clonar um repositório de aparência normalO agente carrega .cursor/rules, CLAUDE.md, os comentários do README, .cursor/mcp.jsonO agente recolhe credenciais de cloud e de clusterO agente exfiltra através de uma chamada a uma tool MCP

Lê essa tabela como um exercício de resposta a incidentes e o problema salta à vista. A janela entre a primeira ação hostil e a exfiltração completa é inferior a dois minutos. Não há pull request. Não há build. Não há artefacto nenhum para analisar. Todos os controlos que vivem a jusante do commit estão a olhar para o lado errado, porque o ataque terminou antes de ser escrita uma linha de código, e muito antes de ser revista.

Nota também o que o atacante não precisou. Nenhum zero-day. Nenhum pacote malicioso. Nenhuma conta de mantenedor comprometida. Precisou de uma razão plausível para clonares um repositório, o que, para quem está a contratar ou à procura de emprego, é a engenharia social mais fácil do setor.

Seis formas de envenenar um ficheiro de instruções

O teste técnico é uma via de entrega. Não é a parte interessante do modelo de ameaça, porque exige que clones algo novo. Estas são as vias que alcançam repositórios em que já confias.

1. O repositório que te pediram para clonar

Exercícios de entrevista, reproduções de bugs, "podes dar uma olhada nisto", repositórios de workshop de conferência, templates de arranque. Tudo o que chega com uma razão legítima para lançar um agente lá dentro. O caso Mitiga é esta via, e funciona porque o pedido é autêntico e a carga é invisível.

2. Uma pull request a partir de um fork

É a via que escala, porque alcança o teu repositório sem qualquer engenharia social. Se um workflow de agente corre com permissões de escrita em eventos originados em forks, o branch de um contribuidor pode adicionar ou modificar AGENTS.md, .clinerules ou uma pasta de regras, e o agente lerá a versão do atacante. A cadeia Clinejection, divulgada publicamente a 9 de fevereiro de 2026 e documentada pela Snyk, é a versão industrial disto: prompt injection através de títulos de issues transformou o workflow de triagem automática do Cline num vetor de ataque à supply chain, e um ator desconhecido usou-o para publicar uma versão não autorizada da CLI do Cline no npm durante uma janela de oito horas.

3. Um skill ou um plugin de marketplace

Os skills de agente são ficheiros de instruções com um canal de distribuição, o que é a pior combinação possível. O estudo ToxicSkills da Snyk sobre o registo ClawHub encontrou prompt injection em 36 % dos skills analisados e catalogou 1467 cargas maliciosas. Como os skills persistem entre sessões depois de ativados, uma única decisão de instalação continua a moldar o comportamento do agente indefinidamente, em todos os repositórios que abras depois. A OWASP mantém já um Agentic Skills Top 10, o que te diz a que velocidade isto se tornou uma categoria própria.

4. Uma troca de configuração MCP

.cursor/mcp.json e os seus equivalentes declaram quais tools existem e o que dizem as suas descrições. Muda a configuração e mudas as ações disponíveis para o agente; muda a descrição de uma tool e mudas aquilo que o modelo entende que essa ação faz. É o mesmo mecanismo do tool poisoning de MCP, que cobrimos em segurança MCP e tool poisoning, a chegar aqui por um ficheiro do repositório em vez de por um servidor.

5. Um ficheiro de instruções vendorizado ou transitivo

Os ficheiros de instruções viajam. Uma subárvore vendorizada, um submódulo git, um template gerado, uma pasta node_modules que o agente decide ler: cada um pode trazer o seu próprio AGENTS.md. Como a maioria dos agentes percorre a árvore e carrega o que encontra, um ficheiro encadeado colocado no fundo de uma dependência pode substituir sem ruído as convenções que escreveste na raiz.

6. O teu próprio repositório, por dentro

A via menos espetacular e a mais provável. Os ficheiros de instruções escapam geralmente à cultura de revisão que envolve o código-fonte. Não estão no CODEOWNERS, não acionam nenhum revisor obrigatório, e leem-se como documentação. Qualquer pessoa com acesso de escrita, incluindo uma conta de desenvolvedor comprometida ou um contribuidor bem-intencionado que copiou uma regra de um artigo, pode mudar a política operacional de todos os agentes da equipa sem que um único olhar de segurança passe pelo diff.

O que os controlos nativos cobrem e o que não cobrem

Os fabricantes de agentes entregaram controlos reais, e seria desonesto insinuar o contrário. As sandboxes limitam onde caem as escritas. As escalas de aprovação criam pontos de controlo. Os valores de rede por omissão estão fechados em vários modos cloud. Existem allowlists e deny lists de terminal. O Antigravity inclui uma allowlist de URL de navegador precisamente para cortar a via de injeção por páginas obtidas. Tudo isso reduz o risco.

A falha é mais estreita e mais concreta do que "os agentes não são seguros".

Dito de forma simples: os controlos falam de capacidade, e a injeção por ficheiro de instruções fala de autoridade. O sandboxing responde a "a que pode este processo tocar". Não tem nada a dizer sobre "de quem são as instruções que o modelo está a seguir". São dois eixos ortogonais, e é por isso que um agente perfeitamente isolado lerá de bom grado um ficheiro de credenciais e o entregará a uma tool, se a política que carregou lho pediu.

É o mesmo ponto estrutural que a OWASP repete sobre os sistemas agênticos em produção, onde o prompt injection continua a ser o principal motor das falhas de segurança em vez de uma categoria resolvida.

Oito controlos que reduzem realmente o risco

Nada disto exige um fabricante novo. Quase tudo é política e canalização, e vale a pena fazê-lo antes de comprar o que seja.

Duas coisas que esta lista deliberadamente não diz. Não te diz para deixares de usar ficheiros de instruções, porque são o mecanismo que torna os agentes úteis numa base de código real e retirá-los equivale a pôr o agente a adivinhar. E não te diz para leres cada ficheiro de regras antes de aceitares uma caixa de diálogo de confiança, porque esse conselho não sobrevive ao contacto com um monorepo.

Onde os controlos param: os ficheiros de instruções são código que ninguém revê

Aplica os oito controlos acima e terás fechado as vias de entrega que vês. O que resta é o problema estrutural, e é a razão pela qual construímos a CybeDefend como construímos.

Um ficheiro de instruções é política executável que nenhuma parte da tua cadeia de ferramentas lê como código. O teu scanner SAST analisa código-fonte; não analisa Markdown que reprograma um agente. O teu scanner de dependências lê manifestos; um ficheiro de regras não tem manifesto. O teu scanner de segredos procura chaves; esta carga não contém nenhuma. E a tua revisão de pull request, o lugar onde a segurança aplicacional vive há quinze anos, só vê a alteração depois de um agente ter passado uma sessão a obedecer-lhe. A cronologia da Mitiga é a prova: todo o incidente terminou 1 minuto e 51 segundos depois de uma pasta ser aberta, ou seja cerca de mil vezes mais depressa do que o ciclo de revisão pensado para o apanhar.

Esse desfasamento de cadência é a tese de todo este site. A revisão de segurança como portão pressupunha um gargalo humano entre a intenção e o código. Os agentes eliminaram o gargalo. Escrevemos sobre a forma geral do problema em segurança dos agentes de código de IA, e a injeção por ficheiro de instruções é o seu caso mais afiado, porque aqui a carga do atacante e o manual operacional do agente são literalmente o mesmo ficheiro.

O controlo tem portanto de estar onde a decisão é tomada, isto é dentro do ciclo do agente e não a jusante.

Na prática isso significa três coisas para esta classe de ataque em particular.

As tuas regras chegam com mais autoridade do que as do repositório. O VibeDefend instala-se no agente como servidor MCP mais hooks, o que significa que a política recebida pelo modelo é a que a tua organização escreveu, não a que estava commitada na pasta. Um ficheiro do repositório que pede ao agente para ler ~/.aws/credentials passa a argumentar contra uma regra que chegou primeiro.

O guarda atua sobre a ação, não sobre o diff. Os hooks avaliam a chamada à tool antes de ela correr. Ler um ficheiro de credenciais, enviar um dump do ambiente para o curl, invocar uma tool cuja descrição mudou desde ontem: são decisões que o agente toma em plena sessão, e são o único lugar onde um controlo ainda pode dizer não.

Os findings estão no ciclo, não num dashboard. O agente tem acesso em direto ao que os nossos scanners encontraram no código, nas dependências, nos segredos, na infraestrutura e nos pipelines, pelo que quando propõe uma alteração raciocina sobre o estado de segurança real do repositório em vez de adivinhar. É também isso que lhe permite notar que o pipeline que lhe acabaram de pedir para modificar corre em eventos de fork com permissões de escrita.

Nada disto elimina a necessidade dos oito controlos. Muda o que acontece no intervalo que eles não conseguem fechar, que são os noventa segundos entre a abertura de uma pasta e a saída de um segredo.

Perguntas frequentes

Um ficheiro Markdown pode realmente executar código?

Não por si só, e é isso que o torna eficaz. O Markdown fornece as instruções; o agente fornece a execução. Se o agente tem acesso a shell e auto-approve ativado, um ficheiro de instruções é funcionalmente um script cujo interpretador é o modelo. O único caso em que o ficheiro se aproxima de uma execução literal é um ficheiro de settings que declara hooks, o que transformou a CVE-2025-59536 numa execução remota de código no Claude Code anterior à 1.0.111.

É seguro fazer commit de um AGENTS.md ou de um CLAUDE.md?

Sim, e deves. O risco não é ter um, é ninguém ser o seu dono. Põe o ficheiro no CODEOWNERS com um revisor de segurança, exige revisão nas alterações, e audita as cópias encadeadas mais abaixo na árvore. O problema é um ficheiro de instruções não revisto; um revisto é documentação que também configura os teus agentes.

A caixa de diálogo de confiança protege-me?

Protege o diretório, não o conteúdo. A Anthropic enunciou esta posição explicitamente ao fechar o relatório do Hookify: uma vez aceite a caixa de diálogo de confiança do diretório, a configuração de projeto sob .claude/, incluindo CLAUDE.md, os hooks de projeto e os ficheiros de regras de plugins, é carregada intencionalmente. Aceitar a caixa és tu a responder pelos ficheiros de instruções, não o fabricante a validá-los.

Que ficheiros devo pôr em revisão obrigatória?

No mínimo: AGENTS.md, CLAUDE.md, GEMINI.md, .clinerules, .cursorrules, e as pastas .cursor/, .claude/, .windsurf/ mais o .github/copilot-instructions.md. Acrescenta qualquer ficheiro de configuração MCP e qualquer SKILL.md da árvore. Depois corre uma busca recursiva, porque são as cópias encadeadas que escapam.

Dá para detetar com grep?

Em parte, e vale a pena. Procura comentários HTML no Markdown, caracteres Unicode de largura zero e bidirecionais, blobs em base64, e os verbos que importam: credentials, ~/.aws, ~/.kube, curl, env, export. O que o grep não consegue julgar é a intenção, porque as cargas eficazes leem-se como convenções de projeto normais. Na investigação do Hookify, cinco cargas apresentadas como convenções inócuas bastaram para provocar uma fuga de segredos.

Isto afeta também o Copilot e o Cursor, ou só o Claude Code?

Todos. O mecanismo é arquitetural, não próprio de um fabricante: todos os agentes mainstream têm uma convenção de instruções ao nível do repositório, e todos a carregam como orientação de projeto de confiança. Cobrimos as particularidades de cada um nos guias do Claude Code, do Cursor, do GitHub Copilot, do OpenAI Codex e do Windsurf.

Em que é diferente do slopsquatting?

O slopsquatting explora um nome de dependência alucinado para que uma instalação descarregue código do atacante, como explicámos em o que é o slopsquatting. A injeção por ficheiro de instruções não precisa de instalação nem de registo. Muda aquilo que o agente tenta fazer, em vez do código que acaba na árvore, e é por isso que a análise de dependências lhe é estruturalmente cega.

O que faço primeiro se achar que um agente seguiu um ficheiro envenenado?

Trata-o como um incidente de credenciais, não de código. Roda tudo o que o agente pudesse ler: chaves de cloud, kubeconfig, tokens de fornecedores, tudo o que estivesse no ambiente. Depois recupera o transcript da sessão do agente e lê as chamadas a tools por ordem, porque é o teu único registo fiável do que realmente foi executado. Olha para o diff só depois, já que nos casos documentados nenhum código tinha sido alterado.