pkgxray — sécurité pré-installation pour les paquets npm, les serveurs MCP et les agents IA

Inspectez un paquet npm ou un serveur MCP avant de l'installer ou de vous y connecter, et obtenez un verdict déterministe et fondé sur des preuves : SAFE, REVIEW ou BLOCK. Analyse statique locale, zéro dépendance — les analyses normales n'exécutent jamais le code des paquets.

Site web · Documentation · Calibration · Signaler un bug

_{Exécutions réelles : guard valide [email protected], puis bloque un échantillon inspiré de la compromission de @solana/web3.js en 2024.}

Points clés

• Zéro dépendance à l'exécution — Node pur, s'exécute entièrement sur votre machine (~25 ms d'analyse statique).
• Les analyses normales n'exécutent jamais le code du paquet — l'archive est lue comme des octets en quarantaine.
• Verdicts déterministes et sourcés — chaque constat nomme le fichier et les preuves ; aucun LLM dans le chemin du verdict, donc le texte injecté ne peut pas l'influencer.
• Conçu pour l'ère des agents — vérifiez les serveurs MCP avant la connexion, contrôlez les installations effectuées par un agent et ré-auditez le trafic MCP en direct.
• Calibré et protégé contre les régressions — zéro faux blocage heuristique sur les 1000 paquets les plus téléchargés, appliqué en CI.

1. Démarrage rapide · 2. Ce qu'il analyse et détecte · 3. Verdicts · 4. Utilisation · 5. Intégrations · 6. Comparaison · 7. Documentation

Pourquoi

Les assistants de codage IA installent des paquets et se connectent à des serveurs MCP à la vitesse de la machine, souvent sans qu'un humain lise le code. Sonatype a identifié plus de 454 600 nouveaux paquets open-source malveillants dans les écosystèmes surveillés en 2025, dont plus de 99 % sur npm (Sonatype). npm audit se demande ce paquet a-t-il une CVE connue ? ; pkgxray se demande aussi que fait réellement le code — avant que quoi que ce soit ne soit installé.

Démarrage rapide

1. Analysez un paquet connu comme bénin (aucune installation de pkgxray nécessaire) :

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

Il place l'archive en quarantaine et exécute les vérifications statiques et de chaîne d'approvisionnement — pas de npm install, pas de scripts de cycle de vie, aucun code de paquet exécuté.

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. Lisez le verdict :

SAFE n'est pas une preuve qu'un paquet est inoffensif ; l'analyse statique ne peut pas voir une charge utile téléchargée uniquement au moment de l'exécution. Voir le modèle de menace.

3. Observez un BLOCK sur le fixture inerte fourni :

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

Le fixture est un texte source inerte modélisant une lecture et une exfiltration de clé SSH fractionnée — il n'est jamais exécuté. Il renvoie BLOCK (code de sortie 2) avec le fichier cité et les preuves.

4. Ajoutez-le à votre flux de travail — rechecks & CI, MCP, porte d'installation Hookshot.

Deux modèles d'exécution. Les analyses par défaut guard et audit sont statiques — le code du paquet n'est jamais exécuté. L'énumération d'un serveur MCP peut le lancer et mcp-proxy l'exécute derrière une porte ; le canary optionnel est la seule exception délibérée qui exécute le paquet dans un bac à sable pour confirmer son comportement — il peut confirmer la malveillance mais jamais prouver qu'un paquet est sûr. Frontière complète : SECURITY.md.

Ce qu'il analyse et détecte

Analyses — pkgxray guard npm:name@version, github:owner/repo, un répertoire local, des lockfiles entiers (npm, yarn, pnpm), des serveurs MCP et des extensions d'agent IA.

Détections — vol d'identifiants (y compris les chemins à fragments scindés), récolte des métadonnées d'instance cloud et des coffres de secrets, injection de prompt, contrebande Unicode, charges utiles base64 et chargeurs de stade 2, exfiltration, persistance (profil shell, planificateur OS et workflows CI/CD injectés), droppers auto-supprimants, réplication de ver de registre (npm publish au moment de l'installation), exécution d'arguments calculés obscurcis, CVE connues (via OSV, avant le téléchargement), divergence des artefacts npm↔GitHub, mises à jour piégées (recheck) et abus de la surface de capacités MCP.

La matrice de couverture complète — et l'angle mort connu du téléchargement ultérieur — se trouve dans le modèle de menace ; un tableau comparatif côte à côte est sur le site web.

Verdicts

Les codes de sortie sont stables et adaptés à la CI : 0 sûr/autoriser · 2 bloquer · 3 examiner.

Utilisation

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

Un .pkgxray.json optionnel (lu par toutes les interfaces) règle la politique ; zéro configuration signifie une sévérité maximale. Les CVE ne peuvent jamais être écartées, chaque assouplissement est affiché, et une analyse en erreur échoue en mode fermé vers review. Schéma et invariants : configuration.md · .pkgxray.example.json.

Intégrations

Un seul moteur derrière chaque point d'entrée. « Fonctionne avec » signifie un guide d'installation documenté, pas une intégration approuvée par un fournisseur.

Comparaison

Exécutez pkgxray en complément de npm audit / OSV-Scanner, pas à leur place — ils répondent à « CVE connue ? ». Face aux outils du même domaine (vérification comportementale de la chaîne d'approvisionnement — Socket.dev, OpenSSF Package Analysis, Cisco MCP Scanner), la comparaison complète des capacités est dans docs/comparison.md et sur le site web.

Preuves

La calibration zéro faux blocage heuristique sur les 1000 paquets les plus téléchargés est protégée contre les régressions en CI (portée & méthodologie), et les exécutions publiées se trouvent sur pkgxray.ca/stats. Cette affirmation est limitée à l'ensemble des plus installés — pas une affirmation de zéro faux blocage sur tous les paquets.

Documentation

Commencez par l'index de la documentation.

Contribuer

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

Les pull requests sont les bienvenues — lisez CONTRIBUTING.md et le Code de conduite. Signalez les vulnérabilités en privé conformément à SECURITY.md. Les versions sont publiées sur npm avec provenance (attestation SLSA), conditionnées aux tests, au benchmark de calibration et au garde de chaîne d'approvisionnement de pkgxray lui-même.