adamsjack711-ux/pkgxraySécurité pré-installation pour agents IA, paquets npm et serveurs MCP. Analyse statique locale sans dépendance ; les analyses normales n'exécutent jamais le code des paquets.
<div align="center"> <img src="https://raw.githubusercontent.com/adamsjack711-ux/pkgxray/main/docs/banner.png" alt="pkgxray — analysez les paquets avant de les installer" width="820"> # 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. [](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) [**Site web**](https://pkgxray.ca) · [**Documentation**](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md) · [**Calibration**](https://pkgxray.ca/stats) · [**Signaler un bug**](https://github.com/adamsjack711-ux/pkgxray/issues) <img src="https://assets.kitploit.com/production/public/readmes/43061/49ce4b9fed6753583cc0f87fd2c64c556d14806d31791844eaeefc14f7c4749e.gif" alt="Le garde pkgxray validant [email protected] avec un verdict SAFE A+, puis bloquant un échantillon piégé avec un verdict BLOCK F et une détection d'accès aux identifiants HIGH" width="820"> <sub>Exécutions réelles : <code>guard</code> valide <code>[email protected]</code>, puis bloque un échantillon inspiré de la compromission de <code>@solana/web3.js</code> en 2024.</sub> </div> ## 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](#quick-start)** · [2. Ce qu'il analyse et détecte](#what-it-scans--detects) · [3. Verdicts](#verdicts) · [4. Utilisation](#usage) · [5. Intégrations](#integrations) · [6. Comparaison](#how-it-compares) · [7. Documentation](#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](https://www.sonatype.com/state-of-the-software-supply-chain/2026/open-source-malware)). `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) : ```bash 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é. <details> <summary>Exemple de sortie</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. Lisez le verdict :** | Verdict | Exit | Signification | |---|---:|---| | `SAFE` | `0` | Aucun indicateur de risque élevé ou moyen ; la politique par défaut autorise la promotion. | | `REVIEW` | `3` | Les preuves sont incomplètes ou une capacité privilégiée nécessite un examen humain. | | `BLOCK` | `2` | Preuves citées de gravité élevée — rejetez ou enquêtez. | `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](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md). **3. Observez un BLOCK sur le fixture inerte fourni :** ```bash 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](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), [porte d'installation Hookshot](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/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`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md#scope). ## 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md) ; un tableau comparatif côte à côte est sur le [site web](https://pkgxray.ca/#catches). ## Verdicts | Verdict | Vous devriez | |---|---| | `SAFE` | Installer. Seul `safe` sort de la quarantaine par défaut. | | `REVIEW` | Inspecter la copie en quarantaine avant de la promouvoir. | | `BLOCK` | Ne pas installer. Chaque constat nomme le fichier et les preuves. | Les codes de sortie sont stables et adaptés à la CI : **`0`** sûr/autoriser · **`2`** bloquer · **`3`** examiner. ## Utilisation ```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 ``` 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](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). ## 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. | Où | Ce qu'il fait | Guide | |---|---|---| | Agents de codage — Codex, Claude Code, Cursor, Windsurf | Contrôle les installations et expose les outils d'audit à l'agent | [coding-agents.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/coding-agents.md) | | Clients MCP | Vérifie un serveur avant la connexion ; exécute pkgxray lui-même comme serveur MCP | [mcp.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md) | | GitHub Actions / CI | Fait échouer la build quand une dépendance franchit la politique | [github-actions.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/github-actions.md) | | Porte d'installation — Hookshot | Exécute `guard` sur chaque paquet qu'un agent tente d'installer | [examples/hookshot/](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot) | | Porte MCP à l'exécution | Proxifie un serveur MCP en direct et contrôle chaque appel d'outil | [`mcp-proxy`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md#per-call-runtime-gate-pkgxray-mcp-proxy) | | Surveillance des dépendances | Revérifie les dépendances installées et pré-vérifie les mises à niveau selon un calendrier | [`recheck`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md#monitoring-pkgxray-recheck) | ## 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/comparison.md) et sur le [site web](https://pkgxray.ca/#comparison). ## 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/benchmark.md)), et les exécutions publiées se trouvent sur [pkgxray.ca/stats](https://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 | Doc | Ce qu'il couvre | |---|---| | [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, interfaces, principes | | [threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md) | Portée, angles morts, position sur l'injection de prompt | | [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) | Vérification MCP, proxy à l'exécution, entrée de registre | | [canary-threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) | Le canary comportemental optionnel | | [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`, politique de sévérité, `recheck`, serveur de cache | | [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) | Calibration et comparaison | | [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) | Contrat 1.0, schéma `--format json` | Commencez par l'[index de la documentation](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md). ## Contribuer ```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 ``` Les pull requests sont les bienvenues — lisez [CONTRIBUTING.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/CONTRIBUTING.md) et le [Code de conduite](https://github.com/adamsjack711-ux/pkgxray/blob/main/CODE_OF_CONDUCT.md). Signalez les vulnérabilités en privé conformément à [SECURITY.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/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. <div align="center"> <sub>Créé par <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>
