glassworm-hunter

Logo di 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

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

# 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

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.
Non eseguire il codice segnalato. Non eseguire, compilare o testare il progetto interessato finché il problema non è risolto.
Risultati CRITICAL: Disinstalla immediatamente l'estensione/pacchetto. Ruota i tuoi token NPM, token GitHub, chiavi SSH e qualsiasi altra credenziale sulla macchina.
Risultati HIGH: Indaga sul file segnalato. Se si trova in una dipendenza che non hai installato esplicitamente, rimuovila.
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):

Hardcoded — incorporato nel sorgente Python, sempre disponibile
Bundled — data/ioc.json distribuito con il pacchetto
User — ~/.glassworm/ioc.json, aggiornato tramite glassworm-hunter update
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

glassworm-hunter v1.0.4

Categorie