glassworm-hunter

Detecta cargas útiles de ataques a la cadena de suministro GlassWorm en tu máquina. Escanea extensiones de VS Code, paquetes npm, paquetes Python y repositorios git.

Este escáner detecta la técnica de ataque en sí misma: cargas útiles invisibles de selectores de variación Unicode, patrones de decodificación de GlassWorm, indicadores C2 y código de recolección de credenciales.

Instalación

pip install glassworm-hunter

O con pipx:

pipx install glassworm-hunter

Inicio rápido

Escanea tu directorio actual sin escanear extensiones de VS Code/Cursor:

glassworm-hunter scan --no-extensions

Escanea un proyecto específico:

glassworm-hunter scan /ruta/al/proyecto

Qué detecta

Detección de técnica (captura variantes desconocidas)

• Cargas útiles Unicode invisibles - caracteres de selector de variación (U+FE00-FE0F, U+E0100-E01EF) usados para codificar código oculto. Los usos legítimos son de 1 a 2 caracteres para emojis. GlassWorm usa miles.
• Patrones de decodificador GlassWorm - la aritmética de codePointAt + rango de selector de variación que decodifica las cargas útiles invisibles
• Caracteres de anulación bidireccional - ataque Trojan Source (CVE-2021-42574)
• Relleno Hangul - identificadores JavaScript válidos invisibles (U+3164)
• eval/Function con contenido dinámico - sumideros de ejecución alimentados por cadenas decodificadas
• Acceso a credenciales - código que lee .npmrc, .gitcredentials, claves SSH, variables de entorno de tokens
• Patrones de comunicación C2 - llamadas RPC de Solana, URLs de Google Calendar, canales de datos WebRTC en contextos inesperados

Coincidencia de IoC conocidos (complementaria)

• 21 IDs de extensiones maliciosas conocidas de VS Code/OpenVSX (las 5 oleadas)
• 4 paquetes npm maliciosos conocidos
• 14 direcciones IP C2 conocidas
• 3 direcciones de billetera C2 de Solana conocidas
• Correo electrónico del atacante y artefactos de ruta de compilación

Niveles de severidad

Nivel	Significado
CRÍTICO	Carga útil activa de GlassWorm detectada (cluster Unicode invisible en código, patrón de decodificador)
ALTO	IoC malicioso conocido coincidente (IP C2, billetera, dependencia de extensión de malware conocido)
MEDIO	Patrón sospechoso que vale la pena revisar (eval + contenido dinámico, acceso a credenciales, Trojan Source)
BAJO	Informativo (densidad inusual de caracteres de ancho cero, scripts de instalación sospechosos)

Opciones de CLI

glassworm-hunter scan [OPCIONES] [RUTAS...]

Opción	Por defecto	Descripción
--extensions / --no-extensions	activado	Escanea extensiones de VS Code/Cursor/Codium
--npm-scan / --no-npm-scan	activado	Escanea node_modules
--pip-scan / --no-pip-scan	desactivado	Escanea site-packages de Python
--git / --no-git	activado	Escanea repositorios git
--format [console|json|sarif]	console	Formato de salida
--output ARCHIVO	stdout	Escribe el informe en un archivo
--severity [critical|high|medium|low]	low	Severidad mínima a reportar
--max-file-size TAMAÑO	10MB	Omite archivos más grandes que esto
--include-hidden	desactivado	Escanea archivos/directorios ocultos
--quiet	desactivado	Suprime la salida de progreso
--verbose	desactivado	Muestra cada archivo que se está escaneando
--exclude PATRÓN	—	Patrones glob para excluir (repetible)
--disable-rule ID_REGL	—	Suprime reglas de detección específicas (repetible)
--ioc-file ARCHIVO	—	Carga indicadores IoC adicionales desde un archivo JSON

Se muestra una barra de progreso Rich en stderr durante el escaneo. Se suprime automáticamente con --quiet o --verbose. Siempre se imprime una línea de resumen (archivos escaneados, hallazgos, ruta de salida) en stderr después de que el escaneo finalice.

Otros comandos

# Listar todos los IDs de reglas de detección (para usar con --disable-rule)
glassworm-hunter rules

# Actualizar la base de datos local de IoC desde GitHub (fuente por defecto:
# https://raw.githubusercontent.com/afine-com/glassworm-hunter/main/data/ioc.json)
glassworm-hunter update

# Actualizar desde una fuente personalizada (p. ej., servidor interno de inteligencia de amenazas)
glassworm-hunter update --source https://internal.corp/ioc.json

# Forzar sobrescritura de la base de datos local de IoC existente
glassworm-hunter update --force

# Imprimir versión
glassworm-hunter version

Códigos de salida

Código	Significado
0	Sin hallazgos
1	Hallazgos detectados
2	Error del escáner

Si encuentras algo

1. No entres en pánico. El escáner encontró un indicador, no una brecha confirmada. Algunas detecciones pueden ser falsos positivos, y nuestro equipo trabaja continuamente para reducirlos y mejorar la precisión de la detección.
2. No ejecutes el código marcado. No ejecutes, compiles ni pruebes el proyecto afectado hasta que se resuelva.
3. Hallazgos CRÍTICOS: Desinstala la extensión/paquete inmediatamente. Rota tus tokens de NPM, tokens de GitHub, claves SSH y cualquier otra credencial en la máquina.
4. Hallazgos ALTOS: Investiga el archivo marcado. Si está en una dependencia que no instalaste explícitamente, elimínalo.
5. Hallazgos MEDIOS: Revisa el código. Estos patrones son sospechosos pero pueden ser legítimos en algunos contextos.

Integración CI/CD

Salida JSON para procesamiento automatizado:

glassworm-hunter scan . --format json --output report.json --no-extensions

SARIF para GitHub Code Scanning:

glassworm-hunter scan . --format sarif --output results.sarif --no-extensions

Subir SARIF a GitHub:

- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Usar códigos de salida en CI:

glassworm-hunter scan . --severity critical --no-extensions || exit 1

Excluir artefactos de compilación y código de proveedores:

glassworm-hunter scan . --exclude "dist/**" --exclude "*.min.js" --no-extensions

Sin acceso a red

Este escáner está completamente fuera de línea por defecto. Solo lee archivos locales. Sin telemetría, sin llamadas a casa, sin comprobaciones de actualización automáticas. Las bases de datos de IoC están incluidas en el paquete.

El único comando que realiza una solicitud de red es glassworm-hunter update, que obtiene la última base de datos de IoC desde GitHub (o una URL --source personalizada). Nunca se llama automáticamente.

Archivo de configuración

Coloca un .glassworm.yml en la raíz de tu proyecto para establecer valores por defecto:

exclude:
  - "*.min.js"
  - "vendor/**"
  - "dist/**"

disable_rules:
  - zero-width-chars

severity: medium

Los indicadores de CLI anulan los valores del archivo de configuración.

Archivos IoC personalizados

Usa --ioc-file para cargar indicadores adicionales desde un archivo JSON. Esto es útil para inteligencia de amenazas de equipo o interna:

glassworm-hunter scan /ruta --ioc-file /ruta/equipo_ioc.json

El archivo debe seguir el mismo esquema que data/ioc.json:

{
  "schema_version": "1.0",
  "extensions": [{"id": "publisher.name"}],
  "npm_packages": [{"name": "pkg", "malicious_versions": "1.0.0"}],
  "c2_ips": [{"ip": "1.2.3.4"}],
  "c2_wallets": [{"address": "..."}],
  "attacker_artifacts": [{"type": "email", "value": "[email protected]"}]
}

El archivo personalizado se fusiona sobre todas las demás capas de IoC (hardcoded → incluido → usuario ~/.glassworm/ioc.json → --ioc-file).

Capas de la base de datos IoC