SkillSpector: analizzare le skill AI prima di installarle

Una skill scaricata dal web può estendere rapidamente Codex, Claude Code, Gemini CLI e altri agenti AI. Può però anche introdurre istruzioni malevole, script pericolosi o dipendenze vulnerabili nello stesso ambiente in cui conservi repository, chiavi SSH, token cloud e credenziali di deployment.

Il rischio più insidioso è proprio questo: potresti aprire una falla senza accorgertene. La skill potrebbe apparire utile e ben documentata, mentre un'istruzione nascosta o un file di supporto induce l'agente a leggere segreti, eseguire comandi, inviare dati verso l'esterno o richiedere privilegi non necessari.

SkillSpector è uno scanner open source di NVIDIA progettato per analizzare le skill degli agenti AI prima dell'installazione. Non certifica che una skill sia innocua, ma aggiunge un controllo tecnico ripetibile prima di concederle fiducia.

Regola pratica: non installare direttamente una skill trovata online. Scaricala o analizzala in un ambiente isolato, esegui una scansione dell'intero bundle e verifica manualmente istruzioni, script, dipendenze e permessi richiesti.

Perché una skill AI può diventare una vulnerabilità

Una skill non è necessariamente un singolo file SKILL.md. Può contenere anche:

script Python, JavaScript o shell;
riferimenti e file che l'agente deve leggere;
comandi per installare pacchetti;
indicazioni per accedere al filesystem o alla rete;
configurazioni MCP e richieste di nuovi strumenti;
istruzioni che modificano il comportamento dell'agente.

Quando l'agente usa la skill, interpreta quelle istruzioni nel contesto della sessione e può invocare gli strumenti che gli hai autorizzato. Se la sessione può leggere il repository, usare il terminale o raggiungere servizi esterni, anche una skill può tentare di sfruttare quelle capacità.

Immagina una skill che promette di automatizzare il controllo di una pipeline. Tra le istruzioni potrebbe chiedere all'agente di cercare variabili d'ambiente, leggere file di configurazione o eseguire uno script remoto. Se il comportamento viene presentato come un passaggio necessario, l'operazione può sembrare legittima e confondersi tra i normali comandi di lavoro.

Il pericolo non richiede sempre malware tradizionale. Può bastare una combinazione di:

prompt injection inserita nelle istruzioni;
accesso eccessivo a file, shell o rete;
dipendenze non fissate o vulnerabili;
comandi come download ed esecuzione di script remoti;
comportamento diverso da quello dichiarato nella descrizione;
persistenza di istruzioni nel contesto o nella memoria dell'agente.

Inoltre, installare una skill non significa necessariamente eseguirne subito ogni componente. Il rischio si concretizza quando l'agente la carica, la richiama o segue le sue istruzioni. Renderla disponibile senza averla verificata introduce comunque una nuova superficie di attacco.

Un rischio misurato anche dalla ricerca

Lo studio Agent Skills in the Wild, pubblicato nel 2026, ha raccolto 42.447 skill da due marketplace e ne ha analizzate 31.132. I ricercatori hanno rilevato almeno una vulnerabilità nel 26,1% del campione analizzato e pattern ad alta severità compatibili con un possibile intento malevolo nel 5,2% dei casi.

Lo stesso lavoro ha osservato che le skill contenenti script eseguibili avevano una probabilità 2,12 volte maggiore di presentare vulnerabilità rispetto a quelle composte soltanto da istruzioni.

Questi numeri descrivono lo specifico dataset e la metodologia dello studio: non significano che il 26,1% di tutte le skill disponibili online sia certamente vulnerabile. Dimostrano però che trattare una skill come contenuto automaticamente affidabile non è una scelta prudente.

Che cos'è SkillSpector

SkillSpector esegue una combinazione di analisi statica e, facoltativamente, analisi semantica tramite un modello linguistico. Al 12 agosto 2026, il README del progetto dichiara 69 pattern di vulnerabilità suddivisi in 17 categorie.

Tra i controlli principali rientrano:

prompt injection e istruzioni nascoste;
esfiltrazione di dati e raccolta di variabili d'ambiente;
accesso a credenziali e richieste di privilegi elevati;
download ed esecuzione di script esterni;
dipendenze vulnerabili tramite interrogazione di OSV.dev;
codice offuscato, pattern pericolosi, analisi AST e taint tracking;
abuso degli strumenti ed eccessiva autonomia;
memory poisoning e perdita del system prompt;
configurazioni MCP con privilegi eccessivi o tool poisoning;
firme YARA e file eseguibili sospetti.

Può analizzare repository Git, URL, archivi ZIP, directory locali o singoli file. I report possono essere prodotti in formato terminale, JSON, Markdown o SARIF, quindi lo scanner può essere usato sia manualmente sia come controllo di una pipeline CI/CD.

La release più recente disponibile durante la stesura di questo articolo è la v2.9.3 dell'11 agosto 2026. Il progetto è distribuito con licenza Apache 2.0 e richiede Python 3.12 o successivo.

Installare SkillSpector

Il metodo rapido documentato dal progetto usa uv:

uv tool install git+https://github.com/NVIDIA/skillspector.git
skillspector --version

In un ambiente aziendale o in CI è preferibile fissare una release o un commit già verificato, invece di installare ogni volta lo stato corrente del branch principale. Anche lo strumento di sicurezza fa parte della supply chain e deve essere aggiornato in modo controllato.

Puoi usare anche l'immagine Docker costruita dal repository ufficiale:

git clone --branch v2.9.3 --depth 1 https://github.com/NVIDIA/skillspector.git
cd skillspector
docker build -t skillspector:v2.9.3 .

L'isolamento del container riduce l'esposizione del sistema host, ma non sostituisce la verifica dell'immagine, del tag e del codice usato per costruirla.

Analizzare una skill prima dell'installazione

Per una prima verifica veloce puoi eseguire soltanto l'analisi statica:

skillspector scan https://github.com/utente/skill-da-verificare --no-llm

Puoi analizzare una directory già scaricata senza doverla copiare nella cartella delle skill attive:

skillspector scan ./skill-da-verificare --no-llm

Oppure produrre un report JSON utilizzabile da uno script:

skillspector scan ./skill-da-verificare \
  --no-llm \
  --format json \
  --output skillspector-report.json

Per conservare un report leggibile durante una revisione:

skillspector scan ./skill-da-verificare \
  --no-llm \
  --format markdown \
  --output skillspector-report.md

La scansione deve comprendere l'intera directory, non soltanto SKILL.md. Una descrizione pulita non esclude che il comportamento pericoloso si trovi in scripts/, nei file di configurazione, nelle dipendenze o in altri contenuti richiamati dalla skill.

Analisi statica e analisi semantica

L'opzione --no-llm è utile per un controllo rapido e ripetibile. Individua firme, costrutti e flussi noti senza inviare il contenuto a un provider LLM.

L'analisi semantica prova invece a riconoscere incongruenze di intento e istruzioni rischiose che non corrispondono a un semplice pattern. SkillSpector supporta provider remoti, endpoint compatibili con OpenAI e runtime CLI locali, tra cui Codex CLI e Claude CLI.

Prima di attivare un provider remoto valuta però la riservatezza del materiale: il contenuto della skill può includere codice proprietario o informazioni che non devono lasciare il tuo ambiente. Per casi sensibili, usa l'analisi statica e un modello locale compatibile, oppure applica le policy previste dalla tua organizzazione.

Come leggere il risultato

SkillSpector calcola un punteggio di rischio da 0 a 100, assegna una severità e restituisce una raccomandazione:

Raccomandazione	Azione consigliata
`SAFE`	Consentire soltanto dopo la revisione manuale prevista
`CAUTION`	Fermarsi, comprendere i finding e accettare il rischio per iscritto
`DO_NOT_INSTALL`	Bloccare l'installazione finché i problemi non sono stati corretti

Un dettaglio importante per la CI: il comando termina con codice 0 sia per SAFE sia per CAUTION, purché il punteggio sia minore o uguale a 50. Il codice 1 indica DO_NOT_INSTALL, mentre il codice 2 segnala un errore di scansione.

Se la tua policy deve ammettere esclusivamente SAFE, non basarti soltanto sull'exit code. Genera il JSON e verifica esplicitamente il campo recommendation:

set +e
skillspector scan ./skill-da-verificare \
  --no-llm \
  --format json \
  --output skillspector-report.json
scan_status=$?
set -e

if [ "$scan_status" -eq 2 ]; then
  echo "Scansione non completata"
  exit 2
fi

jq -e '.recommendation == "SAFE"' skillspector-report.json

In una pipeline più completa puoi salvare anche un report SARIF, bloccare automaticamente i finding critici e alti e richiedere l'approvazione di un revisore per quelli medi. Le eccezioni dovrebbero essere tracciate tramite baseline o fingerprint, non ignorate genericamente.

SkillSpector non garantisce che una skill sia sicura

Lo scanner riduce il rischio, ma non può dimostrare l'assenza di comportamento malevolo. La documentazione ufficiale indica alcuni limiti precisi:

l'analisi statica non osserva il comportamento reale durante l'esecuzione;
contenuti non inglesi possono sfuggire ad alcuni pattern;
testo nascosto in immagini non viene analizzato;
codice compilato, binario o cifrato può risultare opaco;
senza accesso a OSV.dev, il controllo delle vulnerabilità usa una lista offline più limitata;
falsi positivi e falsi negativi restano possibili.

Un risultato SAFE significa quindi che lo scanner non ha rilevato rischi sufficienti con i controlli eseguiti. Non significa che il codice sia stato formalmente verificato, che il maintainer sia affidabile o che la skill non possa comportarsi diversamente a runtime.

Anche una firma crittografica ha uno scopo diverso: prova provenienza e integrità dell'artefatto firmato, non la sua sicurezza. La difesa più solida combina scansione, revisione, provenienza, isolamento e privilegi minimi.

È lo stesso principio discusso in Prompt non basta: servono vincoli architetturali: l'AI diventa affidabile quando opera entro limiti verificabili, non quando ci fidiamo soltanto dell'output che produce.

Workflow consigliato per skill di terze parti

Prima di rendere disponibile una skill a un agente:

Identifica la fonte. Controlla maintainer, repository originale, cronologia, release e licenza.
Fissa la versione. Usa un tag o un commit preciso e registra l'hash analizzato.
Scarica in quarantena. Non copiare subito la directory tra le skill attive.
Scansiona tutto il bundle. Includi SKILL.md, script, riferimenti, configurazioni e dipendenze.
Leggi ogni finding. Verifica se il comportamento è necessario e coerente con lo scopo dichiarato.
Esegui una revisione manuale. Cerca accessi a segreti, rete, shell, filesystem, sudo, download ed esecuzione remota.
Prova in un ambiente isolato. Usa un container o una VM senza credenziali reali e con rete limitata.
Applica il minimo privilegio. Concedi all'agente soltanto strumenti, directory e destinazioni di rete indispensabili.
Monitora l'esecuzione. Registra comandi, connessioni in uscita, file modificati e richieste di autorizzazione.
Ripeti il controllo a ogni aggiornamento. Una versione successiva può introdurre file o comportamenti nuovi.

Questo approccio è particolarmente importante sulle workstation DevOps: un agente può trovarsi nello stesso contesto di kubeconfig, token GitHub, credenziali cloud, chiavi SSH, file .env e accessi alle pipeline. Una skill compromessa non deve necessariamente sfruttare una CVE del sistema operativo: può abusare delle autorizzazioni già concesse all'agente.

Se hai già installato una skill sospetta

Se una scansione o una revisione evidenzia un comportamento inatteso:

disabilita la skill e interrompi le sessioni che l'hanno caricata;
conserva una copia della versione installata, dei report e dei log;
verifica comandi eseguiti, file letti o modificati e connessioni in uscita;
controlla le directory accessibili all'agente e gli eventuali meccanismi di persistenza;
revoca o ruota i segreti potenzialmente esposti;
confronta l'artefatto con il commit o la release attesa;
ripristina l'ambiente da una base attendibile se l'esecuzione malevola è confermata.

La sola rimozione della skill non annulla le azioni già compiute. Se l'agente aveva accesso a credenziali o infrastrutture, l'analisi deve estendersi ai servizi raggiungibili con quei privilegi.

Conclusione

Le skill rendono gli agenti AI più utili, ma trasformano istruzioni e file scaricati dal web in una parte della supply chain operativa. Trattarle come semplici prompt significa sottovalutare la capacità dell'agente di leggere dati, eseguire comandi e interagire con sistemi reali.

SkillSpector aggiunge un controllo concreto prima dell'installazione e può diventare un gate della pipeline. Il suo verdetto deve però restare uno degli elementi della decisione, insieme a revisione umana, firma, isolamento, versioni fissate e minimo privilegio.

Se devi introdurre agenti AI, skill o server MCP in un ambiente aziendale, posso aiutarti a definire un processo di verifica, hardening e monitoraggio coerente con i privilegi e i dati realmente presenti nell'infrastruttura.

Contattami per una valutazione tecnica.