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

Opciones de CLI

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

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

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

El escáner utiliza un sistema de IoC de 3+1 capas (cada capa se fusiona sobre la anterior, nunca elimina):

1. Hardcoded — integrada en el código fuente de Python, siempre disponible
2. Incluida — data/ioc.json enviada con el paquete
3. Usuario — ~/.glassworm/ioc.json, actualizada mediante glassworm-hunter update
4. Personalizada — indicador --ioc-file, máxima prioridad

Créditos

• Koi Security — descubrimiento original de GlassWorm (octubre de 2025) y seguimiento continuo a través de múltiples oleadas, incluida la campaña OpenVSX/VSCode, el pivote binario Rust y el pivote macOS. Los datos IoC en este escáner se basan en su investigación publicada.
• Aikido Security — análisis de la oleada de GlassWorm de marzo de 2026 que atacó repositorios de GitHub y paquetes npm, junto con Socket, Step Security y la comunidad OpenSourceMalware.
• AFINE — este escáner. Lee la investigación completa: Hunting GlassWorm: Open-Source Detection for Invisible Supply Chain Payloads

Windows

El escáner funciona en Windows. 4 pruebas fallan a menos que ejecutes un símbolo del sistema elevado (Administrador).

Licencia

MIT