glassworm-hunter

# glassworm-hunter

![Glassworm Hunter Logo](https://assets.kitploit.com/production/public/readmes/12745/51866d5ae6a1cd658e373c844337ab4ba2f0095768bedf0ee57eb12450547a6a.jpg)

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

```bash
pip install glassworm-hunter
```

O con pipx:

```bash
pipx install glassworm-hunter
```

## Inicio rápido

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

```bash
glassworm-hunter scan --no-extensions
```

Escanea un proyecto específico:

```bash
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

```bash
# 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:

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

SARIF para GitHub Code Scanning:

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

Subir SARIF a GitHub:

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

Usar códigos de salida en CI:

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

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

```bash
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:

```yaml
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:

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

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

```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](https://www.koi.ai) — 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](https://www.aikido.dev) — 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](https://afine.com) — este escáner. Lee la investigación completa: [Hunting GlassWorm: Open-Source Detection for Invisible Supply Chain Payloads](https://afine.com/blogs/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