clidey/deptrustServidor CLI e MCP que verifica versões de pacotes em busca de vulnerabilidades conhecidas em mais de 14 ecossistemas, incluindo npm, PyPI, crates.io, módulos Go e GitHub Actions. Integra-se com agentes de IA por meio de hooks e skills.
# deptrust
```text
__ __ __
___/ /___ ___ / /________ _______/ /_
/ _ / __ \/ _ \/ __/ ___/ / / / ___/ __/
/ __/ /_/ / __/ /_/ / / /_/ (__ ) /_
\__,_/\____/ .___/\__/_/ \__,_/____/\__/
/_/
```
O deptrust é um CLI que verifica versões de pacotes quanto a vulnerabilidades conhecidas em npm, PyPI, crates.io, módulos Go, RubyGems, NuGet, Maven, Packagist, pub.dev, CocoaPods, Hex.pm, Hackage, GitHub Actions e outros.
Ele é executado localmente como CLI e como servidor MCP. Ele chama diretamente as APIs públicas de registros de pacotes e da OSV; não existe um serviço deptrust hospedado em que confiar ou que configurar.
Esta ferramenta nasceu da frustração que são agentes de IA usando constantemente versões antigas.
## Conteúdo
- [Escopo](#escopo)
- [Uso do CLI](#uso-do-cli)
- [Instalação](#instalação)
- [Configuração do Agente](#configuração-do-agente)
- [Configuração Manual do MCP](#configuração-manual-do-mcp)
- [Ferramentas MCP](#ferramentas-mcp)
- [Uso Somente com Skill](#uso-somente-com-skill)
- [Solução de Problemas](#solução-de-problemas)
## Escopo
Ecossistemas suportados:
- npm, incluindo pacotes com escopo como `@clidey/ux`
- PyPI
- Cargo / crates.io
- módulos Go
- RubyGems
- NuGet
- Maven, usando nomes de pacote `groupId:artifactId`
- Packagist / Composer, usando nomes de pacote `vendor/package`
- pub.dev
- CocoaPods
- Hex.pm
- Hackage
- GitHub Actions, usando nomes de pacote `owner/repo` e tags, referências de branch ou SHAs de commit como versões
O deptrust atualmente reporta vulnerabilidades conhecidas e dá uma recomendação simples:
| Maior gravidade conhecida | Recomendação |
| --- | --- |
| critical | block |
| high | block |
| medium / unknown | review |
| low | allow |
| none found | allow |
`allow` significa que nenhuma vulnerabilidade conhecida bloqueante foi encontrada nas fontes de dados públicas. Isso não prova que um pacote é seguro.
O deptrust também emite sinais de risco que não são CVEs. Por exemplo, uma versão publicada nas últimas 72 horas é marcada para revisão para que um agente não instale cegamente uma versão recém-lançada.
Os provedores de avisos são consultados em paralelo:
- OSV
- GitHub Advisory Database, incluindo avisos revisados e avisos de malware
A cobertura dos provedores varia por ecossistema. Se o deptrust conseguir resolver os metadados do registro, mas nenhum provedor de vulnerabilidades configurado for compatível com aquele ecossistema, ele retorna `unknown` em vez de tratar o pacote como seguro.
Cobertura dos provedores:
| Ecossistema | Metadados do registro | OSV | GitHub Advisory DB |
| --- | --- | --- | --- |
| npm | sim | sim | sim |
| PyPI | sim | sim | sim |
| Cargo / crates.io | sim | sim | sim |
| módulos Go | sim | sim | sim |
| RubyGems | sim | sim | sim |
| NuGet | sim | sim | sim |
| Maven | sim | sim | sim |
| Packagist / Composer | sim | sim | sim |
| pub.dev | sim | sim | sim |
| CocoaPods | sim | não | sim |
| Hex.pm | sim | sim | sim |
| Hackage | sim | sim | não |
| GitHub Actions | sim | sim | sim |
A saída JSON inclui campos de cobertura de avisos:
- `checked_providers`: provedores de vulnerabilidade que o deptrust realmente consultou
- `skipped_providers`: provedores configurados ignorados porque o ecossistema não é suportado
- `advisory_coverage`: `full`, `partial`, `none` ou `error`
- `advisory_coverage_reason`: breve explicação para o valor de cobertura
- `registry_verification`: `verified` quando os metadados do registro confirmaram a versão, ou `unverified` quando uma verificação de versão exata continuou após uma falha transitória do registro
- `registry_verification_reason`: o erro do registro quando a verificação não estava disponível
Uma verificação de versão exata ainda consulta os provedores de avisos quando a verificação do registro está temporariamente indisponível. Esse resultado é sempre não instalável e nunca recebe uma recomendação `allow`. Verificações de `latest`, de pacotes desconhecidos e de versões definitivamente inexistentes ainda exigem resolução bem-sucedida do registro.
Requisições HTTP repetem respostas `429`, `502`, `503` e `504` em até três tentativas no total. As novas tentativas usam atrasos exponenciais curtos e respeitam valores `Retry-After` de até dois segundos; esperas mais longas solicitadas pelo servidor falham rapidamente para que o CLI não trave. Tentativas de avisos esgotadas tornam o resultado incompleto e impedem uma recomendação `allow`.
### Autenticação da API do GitHub
Requisições ao GitHub Advisory Database e à API do GitHub Actions podem usar um token de GitHub App de curta duração e privilégio mínimo. Em CI, passe-o via `DEPTRUST_GITHUB_TOKEN`:
```bash
DEPTRUST_GITHUB_TOKEN="$GITHUB_APP_TOKEN" deptrust check npm lodash 4.17.20
```
A precedência de credenciais é `DEPTRUST_GITHUB_TOKEN`, `GITHUB_TOKEN` e depois `GH_TOKEN`. Para uso local, o fallback opcional da CLI do GitHub é ativado explicitamente com `DEPTRUST_GITHUB_AUTH=gh deptrust check ...`; ele executa `gh auth token` sem solicitar entrada. Se nenhuma credencial estiver disponível, o DepTrust continua sem autenticação. Uma falha de limite de taxa ou de permissão da API do GitHub produz `unknown` com diagnósticos e nunca é tratada como sucesso somente via OSV.
O DepTrust nunca armazena, agrupa, cacheia, registra em log, telemetra ou emite tokens do GitHub. Os cabeçalhos de autenticação são enviados somente para `https://api.github.com`.
## Uso do CLI
Verifique uma versão exata:
```bash
deptrust check npm lodash 4.17.20
```
Exemplo de resposta normal:
```text
npm [email protected]: 2 known vulnerabilities found
recommendation: block
risk_score: 80
```
Verifique a versão mais recente:
```bash
deptrust check pypi requests latest
```
Retorne JSON:
```bash
deptrust check --json cargo serde latest
```
Verifique um módulo Go:
```bash
deptrust check go golang.org/x/crypto latest
```
Verifique RubyGems, NuGet ou Maven:
```bash
deptrust check rubygems rails latest
deptrust check nuget Newtonsoft.Json latest
deptrust check maven org.apache.logging.log4j:log4j-core latest
```
Verifique Packagist, pub.dev, CocoaPods, Hex.pm, Hackage ou 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, SHAs completos de commit são tratados como fixados (pinned). Tags semver completas como `v4.2.2` são aceitas sem um sinal extra de fixação. Tags apenas com a major como `v4` e referências de branch como `main` são refs válidas, mas o deptrust adiciona um sinal de revisão porque elas podem mudar.
Exemplo de resposta 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": []
}
```
Sugira a versão mais recente somente quando nenhuma vulnerabilidade conhecida for encontrada:
```bash
deptrust suggest npm lodash
```
Se a versão mais recente não for permitida, o `suggest` verifica versões conhecidas mais antigas e retorna a versão mais nova com uma recomendação `allow`.
Quando os avisos incluem versões corrigidas, o `suggest` verifica primeiro essas versões corrigidas informadas pelos provedores antes de percorrer de volta a lista de versões do registro.
Compare duas versões:
```bash
deptrust compare npm lodash 4.17.20 4.17.21
```
Exemplo de resposta de comparação:
```text
lodash 4.17.20 -> 4.17.21 improves risk: score 80 to 0.
recommendation: allow
next_action: upgrade_to_target
```
Mostre a versão instalada:
```bash
deptrust version
```
## Instalação
O caminho mais fácil de instalação é `npx` ou `pnpx`:
```bash
npx @clidey/deptrust install
pnpx @clidey/deptrust@latest install
```
O instalador padrão é guiado. Ele instala o binário, pergunta quais integrações de agente configurar, imprime os destinos em nível de usuário antes de alterar qualquer coisa e pede confirmação. O instalador guiado habilita por padrão o MCP, o fallback de skill e os hooks de segurança de dependências para Codex e Claude Code. Adicione `--yes` para instalações não interativas somente do binário, ou passe sinalizadores de integração explícitos.
Executar o instalador novamente é seguro. Ele deixa silenciosamente intacta a configuração existente e inalterada de MCP, skills e hooks. Se uma integração apontar para um binário antigo do deptrust ou se a configuração gerenciada dela tiver mudado, o instalador a atualiza automaticamente; os usuários não precisam remover e readicionar manualmente os servidores MCP. Skills personalizadas recebem backup antes da substituição.
Para remover o binário em nível de usuário, a skill e as entradas MCP:
```bash
npx @clidey/deptrust uninstall
pnpx @clidey/deptrust@latest uninstall
```
Usuários de Homebrew podem instalar a partir do tap do Clidey:
```bash
brew install clidey/tap/deptrust
```
Ou adicione o tap primeiro e depois instale e atualize como de costume:
```bash
brew tap clidey/tap
brew install deptrust
brew upgrade deptrust
```
O Homebrew imprime um lembrete após a instalação. Para executar a configuração guiada do Codex e do Claude Code usando o próprio binário do Homebrew (registros MCP e hooks de segurança de dependências):
```bash
deptrust setup
```
A configuração guiada pergunta antes de habilitar o MCP e os hooks de segurança de dependências. Ela deixa intactos os registros que já usam o binário atual e reconcilia registros DepTrust existentes que apontam para um caminho antigo de instalação via npm, Homebrew ou fonte.
Usuários de Go podem instalar diretamente:
```bash
go install github.com/clidey/deptrust/cmd/deptrust@latest
```
### Nix
O projeto fornece saídas opcionais de Nix flake para usuários que já usam Nix. O flake encapsula o binário de release pré-compilado.
```bash
# Run without installing
nix run github:clidey/deptrust
# Install into your profile
nix profile install github:clidey/deptrust
```
O [fluxo de release](https://github.com/clidey/deptrust/blob/main/.github/workflows/release.yml) normal gera os hashes Nix a partir dos mesmos arquivos que publica, avalia o flake antes de publicar e, em seguida, compila e executa o flake contra os artefatos publicados antes de atualizar o branch padrão. `github:clidey/deptrust` pode ficar brevemente defasado enquanto esse fluxo estiver em execução. Tags de release apontam para o commit de origem anterior à atualização gerada do flake e podem ainda referenciar o binário anterior; fixe um commit cujo `flake.nix` contenha a versão de que você precisa quando a reprodutibilidade for importante.
### Devbox
Para ambientes de desenvolvimento reprodutíveis, use o 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
```
O `devbox.json` restringe a versão do toolchain, e o `devbox.lock` versionado fixa as versões exatas dos pacotes e as revisões do nixpkgs. Execute `devbox update` quando quiser intencionalmente atualizar essas fixações.
Ou instale o Devbox via Homebrew:
```bash
brew install jetify-com/devbox/devbox
```
## Configuração do Agente
Para instalar o deptrust e registrar tudo o que o instalador pode configurar sem os prompts guiados:
```bash
npx @clidey/deptrust install --all
pnpx @clidey/deptrust@latest install --all
```
O `--all` instala o binário, registra o MCP do Codex quando a CLI `codex` está disponível, instala o fallback de skill do Codex, registra o MCP do Claude Code quando a CLI `claude` está disponível e instala os hooks de segurança de dependências do Codex e do Claude Code.
Os hooks são hooks `PreToolUse`. Eles verificam comandos de instalação de pacotes antes de serem executados e também verificam GitHub Actions adicionados a arquivos de workflow por meio das ferramentas de edição de arquivos do agente. Um hook bloqueia a chamada da ferramenta quando o deptrust retorna `review`, `block` ou `unknown`. O instalador grava apenas a configuração de hooks em nível de usuário: `~/.codex/hooks.json` para Codex e `~/.claude/settings.json` para Claude Code.
Quando a CLI `gh` está disponível, a configuração guiada também oferece usar o login local existente dela para as verificações dos hooks. Isso grava apenas `DEPTRUST_GITHUB_AUTH=gh`, nunca um token do GitHub, para que os subprocessos dos hooks possam evitar os limites de taxa da API do GitHub sem autenticação.
Use instalações mais enxutas quando preferir:
```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
```
Após a configuração do MCP, os agentes verificarão automaticamente os pacotes antes de recomendar atualizações ou alterações. O servidor MCP envia instruções para avaliar todas as versões de dependências — inclusive responder perguntas como "o que posso atualizar" ou "quais dependências são seguras para atualizar" — antes de fornecer recomendações.
Se estiver usando o deptrust em um contexto sem MCP, lembre seu 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, configure um token de GitHub App de curta duração e privilégio mínimo como `DEPTRUST_GITHUB_TOKEN` para o processo que executa o DepTrust. Para autenticação local com a CLI do GitHub, use `DEPTRUST_GITHUB_AUTH=gh deptrust check ...`. O DepTrust nunca armazena tokens.
## Configuração Manual do MCP
Se o seu cliente for compatível com servidores MCP via stdio, configure-o para executar:
```bash
/absolute/path/to/deptrust mcp
```
Muitos clientes usam este formato JSON:
```json
{
"mcpServers": {
"deptrust": {
"command": "/absolute/path/to/deptrust",
"args": ["mcp"]
}
}
}
```
Para o Codex, você também pode adicioná-lo com:
```bash
codex mcp add deptrust -- /absolute/path/to/deptrust mcp
```
Para o Claude Code:
```bash
claude mcp add --transport stdio deptrust -- /absolute/path/to/deptrust mcp
```
Em `initialize`, o servidor retorna `instructions` do MCP informando ao agente quando usar essas ferramentas (antes de adicionar, atualizar ou recomendar uma dependência, ou quando perguntado se uma versão é segura para atualizar). Clientes que exibem as instruções do servidor aplicam isso automaticamente, portanto o lembrete manual acima é opcional, e não obrigatório.
## Ferramentas MCP
### `check_package`
Verifica uma versão de pacote e retorna vulnerabilidades conhecidas além de uma recomendação.
```json
{
"ecosystem": "npm",
"package": "lodash",
"version": "4.17.20"
}
```
`version` pode ser omitido ou definido como `latest`. Se uma versão exata não existir, o deptrust retorna um erro e sugere a versão explícita mais recente.
A saída do MCP é intencionalmente compacta para que os agentes possam decidir se instalam uma dependência sem trazer os avisos completos para o contexto. Se o usuário pedir para ver os detalhes completos, o agente pode executar o `full_response_command`.
Exemplo de saída estruturada compacta do 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"
}
```
A resposta compacta do MCP omite o array de vulnerabilidades, os `details` dos avisos e as `references` repetidas. Os agentes devem usar por padrão as contagens, a maior gravidade, a cobertura dos provedores, a recomendação e a próxima ação. Se o usuário pedir os detalhes completos dos avisos, execute o `full_response_command`.
Quando o acesso aos avisos do GitHub estiver limitado por taxa ou indisponível, o MCP retorna `unknown`. O agente deve proativamente oferecer configurar um token e tentar novamente, pular ou adiar a versão, ou prosseguir somente depois que o usuário aceitar explicitamente o risco de cobertura não resolvido do GitHub para aquela versão exata. Essa exceção deve permanecer claramente rotulada como incerteza aceita pelo usuário; ela não deve ser reportada como `allow` nem como prova de que a versão é segura.
### `suggest_safe_version`
Verifica primeiro a versão mais recente. Se a mais recente não for permitida, verifica primeiro as versões corrigidas informadas pelos provedores, depois as versões conhecidas mais antigas, e sugere a versão mais nova com uma recomendação `allow`.
```json
{
"ecosystem": "npm",
"package": "lodash"
}
```
### `compare_versions`
Compara uma versão atual e uma versão alvo, incluindo vulnerabilidades resolvidas e adicionadas.
```json
{
"ecosystem": "npm",
"package": "lodash",
"from_version": "4.17.20",
"to_version": "4.17.21"
}
```
## Uso Somente com Skill
Se você não quiser o MCP, instale a skill do Codex incluída:
```bash
npx @clidey/deptrust skills install
```
A skill instrui o Codex a chamar a CLI `deptrust` antes de instalar, atualizar ou recomendar pacotes npm, PyPI, Cargo, módulos Go, RubyGems, NuGet, Maven, Packagist, pub.dev, CocoaPods, Hex.pm, Hackage e GitHub Actions.
## Solução de Problemas
Se `deptrust` não for encontrado:
```bash
export PATH="$HOME/.local/bin:$PATH"
```
Se um cliente MCP não conseguir iniciar o servidor, encontre o caminho completo:
```bash
which deptrust
```
Em seguida, coloque esse caminho absoluto na configuração do MCP.
Se uma verificação de pacote retornar `unknown`, não trate o pacote como seguro. Isso significa que o deptrust não conseguiu obter uma resposta completa de um provedor de avisos ou não conseguiu verificar a versão exata junto ao seu registro.