Revera

Der Kredit-Score für npm-Pakete.

Revera hilft dir zu entscheiden, ob ein Paket eine Installation wert ist, bevor du npm install ausführst. Es analysiert Paketqualität, Wartung, Sicherheit, Ökosystem-Gesundheit und Publisher-Vertrauen – und propagiert das Risiko jetzt transitiv über deinen gesamten Abhängigkeitsgraphen – und erstellt anschließend einen erklärbaren, Bayes'schen Reputationsbericht.

Demo

Beobachte, wie revera Pakete in Echtzeit prüft und erklärt.

Schnellstart

Führe revera sofort ohne Installation aus:

npx revera check react

Beispiel

Die Prüfung eines Pakets wie request (das 2020 veraltet wurde) warnt dich sofort mit konkreten Gründen:

$ 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

Global installieren, um das ausführbare Programm aus jedem Verzeichnis nutzen zu können:

npm install -g @aaravmaloo/revera

Verwendung

1. Paket-Reputation prüfen

Analysiere ein Paket und erhalte einen zusammenfassenden Bericht auf hoher Ebene:

revera check lodash

Im Offline-Modus mit gecachten Dateien ausführen:

revera check express --offline

2. Paketbewertung erklären

Erhalte eine detaillierte Aufschlüsselung des Scores, der positiven Signale und der Abzüge:

revera why node-ipc

3. Prüfen und Abhängigkeit hinzufügen

Prüft Pakete vor der Installation und warnt, wenn die Reputation unter deinen konfigurierten Schwellenwert fällt:

revera add express

Du kannst Flags direkt an deinen Paketmanager weiterreichen:

revera add typescript --save-dev

4. Lokalen Workspace prüfen

Prüft alle Pakete im aktuellen Projekt (einschließlich transitiver Abhängigkeiten) und berechnet einen Gesamtscore für die Projektgesundheit:

revera audit

Nur Produktionsabhängigkeiten prüfen:

revera audit --prod

Nur direkte Abhängigkeiten prüfen, transitive Abhängigkeiten überspringen:

revera audit --direct

5. GitHub-Authentifizierung

Authentifiziere dich bei GitHub, um die API-Ratenlimits zu erhöhen (60/Stunde anonym vs. 5.000/Stunde authentifiziert). Du kannst zwischen browserbasiertem OAuth2 oder manueller Eingabe eines Personal Access Tokens wählen. Nach der Autorisierung verschlüsselt revera den Token sicher und speichert ihn im Schlüsselbund deines Betriebssystems (Windows-DPAPI, macOS-Schlüsselbund oder Linux-Secret-Service):

revera login

6. CLI-Einstellungen

Verwalte lokale Einstellungen, die in ~/.revera/config.json gespeichert sind:

revera config
revera config set minScoreThreshold 75
revera config get minScoreThreshold

7. System-Doctor

Überprüfe Umgebungseinstellungen, API-Status und Netzwerkverbindungslatenzen:

revera doctor

8. Cache-Steuerung

Lokalen Metadaten-Cache anzeigen oder leeren:

revera cache
revera cache clear

9. Update-Prüfung

Überprüfe, ob du die neueste Version der revera-Engine ausführst:

revera update

Vergleich

Bewertungs-Engine (v2)

Revera v2 hat das alte flache gewichtete Summenmodell durch eine vierstufige Bayes'sche DAG-Pipeline ersetzt.

Stufe 1 — Abhängigkeitsgraph (DAG)

Alle Abhängigkeiten im Projekt werden in einem gerichteten azyklischen Graphen aufgelöst. Jeder Knoten verfolgt seine vollständige transitive Abhängigkeitsmenge, damit spätere Stufen genaue Blast-Radien berechnen können.

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

Stufe 2 — Paketweise Bewertung (Bayes'sche Beta-Posteriors)

Jede der 8 Bewertungskategorien startet mit einem archetyp-spezifischen Prior (framework, cli, types-only, utility) statt mit einer flachen, uninformierten Basislinie. Beobachtete Signale aktualisieren ein Posterior einer Beta-Verteilung – das bedeutet, dass ein Timeout oder fehlende Daten das Glaubwürdigkeitsintervall erweitern, anstatt stillschweigend von „sauber“ auszugehen.

Der endgültige paketweise Score ist ein konfidenzgewichteter Gesamtwert der Kategorie-Posteriors (inverse Varianzgewichtung), der sowohl eine Punktschätzung als auch ein 95-%-Glaubwürdigkeitsintervall liefert.

Stufe 3 — Veto-Prüfungen

Drei harte Overrides umgehen die Bayes'sche Bewertung vollständig und lassen ein Paket sofort durchfallen:

Stufe 4 — Transitive Risikoweitergabe

Nachdem die paketweisen Scores berechnet wurden, wird das Risiko von unten nach oben durch den DAG propagiert (topologische Reihenfolge, zuerst die Blätter):

• Wenn das effectiveRisk einer Abhängigkeit einen Schwellenwert überschreitet, wird das Risiko des übergeordneten Pakets auf mindestens 0,8 festgelegt (als kontaminiert markiert).
• Der Blast-Radius jedes Knotens = effectiveRisk × transitive_dependent_count.
• Der schlimmste Teilpfad wird nachverfolgt und im Audit-Ergebnis angezeigt, damit du genau weißt, welche Abhängigkeitskette ein Flag verursacht hat.

Stufe 5 — Berichtssynthese

Der finale Audit-Bericht führt intrinsische Scores, vererbte Kontamination, Glaubwürdigkeitsintervalle und Blast-Radien in einer einzigen nach Rangfolge sortierten Ausgabe zusammen. Der Gesamtscore des Workspace ist ein nach Blast-Radius gewichteter Durchschnitt.

Schwachstellen-Datenbanken

Revera fragt bei jeder Prüfung drei unabhängige Schwachstellen-Datenbanken parallel ab. Die Ergebnisse werden zusammengeführt und nach CVE/GHSA-Alias dedupliziert, bevor sie in die Bewertung einfließen.

Wenn eine Quelle einen Timeout oder Fehler aufweist, laufen die anderen unabhängig weiter. Der VulnResult legt offen, welche Quellen geantwortet haben (sources) und welche fehlgeschlagen sind (failedSources), sodass die Bayes'sche Bewertung das Unsicherheitsintervall angemessen erweitern kann, anstatt von „sauber“ auszugehen.

Architektur & Struktur

.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 wird mit einer integrierten Großserien-Benchmark-Suite in benchmarker/ ausgeliefert, die 100k+ npm-Pakete parallel testet und einen einzigen GitHub-lesbaren Bericht erzeugt.

Einen Benchmark ausführen

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

Jeder Lauf erzeugt ein eigenständiges Ausgabeverzeichnis mit:

Aktueller Benchmark (v2-Algorithmus, Seed-Datensatz)

Der v1-Benchmark wurde ausgeführt, bevor die v2-Veto-Prüfungen bereitgestellt wurden. Die Zahlen für bösartige Pakete/Typosquats pro Label spiegeln den Legacy-Algorithmus wider. Eine vollständige v2-Wiederholung wird im nächsten Release veröffentlicht.

Roadmap

• Bewertung der Paket-Reputation
• Erklärbare Bewertungsberichte
• Direkte und transitive Projektprüfung
• Prüfung von Publisher-Vertrauensvorfällen
• Typosquat-Levenshtein-Warnungen
• Bayes'sche Beta-Posterior-Bewertung (v2)
• Transitive DAG-Risikoweitergabe (v2)
• Schwachstellen-Aggregation aus mehreren Quellen (OSV + GitHub + npm)
• GitHub-lesbare Benchmark-Berichte (BENCHMARK.md)
• Befehle zum Vergleich mehrerer Pakete
• Offizielle GitHub Action für CI-Prüfungen
• Offizielle VS-Code-Erweiterung
• Nativer pnpm-Support
• Nativer Yarn-Support

FAQ

Wie vermeide ich GitHub-API-Ratenlimits?

Ohne Token sind anonyme Abfragen auf 60 Anfragen pro Stunde begrenzt. Du kannst in deiner Konfiguration einen Personal Access Token festlegen:

revera config set githubToken ghp_YOUR_TOKEN

Was passiert, wenn ich offline bin?

Revera greift auf Cache-Dateien zurück. Du kannst Befehle mit dem Flag --offline explizit im Offline-Modus ausführen. Wenn eine Schwachstellenquelle nicht verfügbar ist, erweitert die Bayes'sche Bewertung das Glaubwürdigkeitsintervall für dieses Paket, anstatt von „sauber“ auszugehen.

Ändert der add-Befehl mein Projekt?

Revera fungiert als Shell-Wrapper. Es führt nach der Prüfung den echten Paketinstaller aus.

Was ist ein „kontaminiertes“ Paket in der Audit-Ausgabe?

Ein Paket wird als kontaminiert markiert, wenn eine seiner transitiven Abhängigkeiten ein Veto ausgelöst oder kritisch niedrig abgeschnitten hat. Die Audit-Ausgabe zeigt den schlimmsten Teilpfad, damit du die genaue Abhängigkeitskette nachvollziehen kannst, die das Flag verursacht hat.

Wie werden Schwachstellen über drei Datenbanken hinweg dedupliziert?

Jede Schwachstelle wird über ihre CVE-ID, GHSA-ID oder npm-Advisory-ID identifiziert. Wenn dieselbe Schwachstelle in mehreren Quellen erscheint, wird sie zu einem kanonischen Eintrag zusammengeführt. OSV-Daten haben Priorität bei Prosa-Feldern (Zusammenfassung, Details); die höchste Schweregrad-Einstufung und der vollständigste Bereich gepatchter Versionen über alle Quellen bleiben erhalten.

Mitwirken

Bitte lies den Leitfaden zum Mitwirken, um mit Setup, Stilregeln und PR-Richtlinien zu beginnen.

Haftungsausschluss

Revera liefert einen Reputationswert, der auf beobachtbaren Projektsignalen und historischen Daten basiert. Er soll technische Entscheidungen unterstützen und sollte nicht als endgültiges Sicherheits-Audit behandelt werden.

Lizenz

Revera wird unter der MIT-Lizenz vertrieben.