Revera

Il punteggio di credito per i pacchetti npm.

Revera ti aiuta a decidere se vale la pena installare un pacchetto prima di eseguire npm install. Analizza la qualità del pacchetto, la manutenzione, la sicurezza, la salute dell'ecosistema e la fiducia nel publisher — e ora propaga il rischio in modo transitivo sull'intero grafo delle dipendenze — producendo poi un report di reputazione bayesiano e spiegabile.

Demo

Guarda revera controllare e spiegare i pacchetti in tempo reale.

Avvio rapido

Esegui revera all'istante senza installazione:

npx revera check react

Esempio

Controllare un pacchetto come request (dichiarato deprecato nel 2020) ti avvisa immediatamente con motivazioni specifiche:

$ 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.

Installazione

Installa globalmente per accedere all'eseguibile da qualsiasi directory:

npm install -g @aaravmaloo/revera

Utilizzo

1. Controlla la reputazione di un pacchetto

Analizza un pacchetto e ottieni un report di riepilogo generale:

revera check lodash

Esegui in modalità offline usando i file in cache:

revera check express --offline

2. Spiega la valutazione di un pacchetto

Ottieni una ripartizione dettagliata del punteggio, dei segnali positivi e delle detrazioni:

revera why node-ipc

3. Controlla e aggiungi una dipendenza

Controlla i pacchetti prima dell'installazione e avvisa quando la reputazione scende al di sotto della soglia configurata:

revera add express

Puoi passare i flag direttamente al tuo gestore di pacchetti:

revera add typescript --save-dev

4. Audit del workspace locale

Controlla tutti i pacchetti nel progetto corrente (incluse le dipendenze transitive) e calcola un punteggio complessivo di salute del progetto:

revera audit

Controlla solo le dipendenze di produzione:

revera audit --prod

Controlla solo le dipendenze dirette, saltando quelle transitive:

revera audit --direct

5. Autenticazione GitHub

Autenticati con GitHub per aumentare i limiti di frequenza dell'API (60/ora anonimo contro 5.000/ora autenticato). Puoi scegliere tra OAuth2 basato su browser o l'inserimento manuale di un Personal Access Token. Una volta autorizzato, revera crittografa e archivia in modo sicuro il token nel portachiavi del tuo sistema operativo (DPAPI su Windows, Keychain su macOS o Secret Service su Linux):

revera login

6. Impostazioni CLI

Gestisci le impostazioni locali salvate in ~/.revera/config.json:

revera config
revera config set minScoreThreshold 75
revera config get minScoreThreshold

7. Diagnostica di sistema

Verifica le impostazioni dell'ambiente, lo stato dell'API e le latenze delle connessioni di rete:

revera doctor

8. Gestione della cache

Ispeziona o svuota la cache locale dei metadati:

revera cache
revera cache clear

9. Verifica aggiornamenti

Verifica se stai eseguendo l'ultima versione del motore di revera:

revera update

Confronto

Motore di punteggio (v2)

Revera v2 ha sostituito il vecchio modello a somma pesata piatta con una pipeline bayesiana a DAG in quattro fasi.

Fase 1 — Grafo delle dipendenze (DAG)

Tutte le dipendenze del progetto vengono risolte in un grafo aciclico diretto. Ogni nodo tiene traccia dell'intero insieme dei suoi dipendenti transitivi, così che le fasi successive possano calcolare blast radius accurati.

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

Fase 2 — Punteggio per pacchetto (Posteriori Beta bayesiane)

Ognuna delle 8 categorie di punteggio parte da un prior specifico per archetipo (framework, cli, types-only, utility) invece che da una base piatta e non informata. I segnali osservati aggiornano una distribuzione Beta a posteriori — il che significa che un timeout o dati mancanti allargano l'intervallo di credibilità invece di impostare silenziosamente "pulito".

Il punteggio finale per pacchetto è un aggregato ponderato per confidenza delle posteriori di categoria (ponderazione per varianza inversa), che produce sia una stima puntuale sia un intervallo di credibilità al 95%.

Fase 3 — Controlli di veto

Tre override rigidi bypassano completamente il punteggio bayesiano e bocciano immediatamente un pacchetto:

Fase 4 — Propagazione transitiva del rischio

Dopo il calcolo dei punteggi per pacchetto, il rischio viene propagato dal basso verso l'alto attraverso il DAG (ordine topologico, partendo dalle foglie):

• Se l'effectiveRisk di una dipendenza supera una soglia, il rischio del suo genitore viene limitato a un minimo di 0.8 (contrassegnato come contaminato).
• Il blast radius di ogni nodo = effectiveRisk × transitive_dependent_count.
• Il subpath peggiore viene tracciato e mostrato nell'output dell'audit, così sai esattamente quale catena di dipendenze ha causato un flag.

Fase 5 — Sintesi del report

Il report di audit finale fonde punteggi intrinseci, contaminazione ereditata, intervalli di credibilità e blast radius in un unico output ordinato. Il punteggio complessivo del workspace è una media ponderata per blast radius.

Database di vulnerabilità

Revera interroga tre database di vulnerabilità indipendenti in parallelo a ogni controllo. I risultati vengono uniti e deduplicati per alias CVE/GHSA prima di essere usati nel punteggio.

Se una fonte va in timeout o genera un errore, le altre continuano in modo indipendente. VulnResult espone quali fonti hanno risposto (sources) e quali hanno fallito (failedSources), così che il motore di punteggio bayesiano possa allargare opportunamente l'intervallo di incertezza invece di presupporre che tutto sia pulito.

Architettura e struttura

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

Benchmark

Revera include una suite di benchmark su larga scala integrata in benchmarker/ che testa oltre 100.000 pacchetti npm in parallelo e produce un singolo report leggibile su GitHub.

Esecuzione di un 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

Ogni esecuzione produce una directory di output autonoma con:

Ultimo benchmark (algoritmo v2, dataset seed)

Il benchmark v1 è stato eseguito prima che i controlli di veto v2 fossero implementati. I numeri per etichetta relativi a malicious/typosquat riflettono il vecchio algoritmo. Una nuova esecuzione completa con v2 sarà pubblicata nella prossima release.

Roadmap

• Punteggio della reputazione dei pacchetti
• Report di punteggio spiegabili
• Audit di progetto diretto e transitivo
• Controlli sugli incidenti di fiducia del publisher
• Avvisi typosquat Levenshtein
• Punteggio basato su posteriori Beta bayesiane (v2)
• Propagazione transitiva del rischio nel DAG (v2)
• Aggregazione multi-fonte delle vulnerabilità (OSV + GitHub + npm)
• Report di benchmark leggibili su GitHub (BENCHMARK.md)
• Comandi di confronto multi-pacchetto
• GitHub Action ufficiale per i controlli CI
• Estensione ufficiale per VS Code
• Supporto nativo per pnpm
• Supporto nativo per Yarn

FAQ

Come posso evitare i limiti di frequenza dell'API GitHub?

Senza un token, le query anonime sono limitate a 60 richieste all'ora. Puoi impostare un Personal Access Token nella tua configurazione:

revera config set githubToken ghp_YOUR_TOKEN

Cosa succede se sono offline?

Revera ripiega sull'uso dei file in cache. Puoi eseguire esplicitamente i comandi in modalità offline con il flag --offline. Se una fonte di vulnerabilità non è disponibile, il motore di punteggio bayesiano allarga l'intervallo di credibilità per quel pacchetto invece di presupporre che sia pulito.

Il comando add modifica il mio progetto?

Revera agisce come un wrapper di shell. Esegue il vero installer del pacchetto dopo il controllo.

Cosa significa un pacchetto "contaminato" nell'output dell'audit?

Un pacchetto viene contrassegnato come contaminato quando una delle sue dipendenze transitive ha attivato un veto o ha ottenuto un punteggio criticamente basso. L'output dell'audit mostra il subpath peggiore, così puoi risalire all'esatta catena di dipendenze che ha causato il flag.

Come vengono deduplicate le vulnerabilità tra i tre database?

Ogni vulnerabilità è identificata dal suo CVE ID, GHSA ID o npm advisory ID. Quando la stessa vulnerabilità compare in più fonti, viene unita in un'unica voce canonica. I dati OSV hanno priorità per i campi testuali (riepilogo, dettagli); vengono conservati la valutazione di gravità più alta e l'intervallo di versioni corrette più completo tra tutte le fonti.

Contributi

Consulta la Guida ai contributi per iniziare con la configurazione, le regole di stile e le linee guida per le PR.

Dichiarazione di esclusione di responsabilità

Revera fornisce un punteggio di reputazione basato su segnali osservabili del progetto e dati storici. È pensato per supportare le decisioni ingegneristiche e non deve essere considerato un audit di sicurezza definitivo.

Licenza

Revera è distribuito sotto la Licenza MIT.