SkillSpector

Scanner di sicurezza per le skill degli agenti AI. Rileva vulnerabilità, pattern malevoli e rischi di sicurezza prima di installare le skill degli agenti.

Panoramica

Le skill degli agenti AI (utilizzate da Claude Code, Codex CLI, Gemini CLI, ecc.) vengono eseguite con fiducia implicita e una verifica minima. Nel sottoinsieme di 31.132 skill analizzate del dataset di ricerca, il 26,1% delle skill contiene vulnerabilità e il 5,2% mostra una probabile intenzione malevola.

SkillSpector ti aiuta a rispondere alla domanda: "Questa skill è sicura da installare?"

SkillSpector fa parte della pipeline NVIDIA Verified Skills, che analizza, valuta e firma le skill degli agenti prima della pubblicazione. Le skill che superano i controlli vengono pubblicate nel catalogo delle skill NVIDIA.

Documentazione

• Scansiona le skill degli agenti prima dell'installazione — Guida ospitata: quando eseguire la scansione, come leggere un report e come bloccare le installazioni.
• Guida allo sviluppo — Architettura, struttura dei pacchetti e come estendere la pipeline di analisi.
• Limiti delle risorse di analisi — Limiti fail-closed per bundle, parser, artefatti annidati, ledger e risultati.
• Estensione Pi — Installa SkillSpector come strumento Pi per scansionare le skill dall'interno delle sessioni degli agenti.
• Estensione OpenCode — Installa SkillSpector come strumento OpenCode e comando /skillspector per scansionare le skill dall'interno delle sessioni degli agenti.

Funzionalità

• Input multi-formato: scansiona repository Git, URL, file zip, directory o singoli file
• 71 pattern di vulnerabilità in 17 categorie: prompt injection, esfiltrazione di dati, escalation dei privilegi, supply chain, agenzia eccessiva, gestione dell'output, fuga del system prompt, avvelenamento della memoria, uso improprio degli strumenti, agente canaglia, anti-rifiuto, abuso dei trigger, codice pericoloso (AST), taint tracking, firme YARA, privilegio minimo MCP e avvelenamento degli strumenti MCP
• Analisi in due fasi: analisi statica rapida + valutazione semantica LLM opzionale
• Ricerca di vulnerabilità in tempo reale: SC4 interroga OSV.dev per dati CVE in tempo reale con fallback offline automatico
• Molteplici formati di output: report in Terminale, JSON, Markdown e SARIF
• Punteggio di rischio: punteggio da 0 a 100 con etichette di gravità e raccomandazioni chiare
• Baseline / soppressione dei falsi positivi: accetta risultati noti tramite una baseline a regole glob o fingerprint, così le nuove scansioni mostrano solo i problemi nuovi (documentazione)

Avvio rapido

Installazione

Avviso sul software open source: Questo progetto scaricherà e installerà ulteriori progetti software open source di terze parti. Consulta i termini di licenza di questi progetti open source prima dell'uso.

Crea e attiva prima un ambiente virtuale (tutti i target make presuppongono che il venv sia attivo). Usa uv o pip; il Makefile usa uv se disponibile, altrimenti pip.

Installazione rapida con uv (solo CLI):

uv tool install git+https://github.com/NVIDIA/skillspector.git
# Update later: uv tool update skillspector

Se hai intenzione di eseguire skillspector mcp, installa l'extra MCP al momento dell'installazione:

uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'

Dall'origine:

# Clone the repository
git clone https://github.com/NVIDIA/skillspector.git
cd skillspector

# Create and activate virtual environment
uv venv .venv && source .venv/bin/activate
# or: python3 -m venv .venv && source .venv/bin/activate

# Install for production use
make install

# Or install with development dependencies
make install-dev

Docker (nessun Python richiesto)

Esegui SkillSpector senza installare Python compilandolo localmente dal Dockerfile incluso. L'immagine si basa sull'immagine Docker Official Python 3.12-slim-bookworm.

Compila l'immagine:

make docker-build
# or: docker build -t skillspector .

Scansiona una directory locale montando la tua directory corrente in /scan, la directory di lavoro del container:

docker run --rm -v "$PWD:/scan" skillspector scan ./my-skill/ --no-llm

Scansione con analisi LLM passando le credenziali tramite un file .env locale:

cat > .env <<'EOF'
SKILLSPECTOR_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
EOF

docker run --rm \
  -v "$PWD:/scan" \
  --env-file .env \
  skillspector scan ./my-skill/

Oppure passa le credenziali direttamente dal tuo ambiente shell:

docker run --rm \
  -v "$PWD:/scan" \
  -e SKILLSPECTOR_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  skillspector scan ./my-skill/

Scrivi un report sul filesystem host scrivendo nella directory montata:

docker run --rm --user "$(id -u):$(id -g)" \
  -v "$PWD:/scan" \
  skillspector scan ./my-skill/ --no-llm --format json --output report.json

Alias opzionale per scansioni statiche ripetute:

alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'
skillspector-docker scan ./my-skill/ --no-llm

Utilizzo di base

# Scan a local skill directory
skillspector scan ./my-skill/

# Scan a single SKILL.md file
skillspector scan ./SKILL.md

# Scan a Git repository
skillspector scan https://github.com/user/my-skill

# Scan a zip file
skillspector scan ./my-skill.zip

Limiti di dimensione

SkillSpector applica due limiti indipendenti sugli input remoti e sugli archivi per contenere l'impatto di download sovradimensionati e zip bomb:

• Limite per ingestione: INGEST_MAX_BYTES (100 MiB) — applicato ai download URL in streaming, alla dimensione totale non compressa degli archivi zip e all'utilizzo del disco post-clone dei repository Git.
• Limite per membro zip: INGEST_MAX_ZIP_MEMBERS (10.000) — limita il numero di voci in un singolo zip.

Si noti che il limite di analisi di 1 MB per file (MAX_FILE_BYTES) è un limite separato e a valle: delimita ciò che i singoli analizzatori leggeranno da una directory già ingerita. I limiti di ingestione sopra indicati delimitano invece quanti contenuti possono essere effettivamente scritti su disco. Una violazione di uno dei due limiti di ingestione fallisce in modo sicuro con un IngestLimitExceededError.

Formati di output

# Terminal output (default) - pretty formatted
skillspector scan ./my-skill/

# JSON output - machine readable
skillspector scan ./my-skill/ --format json --output report.json

# Markdown output - for documentation
skillspector scan ./my-skill/ --format markdown --output report.md

# SARIF output - for CI/CD integration and IDE tooling
skillspector scan ./my-skill/ --format sarif --output report.sarif

Scansione in batch

Scansiona intere directory di skill in parallelo da contrib/batch_scan/: