O deptrust atualmente reporta vulnerabilidades conhecidas e dá uma recomendação simples:

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:

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:

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:

Exemplo de resposta normal:

Verifique a versão mais recente:

Retorne JSON:

Verifique um módulo Go:

Verifique RubyGems, NuGet ou Maven:

Verifique Packagist, pub.dev, CocoaPods, Hex.pm, Hackage ou GitHub Actions:

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:

Sugira a versão mais recente somente quando nenhuma vulnerabilidade conhecida for encontrada:

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:

Exemplo de resposta de comparação:

Mostre a versão instalada:

Instalação

O caminho mais fácil de instalação é npx ou pnpx:

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:

Usuários de Homebrew podem instalar a partir do tap do Clidey:

Ou adicione o tap primeiro e depois instale e atualize como de costume:

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):

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:

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.

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.

Devbox

Para ambientes de desenvolvimento reprodutíveis, use o Devbox:

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:

Configuração do Agente

Para instalar o deptrust e registrar tudo o que o instalador pode configurar sem os prompts guiados:

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:

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:

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:

Muitos clientes usam este formato JSON:

Para o Codex, você também pode adicioná-lo com:

Para o Claude Code:

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.

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:

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.

compare_versions

Compara uma versão atual e uma versão alvo, incluindo vulnerabilidades resolvidas e adicionadas.

Uso Somente com Skill

Se você não quiser o MCP, instale a skill do Codex incluída:

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:

Se um cliente MCP não conseguir iniciar o servidor, encontre o caminho completo:

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.