Instruction file injection: come AGENTS.md e CLAUDE.md dirottano il tuo agente di codice

Che cos'è l'instruction file injection?

L'instruction file injection è un attacco di prompt injection indiretta in cui il payload vive in un file del repository che l'agente di codice carica come guida di progetto fidata, e non come input non affidabile. L'attaccante non parla mai al modello. Fa un commit, e l'agente lo legge al tuo posto, sulla tua macchina, con le tue credenziali.

Vale la pena essere precisi su perché questa è una classe diversa dalla prompt injection che tutti conoscono già. L'injection indiretta classica nasconde istruzioni in contenuti che il modello va a recuperare: una pagina web, un ticket Jira, il corpo di una issue. Il modello dovrebbe trattarli come dati, e il difetto è che a volte li tratta come istruzioni. L'instruction file injection ribalta l'impostazione. Questi file sono progettati per essere istruzioni. Caricarli come policy non è un bug, è la funzionalità documentata. CLAUDE.md esiste perché un repository possa spiegare all'agente come funziona il progetto. AGENTS.md esiste perché l'agente raccolga le convenzioni senza che nessuno gliele dica. Tutta la proposta di valore è che l'agente obbedisca al file.

Quindi la vulnerabilità non è "il modello ha confuso dati e istruzioni". La vulnerabilità è che il file fa autorità e la sua paternità non viene verificata. La Cloud Security Alliance lo ha scritto nero su bianco nella sua nota di ricerca di marzo 2026 sull'injection via README: questi file vengono caricati all'avvio della sessione e trattati con un livello di fiducia che si avvicina all'autorità del prompt di sistema, quindi un avversario in grado di modificarli controlla di fatto la policy comportamentale dell'agente per tutte le interazioni successive in quel repository.

“

Una dipendenza deve essere installata per farti danno. Un file di istruzioni deve solo essere letto.

Questa asimmetria è ciò che rende l'attacco economico. Gli attacchi alla supply chain dei pacchetti hanno bisogno di un registry, di un bump di versione, di un passo di installazione e in genere di uno script di ciclo di vita. L'instruction file injection ha bisogno di un file di testo e di qualcuno che apra la cartella. Non c'è nulla da rilevare all'installazione perché non si installa niente. Non c'è nulla da intercettare nel grafo delle dipendenze perché nessuna dipendenza è cambiata. E spesso non c'è nulla nemmeno nel diff, perché su un clone nuovo il diff non esiste.

I file che portano autorità da prompt di sistema

La prima mossa difensiva è conoscere la propria superficie di istruzioni. La maggior parte dei team la sottovaluta di un fattore cinque, perché pensa al "CLAUDE.md che abbiamo scritto" e dimentica il file di settings, la cartella degli skill, la configurazione MCP e le sovrascritture per sottodirectory.

Due righe meritano un secondo sguardo.

La riga .claude/settings.json non è una metafora. Gli hooks sono comandi shell che l'agente esegue attorno alle proprie chiamate alle tool, e sono definiti in un file che vive nel repository. Per questo esiste CVE-2025-59536: in Claude Code prima della versione 1.0.111 era possibile eseguire codice prima che l'utente accettasse la finestra di fiducia all'avvio, tramite hooks di progetto non affidabili definiti in .claude/settings.json. Punteggio CVSS v4.0 di 8.7. La correzione è arrivata in 1.0.111, e la lezione è sopravvissuta alla patch: un file JSON in un repository era una primitiva di esecuzione remota di codice perché l'agente era progettato per eseguire ciò che quel file dichiarava.

L'ultima riga è quella che non smette di crescere. Ogni superficie che un agente legge durante il lavoro ordinario è un canale candidato, e i ricercatori ne trovano di nuovi continuamente. La Cloud Security Alliance ha documentato prompt injection che raggiunge claude-code-action tramite GitHub Actions, e la ricerca GitInject, pubblicata a giugno 2026, ha catalogato casi reali di prompt injection nelle pipeline CI/CD guidate dall'IA. Se l'agente lo legge, un attaccante può scriverlo.

Perché la finestra di fiducia non è un confine di sicurezza

Tutti gli agenti seri mostrano oggi una richiesta di consenso la prima volta che apri una cartella sconosciuta. È un controllo davvero utile, ed è anche il più fraintendito della categoria, per quello che chiede realmente.

Chiede se ti fidi della directory. Non dice nulla, e non può dire nulla, sul contenuto dei file di istruzioni che contiene. Il consenso viene concesso alla granularità di una cartella e poi applicato a una quantità arbitraria di testo di policy controllato dall'attaccante. Ti fanno una domanda, una volta sola, e rispondi prima di aver letto una singola regola.

La dimostrazione più netta di questo divario è arrivata da Hookify, un plugin distribuito attraverso il marketplace ufficiale di Claude Code di Anthropic. Hookify è un motore di regole: legge file di regole dalla directory del progetto, espressi in Markdown con front matter YAML, e ne inietta il contenuto nel canale dei messaggi di sistema fidati del sottosistema hooks. I ricercatori di Pluto Security hanno riportato che un attaccante che depositi un file del genere in un repository ottiene così un canale di pilotaggio verso il modello, per qualunque utente abbia Hookify installato e apra quel repository. Contro Claude Opus 4.6, cinque payload comportamentali presentati come innocue convenzioni di progetto sono bastati a far rivelare al modello variabili d'ambiente e secret locali.

La risposta di Anthropic è la parte da interiorizzare. Il report è stato chiuso come Informative, working as designed: la finestra di fiducia della directory è il confine di sicurezza, e una volta accettata, la configurazione di progetto sotto .claude/, compresi CLAUDE.md, gli hooks di progetto e la configurazione dei plugin come i file di regole di Hookify, viene caricata intenzionalmente.

Quella risposta si difende nei suoi termini. Ed è anche un enunciato molto preciso del rischio residuo che ora è tuo.

È anche per questo che "basta leggere i file prima di accettare" non funziona nella pratica. La superficie di istruzioni è distribuita tra un file di settings, una cartella di regole, una convenzione Markdown per sottodirectory, una cartella di skill e una configurazione MCP. I payload si nascondono in commenti HTML che non rendono nulla. E appena cloni un monorepo, l'albero può contenere una dozzina di file di istruzioni annidati, e ognuno può sovrascrivere quelli sopra.

Anatomia dell'attacco: un minuto e cinquantuno

La prova tecnica avvelenata documentata da Mitiga a giugno 2026 è l'esempio pubblico più pulito, perché i timestamp mostrano esattamente quanto poco tempo ha un umano per intervenire.

Clonare un repository dall'aspetto normaleL'agente carica .cursor/rules, CLAUDE.md, i commenti del README, .cursor/mcp.jsonL'agente raccoglie credenziali cloud e di clusterL'agente esfiltra con una chiamata a una tool MCP

Leggi quella tabella come un esercizio di incident response e il problema salta agli occhi. La finestra tra la prima azione ostile e l'esfiltrazione completa è sotto i due minuti. Non c'è pull request. Non c'è build. Non c'è nessun artefatto da scansionare. Tutti i controlli che vivono a valle del commit stanno guardando nel posto sbagliato, perché l'attacco era finito prima che venisse scritta una riga di codice, e molto prima che venisse revisionata.

Nota anche ciò di cui l'attaccante non ha avuto bisogno. Nessuno zero-day. Nessun pacchetto malevolo. Nessun account di maintainer compromesso. Gli serviva un motivo plausibile perché tu clonassi un repository, che per chi assume o cerca lavoro è l'ingegneria sociale più facile del settore.

Sei modi per avvelenare un file di istruzioni

La prova tecnica è una via di consegna. Non è la parte interessante del modello di minaccia, perché richiede che tu cloni qualcosa di nuovo. Queste sono le vie che raggiungono repository di cui ti fidi già.

1. Il repository che ti hanno chiesto di clonare

Esercizi di colloquio, riproduzioni di bug, "dai un'occhiata a questo", repository di workshop di conferenza, template di partenza. Tutto ciò che arriva con un motivo legittimo per lanciare un agente dentro. Il caso Mitiga è questa via, e funziona perché la richiesta è autentica e il payload è invisibile.

2. Una pull request da un fork

È la via che scala, perché raggiunge il tuo repository senza alcuna ingegneria sociale. Se un workflow di agente gira con permessi di scrittura su eventi originati da fork, il branch di un contributor può aggiungere o modificare AGENTS.md, .clinerules o una cartella di regole, e l'agente leggerà la versione dell'attaccante. La catena Clinejection, divulgata pubblicamente il 9 febbraio 2026 e documentata da Snyk, è la versione industriale di questo: prompt injection attraverso i titoli delle issue ha trasformato il workflow di triage automatico di Cline in un vettore di attacco alla supply chain, e un attore ignoto lo ha usato per pubblicare una versione non autorizzata della CLI di Cline su npm durante una finestra di otto ore.

3. Uno skill o un plugin da marketplace

Gli skill degli agenti sono file di istruzioni dotati di un canale di distribuzione, che è la peggiore combinazione possibile. Lo studio ToxicSkills di Snyk sul registry ClawHub ha trovato prompt injection nel 36 % degli skill analizzati e catalogato 1.467 payload malevoli. Poiché gli skill persistono tra le sessioni una volta attivati, una singola decisione di installazione continua a modellare il comportamento dell'agente indefinitamente, in ogni repository che aprirai dopo. OWASP mantiene già un Agentic Skills Top 10, che ti dice a quale velocità questo è diventato una categoria a sé.

4. Uno scambio di configurazione MCP

.cursor/mcp.json e i suoi equivalenti dichiarano quali tool esistono e cosa dicono le loro descrizioni. Cambia la configurazione e cambi le azioni disponibili per l'agente; cambia la descrizione di una tool e cambi ciò che il modello capisce di quell'azione. È lo stesso meccanismo del tool poisoning MCP, che abbiamo coperto in sicurezza MCP e tool poisoning, che qui arriva da un file del repository invece che da un server.

5. Un file di istruzioni vendorizzato o transitivo

I file di istruzioni viaggiano. Un sottoalbero vendorizzato, un submodule git, un template generato, una cartella node_modules che l'agente decide di leggere: ognuno può portarsi il proprio AGENTS.md. Poiché la maggior parte degli agenti percorre l'albero e carica ciò che trova, un file annidato in fondo a una dipendenza può sovrascrivere senza rumore le convenzioni che hai scritto nella radice.

6. Il tuo stesso repository, dall'interno

La via meno spettacolare e la più probabile. I file di istruzioni sfuggono di solito alla cultura di review che circonda il codice sorgente. Non sono nel CODEOWNERS, non attivano nessun revisore obbligatorio, e si leggono come documentazione. Chiunque abbia accesso in scrittura, compreso un account di sviluppatore compromesso o un contributor bene intenzionato che ha copiato una regola da un articolo, può cambiare la policy operativa di tutti gli agenti del team senza che un solo occhio della sicurezza passi sul diff.

Cosa coprono i controlli nativi e cosa no

I vendor di agenti hanno consegnato controlli reali, e sarebbe disonesto lasciar credere il contrario. Le sandbox limitano dove finiscono le scritture. Le scale di approvazione creano checkpoint. I default di rete sono chiusi in diverse modalità cloud. Esistono allowlist e deny list di terminale. Antigravity include una allowlist di URL del browser proprio per tagliare la via di injection dalle pagine recuperate. Tutto questo riduce il rischio.

Il divario è più stretto e più preciso di "gli agenti non sono sicuri".

Detto semplicemente: i controlli parlano di capacità, e l'instruction file injection parla di autorità. Il sandboxing risponde a "cosa può toccare questo processo". Non ha nulla da dire su "di chi sono le istruzioni che il modello sta seguendo". Sono due assi ortogonali, ed è per questo che un agente perfettamente isolato leggerà volentieri un file di credenziali e lo passerà a una tool, se la policy che ha caricato gliel'ha chiesto.

È lo stesso punto strutturale che OWASP ripete sui sistemi agentici in produzione, dove la prompt injection resta il primo motore dei fallimenti di sicurezza invece di essere una categoria risolta.

Otto controlli che riducono davvero il rischio

Niente di tutto questo richiede un vendor nuovo. Quasi tutto è policy e impiantistica, e vale la pena farlo prima di comprare qualsiasi cosa.

Due cose che questa lista deliberatamente non dice. Non ti dice di smettere di usare file di istruzioni, perché sono il meccanismo che rende utili gli agenti su una codebase reale e togliierli equivale a farli tirare a indovinare. E non ti dice di leggere ogni file di regole prima di accettare una finestra di fiducia, perché quel consiglio non sopravvive al contatto con un monorepo.

Dove i controlli si fermano: i file di istruzioni sono codice che nessuno revisiona

Applica gli otto controlli sopra e avrai chiuso le vie di consegna che vedi. Quel che resta è il problema strutturale, ed è la ragione per cui abbiamo costruito CybeDefend così.

Un file di istruzioni è policy eseguibile che nessuna parte della tua toolchain legge come codice. Il tuo scanner SAST analizza codice sorgente; non analizza Markdown che riprogramma un agente. Il tuo scanner di dipendenze legge manifest; un file di regole non ha manifest. Il tuo scanner di secret cerca chiavi; questo payload non ne contiene. E la tua review della pull request, il posto dove la sicurezza applicativa vive da quindici anni, vede la modifica solo dopo che un agente ha passato una sessione a obbedirle. La cronologia Mitiga è la prova: l'intero incidente è finito 1 minuto e 51 secondi dopo l'apertura di una cartella, cioè circa mille volte più veloce del ciclo di review pensato per intercettarlo.

Questo scarto di cadenza è la tesi di tutto questo sito. La security review come cancello presupponeva un collo di bottiglia umano tra intenzione e codice. Gli agenti hanno rimosso il collo di bottiglia. Abbiamo scritto della forma generale del problema in sicurezza degli agenti di codice IA, e l'instruction file injection ne è il caso più affilato, perché qui il payload dell'attaccante e il manuale operativo dell'agente sono letteralmente lo stesso file.

Il controllo deve quindi stare dove la decisione viene presa, cioè dentro il ciclo dell'agente e non a valle.

In pratica questo significa tre cose per questa classe di attacco in particolare.

Le tue regole arrivano con più autorità di quelle del repository. VibeDefend si installa nell'agente come server MCP più hooks, il che significa che la policy ricevuta dal modello è quella scritta dalla tua organizzazione, non quella che si trovava committata nella cartella. Un file del repository che chiede all'agente di leggere ~/.aws/credentials ora discute contro una regola arrivata prima.

Il guardiano agisce sull'azione, non sul diff. Gli hooks valutano la chiamata alla tool prima che venga eseguita. Leggere un file di credenziali, mandare un dump dell'ambiente in curl, invocare una tool la cui descrizione è cambiata da ieri: sono decisioni che l'agente prende in piena sessione, e sono l'unico posto dove un controllo può ancora dire no.

I finding sono nel ciclo, non in un dashboard. L'agente ha accesso live a ciò che i nostri scanner hanno trovato su codice, dipendenze, secret, infrastruttura e pipeline, quindi quando propone una modifica ragiona sullo stato di sicurezza reale del repository invece di indovinare. È anche quello che gli permette di notare che la pipeline che gli hanno appena chiesto di modificare gira su eventi di fork con permessi di scrittura.

Niente di tutto questo elimina il bisogno degli otto controlli. Cambia cosa succede nello spazio che non possono chiudere, cioè i novanta secondi tra l'apertura di una cartella e l'uscita di un secret.

Domande frequenti

Un file Markdown può davvero eseguire codice?

Non da solo, ed è questo che lo rende efficace. Il Markdown fornisce le istruzioni; l'agente fornisce l'esecuzione. Se l'agente ha accesso alla shell e l'auto-approve attivo, un file di istruzioni è funzionalmente uno script il cui interprete è il modello. L'unico caso in cui il file si avvicina a un'esecuzione letterale è un file di settings che dichiara hooks, il che ha reso CVE-2025-59536 un'esecuzione remota di codice in Claude Code prima della 1.0.111.

È sicuro committare un AGENTS.md o un CLAUDE.md?

Sì, e dovresti. Il rischio non è averlo, è che nessuno ne sia proprietario. Metti il file nel CODEOWNERS con un revisore di sicurezza, richiedi review sulle modifiche, e verifica le copie annidate più in basso nell'albero. Il problema è un file di istruzioni non revisionato; uno revisionato è documentazione che configura anche i tuoi agenti.

La finestra di fiducia mi protegge?

Protegge la directory, non il contenuto. Anthropic ha enunciato questa posizione esplicitamente chiudendo il report Hookify: una volta accettata la finestra di fiducia della directory, la configurazione di progetto sotto .claude/, compresi CLAUDE.md, gli hooks di progetto e i file di regole dei plugin, viene caricata intenzionalmente. Accettare la finestra sei tu che rispondi per i file di istruzioni, non il vendor che li valida.

Quali file mettere in review obbligatoria?

Come minimo: AGENTS.md, CLAUDE.md, GEMINI.md, .clinerules, .cursorrules, e le cartelle .cursor/, .claude/, .windsurf/ più .github/copilot-instructions.md. Aggiungi qualunque file di configurazione MCP e qualunque SKILL.md dell'albero. Poi lancia una ricerca ricorsiva, perché sono le copie annidate quelle che sfuggono.

Si può rilevare con grep?

In parte, e vale la pena. Cerca i commenti HTML nel Markdown, i caratteri Unicode a larghezza zero e bidirezionali, i blob in base64, e i verbi che contano: credentials, ~/.aws, ~/.kube, curl, env, export. Quello che grep non può giudicare è l'intenzione, perché i payload efficaci si leggono come normali convenzioni di progetto. Nella ricerca Hookify, cinque payload presentati come convenzioni innocue sono bastati a provocare una fuga di secret.

Riguarda anche Copilot e Cursor, o solo Claude Code?

Tutti. Il meccanismo è architetturale, non proprio di un vendor: ogni agente mainstream ha una convenzione di istruzioni a livello di repository, e ognuno la carica come guida di progetto fidata. Copriamo le specificità di ciascuno nelle guide di Claude Code, Cursor, GitHub Copilot, OpenAI Codex e Windsurf.

In cosa è diverso dallo slopsquatting?

Lo slopsquatting sfrutta un nome di dipendenza allucinato perché un'installazione scarichi codice dell'attaccante, come abbiamo spiegato in che cos'è lo slopsquatting. L'instruction file injection non ha bisogno né di installazione né di registry. Cambia ciò che l'agente cerca di fare, invece del codice che finisce nell'albero, ed è per questo che la scansione delle dipendenze le è strutturalmente cieca.

Cosa faccio per primo se penso che un agente abbia seguito un file avvelenato?

Trattalo come un incidente di credenziali, non di codice. Ruota tutto ciò che l'agente poteva leggere: chiavi cloud, kubeconfig, token dei provider, qualunque cosa fosse nell'ambiente. Poi recupera il transcript della sessione dell'agente e leggi le chiamate alle tool in ordine, perché è il tuo unico registro affidabile di ciò che è stato davvero eseguito. Guarda il diff solo dopo, dato che nei casi documentati nessun codice era stato modificato.