adamsjack711-ux/pkgxraySeguridad previa a la instalación para agentes de IA, paquetes npm y servidores MCP. Análisis estático local sin dependencias; los escaneos normales nunca ejecutan código de paquetes.
<div align="center"> <img src="https://raw.githubusercontent.com/adamsjack711-ux/pkgxray/main/docs/banner.png" alt="pkgxray — analiza los paquetes antes de instalarlos" width="820"> # pkgxray — seguridad previa a la instalación para paquetes npm, servidores MCP y agentes de IA Inspecciona un paquete npm o un servidor MCP **antes** de instalarlo o conectarte a él, y obtén un veredicto determinista respaldado por evidencia: `SAFE`, `REVIEW` o `BLOCK`. Análisis estático local y sin dependencias: los escaneos normales nunca ejecutan el código del paquete. [](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) [**Sitio web**](https://pkgxray.ca) · [**Documentación**](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md) · [**Calibración**](https://pkgxray.ca/stats) · [**Reportar un error**](https://github.com/adamsjack711-ux/pkgxray/issues) <img src="https://assets.kitploit.com/production/public/readmes/43061/49ce4b9fed6753583cc0f87fd2c64c556d14806d31791844eaeefc14f7c4749e.gif" alt="el guard de pkgxray aprueba [email protected] con un veredicto SAFE A+ y luego bloquea una muestra troyanizada con un veredicto BLOCK F y un hallazgo HIGH de acceso a credenciales" width="820"> <sub>Ejecuciones reales: `guard` aprueba `[email protected]` y luego bloquea una muestra modelada a partir del compromiso de 2024 de `@solana/web3.js`.</sub> </div> ## Destacados - **Cero dependencias en tiempo de ejecución**: Node puro, se ejecuta por completo en tu máquina (pasada estática de ~25 ms). - **Los escaneos normales nunca ejecutan el código del paquete**: el tarball se lee como bytes en cuarentena. - **Veredictos deterministas y citados**: cada hallazgo nombra el archivo y la evidencia; no hay LLM en la ruta del veredicto, por lo que el texto inyectado no puede desviarlo. - **Diseñado para la era de los agentes**: evalúa servidores MCP antes de conectar, controla las instalaciones que ejecuta un agente y reaudita el tráfico MCP en vivo. - **Calibrado y con control de regresiones**: cero bloqueos falsos heurísticos en los 1000 paquetes más descargados, garantizado en CI. > **[1. Inicio rápido](#quick-start)** · [2. Qué escanea y detecta](#what-it-scans--detects) · [3. Veredictos](#verdicts) · [4. Uso](#usage) · [5. Integraciones](#integrations) · [6. Cómo se compara](#how-it-compares) · [7. Documentación](#documentation) ## Por qué Los asistentes de codificación con IA instalan paquetes y se conectan a servidores MCP a velocidad de máquina, a menudo sin que un humano lea el código. Sonatype identificó **más de 454 600 paquetes de código abierto maliciosos nuevos en los ecosistemas monitorizados en 2025**, más del 99 % de ellos en npm ([Sonatype](https://www.sonatype.com/state-of-the-software-supply-chain/2026/open-source-malware)). `npm audit` pregunta *¿tiene un CVE conocido?*; pkgxray también pregunta *¿qué hace realmente el código?* — antes de que se instale nada. ## Inicio rápido **1. Escanea un paquete conocido como benigno** (no hace falta instalar pkgxray): ```bash npx --yes [email protected] guard npm:[email protected] ``` Prepara el tarball en cuarentena y ejecuta las comprobaciones estáticas y de cadena de suministro — sin `npm install`, sin scripts de ciclo de vida, sin ejecutar código del paquete. <details> <summary>Salida de ejemplo</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. Lee el veredicto:** | Veredicto | Salida | Significado | |---|---:|---| | `SAFE` | `0` | No hay indicadores de riesgo alto ni medio; la política predeterminada permite la promoción. | | `REVIEW` | `3` | La evidencia es incompleta o una capacidad privilegiada necesita revisión humana. | | `BLOCK` | `2` | Evidencia citada de alta severidad: rechazar o investigar. | `SAFE` no es una prueba de que un paquete sea inofensivo; el análisis estático no puede ver un payload que se descarga solo en tiempo de ejecución. Consulta el [modelo de amenazas](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md). **3. Observa un BLOCK en el fixture inerte incluido:** ```bash npx --yes [email protected] --file examples/onboarding-malicious.json --format markdown ``` El fixture es texto fuente inerte que modela la lectura de una clave SSH dividida en fragmentos y su exfiltración — **nunca se ejecuta**. Devuelve `BLOCK` (salida `2`) con el archivo citado y la evidencia. **4. Añádelo a tu flujo de trabajo** — [rechecks y 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), [puerta de instalación Hookshot](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot). > **Dos modelos de ejecución.** Los escaneos `guard` y `audit` por defecto son **estáticos**: > el código del paquete nunca se ejecuta. Enumerar un servidor MCP puede lanzarlo y > `mcp-proxy` lo ejecuta tras una puerta de control; el > [`canary`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) opcional es la única excepción deliberada que > *ejecuta* el paquete en un sandbox para confirmar el comportamiento: puede confirmar > malicia, pero nunca probar que un paquete es seguro. Límite completo: [SECURITY.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md#scope). ## Qué escanea y detecta **Escanea** — `pkgxray guard npm:name@version`, `github:owner/repo`, un directorio local, lockfiles completos (`npm`, `yarn`, `pnpm`), servidores MCP y extensiones de agentes de IA. **Detecta** — robo de credenciales (incluidas rutas con fragmentos divididos), recolección de metadatos de instancia en la nube y de almacenes de secretos, inyección de prompts, contrabando Unicode, payloads base64 y cargadores de etapa 2, exfiltración, persistencia (perfil de shell, programador del SO y flujos de trabajo CI/CD inyectados), droppers que se autoeliminan, replicación de gusanos en el registro (`npm publish` en tiempo de instalación), ejecución ofuscada de argumentos calculados, CVEs conocidos (vía OSV, antes de la descarga), divergencia de artefactos npm↔GitHub, actualizaciones troyanizadas (`recheck`) y abuso de la superficie de capacidades de MCP. La matriz de cobertura completa — y el punto ciego conocido de descarga posterior — está en el [modelo de amenazas](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md); una tabla comparativa lado a lado está en el [sitio web](https://pkgxray.ca/#catches). ## Veredictos | Veredicto | Qué hacer | |---|---| | `SAFE` | Instala. Solo `safe` sale de cuarentena por defecto. | | `REVIEW` | Inspecciona la copia en cuarentena antes de promoverla. | | `BLOCK` | No lo instales. Cada hallazgo nombra el archivo y la evidencia. | Los códigos de salida son estables y aptos para CI: **`0`** seguro/permitir · **`2`** bloquear · **`3`** revisar. ## Uso ```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` opcional (leído por todas las superficies) ajusta la política; cero configuración significa máxima rigurosidad. Los CVEs nunca pueden omitirse, cada relajación se imprime y un escaneo con errores falla en modo seguro hacia `review`. Esquema e invariantes: [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). ## Integraciones Un único motor detrás de cada punto de entrada. "Funciona con" significa una guía de configuración documentada, no una integración respaldada por el proveedor. | Dónde | Qué hace | Guía | |---|---|---| | Agentes de codificación — Codex, Claude Code, Cursor, Windsurf | Controla las instalaciones y expone las herramientas de auditoría al agente | [coding-agents.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/coding-agents.md) | | Clientes MCP | Evalúa un servidor antes de conectarte; ejecuta pkgxray como servidor MCP | [mcp.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md) | | GitHub Actions / CI | Haz que falle una compilación cuando una dependencia infrinja la política | [github-actions.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/integrations/github-actions.md) | | Puerta de instalación — Hookshot | Ejecuta `guard` en cada paquete que un agente intente instalar | [examples/hookshot/](https://github.com/adamsjack711-ux/pkgxray/blob/main/examples/hookshot) | | Puerta de control MCP en tiempo de ejecución | Haz de proxy de un servidor MCP en vivo y controla cada llamada de herramienta | [`mcp-proxy`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/mcp.md#per-call-runtime-gate-pkgxray-mcp-proxy) | | Monitoreo de dependencias | Reevalúa las dependencias instaladas y preevalúa las actualizaciones de forma programada | [`recheck`](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/reference.md#monitoring-pkgxray-recheck) | ## Cómo se compara Ejecuta pkgxray *junto a* `npm audit` / OSV-Scanner, no en lugar de ellos: responden a *"¿CVE conocido?"*. Frente a herramientas de la misma categoría (evaluación conductual de la cadena de suministro — Socket.dev, OpenSSF Package Analysis, Cisco MCP Scanner), la comparación completa de capacidades está en [docs/comparison.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/comparison.md) y en el [sitio web](https://pkgxray.ca/#comparison). ## Evidencia La **calibración de cero bloqueos falsos heurísticos en los 1000 paquetes más descargados** está sujeta a control de regresiones en CI ([alcance y metodología](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/benchmark.md)), y las ejecuciones publicadas están en [pkgxray.ca/stats](https://pkgxray.ca/stats). Esa afirmación se limita al conjunto más instalado: no es una afirmación de cero bloqueos falsos en todos los paquetes. ## Documentación | Doc | Qué cubre | |---|---| | [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, superficies, principios | | [threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/threat-model.md) | Alcance, puntos ciegos, postura ante la inyección de prompts | | [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) | Evaluación de MCP, proxy en tiempo de ejecución, entrada en el registro | | [canary-threat-model.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/canary-threat-model.md) | El canary conductual opcional | | [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`, política de severidad, `recheck`, servidor de caché | | [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) | Calibración y comparación | | [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) | Contrato 1.0, esquema `--format json` | Empieza por el [índice de documentación](https://github.com/adamsjack711-ux/pkgxray/blob/main/docs/README.md). ## Contribuciones ```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 ``` Las pull requests son bienvenidas: lee [CONTRIBUTING.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/CONTRIBUTING.md) y el [Código de Conducta](https://github.com/adamsjack711-ux/pkgxray/blob/main/CODE_OF_CONDUCT.md). Reporta vulnerabilidades de forma privada según [SECURITY.md](https://github.com/adamsjack711-ux/pkgxray/blob/main/SECURITY.md). Los lanzamientos se publican en npm con procedencia (atestación SLSA), sujetos a las pruebas, al benchmark de calibración y al propio guard de cadena de suministro de pkgxray. <div align="center"> <sub>Creado por <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>
