Revera

O score de crédito para pacotes npm.

O revera ajuda você a decidir se vale a pena instalar um pacote antes de executar npm install. Ele analisa qualidade do pacote, manutenção, segurança, saúde do ecossistema e confiança do publicador — e agora propaga risco transitivamente por todo o seu grafo de dependências — e então produz um relatório de reputação bayesiano e explicável.

Demonstração

Assista ao revera verificando e explicando pacotes em tempo real.

Início Rápido

Execute o revera instantaneamente sem instalação:

npx revera check react

Exemplo

Verificar um pacote como request (que foi descontinuado em 2020) alerta você imediatamente com motivos específicos:

$ revera why request

  ▲ revera EXPLAIN
  ──────────────────────────────────────────────────
  Package:   [email protected]
  Overall:   38/100  Not Recommended

  Score Breakdown

    Maintenance             15/100  ███░░░░░░░░░░░░░░░░░
                           Release cadence, commit activity, issue responsiveness, maintainer count

    Stability               90/100  ██████████████████░░
                           SemVer compliance, major version history, API volatility over time

    Security               100/100  ████████████████████
                           Known CVEs, install scripts, repository transparency

    Package Quality         40/100  ████████░░░░░░░░░░░░
                           README completeness, license, test coverage indicators, exports

    Ecosystem              100/100  ████████████████████
                           Weekly download volume, GitHub stars, community forks

    Documentation           90/100  ██████████████████░░
                           README length, code examples, API references, external docs presence

    Developer Experience    40/100  ████████░░░░░░░░░░░░
                           TypeScript support, ESM compatibility, CLI tooling

    Publisher Trust        100/100  ████████████████████
                           Known malicious releases, protestware history, supply-chain incidents

  Why it scores well
    +  Stable API (v1.0.0+)
    +  Low API volatility
    +  Zero known vulnerabilities
    +  Permissive open-source license
    +  Code examples in README
    +  Structured API documentation
    +  No known publisher trust incidents

  Minor deductions
    -  Last release was 59 months ago
    -  Single maintainer (bus factor of 1)
    -  Missing native type definitions
    -  Legacy CommonJS only
    -  No native typings (bad TypeScript DX)

  Warnings
    !  Last release: 59 months ago. No recent updates detected. This may be normal for mature, stable libraries.
    !  Package has been officially marked as deprecated by the maintainer.

  Verdict
    Request has low confidence. revera recommends looking for alternatives due to security, activity, or stability concerns.

Instalação

Instale globalmente para acessar o executável de qualquer diretório:

npm install -g @aaravmaloo/revera

Uso

1. Verificar a Reputação do Pacote

Analise um pacote e obtenha um relatório resumido de alto nível:

revera check lodash

Execute em modo offline usando arquivos em cache:

revera check express --offline

2. Explicar a Avaliação do Pacote

Obtenha um detalhamento aprofundado da pontuação, sinais positivos e deduções:

revera why node-ipc

3. Avaliar e Adicionar Dependência

Avalia pacotes antes da instalação e alerta quando a reputação cai abaixo do limite configurado:

revera add express

Você pode passar flags diretamente para o seu gerenciador de pacotes:

revera add typescript --save-dev

4. Auditar o Workspace Local

Audite todos os pacotes do projeto atual (inclui dependências transitivas) e calcule uma pontuação geral de saúde do projeto:

revera audit

Audite apenas dependências de produção:

revera audit --prod

Audite apenas dependências diretas, ignorando as transitivas:

revera audit --direct

5. Autenticação no GitHub

Autentique-se no GitHub para aumentar os limites de taxa da API (60/hora anônimo vs 5.000/hora autenticado). Você pode escolher entre OAuth2 baseado em navegador ou inserir manualmente um Personal Access Token. Uma vez autorizado, o revera criptografa e armazena o token com segurança no chaveiro do seu sistema operacional (DPAPI no Windows, Keychain no macOS ou Secret Service no Linux):

revera login

6. Configurações da CLI

Gerencie as configurações locais salvas em ~/.revera/config.json:

revera config
revera config set minScoreThreshold 75
revera config get minScoreThreshold

7. Diagnóstico do Sistema

Verifique as configurações do ambiente, o status da API e as latências de conexão de rede:

revera doctor

8. Controle de Cache

Inspecione ou limpe o cache local de metadados:

revera cache
revera cache clear

9. Verificação de Atualização

Verifique se você está executando a versão mais recente do mecanismo do revera:

revera update

Comparação

Mecanismo de Pontuação (v2)

O revera v2 substituiu o antigo modelo de soma ponderada plana por um pipeline bayesiano em DAG de quatro estágios.

Estágio 1 — Grafo de Dependências (DAG)

Todas as dependências do projeto são resolvidas em um grafo acíclico direcionado. Cada nó rastreia todo o seu conjunto de dependentes transitivos para que os estágios posteriores possam calcular raios de impacto precisos.

lodash ──► your-app
express ──► your-app
axios ──► some-lib ──► your-app   ← transitive

Estágio 2 — Pontuação por Pacote (Posteriores Beta Bayesianos)

Cada uma das 8 categorias de pontuação parte de um prior específico de arquétipo (framework, cli, types-only, utility) em vez de uma linha de base plana e sem informação. Sinais observados atualizam um posterior de distribuição Beta — ou seja, um timeout ou dados ausentes ampliam o intervalo de credibilidade em vez de assumir silenciosamente "limpo".

A pontuação final por pacote é um agregado ponderado por confiança dos posteriores das categorias (ponderação por variância inversa), produzindo tanto uma estimativa pontual quanto um intervalo de credibilidade de 95%.

Estágio 3 — Verificações de Veto

Três overrides rígidos ignoram completamente a pontuação bayesiana e reprovam imediatamente um pacote:

Estágio 4 — Propagação de Risco Transitivo

Depois que as pontuações por pacote são calculadas, o risco é propagado de baixo para cima através do DAG (ordem topológica, folhas primeiro):

• Se o effectiveRisk de uma dependência exceder um limite, o risco do pai tem piso em 0.8 (marcado como contaminado).
• O raio de impacto de cada nó = effectiveRisk × transitive_dependent_count.
• O pior subcaminho é rastreado e exibido na saída da auditoria para que você saiba exatamente qual cadeia de dependências causou a sinalização.

Estágio 5 — Síntese do Relatório

O relatório final de auditoria mescla pontuações intrínsecas, contaminação herdada, intervalos de credibilidade e raios de impacto em uma única saída classificada. A pontuação geral do workspace é uma média ponderada pelo raio de impacto.

Bancos de Dados de Vulnerabilidades

O revera consulta três bancos de dados de vulnerabilidades independentes em paralelo em cada verificação. Os resultados são mesclados e deduplicados por alias de CVE/GHSA antes de serem usados na pontuação.

Se uma fonte expirar ou apresentar erro, as outras continuam de forma independente. O VulnResult expõe quais fontes responderam (sources) e quais falharam (failedSources) para que o pontuador bayesiano possa ampliar o intervalo de incerteza adequadamente em vez de presumir limpeza.

Arquitetura e Estrutura

.github/              # CI configurations
docs/                 # Architecture specs and algorithm diagrams
src/
  ├── commands/       # CLI command handlers (check, why, add, audit, config, cache, update)
  ├── engine/
  │   ├── dag.ts          # DAG construction + topological sort + blast-radius computation
  │   ├── propagation.ts  # Bottom-up transitive risk propagation
  │   ├── scoring.ts      # Bayesian Beta posteriors, archetype priors, veto checks
  │   ├── vuln.ts         # Multi-source vuln aggregator (OSV + GitHub + npm)
  │   ├── trust.ts        # Publisher trust incident database
  │   ├── typosquat.ts    # Edit-distance typosquat detection
  │   ├── npm.ts          # npm registry + download stats fetcher
  │   └── github.ts       # GitHub repo stats + README fetcher
  ├── ui/             # Console view templates (reporter formatters, theme styles)
  └── utils/          # Filesystem helpers (caching, configuration, package managers)
tests/                # Unit test suites
benchmarker/          # Large-scale benchmark suite (100k+ packages)

Benchmarks

O revera acompanha uma suíte de benchmarks de grande escala integrada em benchmarker/ que testa mais de 100 mil pacotes npm em paralelo e produz um único relatório legível no GitHub.

Executando um benchmark

cd benchmarker
npm install
npm run fetch-dataset          # one-time: pulls ~100k packages into datasets/npm.jsonl
./benchmark.sh --workers 16   # runs the full suite

Cada execução produz um diretório de saída autocontido com:

Último benchmark (algoritmo v2, conjunto de dados base)

O benchmark v1 foi executado antes da implantação das verificações de veto da v2. Os números por rótulo de malicious/typosquat refletem o algoritmo legado. Uma nova execução completa da v2 será publicada no próximo lançamento.

Roteiro

• Pontuação de reputação de pacotes
• Relatórios de pontuação explicáveis
• Auditoria direta e transitiva de projetos
• Verificações de incidentes de confiança do publicador
• Avisos de typosquat por Levenshtein
• Pontuação Beta posterior bayesiana (v2)
• Propagação de risco transitivo em DAG (v2)
• Agregação de vulnerabilidades de múltiplas fontes (OSV + GitHub + npm)
• Relatórios de benchmark legíveis no GitHub (BENCHMARK.md)
• Comandos de comparação entre múltiplos pacotes
• GitHub Action oficial para verificações de CI
• Extensão oficial para VS Code
• Suporte nativo a pnpm
• Suporte nativo a Yarn

Perguntas Frequentes

Como evito os limites de taxa da API do GitHub?

Sem um token, consultas anônimas são limitadas a 60 solicitações por hora. Você pode definir um Personal Access Token na sua configuração:

revera config set githubToken ghp_YOUR_TOKEN

O que acontece se eu estiver offline?

O revera usa arquivos de cache como fallback. Você pode executar comandos explicitamente em modo offline com a flag --offline. Se uma fonte de vulnerabilidade estiver indisponível, o pontuador bayesiano amplia o intervalo de credibilidade para aquele pacote em vez de presumir que está limpo.

O comando add modifica meu projeto?

O revera atua como um wrapper de shell. Ele executa o instalador real do pacote após a triagem.

O que é um pacote "contaminado" na saída da auditoria?

Um pacote é marcado como contaminado quando uma de suas dependências transitivas acionou um veto ou obteve pontuação criticamente baixa. A saída da auditoria mostra o pior subcaminho para que você possa rastrear a cadeia exata de dependências que causou a sinalização.

Como as vulnerabilidades são deduplicadas entre três bancos de dados?

Cada vulnerabilidade é identificada pelo seu CVE ID, GHSA ID ou npm advisory ID. Quando a mesma vulnerabilidade aparece em múltiplas fontes, ela é mesclada em uma única entrada canônica. Os dados do OSV têm prioridade para campos textuais (resumo, detalhes); a classificação de severidade mais alta e o intervalo de versões corrigidas mais completo entre todas as fontes são preservados.

Contribuindo

Revise o Guia de Contribuição para começar com a configuração, regras de estilo e diretrizes de PR.

Aviso Legal

O revera fornece uma pontuação de reputação baseada em sinais observáveis do projeto e dados históricos. Ele se destina a auxiliar decisões de engenharia e não deve ser tratado como uma auditoria de segurança definitiva.

Licença

O revera é distribuído sob a Licença MIT.