clidey/deptrustServidor CLI y MCP que comprueba las versiones de paquetes en busca de vulnerabilidades conocidas en más de 14 ecosistemas, incluidos npm, PyPI, crates.io, módulos de Go y GitHub Actions. Se integra con agentes de IA mediante hooks y skills.
# deptrust
```text
__ __ __
___/ /___ ___ / /________ _______/ /_
/ _ / __ \/ _ \/ __/ ___/ / / / ___/ __/
/ __/ /_/ / __/ /_/ / / /_/ (__ ) /_
\__,_/\____/ .___/\__/_/ \__,_/____/\__/
/_/
```
deptrust es una CLI que comprueba las versiones de paquetes en busca de vulnerabilidades conocidas en npm, PyPI, crates.io, módulos de Go, RubyGems, NuGet, Maven, Packagist, pub.dev, CocoaPods, Hex.pm, Hackage, GitHub Actions y más.
Funciona localmente como CLI y como servidor MCP. Llama directamente a las APIs públicas de los registros de paquetes y a las de OSV; no hay ningún servicio de deptrust alojado en el que confiar o que configurar.
Esta herramienta nació de la frustración que supone que los agentes de IA utilicen constantemente versiones antiguas.
## Contenido
- [Alcance](#alcance)
- [Uso de la CLI](#uso-de-la-cli)
- [Instalación](#instalación)
- [Configuración de agentes](#configuración-de-agentes)
- [Configuración manual de MCP](#configuración-manual-de-mcp)
- [Herramientas MCP](#herramientas-mcp)
- [Uso solo con skill](#uso-solo-con-skill)
- [Solución de problemas](#solución-de-problemas)
## Alcance
Ecosistemas compatibles:
- npm, incluidos los paquetes con ámbito (scoped) como `@clidey/ux`
- PyPI
- Cargo / crates.io
- Módulos de Go
- RubyGems
- NuGet
- Maven, con nombres de paquete `groupId:artifactId`
- Packagist / Composer, con nombres de paquete `vendor/package`
- pub.dev
- CocoaPods
- Hex.pm
- Hackage
- GitHub Actions, con nombres de paquete `owner/repo` y etiquetas, referencias de rama o SHAs de commit como versiones
deptrust actualmente informa de vulnerabilidades conocidas y ofrece una recomendación sencilla:
| Severidad máxima conocida | Recomendación |
| --- | --- |
| critical | block |
| high | block |
| medium / unknown | review |
| low | allow |
| none found | allow |
`allow` significa que no se encontró ninguna vulnerabilidad conocida bloqueante en las fuentes de datos públicas. No demuestra que un paquete sea seguro.
deptrust también emite señales de riesgo que no son CVEs. Por ejemplo, una versión publicada en las últimas 72 horas se marca para revisión para que un agente no instale a ciegas una versión recién publicada.
Los proveedores de avisos se consultan en paralelo:
- OSV
- GitHub Advisory Database, incluidos los avisos revisados y los avisos de malware
La cobertura de proveedores varía según el ecosistema. Si deptrust puede resolver los metadatos del registro pero ningún proveedor de vulnerabilidades configurado es compatible con ese ecosistema, devuelve `unknown` en lugar de tratar el paquete como seguro.
Cobertura de proveedores:
| Ecosistema | Metadatos del registro | OSV | GitHub Advisory DB |
| --- | --- | --- | --- |
| npm | sí | sí | sí |
| PyPI | sí | sí | sí |
| Cargo / crates.io | sí | sí | sí |
| Módulos de 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í |
La salida JSON incluye campos de cobertura de avisos:
- `checked_providers`: los proveedores de vulnerabilidades que deptrust consultó realmente
- `skipped_providers`: los proveedores configurados que se omitieron porque el ecosistema no es compatible
- `advisory_coverage`: `full`, `partial`, `none` o `error`
- `advisory_coverage_reason`: una breve explicación del valor de cobertura
- `registry_verification`: `verified` cuando los metadatos del registro confirmaron la versión, o `unverified` cuando una comprobación de versión exacta continuó tras un fallo transitorio del registro
- `registry_verification_reason`: el error del registro cuando la verificación no estuvo disponible
Una comprobación de versión exacta sigue consultando a los proveedores de avisos cuando la verificación del registro no está disponible temporalmente. Ese resultado siempre es no instalable y nunca recibe una recomendación `allow`. Las comprobaciones de `latest`, paquetes desconocidos y versiones definitivamente inexistentes siguen requiriendo una resolución satisfactoria del registro.
Las solicitudes HTTP reintentan las respuestas `429`, `502`, `503` y `504` hasta un máximo de tres intentos. Los reintentos usan breves retardos exponenciales y respetan los valores `Retry-After` de hasta dos segundos; las esperas más largas solicitadas por el servidor fallan rápidamente para que la CLI no se cuelgue. El agotamiento de los reintentos de avisos hace que el resultado sea incompleto e impide una recomendación `allow`.
### Autenticación con la API de GitHub
Las solicitudes a la API de GitHub Advisory Database y de GitHub Actions pueden usar un token de GitHub App de corta duración y con privilegios mínimos. En CI, pásalo a través de `DEPTRUST_GITHUB_TOKEN`:
```bash
DEPTRUST_GITHUB_TOKEN="$GITHUB_APP_TOKEN" deptrust check npm lodash 4.17.20
```
La precedencia de credenciales es `DEPTRUST_GITHUB_TOKEN`, `GITHUB_TOKEN` y luego `GH_TOKEN`. Para uso local, el respaldo opcional de GitHub CLI se habilita explícitamente con `DEPTRUST_GITHUB_AUTH=gh deptrust check ...`; ejecuta `gh auth token` sin preguntar. Si no hay ninguna credencial disponible, DepTrust continúa sin autenticación. Un fallo por límite de tasa o por permisos de la API de GitHub produce `unknown` con diagnósticos y nunca se trata como un éxito solo con OSV.
DepTrust nunca almacena, empaqueta, guarda en caché, registra, hace telemetría ni emite tokens de GitHub. Las cabeceras de autenticación solo se envían a `https://api.github.com`.
## Uso de la CLI
Comprueba una versión exacta:
```bash
deptrust check npm lodash 4.17.20
```
Ejemplo de respuesta normal:
```text
npm [email protected]: 2 known vulnerabilities found
recommendation: block
risk_score: 80
```
Comprueba la última versión:
```bash
deptrust check pypi requests latest
```
Devuelve JSON:
```bash
deptrust check --json cargo serde latest
```
Comprueba un módulo de Go:
```bash
deptrust check go golang.org/x/crypto latest
```
Comprueba 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
```
Comprueba 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
```
Para GitHub Actions, los SHAs de commit completos se tratan como fijados (pinned). Las etiquetas semver completas como `v4.2.2` se aceptan sin una señal adicional de fijación. Las etiquetas solo con versión mayor como `v4` y las referencias de rama como `main` son refs válidas, pero deptrust añade una señal de revisión porque pueden moverse.
Ejemplo de respuesta 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": "Found 2 known vulnerability records.",
"next_action": "do_not_install; use suggest_safe_version or compare_versions to choose a safer version",
"summary": "lodash 4.17.20 has 2 known vulnerabilities, including high severity. Block this exact version and prefer a fixed release.",
"signals": [],
"checked_providers": [
"OSV",
"GitHub Advisory DB"
],
"skipped_providers": [],
"advisory_coverage": "full",
"advisory_coverage_reason": "all configured vulnerability providers were checked",
"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": "Command Injection in lodash",
"severity": "high",
"source": "OSV",
"advisory_url": "https://github.com/advisories/GHSA-35jh-r3h4-6jhm",
"affected_ranges": [
"SEMVER: introduced 0, fixed 4.17.21"
],
"fixed_versions": [
"4.17.21"
],
"references": [
{
"type": "ADVISORY",
"url": "https://github.com/advisories/GHSA-35jh-r3h4-6jhm"
}
]
}
],
"provider_errors": []
}
```
Sugiere la última versión solo cuando no se encuentran vulnerabilidades conocidas:
```bash
deptrust suggest npm lodash
```
Si la última versión no está permitida, `suggest` comprueba las versiones anteriores conocidas y devuelve la versión más reciente con una recomendación `allow`.
Cuando los avisos incluyen versiones corregidas, `suggest` comprueba primero esas versiones corregidas notificadas por el proveedor antes de recorrer hacia atrás la lista de versiones del registro.
Compara dos versiones:
```bash
deptrust compare npm lodash 4.17.20 4.17.21
```
Ejemplo de respuesta de comparación:
```text
lodash 4.17.20 -> 4.17.21 improves risk: score 80 to 0.
recommendation: allow
next_action: upgrade_to_target
```
Muestra la versión instalada:
```bash
deptrust version
```
## Instalación
La vía de instalación más sencilla es `npx` o `pnpx`:
```bash
npx @clidey/deptrust install
pnpx @clidey/deptrust@latest install
```
El instalador predeterminado es guiado. Instala el binario, pregunta qué integraciones de agentes configurar, imprime los destinos a nivel de usuario antes de cambiar nada y pide confirmación. El instalador guiado habilita por defecto MCP, el respaldo de skill y los hooks de seguridad de dependencias para Codex y Claude Code. Añade `--yes` para instalaciones no interactivas solo del binario, o pasa indicadores de integración explícitos.
Volver a ejecutar el instalador es seguro. Deja intacta la configuración de MCP, skill y hooks sin cambios. Si una integración apunta a un binario antiguo de deptrust o su configuración gestionada ha cambiado, el instalador la actualiza automáticamente; los usuarios no necesitan eliminar y volver a añadir manualmente los servidores MCP. Las skills personalizadas se respaldan antes de reemplazarse.
Para eliminar el binario, la skill y las entradas MCP a nivel de usuario:
```bash
npx @clidey/deptrust uninstall
pnpx @clidey/deptrust@latest uninstall
```
Los usuarios de Homebrew pueden instalar desde el tap de Clidey:
```bash
brew install clidey/tap/deptrust
```
O añadir el tap primero y luego instalar y actualizar como es habitual:
```bash
brew tap clidey/tap
brew install deptrust
brew upgrade deptrust
```
Homebrew muestra un recordatorio después de la instalación. Para ejecutar la configuración guiada de Codex y Claude Code usando el propio binario de Homebrew (registros MCP y hooks de seguridad de dependencias):
```bash
deptrust setup
```
La configuración guiada pregunta antes de habilitar MCP y los hooks de seguridad de dependencias. Deja intactos los registros que ya usan el binario actual y reconcilia los registros existentes de DepTrust que apuntan a una ruta de instalación anterior de npm, Homebrew o desde el código fuente.
Los usuarios de Go pueden instalar directamente:
```bash
go install github.com/clidey/deptrust/cmd/deptrust@latest
```
### Nix
El proyecto ofrece salidas opcionales de Nix flake para usuarios que ya usan Nix. El flake envuelve el binario de la versión precompilada.
```bash
# Run without installing
nix run github:clidey/deptrust
# Install into your profile
nix profile install github:clidey/deptrust
```
El [flujo de trabajo de publicación](https://github.com/clidey/deptrust/blob/main/.github/workflows/release.yml) normal genera los hashes de Nix a partir de los mismos archivos que publica, evalúa el flake antes de publicar, luego lo compila y lo ejecuta contra los activos publicados antes de actualizar la rama predeterminada. `github:clidey/deptrust` puede ir con un pequeño retraso mientras ese flujo de trabajo se está ejecutando. Las etiquetas de publicación apuntan al commit de origen anterior a la actualización generada del flake y pueden seguir referenciando el binario anterior; fija un commit cuyo `flake.nix` contenga la versión que necesitas cuando la reproducibilidad sea importante.
### Devbox
Para entornos de desarrollo reproducibles, usa Devbox:
```bash
# Install Devbox first (if not already installed)
curl -fsSL https://get.jetify.dev/devbox | bash
# Initialize the environment
devbox shell
# Build the project
devbox run build
```
`devbox.json` restringe la versión de la cadena de herramientas y el `devbox.lock` confirmado fija las versiones exactas de los paquetes y las revisiones de nixpkgs. Ejecuta `devbox update` cuando quieras actualizar intencionadamente esas fijaciones.
O instala Devbox mediante Homebrew:
```bash
brew install jetify-com/devbox/devbox
```
## Configuración de agentes
Para instalar deptrust y registrar todo lo que el instalador puede configurar sin las indicaciones guiadas:
```bash
npx @clidey/deptrust install --all
pnpx @clidey/deptrust@latest install --all
```
`--all` instala el binario, registra Codex MCP cuando la CLI `codex` está disponible, instala el respaldo de skill de Codex, registra Claude Code MCP cuando la CLI `claude` está disponible e instala los hooks de seguridad de dependencias de Codex y Claude Code.
Los hooks son hooks `PreToolUse`. Comprueban los comandos de instalación de paquetes antes de que se ejecuten y también comprueban las GitHub Actions añadidas a los archivos de flujo de trabajo mediante las herramientas de edición de archivos del agente. Un hook bloquea la llamada a la herramienta cuando deptrust devuelve `review`, `block` o `unknown`. El instalador solo escribe configuración de hooks a nivel de usuario: `~/.codex/hooks.json` para Codex y `~/.claude/settings.json` para Claude Code.
Cuando la CLI `gh` está disponible, la configuración guiada también ofrece usar su inicio de sesión local existente para las comprobaciones de los hooks. Esto escribe solo `DEPTRUST_GITHUB_AUTH=gh`, nunca un token de GitHub, para que los subprocesos de los hooks puedan evitar los límites de tasa de la API de GitHub sin autenticación.
Usa instalaciones más reducidas si lo prefieres:
```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
```
Después de la configuración de MCP, los agentes comprobarán automáticamente los paquetes antes de recomendar actualizaciones o cambios. El servidor MCP envía instrucciones para examinar todas las versiones de dependencias —incluido responder a preguntas como "¿qué puedo actualizar?" o "qué dependencias son seguras de actualizar"— antes de ofrecer recomendaciones.
Si usas deptrust en un contexto sin MCP, recuerda a tu agente:
```text
Before listing, comparing, or recommending specific package versions, check them with deptrust. This includes answering "what can I update" — do not provide version recommendations until after checking for known vulnerabilities.
```
Para CI, configura un token de GitHub App de corta duración y con privilegios mínimos como `DEPTRUST_GITHUB_TOKEN` para el proceso que ejecuta DepTrust. Para la autenticación local con la CLI de GitHub, usa `DEPTRUST_GITHUB_AUTH=gh deptrust check ...`. DepTrust nunca almacena tokens.
## Configuración manual de MCP
Si tu cliente admite servidores MCP por stdio, configúralo para que ejecute:
```bash
/absolute/path/to/deptrust mcp
```
Muchos clientes usan esta forma JSON:
```json
{
"mcpServers": {
"deptrust": {
"command": "/absolute/path/to/deptrust",
"args": ["mcp"]
}
}
}
```
Para Codex, también puedes añadirlo con:
```bash
codex mcp add deptrust -- /absolute/path/to/deptrust mcp
```
Para Claude Code:
```bash
claude mcp add --transport stdio deptrust -- /absolute/path/to/deptrust mcp
```
En `initialize`, el servidor devuelve `instructions` de MCP que indican al agente cuándo recurrir a estas herramientas (antes de añadir, actualizar o recomendar una dependencia, o cuando se le pregunte si una versión es segura de actualizar). Los clientes que muestran las instrucciones del servidor aplicarán esto automáticamente, por lo que el recordatorio manual anterior es opcional en lugar de obligatorio.
## Herramientas MCP
### `check_package`
Comprueba una versión de paquete y devuelve las vulnerabilidades conocidas más una recomendación.
```json
{
"ecosystem": "npm",
"package": "lodash",
"version": "4.17.20"
}
```
`version` puede omitirse o establecerse a `latest`. Si una versión exacta no existe, deptrust devuelve un error y sugiere la última versión explícita.
La salida de MCP es intencionadamente compacta para que los agentes puedan decidir si instalar una dependencia sin incluir los cuerpos completos de los avisos en el contexto. Si el usuario pide ver todos los detalles, el agente puede ejecutar `full_response_command`.
Ejemplo de salida estructurada compacta de MCP:
```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": "Found 7 known vulnerability records.",
"next_action": "do_not_install; use suggest_safe_version or compare_versions to choose a safer version",
"summary": "vite 7.0.0 has 7 known vulnerabilities, including high severity. Block this exact version and prefer a fixed release.",
"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": "all configured vulnerability providers were checked",
"registry_verification": "verified",
"full_response_command": "deptrust check --json npm vite 7.0.0"
}
```
La respuesta compacta de MCP omite el array de vulnerabilidades, los `details` de los avisos y las `references` repetidas. Los agentes deben usar por defecto los recuentos, la severidad más alta, la cobertura de proveedores, la recomendación y la siguiente acción. Si el usuario pide los detalles completos del aviso, ejecuta `full_response_command`.
Cuando el acceso a los avisos de GitHub está limitado por tasa o no está disponible, MCP devuelve `unknown`. El agente debe ofrecer proactivamente configurar un token y reintentar, omitir o aplazar la versión, o continuar solo después de que el usuario acepte explícitamente el riesgo de cobertura de GitHub no resuelto para esa versión exacta. Esa excepción debe seguir claramente etiquetada como incertidumbre aceptada por el usuario; no debe informarse como `allow` ni como prueba de que la versión es segura.
### `suggest_safe_version`
Comprueba primero la última versión. Si la última no está permitida, comprueba primero las versiones corregidas notificadas por el proveedor, luego las versiones anteriores conocidas, y sugiere la versión más reciente con una recomendación `allow`.
```json
{
"ecosystem": "npm",
"package": "lodash"
}
```
### `compare_versions`
Compara una versión actual y una versión objetivo, incluidas las vulnerabilidades resueltas y añadidas.
```json
{
"ecosystem": "npm",
"package": "lodash",
"from_version": "4.17.20",
"to_version": "4.17.21"
}
```
## Uso solo con skill
Si no quieres MCP, instala la skill de Codex incluida:
```bash
npx @clidey/deptrust skills install
```
La skill indica a Codex que llame a la CLI `deptrust` antes de instalar, actualizar o recomendar paquetes de npm, PyPI, Cargo, módulos de Go, RubyGems, NuGet, Maven, Packagist, pub.dev, CocoaPods, Hex.pm, Hackage y GitHub Actions.
## Solución de problemas
Si no se encuentra `deptrust`:
```bash
export PATH="$HOME/.local/bin:$PATH"
```
Si un cliente MCP no puede iniciar el servidor, encuentra la ruta completa:
```bash
which deptrust
```
Luego pon esa ruta absoluta en la configuración de MCP.
Si una comprobación de paquete devuelve `unknown`, no trates el paquete como seguro. Significa que deptrust no pudo obtener una respuesta completa de un proveedor de avisos o no pudo verificar la versión exacta con su registro.