glassworm-hunter

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

pip install glassworm-hunter

Or with pipx:

pipx install glassworm-hunter

Quick start

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

glassworm-hunter scan --no-extensions

Scansiona un progetto specifico:

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

CLI options

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

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

# 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

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:

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

SARIF per GitHub Code Scanning:

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

Carica SARIF su GitHub:

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

Usa i codici di uscita in CI:

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

Escludi artefatti di build e codice vendor:

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:

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:

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

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

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 — 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 — 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 — questo scanner. Leggi la ricerca completa: 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