pkgxray — sicurezza pre-installazione per pacchetti npm, server MCP e agenti AI

Ispeziona un pacchetto npm o un server MCP prima di installarlo o di connetterti ad esso, e ottieni un verdetto deterministico e basato su prove: SAFE, REVIEW, o BLOCK. Analisi statica locale, a zero dipendenze — le scansioni normali non eseguono mai il codice del pacchetto.

Sito web · Documentazione · Calibrazione · Segnala un bug

_{Esecuzioni reali: guard approva [email protected], poi blocca un campione modellato sul compromesso del 2024 di @solana/web3.js.}

Punti salienti

• Zero dipendenze runtime — puro Node, gira interamente sulla tua macchina (passata statica ~25 ms).
• Le scansioni normali non eseguono mai il codice del pacchetto — il tarball viene letto come byte in quarantena.
• Verdetti deterministici e citati — ogni rilevamento indica il file e le prove; nessun LLM nel percorso del verdetto, quindi il testo iniettato non può influenzarlo.
• Pensato per l'era degli agenti — verifica i server MCP prima della connessione, controlla le installazioni eseguite da un agente e ri-audita il traffico MCP in tempo reale.
• Calibrato e protetto da regressioni — zero falsi blocchi euristici sui 1000 pacchetti più scaricati, garantito in CI.

1. Avvio rapido · 2. Cosa scansiona e rileva · 3. Verdetti · 4. Utilizzo · 5. Integrazioni · 6. Come si confronta · 7. Documentazione

Perché

Gli assistenti di codifica AI installano pacchetti e si connettono a server MCP a velocità macchina, spesso senza che un umano legga il codice. Sonatype ha identificato più di 454.600 nuovi pacchetti open-source dannosi negli ecosistemi monitorati nel 2025, oltre il 99% dei quali su npm (Sonatype). npm audit chiede esiste una CVE nota?; pkgxray chiede anche cosa fa davvero il codice — prima che qualsiasi cosa venga installata.

Avvio rapido

1. Scansiona un pacchetto noto come benigno (non è necessaria l'installazione di pkgxray):

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

Prepara il tarball in quarantena ed esegue i controlli statici e di supply chain — niente npm install, niente script di ciclo di vita, nessun codice di pacchetto eseguito.

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. Leggi il verdetto:

SAFE non è la prova che un pacchetto sia innocuo; l'analisi statica non può vedere un payload scaricato solo a runtime. Vedi il modello di minaccia.

3. Vedi un BLOCK sul fixture inerte fornito:

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

Il fixture è testo sorgente inerte che modella una lettura di chiave SSH a stringa spezzata e l'exfiltrazione — non viene mai eseguito. Restituisce BLOCK (exit 2) con il file e le prove citati.

4. Aggiungilo al tuo flusso di lavoro — recheck e CI, MCP, gate di installazione Hookshot.

Due modelli di esecuzione. Le scansioni predefinite guard e audit sono statiche — il codice del pacchetto non viene mai eseguito. L'enumerazione di un server MCP può avviarlo e mcp-proxy lo esegue dietro un gate; l'opzionale canary è l'unica eccezione deliberata che esegue il pacchetto in una sandbox per confermarne il comportamento — può confermare la malizia ma non provare mai che un pacchetto sia sicuro. Confine completo: SECURITY.md.

Cosa scansiona e rileva

Scansioni — pkgxray guard npm:name@version, github:owner/repo, una directory locale, interi file di lock (npm, yarn, pnpm), server MCP ed estensioni per agenti AI.

Rilevamenti — furto di credenziali (incl. percorsi a frammenti separati), cloud raccolta di metadati dell'istanza e di secret store, prompt injection, contrabbando Unicode payload base64 e loader di stage-2, esfiltrazione, persistenza (profilo di shell, scheduler del sistema operativo e workflow CI/CD iniettati), dropper auto-eliminanti, replicazione worm nei registry (npm publish durante l'installazione), esecuzione offuscata di argomenti calcolati, CVE note (via OSV, prima del download), divergenza degli artefatti npm↔GitHub, aggiornamenti trojanizzati (recheck) e abuso della superficie di capacità MCP.

La matrice di copertura completa — e il noto punto cieco del download successivo — è nel modello di minaccia; una tabella di confronto affiancato è sul sito web.

Verdetti

I codici di uscita sono stabili e adatti alla CI: 0 safe/allow · 2 block · 3 review.

Utilizzo

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 opzionale (letto da ogni superficie) regola la policy; configurazione zero significa massima severità. Le CVE non possono mai essere disattivate, ogni allentamento viene stampato e una scansione che va in errore fallisce in modalità chiusa verso review. Schema e invarianti: configuration.md · .pkgxray.example.json.

Integrazioni

Un solo motore dietro ogni punto di ingresso. "Funziona con" significa una guida di configurazione documentata, non un'integrazione approvata dal fornitore.

Come si confronta

Esegui pkgxray insieme a npm audit / OSV-Scanner, non al posto loro — rispondono a "CVE nota?". Rispetto agli strumenti della stessa categoria (verifica comportamentale della supply chain — Socket.dev, OpenSSF Package Analysis, Cisco MCP Scanner), il confronto completo delle capacità è in docs/comparison.md e sul sito web.

Prove

La calibrazione a zero falsi blocchi euristici sui 1000 pacchetti più scaricati è protetta da regressioni in CI (ambito e metodologia), e le esecuzioni pubblicate sono su pkgxray.ca/stats. Questa affermazione è limitata all'insieme più installato — non è un'affermazione di zero falsi blocchi su ogni pacchetto.

Documentazione

Inizia dall'indice della documentazione.

Contribuire

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

Le pull request sono benvenute — leggi CONTRIBUTING.md e il Codice di condotta. Segnala le vulnerabilità privatamente secondo SECURITY.md. Le release vengono pubblicate su npm con provenienza (attestazione SLSA), controllate da test, benchmark di calibrazione e dalla guardia di supply chain di pkgxray stessa.