Se hai intenzione 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 (non richiede Python)

Esegui SkillSpector senza installare Python, costruendo l'immagine localmente dal [Dockerfile](https://github.com/nvidia/skillspector/blob/HEAD/Dockerfile) incluso. L'immagine si basa sull'immagine Python ufficiale di Docker `3.12-slim-bookworm`.

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

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

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 impone due limiti indipendenti sugli input remoti e sugli archivi per contenere l'impatto di download sovradimensionati e zip bomb:

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

Nota che il limite di analisi di 1 MB per file (`MAX_FILE_BYTES`) è un limite separato e successivo: limita ciò che i singoli analizzatori leggono da una directory già acquisita. I limiti di acquisizione precedenti limitano la quantità di contenuto che può finire su disco in primo luogo. La violazione di uno dei due limiti di acquisizione fallisce in modalità chiusa 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/HEAD/contrib/batch_scan/.env.example) — il pool migliora la velocità effettiva
e la resilienza, a condizione che le chiavi non condividano un limite di velocità a livello di account.

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

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

### Soppressione dei falsi positivi (baseline)

Sopprimi i risultati noti/accettati così che il punteggio di rischio rifletta solo i problemi
non triage e le nuove scansioni mostrino solo *nuovi* risultati. Consulta la
[guida alla soppressione](https://github.com/nvidia/skillspector/blob/HEAD/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

### Server MCP

Esegui SkillSpector come server [Model Context Protocol](https://modelcontextprotocol.io)
così che qualsiasi agente compatibile con MCP (Claude Code, Codex CLI, Gemini CLI) o runtime
remoto possa richiamare la scansione come strumento e **condizionare le installazioni di skill/MCP al
risultato** — trasformando SkillSpector in una barriera di protezione 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

> **Security — modello di fiducia del trasporto HTTP**
>
> Il trasporto HTTP non include **autenticazione**. Qualsiasi chiamante che
> raggiunga la porta può invocare `scan_skill`. Via stdio o `127.0.0.1` questo
> è lo stesso confine di fiducia della CLI. Se ti leghi a un'interfaccia instradabile:
>
> - Posiziona il server dietro un proxy inverso con autenticazione (ad es. nginx + mTLS)
>   prima di esporlo esternamente.
> - I percorsi locali e gli URL `file://` vengono **rifiutati automaticamente** via HTTP
>   per impedire a chiamanti non autenticati di leggere file arbitrari dell'host. Vengono
>   accettati solo URL Git remoti e `.zip`.

## Pattern di vulnerabilità

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

### Iniezione di prompt (5 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| P1 | Instruction Override | HIGH | Comandi per ignorare i vincoli di sicurezza |
| P2 | Hidden Instructions | HIGH | Direttive dannose in commenti/testo invisibile |
| P3 | Exfiltration Commands | HIGH | Istruzioni per trasmettere il contesto all'esterno |
| P4 | Behavior Manipulation | MEDIUM | Istruzioni sottili che alterano le decisioni dell'agente |
| P5 | Harmful Content | CRITICAL | Istruzioni che potrebbero causare danni fisici |

### Anti-rifiuto (3 pattern)

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

### Esfiltrazione di dati (4 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| E1 | External Transmission | MEDIUM | Invio di dati a URL esterni |
| E2 | Env Variable Harvesting | HIGH | Raccolta di chiavi API e segreti |
| E3 | File System Enumeration | MEDIUM | Scansione delle directory per file sensibili |
| E4 | Context Leakage | HIGH | Trasmissione del contesto della conversazione all'esterno |

### Escalation dei privilegi (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 (6 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 Base64/hex |
| SC4 | Known Vulnerable Dependencies | HIGH | Dipendenze con CVE noti (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 |

### Agenzia eccessiva (4 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 velocità o quota sul consumo di risorse |

### Gestione dell'output (3 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| OH1 | Unvalidated Output Injection | HIGH | Output del modello utilizzato senza sanificazione |
| OH2 | Cross-Context Output | MEDIUM | L'output attraversa i confini di fiducia senza validazione |
| OH3 | Unbounded Output | MEDIUM | Nessun limite sulla dimensione dell'output o sulla velocità di generazione |

### Fuga del prompt di sistema (3 pattern)

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

### Avvelenamento della memoria (3 pattern)

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

### Uso improprio degli strumenti (3 pattern)

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

### Agente canaglia (2 pattern)

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

### Abuso dei trigger (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 |

### AST comportamentale (9 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| AST1 | exec() Call | CRITICAL | Chiamata diretta a exec() che abilita l'esecuzione di codice arbitrario |
| AST2 | eval() Call | HIGH | Chiamata diretta a eval() 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 arbitrario agli attributi con nomi non letterali |
| AST8 | Dangerous Execution Chain | CRITICAL | exec/eval combinati con sorgente dinamica (rete, dati codificati) |
| AST9 | Reflective getattr() Sink | HIGH | exec riflessiva tramite `getattr(os,'system')` / `getattr(builtins,'exec')` che elude AST1/AST5 |

### Tracciamento del taint (5 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| TT1 | Direct Taint Flow | HIGH | I dati fluiscono direttamente da una sorgente a un sink senza sanificazione |
| 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 | I contenuti dei file fluiscono verso sink di output di rete |
| TT5 | External Input to Code Execution | CRITICAL | L'input di rete o dell'utente fluisce verso sink exec/eval/subprocess |

### Firme YARA (4 pattern)

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

### Privilegio minimo MCP (4 pattern)

| ID | Pattern | Gravità | Descrizione |
|----|---------|----------|-------------|
| LP1 | Underdeclared Capability | HIGH | Il codice utilizza capacità non elencate nelle autorizzazioni dichiarate |
| LP2 | Wildcard Permission | MEDIUM | L'elenco delle autorizzazioni 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 |

### Avvelenamento degli strumenti MCP (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 con script misti nei metadati degli strumenti |
| TP3 | Parameter Description Injection | MEDIUM | Pattern di injection nelle definizioni dei parametri (override, token di sistema, default dannosi) |
| 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 precedenti.

## 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` esce con:

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

> Il codice di uscita riduce `SAFE` e `CAUTION` a `0`. Per agire in modo diverso su di essi (ad es. *avvisare* su `CAUTION` ma *bloccare* su `DO_NOT_INSTALL`), leggi il campo `recommendation` dall'output JSON invece di fare affidamento sul 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` compare 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 contatori di token. È una lista vuota quando l'utilizzo non è disponibile;
  SkillSpector non stima mai i token mancanti. I totali dei prompt includono la cache
  in lettura e in scrittura, così che la tariffazione a valle possa separare quelle partizioni in modo sicuro.
  `model_source` distingue un modello provider identificato indipendentemente da
  il modello esatto richiesto utilizzato quando l'identità della risposta è assente o ambigua.
  SkillSpector attualmente non invia controlli Anthropic prompt-cache, 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 [telemetria sull'utilizzo dell'inferenza](https://github.com/nvidia/skillspector/blob/HEAD/docs/INFERENCE_USAGE.md) per il
  contratto completo di provenienza, contabilità della cache, privacy, acquisizione fail-closed e
  prezzi a valle.
- La forma completa per problema è definita da `Finding.to_dict()` in [models.py](https://github.com/nvidia/skillspector/blob/HEAD/src/skillspector/models.py); fai affidamento sui campi sopra indicati e tratta qualsiasi campo aggiuntivo come best-effort.

Per gli strumenti CI/IDE, `--format sarif` emette SARIF 2.1.0.

### Mappatura consigliata del gate

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

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

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

## Sviluppo

### Configurazione

Tutti i target `make` presuppongono che un ambiente virtuale sia già stato 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 - vedi [LICENSE](https://github.com/nvidia/skillspector/blob/HEAD/LICENSE) per i dettagli.

## Contributi

I contributi sono benvenuti! Si prega di leggere le nostre linee guida per i contributi e inviare pull request.

## Supporto

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