pkgxray — Sicherheit vor der Installation für npm-Pakete, MCP-Server und KI-Agenten

Prüfe ein npm-Paket oder einen MCP-Server, bevor du es installierst oder dich damit verbindest, und erhalte ein deterministisches, evidenzbasiertes SAFE-, REVIEW- oder BLOCK-Urteil. Lokale, abhängigkeitsfreie statische Analyse — normale Scans führen niemals Paketcode aus.

Website · Dokumentation · Kalibrierung · Fehler melden

_{Echte Läufe: guard lässt [email protected] durchlaufen, dann blockiert es eine Probe, die dem 2024er-Kompromiss von @solana/web3.js nachempfunden ist.}

Highlights

• Keine Laufzeitabhängigkeiten — reines Node, läuft vollständig auf deinem Rechner (~25 ms statischer Durchlauf).
• Normale Scans führen niemals Paketcode aus — das Tarball wird in Quarantäne als Bytes gelesen.
• Deterministische, zitierte Urteile — jeder Befund nennt Datei und Beweis; kein LLM im Urteilspfad, sodass eingeschleuster Text es nicht lenken kann.
• Gebaut für das Agentenzeitalter — MCP-Server vor dem Verbinden prüfen, die Installationen eines Agenten absichern und Live-MCP-Datenverkehr erneut prüfen.
• Kalibriert und regressionsgesichert — null heuristische Fehlblöcke bei den 1000 am häufigsten heruntergeladenen Paketen, in CI durchgesetzt.

1. Schnellstart · 2. Was es scannt & erkennt · 3. Urteile · 4. Verwendung · 5. Integrationen · 6. Wie es im Vergleich abschneidet · 7. Dokumentation

Warum

KI-Codierungsassistenten installieren Pakete und verbinden sich mit MCP-Servern in Maschinengeschwindigkeit, oft ohne dass ein Mensch den Code liest. Sonatype identifizierte im Jahr 2025 mehr als 454.600 neue bösartige Open-Source-Pakete in überwachten Ökosystemen, über 99 % davon auf npm (Sonatype). npm audit fragt hat dies eine bekannte CVE?; pkgxray fragt auch was macht der Code tatsächlich — bevor irgendetwas installiert wird.

Schnellstart

1. Ein bekanntes, unbedenkliches Paket scannen (keine Installation von pkgxray nötig):

npx --yes [email protected] guard npm:[email protected]

Es legt das Tarball in Quarantäne und führt die statischen und Supply-Chain-Prüfungen durch — kein npm install, keine Lebenszyklus-Skripte, kein ausgeführter Paketcode.

Decision: SAFE   Grade: A+ (99/100)
No high- or medium-risk indicators were found in the provided evidence.

Notes:
- INFO npm-vs-github-clean — npm tarball matches the linked GitHub repo at the
  published version. (15/16 files match GitHub @4.21.0)

2. Das Urteil lesen:

SAFE ist kein Beweis, dass ein Paket harmlos ist; statische Analyse kann einen Payload, der nur zur Laufzeit heruntergeladen wird, nicht erkennen. Siehe das Bedrohungsmodell.

3. Ein BLOCK bei der mitgelieferten inerten Fixture sehen:

npx --yes [email protected] --file examples/onboarding-malicious.json --format markdown

Die Fixture ist inaktiver Quelltext, der eine Split-String-SSH-Key-Auslesung und -Exfiltration modelliert — sie wird niemals ausgeführt. Sie gibt BLOCK (Exit 2) mit der zitierten Datei und den Beweisen zurück.

4. Füge es in deinen Workflow ein — Rechecks & CI, MCP, Hookshot-Installations-Gate.

Zwei Ausführungsmodelle. Standardmäßige guard- und audit-Scans sind statisch — Paketcode wird nie ausgeführt. Das Auflisten eines MCP-Servers kann ihn starten, und mcp-proxy führt ihn hinter einem Gate aus; das optionale canary ist die eine bewusste Ausnahme, die das Paket ausführt, um das Verhalten zu bestätigen — es kann Bösartigkeit bestätigen, aber nie beweisen, dass ein Paket sicher ist. Vollständige Grenze: SECURITY.md.

Was es scannt & erkennt

Scans — pkgxray guard npm:name@version, github:owner/repo, ein lokales Verzeichnis, ganze Lockfiles (npm, yarn, pnpm), MCP-Server und KI-Agenten-Erweiterungen.

Erkennt — Zugangsdaten-Diebstahl (inkl. Split-Fragment-Pfaden), Cloud-Instanzmetadaten- und Secret-Store-Auslesen, Prompt-Injection, Unicode-Schmuggel, Base64-Payloads und Stage-2-Loader, Exfiltration, Persistenz (Shell-Profil, OS-Scheduler und injizierte CI/CD-Workflows), selbstlöschende Dropper, Registry-Wurm-Replikation (npm publish zur Installationszeit), verschleierte Ausführung berechneter Argumente, bekannte CVEs (über OSV, vor dem Herunterladen), npm↔GitHub-Artefaktabweichung, trojanisierte Updates (recheck) und Missbrauch der MCP-Fähigkeitsoberfläche.

Die vollständige Abdeckungsmatrix — und der bekannte blinde Fleck bei späteren Downloads — steht im Bedrohungsmodell; eine direkte Vergleichstabelle gibt es auf der Webseite.

Urteile

Exit-Codes sind stabil und CI-freundlich: 0 sicher/erlauben · 2 blockieren · 3 prüfen.

Verwendung

pkgxray guard npm:[email protected] [--format json]   # vet a package before install
pkgxray mcp --package npm:[email protected] npx some-mcp-server   # vet an MCP server; --recheck catches the rug-pull
pkgxray audit package-lock.json [--deep]               # also: yarn.lock, pnpm-lock.yaml, package.json
pkgxray recheck package-lock.json                      # scheduled: non-zero only on a regression

Eine optionale .pkgxray.json (von jeder Oberfläche gelesen) justiert die Richtlinie; keine Konfiguration bedeutet maximale Striktheit. CVEs können niemals wegkonfiguriert werden, jede Lockerung wird ausgegeben, und ein Scan, der einen Fehler aufweist, schlägt fail-closed mit review fehl. Schema und Invarianten: configuration.md · .pkgxray.example.json.

Integrationen

Eine Engine hinter jedem Einstiegspunkt. „Works with“ bedeutet eine dokumentierte Einrichtungsanleitung, keine herstellerseitig unterstützte Integration.

Wie es im Vergleich abschneidet

Führe pkgxray neben npm audit / OSV-Scanner aus, nicht an ihrer Stelle — sie beantworten „bekannte CVE?“. Gegenüber Tools in derselben Kategorie (verhaltensbasierte Supply-Chain-Prüfung — Socket.dev, OpenSSF Package Analysis, Cisco MCP Scanner) findest du den vollständigen Fähigkeitsvergleich in docs/comparison.md und auf der Webseite.

Evidenz

Die Kalibrierung mit null heuristischen Fehlblöcken bei den 1000 am häufigsten heruntergeladenen Paketen ist in CI regressionsgesichert (Umfang & Methodik), und die veröffentlichten Läufe liegen unter pkgxray.ca/stats. Diese Behauptung bezieht sich auf die am häufigsten installierte Gruppe — nicht auf eine Behauptung von null Fehlblöcken für jedes Paket.

Dokumentation

Beginne mit dem Dokumentationsindex.

Mitwirken

npm test                 # zero-dep node --test suite
npm run benchmark        # calibration corpus: precision/recall + 0-false-block gate
npm run validate:website # regenerate + validate the calibration pages

Pull Requests sind willkommen — lies CONTRIBUTING.md und den Verhaltenskodex. Melde Schwachstellen privat gemäß SECURITY.md. Releases veröffentlichen auf npm mit Provenienz (SLSA-Attestierung), abgesichert durch Tests, die Kalibrierungs-Benchmark und pkgxrays eigene Supply-Chain-Absicherung.