adamsjack711-ux/pkgxraySicurezza pre-installazione per agenti AI, pacchetti npm e server MCP. Analisi statica locale zero-dipendenze; le scansioni normali non eseguono mai il codice dei pacchetti.
<div align="center"> <img src="https://raw.githubusercontent.com/adamsjack711-ux/pkgxray/main/docs/banner.png" alt="pkgxray — analizza i pacchetti prima di installarli" width="820"> # 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. [](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) [**Sito web**](https://pkgxray.ca) · [**Documentazione**](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md) · [**Calibrazione**](https://pkgxray.ca/stats) · [**Segnala un bug**](https://github.com/adamsjack711-ux/pkgxray/issues) <img src="https://assets.kitploit.com/production/public/readmes/43061/49ce4b9fed6753583cc0f87fd2c64c556d14806d31791844eaeefc14f7c4749e.gif" alt="pkgxray guard che approva [email protected] con un verdetto SAFE A+, poi blocca un campione trojanizzato con un verdetto BLOCK F e un rilevamento HIGH di accesso alle credenziali" width="820"> <sub>Esecuzioni reali: <code>guard</code> approva <code>[email protected]</code>, poi blocca un campione modellato sul compromesso del 2024 di <code>@solana/web3.js</code>.</sub> </div> ## 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](#quick-start)** · [2. Cosa scansiona e rileva](#what-it-scans--detects) · [3. Verdetti](#verdicts) · [4. Utilizzo](#usage) · [5. Integrazioni](#integrations) · [6. Come si confronta](#how-it-compares) · [7. Documentazione](#documentation) ## 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](https://www.sonatype.com/state-of-the-software-supply-chain/2026/open-source-malware)). `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): ```bash 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. <details> <summary>Esempio di output</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. Leggi il verdetto:** | Verdetto | Exit | Significato | |---|---:|---| | `SAFE` | `0` | Nessun indicatore ad alto o medio rischio; la policy predefinita consente la promozione. | | `REVIEW` | `3` | Le prove sono incomplete o una capacità privilegiata richiede una revisione umana. | | `BLOCK` | `2` | Prove citate ad alta gravità — rifiuta o indaga. | `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](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md). **3. Vedi un BLOCK sul fixture inerte fornito:** ```bash 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](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), [gate di installazione Hookshot](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/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`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) è 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md#scope). ## 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md); una tabella di confronto affiancato è sul [sito web](https://pkgxray.ca/#catches). ## Verdetti | Verdetto | Cosa fare | |---|---| | `SAFE` | Installa. Solo `safe` promuove fuori dalla quarantena per impostazione predefinita. | | `REVIEW` | Ispeziona la copia in quarantena prima di promuoverla. | | `BLOCK` | Non installare. Ogni rilevamento indica il file e le prove. | I codici di uscita sono stabili e adatti alla CI: **`0`** safe/allow · **`2`** block · **`3`** review. ## Utilizzo ```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` 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](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). ## Integrazioni Un solo motore dietro ogni punto di ingresso. "Funziona con" significa una guida di configurazione documentata, non un'integrazione approvata dal fornitore. | Dove | Cosa fa | Guida | |---|---|---| | Agenti di codifica — Codex, Claude Code, Cursor, Windsurf | Controlla le installazioni ed espone gli strumenti di audit all'agente | [coding-agents.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/coding-agents.md) | | Client MCP | Verifica un server prima della connessione; esegui pkgxray stesso come server MCP | [mcp.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md) | | GitHub Actions / CI | Fa fallire una build quando una dipendenza viola la policy | [github-actions.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/github-actions.md) | | Gate di installazione — Hookshot | Esegue `guard` su ogni pacchetto che un agente tenta di installare | [examples/hookshot/](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot) | | Gate MCP runtime | Funge da proxy per un server MCP live e controlla ogni chiamata di tool | [`mcp-proxy`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md#per-call-runtime-gate-pkgxray-mcp-proxy) | | Monitoraggio dipendenze | Ri-verifica le dipendenze installate e pre-verifica gli aggiornamenti secondo una pianificazione | [`recheck`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md#monitoring-pkgxray-recheck) | ## 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](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/comparison.md) e sul [sito web](https://pkgxray.ca/#comparison). ## Prove La **calibrazione a zero falsi blocchi euristici sui 1000 pacchetti più scaricati** è protetta da regressioni in CI ([ambito e metodologia](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/benchmark.md)), e le esecuzioni pubblicate sono su [pkgxray.ca/stats](https://pkgxray.ca/stats). Questa affermazione è limitata all'insieme più installato — non è un'affermazione di zero falsi blocchi su ogni pacchetto. ## Documentazione | Documenti | Cosa copre | |---|---| | [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, superfici, principi | | [threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md) | Ambito, punti ciechi, posizione sulla 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) | Verifica MCP, proxy runtime, voce di registry | | [canary-threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) | Il canary comportamentale opzionale (opt-in) | | [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`, policy di gravità, `recheck`, server 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) | Calibrazione e confronto | | [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) | Contratto 1.0, schema `--format json` | Inizia dall'[indice della documentazione](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md). ## Contribuire ```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 ``` Le pull request sono benvenute — leggi [CONTRIBUTING.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/CONTRIBUTING.md) e il [Codice di condotta](https://github.com/adamsjack711-ux/pkgxray/blob/main/CODE_OF_CONDUCT.md). Segnala le vulnerabilità privatamente secondo [SECURITY.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/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. <div align="center"> <sub>Built by <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>
