clidey/deptrustServer CLI e MCP che controlla le versioni dei pacchetti per vulnerabilità note in oltre 14 ecosistemi tra cui npm, PyPI, crates.io, Go modules e GitHub Actions. Si integra con agenti AI tramite hook e skill.
# deptrust
```text
__ __ __
___/ /___ ___ / /________ _______/ /_
/ _ / __ \/ _ \/ __/ ___/ / / / ___/ __/
/ __/ /_/ / __/ /_/ / / /_/ (__ ) /_
\__,_/\____/ .___/\__/_/ \__,_/____/\__/
/_/
```
deptrust è un'interfaccia a riga di comando che controlla le versioni dei pacchetti per vulnerabilità note su npm, PyPI, crates.io, moduli Go, RubyGems, NuGet, Maven, Packagist, pub.dev, CocoaPods, Hex.pm, Hackage, GitHub Actions e altri.
Funziona localmente come CLI e come server MCP. Chiama direttamente le API dei registry pubblici e di OSV; non esiste un servizio deptrust ospitato da configurare o di cui fidarsi.
Questo strumento nasce dalla frustrazione degli agenti AI che usano costantemente versioni vecchie.
## Sommario
- [Scopo](#scopo)
- [Utilizzo CLI](#utilizzo-cli)
- [Installazione](#installazione)
- [Configurazione per agenti](#configurazione-per-agenti)
- [Configurazione manuale MCP](#configurazione-manuale-mcp)
- [Strumenti MCP](#strumenti-mcp)
- [Solo abilità (skill)](#solo-abilità-skill)
- [Risoluzione dei problemi](#risoluzione-dei-problemi)
## Scopo
Ecosistemi supportati:
- npm, inclusi pacchetti con scope come `@clidey/ux`
- PyPI
- Cargo / crates.io
- Moduli Go
- RubyGems
- NuGet
- Maven, usando nomi di pacchetto `groupId:artifactId`
- Packagist / Composer, usando nomi di pacchetto `vendor/package`
- pub.dev
- CocoaPods
- Hex.pm
- Hackage
- GitHub Actions, usando nomi di pacchetto `owner/repo` e tag, riferimenti a branch o SHA di commit come versioni
deptrust attualmente segnala vulnerabilità note e fornisce una raccomandazione semplice:
| Massima gravità nota | Raccomandazione |
| --- | --- |
| critical | blocca |
| high | blocca |
| medium / unknown | verifica |
| low | permetti |
| nessuna trovata | permetti |
`permetti` significa che non è stata trovata alcuna vulnerabilità nota bloccante nelle fonti di dati pubbliche. Non prova che un pacchetto sia sicuro.
deptrust emette anche segnali di rischio che non sono CVE. Ad esempio, una versione pubblicata nelle ultime 72 ore viene contrassegnata per verifica in modo che un agente non installi ciecamente una nuova release.
I fornitori di advisory vengono interrogati in parallelo:
- OSV
- Database Advisory di GitHub, inclusi advisory recensiti e advisory di malware
La copertura dei fornitori varia per ecosistema. Se deptrust riesce a risolvere i metadati del registry ma nessun fornitore di vulnerabilità configurato supporta quell'ecosistema, restituisce `unknown` invece di trattare il pacchetto come sicuro.
Copertura dei fornitori:
| Ecosistema | Metadati registry | OSV | DB Advisory GitHub |
| --- | --- | --- | --- |
| npm | sì | sì | sì |
| PyPI | sì | sì | sì |
| Cargo / crates.io | sì | sì | sì |
| Moduli Go | sì | sì | sì |
| RubyGems | sì | sì | sì |
| NuGet | sì | sì | sì |
| Maven | sì | sì | sì |
| Packagist / Composer | sì | sì | sì |
| pub.dev | sì | sì | sì |
| CocoaPods | sì | no | sì |
| Hex.pm | sì | sì | sì |
| Hackage | sì | sì | no |
| GitHub Actions | sì | sì | sì |
L'output JSON include i campi di copertura degli advisory:
- `checked_providers`: fornitori di vulnerabilità che deptrust ha effettivamente interrogato
- `skipped_providers`: fornitori configurati saltati perché l'ecosistema non è supportato
- `advisory_coverage`: `full`, `partial`, `none` o `error`
- `advisory_coverage_reason`: breve spiegazione del valore di copertura
- `registry_verification`: `verified` quando i metadati del registry hanno confermato la versione, o `unverified` quando un controllo di versione esatta è proseguito dopo un errore transitorio del registry
- `registry_verification_reason`: l'errore del registry quando la verifica non era disponibile
Un controllo di versione esatta interroga comunque i fornitori di advisory quando la verifica del registry non è temporaneamente disponibile. Tale risultato è sempre non installabile e non riceve mai una raccomandazione `allow`. I controlli per `latest`, pacchetti sconosciuti e versioni definitivamente inesistenti richiedono ancora una risoluzione riuscita del registry.
Le richieste HTTP ritentano le risposte `429`, `502`, `503` e `504` fino a tre tentativi totali. I tentativi usano brevi ritardi esponenziali e rispettano i valori `Retry-After` fino a due secondi; attese più lunghe richieste dal server falliscono rapidamente in modo che la CLI non si blocchi. I tentativi esauriti degli advisory rendono il risultato incompleto e impediscono una raccomandazione `allow`.
### Autenticazione API GitHub
Le richieste al Database Advisory GitHub e alle API di GitHub Actions possono utilizzare un token di GitHub App a breve durata e con privilegi minimi. In CI, passalo attraverso `DEPTRUST_GITHUB_TOKEN`:
```bash
DEPTRUST_GITHUB_TOKEN="$GITHUB_APP_TOKEN" deptrust check npm lodash 4.17.20
```
La precedenza delle credenziali è `DEPTRUST_GITHUB_TOKEN`, `GITHUB_TOKEN`, poi `GH_TOKEN`. Per uso locale, il fallback facoltativo della CLI GitHub è abilitato esplicitamente con `DEPTRUST_GITHUB_AUTH=gh deptrust check ...`; esegue `gh auth token` senza richiedere input. Se non è disponibile alcuna credenziale, DepTrust continua senza autenticazione. Un errore di limite di velocità o permesso dell'API GitHub produce `unknown` con diagnostica e non viene mai trattato come successo solo OSV.
DepTrust non memorizza mai, raggruppa, mette in cache, registra, teletrasmette né emette token GitHub. Le intestazioni di autenticazione vengono inviate solo a `https://api.github.com`.
## Utilizzo CLI
Controlla una versione esatta:
```bash
deptrust check npm lodash 4.17.20
```
Esempio di risposta normale:
```text
npm [email protected]: 2 vulnerabilità note trovate
raccomandazione: blocca
punteggio_rischio: 80
```
Controlla l'ultima versione:
```bash
deptrust check pypi requests latest
```
Restituisci JSON:
```bash
deptrust check --json cargo serde latest
```
Controlla un modulo Go:
```bash
deptrust check go golang.org/x/crypto latest
```
Controlla RubyGems, NuGet o Maven:
```bash
deptrust check rubygems rails latest
deptrust check nuget Newtonsoft.Json latest
deptrust check maven org.apache.logging.log4j:log4j-core latest
```
Controlla Packagist, pub.dev, CocoaPods, Hex.pm, Hackage o GitHub Actions:
```bash
deptrust check packagist monolog/monolog latest
deptrust check pub http latest
deptrust check cocoapods AFNetworking latest
deptrust check hex plug latest
deptrust check hackage aeson latest
deptrust check github-actions actions/checkout v7.0.0
deptrust check github-actions actions/checkout main
```
Per GitHub Actions, gli SHA di commit completi vengono trattati come fissati. I tag semver completi come `v4.2.2` sono accettati senza un segnale di fissaggio aggiuntivo. I tag solo major come `v4` e i riferimenti a branch come `main` sono riferimenti validi, ma deptrust aggiunge un segnale di verifica perché possono spostarsi.
Esempio di risposta JSON:
```json
{
"ecosystem": "npm",
"package": "lodash",
"version": "4.17.20",
"latest_version": "4.17.21",
"known_vulnerabilities_found": true,
"safe_to_use": false,
"should_install": false,
"risk_score": 80,
"recommendation": "block",
"classification": "vulnerable",
"reason": "Trovati 2 record di vulnerabilità note.",
"next_action": "non_installare; usa suggest_safe_version o compare_versions per scegliere una versione più sicura",
"summary": "lodash 4.17.20 ha 2 vulnerabilità note, tra cui ad alta gravità. Blocca questa versione esatta e preferisci una release corretta.",
"signals": [],
"checked_providers": [
"OSV",
"GitHub Advisory DB"
],
"skipped_providers": [],
"advisory_coverage": "full",
"advisory_coverage_reason": "tutti i fornitori di vulnerabilità configurati sono stati controllati",
"registry_verification": "verified",
"vulnerabilities": [
{
"id": "GHSA-35jh-r3h4-6jhm",
"aliases": [
"CVE-2021-23337"
],
"cve_ids": [
"CVE-2021-23337"
],
"ghsa_ids": [
"GHSA-35jh-r3h4-6jhm"
],
"summary": "Iniezione di comandi in lodash",
"severity": "high",
"source": "OSV",
"advisory_url": "https://github.com/advisories/GHSA-35jh-r3h4-6jhm",
"affected_ranges": [
"SEMVER: introdotta 0, corretta 4.17.21"
],
"fixed_versions": [
"4.17.21"
],
"references": [
{
"type": "ADVISORY",
"url": "https://github.com/advisories/GHSA-35jh-r3h4-6jhm"
}
]
}
],
"provider_errors": []
}
```
Suggerisci l'ultima versione solo quando non vengono trovate vulnerabilità note:
```bash
deptrust suggest npm lodash
```
Se l'ultima versione non è consentita, `suggest` controlla le versioni note precedenti e restituisce la versione più recente con una raccomandazione `allow`.
Quando gli advisory includono versioni corrette, `suggest` controlla prima quelle versioni corrette segnalate dal fornitore prima di tornare indietro nell'elenco delle versioni del registry.
Confronta due versioni:
```bash
deptrust compare npm lodash 4.17.20 4.17.21
```
Esempio di risposta di confronto:
```text
lodash 4.17.20 -> 4.17.21 migliora il rischio: punteggio da 80 a 0.
raccomandazione: permetti
prossima_azione: aggiorna_a_destinazione
```
Mostra la versione installata:
```bash
deptrust version
```
## Installazione
Il percorso di installazione più semplice è `npx` o `pnpx`:
```bash
npx @clidey/deptrust install
pnpx @clidey/deptrust@latest install
```
L'installatore predefinito è guidato. Installa il binario, chiede quali integrazioni con agenti configurare, stampa le destinazioni a livello utente prima di modificare qualsiasi cosa e chiede conferma. L'installatore guidato abilita per impostazione predefinita MCP, il fallback delle abilità e gli hook di sicurezza delle dipendenze per Codex e Claude Code. Aggiungi `--yes` per installazioni non interattive solo binario, oppure passa flag di integrazione espliciti.
Rieseguire l'installatore è sicuro. Lascia inalterate silenziosamente le configurazioni MCP, abilità e hook. Se un'integrazione punta a un vecchio binario deptrust o la sua configurazione gestita è cambiata, l'installatore la aggiorna automaticamente; gli utenti non devono rimuovere e riaggiungere manualmente i server MCP. Le abilità personalizzate vengono sottoposte a backup prima della sostituzione.
Per rimuovere il binario a livello utente, l'abilità e le voci MCP:
```bash
npx @clidey/deptrust uninstall
pnpx @clidey/deptrust@latest uninstall
```
Gli utenti Homebrew possono installare dal tap Clidey:
```bash
brew install clidey/tap/deptrust
```
Oppure aggiungi prima il tap, poi installa e aggiorna come al solito:
```bash
brew tap clidey/tap
brew install deptrust
brew upgrade deptrust
```
Homebrew stampa un promemoria dopo l'installazione. Per eseguire la configurazione guidata di Codex e Claude Code utilizzando il binario Homebrew stesso (registrazioni MCP e hook di sicurezza delle dipendenze):
```bash
deptrust setup
```
La configurazione guidata chiede prima di abilitare MCP e gli hook di sicurezza delle dipendenze. Lascia inalterate le registrazioni che usano già il binario corrente e riconcilia le registrazioni DepTrust esistenti che puntano a un vecchio percorso npm, Homebrew o installato da sorgente.
Gli utenti Go possono installare direttamente:
```bash
go install github.com/clidey/deptrust/cmd/deptrust@latest
```
### Nix
Il progetto fornisce output opzionali di flake Nix per utenti che già usano Nix. Il flake racchiude il binario di release precompilato.
```bash
# Esegui senza installare
nix run github:clidey/deptrust
# Installa nel tuo profilo
nix profile install github:clidey/deptrust
```
Il normale [flusso di lavoro di release](https://github.com/clidey/deptrust/blob/main/.github/workflows/release.yml) genera gli hash Nix dagli stessi archivi che pubblica, valuta il flake prima di pubblicare, poi lo costruisce e lo esegue contro gli asset pubblicati prima di aggiornare il ramo predefinito. `github:clidey/deptrust` potrebbe essere in breve ritardo mentre quel flusso di lavoro è in esecuzione. I tag di release puntano al commit sorgente precedente all'aggiornamento del flake generato e potrebbero ancora fare riferimento al binario precedente; fissa un commit il cui `flake.nix` contenga la versione che ti serve quando la riproducibilità è importante.
### Devbox
Per ambienti di sviluppo riproducibili, usa Devbox:
```bash
# Installa prima Devbox (se non già installato)
curl -fsSL https://get.jetify.dev/devbox | bash
# Inizializza l'ambiente
devbox shell
# Costruisci il progetto
devbox run build
```
`devbox.json` vincola la versione della toolchain e il `devbox.lock` committato fissa le versioni esatte dei pacchetti e le revisioni di nixpkgs. Esegui `devbox update` quando vuoi intenzionalmente aggiornare quei vincoli.
Oppure installa Devbox tramite Homebrew:
```bash
brew install jetify-com/devbox/devbox
```
## Configurazione per agenti
Per installare deptrust e registrare tutto ciò che l'installatore può configurare senza i prompt guidati:
```bash
npx @clidey/deptrust install --all
pnpx @clidey/deptrust@latest install --all
```
`--all` installa il binario, registra MCP di Codex quando la CLI `codex` è disponibile, installa il fallback dell'abilità Codex, registra MCP di Claude Code quando la CLI `claude` è disponibile e installa gli hook di sicurezza delle dipendenze per Codex e Claude Code.
Gli hook sono hook `PreToolUse`. Controllano i comandi di installazione dei pacchetti prima che vengano eseguiti e controllano anche le GitHub Actions aggiunte ai file di flusso di lavoro attraverso gli strumenti di modifica file degli agenti. Un hook blocca la chiamata dello strumento quando deptrust restituisce `review`, `block` o `unknown`. L'installatore scrive solo la configurazione dell'hook a livello utente: `~/.codex/hooks.json` per Codex e `~/.claude/settings.json` per Claude Code.
Quando la CLI `gh` è disponibile, la configurazione guidata offre anche di utilizzare il suo login locale esistente per i controlli degli hook. Questo scrive solo `DEPTRUST_GITHUB_AUTH=gh`, mai un token GitHub, in modo che i sottoprocessi degli hook possano evitare i limiti di velocità dell'API GitHub non autenticata.
Usa installazioni più ristrette quando preferito:
```bash
npx @clidey/deptrust install --codex-mcp
npx @clidey/deptrust install --claude-code-mcp
npx @clidey/deptrust skills install
pnpx @clidey/deptrust@latest install --codex-mcp
pnpx @clidey/deptrust@latest install --claude-code-mcp
pnpx @clidey/deptrust@latest skills install
```
Dopo la configurazione MCP, gli agenti controlleranno automaticamente i pacchetti prima di raccomandare aggiornamenti o modifiche. Il server MCP invia istruzioni per verificare tutte le versioni delle dipendenze — incluse risposte a domande come "cosa posso aggiornare" o "quali dipendenze sono sicure da aggiornare" — prima di fornire raccomandazioni.
Se usi deptrust in un contesto non MCP, ricorda al tuo agente:
```text
Prima di elencare, confrontare o raccomandare versioni specifiche di pacchetti, controllale con deptrust. Questo include rispondere a "cosa posso aggiornare" — non fornire raccomandazioni di versione finché non hai verificato la presenza di vulnerabilità note.
```
Per CI, configura un token di GitHub App a breve durata e con privilegi minimi come `DEPTRUST_GITHUB_TOKEN` per il processo che esegue DepTrust. Per l'autenticazione locale della CLI GitHub, usa `DEPTRUST_GITHUB_AUTH=gh deptrust check ...`. DepTrust non memorizza mai token.
## Configurazione manuale MCP
Se il tuo client supporta server MCP stdio, configura per eseguire:
```bash
/percorso/assoluto/di/deptrust mcp
```
Molti client usano questa forma JSON:
```json
{
"mcpServers": {
"deptrust": {
"command": "/percorso/assoluto/di/deptrust",
"args": ["mcp"]
}
}
}
```
Per Codex, puoi anche aggiungerlo con:
```bash
codex mcp add deptrust -- /percorso/assoluto/di/deptrust mcp
```
Per Claude Code:
```bash
claude mcp add --transport stdio deptrust -- /percorso/assoluto/di/deptrust mcp
```
Su `initialize`, il server restituisce `instructions` MCP che dicono all'agente quando usare questi strumenti (prima di aggiungere, aggiornare o raccomandare una dipendenza, o quando gli viene chiesto se una versione è sicura da aggiornare). I client che mostrano le istruzioni del server applicheranno questo automaticamente, quindi il promemoria manuale sopra è opzionale piuttosto che obbligatorio.
## Strumenti MCP
### `check_package`
Controlla una versione di un pacchetto e restituisce vulnerabilità note più una raccomandazione.
```json
{
"ecosystem": "npm",
"package": "lodash",
"version": "4.17.20"
}
```
`version` può essere omesso o impostato a `latest`. Se una versione esatta non esiste, deptrust restituisce un errore e suggerisce l'ultima versione esplicita.
L'output MCP è intenzionalmente compatto in modo che gli agenti possano decidere se installare una dipendenza senza includere i corpi completi degli advisory nel contesto. Se l'utente chiede di vedere i dettagli completi, l'agente può eseguire `full_response_command`.
Esempio di output strutturato MCP compatto:
```json
{
"ecosystem": "npm",
"package": "vite",
"version": "7.0.0",
"latest_version": "8.0.16",
"known_vulnerabilities_found": true,
"safe_to_use": false,
"should_install": false,
"risk_score": 80,
"classification": "vulnerable",
"recommendation": "block",
"reason": "Trovati 7 record di vulnerabilità note.",
"next_action": "non_installare; usa suggest_safe_version o compare_versions per scegliere una versione più sicura",
"summary": "vite 7.0.0 ha 7 vulnerabilità note, tra cui ad alta gravità. Blocca questa versione esatta e preferisci una release corretta.",
"vulnerability_count": 7,
"vulnerability_counts": {
"critical": 0,
"high": 2,
"medium": 3,
"low": 2,
"unknown": 0
},
"highest_severity": "high",
"checked_providers": [
"OSV",
"GitHub Advisory DB"
],
"skipped_providers": [],
"advisory_coverage": "full",
"advisory_coverage_reason": "tutti i fornitori di vulnerabilità configurati sono stati controllati",
"registry_verification": "verified",
"full_response_command": "deptrust check --json npm vite 7.0.0"
}
```
La risposta MCP compatta omette l'array delle vulnerabilità, i `details` degli advisory e i `references` ripetuti. Gli agenti dovrebbero usare i conteggi, la massima gravità, la copertura dei fornitori, la raccomandazione e la prossima azione per impostazione predefinita. Se l'utente chiede i dettagli completi dell'advisory, esegui `full_response_command`.
Quando l'accesso agli advisory GitHub è limitato dal tasso o non disponibile, MCP restituisce `unknown`. L'agente dovrebbe offrire proattivamente di configurare un token e riprovare, saltare o rimandare la versione, o procedere solo dopo che l'utente ha accettato esplicitamente il rischio di copertura irrisolta di GitHub per quella versione esatta. Tale eccezione deve rimanere chiaramente etichettata come incertezza accettata dall'utente; non deve essere segnalata come `allow` o come prova che la versione è sicura.
### `suggest_safe_version`
Controlla prima l'ultima versione. Se l'ultima non è consentita, controlla prima le versioni corrette segnalate dal fornitore, poi le versioni note precedenti e suggerisce la versione più recente con una raccomandazione `allow`.
```json
{
"ecosystem": "npm",
"package": "lodash"
}
```
### `compare_versions`
Confronta una versione corrente e una versione target, incluse vulnerabilità risolte e aggiunte.
```json
{
"ecosystem": "npm",
"package": "lodash",
"from_version": "4.17.20",
"to_version": "4.17.21"
}
```
## Solo abilità (skill)
Se non vuoi MCP, installa l'abilità Codex in bundle:
```bash
npx @clidey/deptrust skills install
```
L'abilità dice a Codex di chiamare la CLI `deptrust` prima di installare, aggiornare o raccomandare pacchetti npm, PyPI, Cargo, moduli Go, RubyGems, NuGet, Maven, Packagist, pub.dev, CocoaPods, Hex.pm, Hackage e GitHub Actions.
## Risoluzione dei problemi
Se `deptrust` non viene trovato:
```bash
export PATH="$HOME/.local/bin:$PATH"
```
Se un client MCP non riesce ad avviare il server, trova il percorso completo:
```bash
which deptrust
```
Poi inserisci quel percorso assoluto nella configurazione MCP.
Se un controllo del pacchetto restituisce `unknown`, non trattare il pacchetto come sicuro. Significa che deptrust non ha potuto ottenere una risposta completa da un fornitore di advisory o non ha potuto verificare la versione esatta con il suo registry.