glassworm-hunter

# glassworm-hunter

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

Erkennt GlassWorm-Supply-Chain-Angriffspayloads auf Ihrem Rechner. Scannt VS Code-Erweiterungen, npm-Pakete, Python-Pakete und Git-Repositorys.

Dieser Scanner **erkennt die Angriffstechnik selbst** – unsichtbare Unicode-Variation-Selector-Payloads, GlassWorm-Decoder-Muster, C2-Indikatoren und Code zur Erfassung von Anmeldeinformationen.

## Install

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

Oder mit pipx:

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

## Schnellstart

Durchsuchen Sie Ihr aktuelles Verzeichnis, ohne VS Code/Cursor-Erweiterungen zu scannen:

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

Ein bestimmtes Projekt scannen:

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

## Was es erkennt

### Erkennung von Techniken (erfasst unbekannte Varianten)

- **Unsichtbare Unicode-Payloads** – Variationsselektor-Zeichen (U+FE00-FE0F, U+E0100-E01EF) zur Kodierung versteckten Codes. Legitime Verwendungen sind 1-2 Zeichen für Emojis. GlassWorm verwendet Tausende.
- **GlassWorm-Decoder-Muster** – die codePointAt + Variationsselektor-Bereichsarithmetik, die unsichtbare Payloads dekodiert
- **Bidirektionale Überschreibungszeichen** – Trojan Source-Angriff (CVE-2021-42574)
- **Hangul-Füllzeichen** – unsichtbare gültige JavaScript-Bezeichner (U+3164)
- **eval/Function mit dynamischem Inhalt** – Ausführungssenken, die von dekodierten Zeichenketten gespeist werden
- **Zugriff auf Anmeldeinformationen** – Code, der .npmrc, .gitcredentials, SSH-Schlüssel, Token-Umgebungsvariablen liest
- **C2-Kommunikationsmuster** – Solana-RPC-Aufrufe, Google-Kalender-URLs, WebRTC-Datenkanäle in unerwarteten Kontexten

### Bekannter IOC-Abgleich (ergänzend)

- 21 bekannte bösartige VS Code/OpenVSX-Erweiterungs-IDs (alle 5 Wellen)
- 4 bekannte bösartige npm-Pakete
- 14 bekannte C2-IP-Adressen
- 3 bekannte Solana-C2-Wallet-Adressen
- Angreifer-E-Mail und Build-Pfad-Artefakte

## Schweregrade

| Stufe | Bedeutung |
|-------|-----------|
| **KRITISCH** | Aktiver GlassWorm-Payload erkannt (unsichtbarer Unicode-Cluster im Code, Decoder-Muster) |
| **HOCH** | Bekannter bösartiger IOC gefunden (C2-IP, Wallet, Erweiterungsabhängigkeit von bekannter Malware) |
| **MITTEL** | Verdächtiges Muster, das überprüft werden sollte (eval + dynamischer Inhalt, Zugriff auf Anmeldeinformationen, Trojan Source) |
| **NIEDRIG** | Informationell (ungewöhnliche Dichte an Nullbreitenzeichen, verdächtige Installationsskripte) |

## CLI-Optionen

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

| Option | Standard | Beschreibung |
|--------|----------|--------------|
| `--extensions / --no-extensions` | an | VS Code/Cursor/Codium-Erweiterungen scannen |
| `--npm-scan / --no-npm-scan` | an | node_modules scannen |
| `--pip-scan / --no-pip-scan` | aus | Python site-packages scannen |
| `--git / --no-git` | an | Git-Repositorys scannen |
| `--format [console\|json\|sarif]` | console | Ausgabeformat |
| `--output FILE` | stdout | Bericht in Datei schreiben |
| `--severity [critical\|high\|medium\|low]` | low | Mindestschweregrad für Meldung |
| `--max-file-size SIZE` | 10MB | Dateien überspringen, die größer sind als dieser Wert |
| `--include-hidden` | aus | Versteckte Dateien/Verzeichnisse scannen |
| `--quiet` | aus | Fortschrittsausgabe unterdrücken |
| `--verbose` | aus | Jede gescannte Datei anzeigen |
| `--exclude PATTERN` | — | Glob-Muster zum Ausschließen (wiederholbar) |
| `--disable-rule RULE_ID` | — | Bestimmte Erkennungsregeln deaktivieren (wiederholbar) |
| `--ioc-file FILE` | — | Zusätzliche IoC-Indikatoren aus einer JSON-Datei laden |

Während des Scans wird ein Rich-Fortschrittsbalken auf stderr angezeigt. Er wird automatisch mit `--quiet` oder `--verbose` unterdrückt. Eine Zusammenfassungszeile (gescannte Dateien, Funde, Ausgabepfad) wird nach Abschluss des Scans immer auf stderr ausgegeben.

### Weitere Befehle

```bash
# Listet alle Erkennungsregel-IDs auf (zur Verwendung mit --disable-rule)
glassworm-hunter rules

# Aktualisiert die lokale IoC-Datenbank von GitHub (Standardquelle:
# https://raw.githubusercontent.com/afine-com/glassworm-hunter/main/data/ioc.json)
glassworm-hunter update

# Von einer benutzerdefinierten Quelle aktualisieren (z.B. internem Threat-Intelligence-Server)
glassworm-hunter update --source https://internal.corp/ioc.json

# Vorhandene lokale IoC-Datenbank überschreiben erzwingen
glassworm-hunter update --force

# Version ausgeben
glassworm-hunter version
```

## Exit-Codes

| Code | Bedeutung |
|------|-----------|
| 0 | Keine Funde |
| 1 | Funde erkannt |
| 2 | Scanner-Fehler |

## Wenn Sie etwas finden

1. **Keine Panik.** Der Scanner hat einen Indikator gefunden, keinen bestätigten Einbruch. Einige Erkennungen können Fehlalarme sein, und unser Team arbeitet kontinuierlich daran, diese zu reduzieren und die Erkennungsgenauigkeit zu verbessern.
2. **Führen Sie den markierten Code nicht aus.** Starten, bauen oder testen Sie das betroffene Projekt nicht, bis die Situation geklärt ist.
3. **KRITISCHE Funde:** Deinstallieren Sie die Erweiterung/das Paket sofort. Rotieren Sie Ihre NPM-Tokens, GitHub-Tokens, SSH-Schlüssel und alle anderen Anmeldeinformationen auf dem Rechner.
4. **HOHE Funde:** Untersuchen Sie die markierte Datei. Wenn sie sich in einer Abhängigkeit befindet, die Sie nicht explizit installiert haben, entfernen Sie sie.
5. **MITTlere Funde:** Überprüfen Sie den Code. Diese Muster sind verdächtig, können aber in manchen Kontexten legitim sein.

## CI/CD-Integration

JSON-Ausgabe für automatisierte Verarbeitung:

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

SARIF für GitHub Code Scanning:

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

SARIF nach GitHub hochladen:

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

Exit-Codes in CI verwenden:

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

Build-Artefakte und Vendor-Code ausschließen:

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

## Kein Netzwerkzugriff

Dieser Scanner ist standardmäßig vollständig offline. Er liest nur lokale Dateien. Keine Telemetrie, kein Heimtelefonieren, keine automatischen Update-Prüfungen. IoC-Datenbanken sind im Paket enthalten.

Der einzige Befehl, der eine Netzwerkanfrage stellt, ist `glassworm-hunter update`, der die neueste IoC-Datenbank von GitHub (oder einer benutzerdefinierten `--source`-URL) abruft. Er wird nie automatisch aufgerufen.

## Konfigurationsdatei

Legen Sie eine `.glassworm.yml` im Stammverzeichnis Ihres Projekts ab, um Standardwerte festzulegen:

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

disable_rules:
  - zero-width-chars

severity: medium
```

CLI-Flags überschreiben Konfigurationsdateiwerte.

## Benutzerdefinierte IoC-Dateien

Verwenden Sie `--ioc-file`, um zusätzliche Indikatoren aus einer JSON-Datei zu laden. Dies ist nützlich für team-spezifische oder interne Bedrohungsdaten:

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

Die Datei muss dem gleichen Schema wie `data/ioc.json` folgen:

```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]"}]
}
```

Die benutzerdefinierte Datei wird auf alle anderen IoC-Ebenen aufgespielt (hartcodiert → gebündelt → Benutzer `~/.glassworm/ioc.json` → `--ioc-file`).

## IoC-Datenbankebenen

Der Scanner verwendet ein 3+1-Ebenen-IoC-System (jede Ebene wird auf die vorherige aufgespielt, nie entfernt):

1. **Hartcodiert** – im Python-Quellcode integriert, immer verfügbar
2. **Gebündelt** – `data/ioc.json` im Paket enthalten
3. **Benutzer** – `~/.glassworm/ioc.json`, aktualisiert über `glassworm-hunter update`
4. **Benutzerdefiniert** – `--ioc-file`-Flag, höchste Priorität

## Danksagungen

- [Koi Security](https://www.koi.ai) – ursprüngliche Entdeckung von GlassWorm (Oktober 2025) und fortlaufende Verfolgung über mehrere Wellen, einschließlich der OpenVSX/VSCode-Kampagne, Rust-Binary-Pivot und macOS-Pivot. IoC-Daten in diesem Scanner bauen auf ihrer veröffentlichten Forschung auf.
- [Aikido Security](https://www.aikido.dev) – Analyse der GlassWorm-Welle vom März 2026, die GitHub-Repositorys und npm-Pakete angriff, zusammen mit Socket, Step Security und der OpenSourceMalware-Community.
- [AFINE](https://afine.com) – dieser Scanner. Lesen Sie die vollständige Forschung: [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

Der Scanner funktioniert unter Windows. 4 Tests schlagen fehl, wenn Sie keine erhöhte (Administrator-) Eingabeaufforderung ausführen.

## Lizenz

MIT