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.
__ __ __
___/ /___ ___ / /________ _______/ /_
/ _ / __ \/ _ \/ __/ ___/ / / / ___/ __/
/ __/ /_/ / __/ /_/ / / /_/ (__ ) /_
\__,_/\____/ .___/\__/_/ \__,_/____/\__/
/_/
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.
Ecossistemas suportados:
@clidey/uxgroupId:artifactIdvendor/packageowner/repo e tags, referências de branch ou SHAs de commit como versõesO 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 |
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:
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:
A saída JSON inclui campos de cobertura de avisos:
checked_providers: provedores de vulnerabilidade que o deptrust realmente consultouskipped_providers: provedores configurados ignorados porque o ecossistema não é suportadoadvisory_coverage: full, partial, none ou erroradvisory_coverage_reason: breve explicação para o valor de coberturaregistry_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 registroregistry_verification_reason: o erro do registro quando a verificação não estava disponívelUma 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.
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:
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.
Verifique uma versão exata:
deptrust check npm lodash 4.17.20
Exemplo de resposta normal:
npm [email protected]: 2 known vulnerabilities found
recommendation: block
risk_score: 80
Verifique a versão mais recente:
deptrust check pypi requests latest
Retorne JSON:
deptrust check --json cargo serde latest
Verifique um módulo Go:
deptrust check go golang.org/x/crypto latest
Verifique RubyGems, NuGet ou Maven:
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:
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:
{
"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:
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:
deptrust compare npm lodash 4.17.20 4.17.21
Exemplo de resposta de comparação:
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:
deptrust version
O caminho mais fácil de instalação é npx ou pnpx:
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:
npx @clidey/deptrust uninstall
pnpx @clidey/deptrust@latest uninstall
Usuários de Homebrew podem instalar a partir do tap do Clidey:
brew install clidey/tap/deptrust
Ou adicione o tap primeiro e depois instale e atualize como de costume:
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):
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:
go install github.com/clidey/deptrust/cmd/deptrust@latest
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.
# Run without installing
nix run github:clidey/deptrust
# Install into your profile
nix profile install github:clidey/deptrust
O fluxo de release 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.
Para ambientes de desenvolvimento reprodutíveis, use o Devbox:
# 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:
brew install jetify-com/devbox/devbox
Para instalar o deptrust e registrar tudo o que o instalador pode configurar sem os prompts guiados:
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:
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:
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.
Se o seu cliente for compatível com servidores MCP via stdio, configure-o para executar:
/absolute/path/to/deptrust mcp
Muitos clientes usam este formato JSON:
{
"mcpServers": {
"deptrust": {
"command": "/absolute/path/to/deptrust",
"args": ["mcp"]
}
}
}
Para o Codex, você também pode adicioná-lo com:
codex mcp add deptrust -- /absolute/path/to/deptrust mcp
Para o Claude Code:
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.
check_packageVerifica uma versão de pacote e retorna vulnerabilidades conhecidas além de uma recomendação.
{
"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:
{
"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_versionVerifica 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.
{
"ecosystem": "npm",
"package": "lodash"
}
compare_versionsCompara uma versão atual e uma versão alvo, incluindo vulnerabilidades resolvidas e adicionadas.
{
"ecosystem": "npm",
"package": "lodash",
"from_version": "4.17.20",
"to_version": "4.17.21"
}
Se você não quiser o MCP, instale a skill do Codex incluída:
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.
Se deptrust não for encontrado:
export PATH="$HOME/.local/bin:$PATH"
Se um cliente MCP não conseguir iniciar o servidor, encontre o caminho completo:
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.
| none found |
| allow |
| 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 |