shai-scan

Escáner CLI sin dependencias para compromisos en la cadena de suministro de npm y PyPI.

¿Por qué?

El 11 de mayo de 2026, un gusano de cadena de suministro autopropagante denominado Mini Shai-Hulud (CVE-2026-45321, GHSA-g7cv-rxg3-hmpx) comprometió el ecosistema de npm. Atribuido a TeamPCP (también conocido como DeadCatx3, PCPcat, ShellForce, CipherForce), el malware secuestró tokens OIDC de GitHub Actions para publicar paquetes maliciosos con procedencia válida de SLSA Build Level 3. Robó credenciales de pipelines CI/CD, proveedores de nube y billeteras de criptomonedas, e instaló hooks de persistencia en Claude Code y VS Code. Un interruptor de seguridad incorporado amenazaba con borrar el directorio home del usuario si los tokens npm eran revocados.

Los paquetes afectados incluyeron TanStack router y start packages, Mistral AI SDKs, OpenSearch client, UiPath tooling y decenas de otros. Debido a que los ataques a la cadena de suministro avanzan rápido, las organizaciones necesitan un escáner ligero y confiable que puedan ejecutar en cualquier lugar sin agregar nuevas dependencias a su propia superficie de ataque.

Características

• Escaneo de lockfiles — Detecta paquetes npm y PyPI comprometidos en package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lock, bun.lockb, poetry.lock, Pipfile.lock y requirements.txt
• Verificaciones de IOC del sistema — Escanea procesos en ejecución, artefactos del sistema de archivos, conexiones de red y rutas de persistencia conocidas en busca de indicadores de compromiso
• Cero dependencias en tiempo de ejecución — Utiliza solo módulos incorporados de Node.js/Bun (fs, path, child_process, os). El escáner no aumenta el riesgo de su cadena de suministro
• Múltiples formatos de salida — Texto legible para humanos, JSON legible por máquinas y SARIF para GitHub Code Scanning

Instalación

No se requiere instalación. Ejecute directamente con su gestor de paquetes preferido:

# npx
npx @digi4care/shai-scan

# bunx
bunx @digi4care/shai-scan

# pnpm dlx
pnpm dlx @digi4care/shai-scan

Instalación global (opcional):

npm install -g @digi4care/shai-scan
# o
pnpm add -g @digi4care/shai-scan

Desde el código fuente:

git clone https://github.com/digi4care/shai-scan.git
cd shai-scan
pnpm install
bun run src/cli.ts --help   # Bun (recomendado para desarrollo)
# o compile y ejecute con Node.js:
pnpm run build && node dist/cli.js --help

Uso

Escanear el proyecto actual

npx @digi4care/shai-scan

Escanear una ruta específica

npx @digi4care/shai-scan ~/projects/my-app

Salida JSON para automatización

npx @digi4care/shai-scan --json .

Salida SARIF para GitHub Code Scanning

npx @digi4care/shai-scan --sarif --sarif-file results.sarif .

Códigos de salida en CI/CD

#!/bin/bash
npx @digi4care/shai-scan --severity high . || {
  code=$?
  if [ "$code" -eq 1 ]; then
    echo "Hallazgos en la cadena de suministro detectados"
    exit 1
  elif [ "$code" -eq 2 ]; then
    echo "Error del escáner"
    exit 2
  fi
}

Integración en CI/CD

GitHub Actions (salida de texto)

name: Supply Chain Scan
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: pnpm install --frozen-lockfile
      - run: npx @digi4care/shai-scan --severity high .

GitHub Actions (carga SARIF)

name: Supply Chain Scan SARIF
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 6 * * 1'

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: pnpm install --frozen-lockfile
      - run: npx @digi4care/shai-scan --sarif --sarif-file results.sarif .
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Formatos de salida

Ejemplo de extracto JSON:

[
  {
    "package": "@tanstack/react-router",
    "version": "1.169.5",
    "ecosystem": "npm",
    "severity": "critical",
    "campaign": "mini-shai-hulud-wave4",
    "cve": "CVE-2026-45321",
    "reference": "https://github.com/TanStack/router/security/advisories/GHSA-g7cv-rxg3-hmpx"
  }
]

Códigos de salida

Agregar nuevas campañas

Cuando se descubra un nuevo ataque a la cadena de suministro, actualice src/db.ts:

1. Agregue un nuevo arreglo CompromisedVersion[] con los paquetes y versiones afectados
2. Añada un nuevo objeto Campaign al arreglo CAMPAIGNS, incluyendo identificadores CVE/GHSA, gravedad, descripción, URL de referencia e indicadores IOC
3. La función buildLookup() reconstruye automáticamente el mapa de búsqueda en la siguiente ejecución

No se requiere un paso de recompilación cuando se usa Bun. Los cambios en src/db.ts surten efecto inmediatamente con bun run src/cli.ts. Para el paquete npm, ejecute pnpm run build después de editar.

Consideraciones de seguridad

• Cero dependencias en tiempo de ejecución: El escáner utiliza solo módulos incorporados de Node.js/Bun. No descarga ni ejecuta código de terceros en tiempo de ejecución, eliminando el riesgo de que el propio escáner se convierta en un vector de compromiso.

• pnpm como gestor de paquetes: pnpm utiliza lockfiles estrictos, no ejecuta scripts de ciclo de vida por defecto y admite almacenamiento direccionable por contenido. Estas propiedades reducen la superficie de ataque en comparación con otros gestores de paquetes.

• Configuración recomendada de .npmrc: Para máxima protección al instalar paquetes, agregue lo siguiente a su .npmrc de proyecto o global:

  root@kitploit:~

  ignore-scripts=true
  engine-strict=true
  

• Sin llamadas de red: shai-scan no se comunica con servidores externos, no descarga firmas ni requiere una clave API. Todos los datos de campaña se distribuyen con el paquete.

Paquetes afectados (Campaña actual)

Se sabe que los siguientes paquetes y versiones están comprometidos en CVE-2026-45321 (Mini Shai-Hulud Wave 4). Esta es un subconjunto representativo; la lista completa se mantiene en src/db.ts.

Licencia

MIT. Consulte LICENSE para más detalles.

Aviso legal

shai-scan es una ayuda de detección, no un sustituto de auditorías de seguridad integrales, revisión de dependencias o plataformas de inteligencia de amenazas. Identifica versiones comprometidas conocidas basándose en la base de datos incluida; los ataques nuevos o de día cero a la cadena de suministro pueden no ser detectados hasta que se agregue una campaña. Practique siempre la defensa en profundidad: audite dependencias, fije versiones, verifique la procedencia y supervise los pipelines CI/CD.