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

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):