adamsjack711-ux/pkgxraySicherheit vor der Installation für KI-Agenten, npm-Pakete und MCP-Server. Lokale statische Analyse ohne Abhängigkeiten; normale Scans führen niemals Paketcode aus.
<div align="center"> <img src="https://raw.githubusercontent.com/adamsjack711-ux/pkgxray/main/docs/banner.png" alt="pkgxray — Pakete analysieren, bevor du sie installierst" width="820"> # 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. [](https://www.npmjs.com/package/pkgxray) [](https://www.npmjs.com/package/pkgxray) [](https://github.com/adamsjack711-ux/pkgxray/actions/workflows/pkgxray-test.yml) [](https://github.com/adamsjack711-ux/pkgxray/actions/workflows/pkgxray-benchmark.yml) [](LICENSE) [**Website**](https://pkgxray.ca) · [**Dokumentation**](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md) · [**Kalibrierung**](https://pkgxray.ca/stats) · [**Fehler melden**](https://github.com/adamsjack711-ux/pkgxray/issues) <img src="https://assets.kitploit.com/production/public/readmes/43061/49ce4b9fed6753583cc0f87fd2c64c556d14806d31791844eaeefc14f7c4749e.gif" alt="pkgxray guard lässt [email protected] mit einem SAFE-A+-Urteil durchlaufen und blockiert dann eine trojanisierte Probe mit einem BLOCK-F-Urteil und einem HIGH-Befund für Credential Access" width="820"> <sub>Echte Läufe: <code>guard</code> lässt <code>[email protected]</code> durchlaufen, dann blockiert es eine Probe, die dem 2024er-Kompromiss von <code>@solana/web3.js</code> nachempfunden ist.</sub> </div> ## 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](#quick-start)** · [2. Was es scannt & erkennt](#what-it-scans--detects) · [3. Urteile](#verdicts) · [4. Verwendung](#usage) · [5. Integrationen](#integrations) · [6. Wie es im Vergleich abschneidet](#how-it-compares) · [7. Dokumentation](#documentation) ## 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](https://www.sonatype.com/state-of-the-software-supply-chain/2026/open-source-malware)). `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): ```bash 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. <details> <summary>Beispielausgabe</summary> ```text 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) ``` </details> **2. Das Urteil lesen:** | Urteil | Exit | Bedeutung | |---|---:|---| | `SAFE` | `0` | Keine Hinweise auf hohes oder mittleres Risiko; die Standardrichtlinie erlaubt die Freigabe. | | `REVIEW` | `3` | Die Beweislage ist unvollständig oder eine privilegierte Fähigkeit erfordert menschliche Prüfung. | | `BLOCK` | `2` | Hochriskante, zitierte Beweise — ablehnen oder untersuchen. | `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](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md). **3. Ein BLOCK bei der mitgelieferten inerten Fixture sehen:** ```bash 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md#monitoring-pkgxray-recheck), [MCP](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md#the-pkgxray-mcp-server), [Hookshot-Installations-Gate](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot). > **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`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md#scope). ## 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md); eine direkte Vergleichstabelle gibt es auf der [Webseite](https://pkgxray.ca/#catches). ## Urteile | Urteil | Das solltest du tun | |---|---| | `SAFE` | Installieren. Nur `safe` wird standardmäßig aus der Quarantäne übernommen. | | `REVIEW` | Die quarantänisierte Kopie vor der Übernahme prüfen. | | `BLOCK` | Nicht installieren. Jeder Befund nennt Datei und Beweis. | Exit-Codes sind stabil und CI-freundlich: **`0`** sicher/erlauben · **`2`** blockieren · **`3`** prüfen. ## Verwendung ```bash 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/configuration.md) · [`.pkgxray.example.json`](https://github.com/adamsjack711-ux/pkgxray/blob/main/.pkgxray.example.json). ## Integrationen Eine Engine hinter jedem Einstiegspunkt. „Works with“ bedeutet eine dokumentierte Einrichtungsanleitung, keine herstellerseitig unterstützte Integration. | Wo | Was es tut | Anleitung | |---|---|---| | Codierungsagenten — Codex, Claude Code, Cursor, Windsurf | Installationen absichern und die Audit-Tools dem Agenten zugänglich machen | [coding-agents.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/coding-agents.md) | | MCP-Clients | Server vor dem Verbinden prüfen; pkgxray selbst als MCP-Server ausführen | [mcp.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md) | | GitHub Actions / CI | Build fehlschlagen lassen, wenn eine Abhängigkeit die Richtlinie verletzt | [github-actions.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/github-actions.md) | | Installations-Gate — Hookshot | `guard` für jedes Paket ausführen, das ein Agent zu installieren versucht | [examples/hookshot/](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot) | | MCP-Laufzeit-Gate | Einen Live-MCP-Server proxen und jeden Tool-Aufruf absichern | [`mcp-proxy`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md#per-call-runtime-gate-pkgxray-mcp-proxy) | | Abhängigkeitsüberwachung | Installierte Abhängigkeiten erneut prüfen und Upgrades planmäßig vorab prüfen | [`recheck`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md#monitoring-pkgxray-recheck) | ## 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/comparison.md) und auf der [Webseite](https://pkgxray.ca/#comparison). ## Evidenz Die **Kalibrierung mit null heuristischen Fehlblöcken bei den 1000 am häufigsten heruntergeladenen Paketen** ist in CI regressionsgesichert ([Umfang & Methodik](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/benchmark.md)), und die veröffentlichten Läufe liegen unter [pkgxray.ca/stats](https://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 | Dokument | Inhalt | |---|---| | [architecture.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/architecture.md) · [design.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/design.md) | Pipeline, Oberflächen, Prinzipien | | [threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md) | Umfang, blinde Flecken, Haltung zur Prompt-Injection | | [mcp.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md) · [mcp-registry.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp-registry.md) | MCP-Prüfung, Laufzeit-Proxy, Registry-Eintrag | | [canary-threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) | Die optionale verhaltensbasierte Canary-Funktion | | [configuration.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/configuration.md) · [reference.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md) | `.pkgxray.json`, Schweregradrichtlinie, `recheck`, Cache-Server | | [benchmark.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/benchmark.md) · [comparison.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/comparison.md) | Kalibrierung und wie es im Vergleich abschneidet | | [compatibility.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/compatibility.md) · [json-schema.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/json-schema.md) | 1.0-Vertrag, `--format json`-Schema | Beginne mit dem [Dokumentationsindex](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md). ## Mitwirken ```bash 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/CONTRIBUTING.md) und den [Verhaltenskodex](https://github.com/adamsjack711-ux/pkgxray/blob/main/CODE_OF_CONDUCT.md). Melde Schwachstellen privat gemäß [SECURITY.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md). Releases veröffentlichen auf npm mit Provenienz (SLSA-Attestierung), abgesichert durch Tests, die Kalibrierungs-Benchmark und pkgxrays eigene Supply-Chain-Absicherung. <div align="center"> <sub>Erstellt von <a href="https://github.com/adamsjack711-ux">Jack Adams-Lovell</a> · <a href="https://github.com/adamsjack711-ux/pkgxray/blob/main/LICENSE">MIT</a> · <a href="https://pkgxray.ca">pkgxray.ca</a></sub> </div>
