Revera

Le score de crédit pour les paquets npm.

Revera vous aide à décider si un paquet vaut la peine d'être installé avant d'exécuter npm install. Il analyse la qualité du paquet, la maintenance, la sécurité, la santé de l'écosystème et la confiance envers l'éditeur — et propage désormais le risque de manière transitive à travers l'intégralité de votre graphe de dépendances — puis produit un rapport de réputation bayésien et explicable.

Demo

Regardez revera vérifier et expliquer des paquets en temps réel.

Quick Start

Exécutez revera instantanément, sans installation :

npx revera check react

Example

Vérifier un paquet comme request (qui a été déprécié en 2020) vous avertit immédiatement avec des raisons précises :

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

Installation

Installez-le globalement pour accéder à l'exécutable depuis n'importe quel répertoire :

npm install -g @aaravmaloo/revera

Usage

1. Check Package Reputation

Analysez un paquet et obtenez un rapport de synthèse de haut niveau :

revera check lodash

Exécutez en mode hors ligne en utilisant les fichiers en cache :

revera check express --offline

2. Explain Package Rating

Obtenez une analyse détaillée du score, des signaux positifs et des déductions :

revera why node-ipc

3. Screen and Add Dependency

Filtre les paquets avant l'installation et avertit lorsque la réputation tombe sous votre seuil configuré :

revera add express

Vous pouvez passer des options directement à votre gestionnaire de paquets :

revera add typescript --save-dev

4. Audit Local Workspace

Auditez tous les paquets du projet courant (y compris les dépendances transitives) et calculez un score de santé global pour le projet :

revera audit

Auditez uniquement les dépendances de production :

revera audit --prod

Auditez uniquement les dépendances directes, en ignorant les dépendances transitives :

revera audit --direct

5. GitHub Authentication

Authentifiez-vous auprès de GitHub pour augmenter les limites de débit de l'API (60/heure anonyme contre 5 000/heure authentifié). Vous pouvez choisir entre OAuth2 basé sur navigateur ou la saisie manuelle d'un Personal Access Token. Une fois autorisé, revera chiffre et stocke le jeton en toute sécurité dans le trousseau de votre système d'exploitation (DPAPI Windows, Keychain macOS ou Secret Service Linux) :

revera login

6. CLI Settings

Gérez les paramètres locaux enregistrés dans ~/.revera/config.json :

revera config
revera config set minScoreThreshold 75
revera config get minScoreThreshold

7. System Doctor

Vérifiez les paramètres d'environnement, l'état de l'API et les latences de connexion réseau :

revera doctor

8. Cache Control

Inspectez ou videz le cache local des métadonnées :

revera cache
revera cache clear

9. Update Check

Vérifiez si vous exécutez la dernière version du moteur revera :

revera update

Comparison

Scoring Engine (v2)

Revera v2 a remplacé l'ancien modèle à somme pondérée plate par un pipeline bayésien en quatre étages basé sur un DAG.

Stage 1 — Dependency Graph (DAG)

Toutes les dépendances du projet sont résolues en un graphe orienté acyclique. Chaque nœud suit l'ensemble complet de ses dépendants transitifs afin que les étapes suivantes puissent calculer des rayons d'impact précis.

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

Stage 2 — Per-Package Scoring (Bayesian Beta Posteriors)

Chacune des 8 catégories de notation part d'un a priori spécifique à un archétype (framework, cli, types-only, utility) plutôt que d'une base plate non informée. Les signaux observés mettent à jour une distribution a posteriori Beta — ce qui signifie qu'un délai d'attente ou des données manquantes élargissent l'intervalle de crédibilité au lieu de supposer silencieusement « propre ».

Le score final de chaque paquet est un agrégat pondéré par la confiance des distributions a posteriori des catégories (pondération par variance inverse), produisant à la fois une estimation ponctuelle et un intervalle de crédibilité de 95 %.

Stage 3 — Veto Checks

Trois dérogations strictes contournent entièrement la notation bayésienne et font immédiatement échouer un paquet :

Stage 4 — Transitive Risk Propagation

Une fois les scores de chaque paquet calculés, le risque est propagé de bas en haut à travers le DAG (ordre topologique, feuilles d'abord) :

• Si le effectiveRisk d'une dépendance dépasse un seuil, le risque de son parent est porté à un minimum de 0.8 (marqué comme contaminé).
• Le rayon d'impact de chaque nœud = effectiveRisk × transitive_dependent_count.
• Le pire sous-chemin est tracé et affiché dans la sortie d'audit afin que vous sachiez exactement quelle chaîne de dépendances a provoqué un signalement.

Stage 5 — Report Synthesis

Le rapport d'audit final fusionne les scores intrinsèques, la contamination héritée, les intervalles de crédibilité et les rayons d'impact dans une seule sortie classée. Le score global de l'espace de travail est une moyenne pondérée par le rayon d'impact.

Vulnerability Databases

Revera interroge trois bases de données de vulnérabilités indépendantes en parallèle à chaque vérification. Les résultats sont fusionnés et dédupliqués par alias CVE/GHSA avant d'être utilisés dans la notation.

Si une source expire ou génère une erreur, les autres continuent indépendamment. VulnResult expose les sources ayant répondu (sources) et celles ayant échoué (failedSources) afin que le scoreur bayésien puisse élargir l'intervalle d'incertitude de manière appropriée plutôt que de supposer un état propre.

Architecture & Structure

.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

Revera est fourni avec une suite de benchmarks à grande échelle intégrée dans benchmarker/ qui teste plus de 100 000 paquets npm en parallèle et produit un rapport unique lisible sur GitHub.

Running a 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

Chaque exécution produit un répertoire de sortie autonome contenant :

Latest benchmark (v2 algorithm, seed dataset)

Le benchmark v1 a été exécuté avant le déploiement des vérifications de veto v2. Les chiffres par étiquette malicious/typosquat reflètent l'ancien algorithme. Une ré-exécution complète en v2 sera publiée dans la prochaine version.

Roadmap

• Notation de la réputation des paquets
• Rapports de notation explicables
• Audit direct et transitif des projets
• Vérifications des incidents de confiance de l'éditeur
• Avertissements Levenshtein de typosquat
• Notation bayésienne des a posteriori Beta (v2)
• Propagation transitive du risque dans le DAG (v2)
• Agrégation multi-sources des vulnérabilités (OSV + GitHub + npm)
• Rapports de benchmark lisibles sur GitHub (BENCHMARK.md)
• Commandes de comparaison multi-paquets
• Action GitHub officielle pour les vérifications CI
• Extension VS Code officielle
• Prise en charge native de pnpm
• Prise en charge native de Yarn

FAQ

How do I avoid GitHub API rate limits?

Sans jeton, les requêtes anonymes sont limitées à 60 demandes par heure. Vous pouvez définir un Personal Access Token dans votre configuration :

revera config set githubToken ghp_YOUR_TOKEN

What happens if I am offline?

Revera revient à l'utilisation des fichiers en cache. Vous pouvez explicitement exécuter des commandes en mode hors ligne avec l'option --offline. Si une source de vulnérabilités est indisponible, le scoreur bayésien élargit l'intervalle de crédibilité pour ce paquet plutôt que de supposer un état propre.

Does the add command modify my project?

Revera agit comme un wrapper shell. Il exécute le véritable installateur de paquets après le filtrage.

What is a "tainted" package in the audit output?

Un paquet est marqué comme « contaminé » lorsque l'une de ses dépendances transitives a déclenché un veto ou a obtenu un score critique. La sortie d'audit montre le pire sous-chemin afin que vous puissiez retracer la chaîne exacte de dépendances ayant provoqué le signalement.

How are vulnerabilities deduplicated across three databases?

Chaque vulnérabilité est identifiée par son ID CVE, son ID GHSA ou son ID d'avis npm. Lorsque la même vulnérabilité apparaît dans plusieurs sources, elle est fusionnée en une entrée canonique unique. Les données OSV ont priorité pour les champs descriptifs (résumé, détails) ; la note de sévérité la plus élevée et la plage de versions corrigées la plus complète parmi toutes les sources sont conservées.

Contributing

Veuillez consulter le Guide de contribution pour commencer avec la configuration, les règles de style et les directives relatives aux PR.

Disclaimer

Revera fournit un score de réputation basé sur des signaux observables du projet et des données historiques. Il est destiné à aider les décisions d'ingénierie et ne doit pas être considéré comme un audit de sécurité définitif.

License

Revera est distribué sous la licence MIT.