glassworm-hunter

# glassworm-hunter

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

Rileva i payload dell'attacco alla supply chain GlassWorm sulla tua macchina. Scansiona estensioni VS Code, pacchetti npm, pacchetti Python e repository git.

Questo scanner **rileva la tecnica di attacco stessa** - payload invisibili con selettori di variazione Unicode, pattern di decodifica GlassWorm, indicatori C2 e codice di raccolta delle credenziali.

## Install

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

Or with pipx:

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

## Quick start

Scansiona la directory corrente senza scansionare le estensioni VS Code/Cursor:

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

Scansiona un progetto specifico:

```bash
glassworm-hunter scan /path/to/project
```

## What it detects

### Technique detection (catches unknown variants)

- **Payload Unicode invisibili** - caratteri selettori di variazione (U+FE00-FE0F, U+E0100-E01EF) usati per codificare codice nascosto. Gli usi legittimi sono 1-2 caratteri per le emoji. GlassWorm ne usa migliaia.
- **Pattern di decodifica GlassWorm** - l'aritmetica codePointAt + intervallo di selettori di variazione che decodifica i payload invisibili
- **Caratteri di override bidirezionale** - attacco Trojan Source (CVE-2021-42574)
- **Riempitivo Hangul** - identificatori JavaScript validi invisibili (U+3164)
- **eval/Function con contenuto dinamico** - sink di esecuzione alimentati da stringhe decodificate
- **Accesso alle credenziali** - codice che legge .npmrc, .gitcredentials, chiavi SSH, variabili d'ambiente dei token
- **Pattern di comunicazione C2** - chiamate RPC di Solana, URL di Google Calendar, canali dati WebRTC in contesti inaspettati

### Known IOC matching (supplementary)

- 21 ID di estensioni VS Code/OpenVSX maligne note (tutte e 5 le ondate)
- 4 pacchetti npm maligni noti
- 14 indirizzi IP C2 noti
- 3 indirizzi wallet Solana C2 noti
- Email dell'attaccante e artefatti del percorso di build

## Severity levels

| Livello | Significato |
|---------|-------------|
| **CRITICAL** | Payload GlassWorm attivo rilevato (cluster di Unicode invisibile nel codice, pattern di decodifica) |
| **HIGH** | IoC noto corrispondente (IP C2, wallet, dipendenza di estensione da malware noto) |
| **MEDIUM** | Pattern sospetto da verificare (eval + contenuto dinamico, accesso alle credenziali, Trojan Source) |
| **LOW** | Informativo (densità anomala di caratteri a larghezza zero, script di installazione sospetti) |

## CLI options

```
glassworm-hunter scan [OPTIONS] [PATHS...]
```

| Opzione | Default | Descrizione |
|---------|---------|-------------|
| `--extensions / --no-extensions` | on | Scansiona estensioni VS Code/Cursor/Codium |
| `--npm-scan / --no-npm-scan` | on | Scansiona node_modules |
| `--pip-scan / --no-pip-scan` | off | Scansiona i site-packages di Python |
| `--git / --no-git` | on | Scansiona repository git |
| `--format [console\|json\|sarif]` | console | Formato di output |
| `--output FILE` | stdout | Scrivi report su file |
| `--severity [critical\|high\|medium\|low]` | low | Livello di gravità minimo da segnalare |
| `--max-file-size SIZE` | 10MB | Salta file più grandi di questo |
| `--include-hidden` | off | Scansiona file/directory nascosti |
| `--quiet` | off | Sopprime l'output di avanzamento |
| `--verbose` | off | Mostra ogni file in scansione |
| `--exclude PATTERN` | — | Pattern glob da escludere (ripetibile) |
| `--disable-rule RULE_ID` | — | Sopprime regole di rilevamento specifiche (ripetibile) |
| `--ioc-file FILE` | — | Carica indicatori IoC aggiuntivi da un file JSON |

Una barra di avanzamento Rich viene mostrata su stderr durante la scansione. Viene automaticamente soppressa con `--quiet` o `--verbose`. Una riga di riepilogo (file scansionati, risultati, percorso di output) viene sempre stampata su stderr al termine della scansione.

### Other commands

```bash
# Elenca tutti gli ID delle regole di rilevamento (per uso con --disable-rule)
glassworm-hunter rules

# Aggiorna il database IoC locale da GitHub (fonte predefinita:
# https://raw.githubusercontent.com/afine-com/glassworm-hunter/main/data/ioc.json)
glassworm-hunter update

# Aggiorna da una fonte personalizzata (es. server interno di threat intelligence)
glassworm-hunter update --source https://internal.corp/ioc.json

# Forza la sovrascrittura del database IoC locale esistente
glassworm-hunter update --force

# Stampa la versione
glassworm-hunter version
```

## Exit codes

| Codice | Significato |
|--------|-------------|
| 0 | Nessun risultato |
| 1 | Risultati rilevati |
| 2 | Errore dello scanner |

## If you find something

1. **Niente panico.** Lo scanner ha trovato un indicatore, non una violazione confermata. Alcuni rilevamenti potrebbero essere falsi positivi, e il nostro team sta lavorando continuamente per ridurli e migliorare la precisione dei rilevamenti.
2. **Non eseguire il codice segnalato.** Non eseguire, compilare o testare il progetto interessato finché il problema non è risolto.
3. **Risultati CRITICAL:** Disinstalla immediatamente l'estensione/pacchetto. Ruota i tuoi token NPM, token GitHub, chiavi SSH e qualsiasi altra credenziale sulla macchina.
4. **Risultati HIGH:** Indaga sul file segnalato. Se si trova in una dipendenza che non hai installato esplicitamente, rimuovila.
5. **Risultati MEDIUM:** Rivedi il codice. Questi pattern sono sospetti ma potrebbero essere legittimi in alcuni contesti.

## CI/CD integration

Output JSON per elaborazione automatica:

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

SARIF per GitHub Code Scanning:

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

Carica SARIF su GitHub:

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

Usa i codici di uscita in CI:

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

Escludi artefatti di build e codice vendor:

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

## No network access

Questo scanner è completamente offline per impostazione predefinita. Legge solo file locali. Nessuna telemetria, nessun phone-home, nessun controllo automatico degli aggiornamenti. I database IoC sono inclusi nel pacchetto.

L'unico comando che effettua una richiesta di rete è `glassworm-hunter update`, che recupera l'ultimo database IoC da GitHub (o da un URL `--source` personalizzato). Non viene mai chiamato automaticamente.

## Configuration file

Posiziona un file `.glassworm.yml` nella radice del tuo progetto per impostare le impostazioni predefinite:

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

disable_rules:
  - zero-width-chars

severity: medium
```

I flag CLI hanno la precedenza sui valori del file di configurazione.

## Custom IoC files

Usa `--ioc-file` per caricare indicatori aggiuntivi da un file JSON. Questo è utile per intelligence specifica del team o interna:

```bash
glassworm-hunter scan /path --ioc-file /path/to/team_ioc.json
```

Il file deve seguire lo stesso schema di `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]"}]
}
```

Il file personalizzato viene unito sopra tutti gli altri livelli IoC (hardcoded → bundled → utente `~/.glassworm/ioc.json` → `--ioc-file`).

## IoC database layers

Lo scanner utilizza un sistema IoC a 3+1 livelli (ogni livello si unisce sopra il precedente, non rimuove mai):

1. **Hardcoded** — incorporato nel sorgente Python, sempre disponibile
2. **Bundled** — `data/ioc.json` distribuito con il pacchetto
3. **User** — `~/.glassworm/ioc.json`, aggiornato tramite `glassworm-hunter update`
4. **Custom** — flag `--ioc-file`, massima priorità

## Credits

- [Koi Security](https://www.koi.ai) — scoperta originale di GlassWorm (ottobre 2025) e monitoraggio continuo su più ondate, inclusa la campagna OpenVSX/VSCode, il pivot binario Rust e il pivot macOS. I dati IoC in questo scanner si basano sulla loro ricerca pubblicata.
- [Aikido Security](https://www.aikido.dev) — analisi dell'ondata di marzo 2026 di GlassWorm che ha preso di mira repository GitHub e pacchetti npm, insieme a Socket, Step Security e la comunità OpenSourceMalware.
- [AFINE](https://afine.com) — questo scanner. Leggi la ricerca 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

Lo scanner funziona su Windows. 4 test falliscono a meno che non si esegua un prompt dei comandi elevato (Amministratore).

## License

MIT