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.

Sitio web · Documentación · Calibración · Reportar un error

_{Ejecuciones reales: guard aprueba [email protected] y luego bloquea una muestra modelada a partir del compromiso de 2024 de @solana/web3.js.}

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 · 2. Qué escanea y detecta · 3. Veredictos · 4. Uso · 5. Integraciones · 6. Cómo se compara · 7. Documentación

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). 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):

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.

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. Lee el veredicto:

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.

3. Observa un BLOCK en el fixture inerte incluido:

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, MCP, puerta de instalación 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 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.

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; una tabla comparativa lado a lado está en el sitio web.

Veredictos

Los códigos de salida son estables y aptos para CI: 0 seguro/permitir · 2 bloquear · 3 revisar.

Uso

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 · .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.

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 y en el sitio web.

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), y las ejecuciones publicadas están en 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

Empieza por el índice de documentación.

Contribuciones

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 y el Código de Conducta. Reporta vulnerabilidades de forma privada según 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.