Обнаруживает полезные нагрузки атаки GlassWorm на цепочку поставок, сканируя расширения VS Code, пакеты npm/PyPI и git-репозитории на наличие невидимых Unicode-нагрузок, паттернов декодеров, маркеров C2 и известных вредоносных IOCs.
# glassworm-hunter

![Логотип Glassworm Hunter](https://assets.kitploit.com/production/public/readmes/12745/51866d5ae6a1cd658e373c844337ab4ba2f0095768bedf0ee57eb12450547a6a.jpg)

Обнаруживает полезные нагрузки атак на цепочку поставок GlassWorm на вашем устройстве. Сканирует расширения VS Code, пакеты npm, пакеты Python и репозитории git.

Этот сканер **обнаруживает саму технику атаки** — невидимые полезные нагрузки на основе селекторов вариантов Unicode, шаблоны декодировщика GlassWorm, индикаторы C2 и код сбора учетных данных.

## Установка

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

Или с помощью pipx:

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

## Быстрый старт

Сканирование текущей папки без проверки расширений VS Code/Cursor:

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

Сканирование конкретного проекта:

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

## Что он обнаруживает

### Обнаружение техники (ловит неизвестные варианты)

- **Невидимые полезные нагрузки Unicode** — символы селектора вариантов (U+FE00-FE0F, U+E0100-E01EF), используемые для кодирования скрытого кода. Легитимное использование — 1–2 символа для эмодзи. GlassWorm использует тысячи.
- **Шаблоны декодировщика GlassWorm** — арифметика codePointAt + диапазон селекторов вариантов, которая декодирует невидимые полезные нагрузки
- **Символы двунаправленного переопределения** — атака Trojan Source (CVE-2021-42574)
- **Заполнитель хангыль** — невидимые допустимые идентификаторы JavaScript (U+3164)
- **eval/Function с динамическим содержимым** — точки выполнения, получающие декодированные строки
- **Доступ к учетным данным** — код, читающий .npmrc, .gitcredentials, SSH-ключи, переменные окружения с токенами
- **Шаблоны C2-связи** — вызовы RPC Solana, URL Google Calendar, каналы данных WebRTC в неожиданных контекстах

### Сопоставление известных IOC (дополнительно)

- 21 известный вредоносный идентификатор расширения VS Code/OpenVSX (все 5 волн)
- 4 известных вредоносных пакета npm
- 14 известных IP-адресов C2
- 3 известных адреса кошельков Solana C2
- Артефакты электронной почты злоумышленника и пути сборки

## Уровни серьезности

| Уровень | Значение |
|---------|----------|
| **КРИТИЧЕСКИЙ** | Обнаружена активная полезная нагрузка GlassWorm (невидимый кластер Unicode в коде, шаблон декодировщика) |
| **ВЫСОКИЙ** | Совпадение с известным вредоносным IOC (IP C2, кошелек, зависимость расширения от известного вредоносного ПО) |
| **СРЕДНИЙ** | Подозрительный шаблон, требующий проверки (eval + динамическое содержимое, доступ к учетным данным, Trojan Source) |
| **НИЗКИЙ** | Информационный (аномальная плотность символов нулевой ширины, подозрительные скрипты установки) |

## Параметры командной строки

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

| Параметр | По умолчанию | Описание |
|----------|-------------|----------|
| `--extensions / --no-extensions` | вкл | Сканировать расширения VS Code/Cursor/Codium |
| `--npm-scan / --no-npm-scan` | вкл | Сканировать node_modules |
| `--pip-scan / --no-pip-scan` | выкл | Сканировать Python site-packages |
| `--git / --no-git` | вкл | Сканировать репозитории git |
| `--format [console\|json\|sarif]` | console | Формат вывода |
| `--output FILE` | stdout | Записать отчёт в файл |
| `--severity [critical\|high\|medium\|low]` | низкий | Минимальный уровень серьезности для отчёта |
| `--max-file-size SIZE` | 10MB | Пропускать файлы больше этого размера |
| `--include-hidden` | выкл | Сканировать скрытые файлы/папки |
| `--quiet` | выкл | Подавить вывод прогресса |
| `--verbose` | выкл | Показывать каждый сканируемый файл |
| `--exclude PATTERN` | — | Шаблоны исключения (можно повторять) |
| `--disable-rule RULE_ID` | — | Подавить определённые правила обнаружения (можно повторять) |
| `--ioc-file FILE` | — | Загрузить дополнительные индикаторы IOC из JSON-файла |

Во время сканирования на stderr отображается расширенный индикатор прогресса. Он автоматически подавляется при использовании `--quiet` или `--verbose`. После завершения сканирования всегда выводится сводка (сканировано файлов, находки, путь вывода).

### Другие команды

```bash
# Вывести все идентификаторы правил обнаружения (для использования с --disable-rule)
glassworm-hunter rules

# Обновить локальную базу IOC из GitHub (источник по умолчанию:
# https://raw.githubusercontent.com/afine-com/glassworm-hunter/main/data/ioc.json)
glassworm-hunter update

# Обновить из пользовательского источника (например, внутренний сервер threat intelligence)
glassworm-hunter update --source https://internal.corp/ioc.json

# Принудительно перезаписать существующую локальную базу IOC
glassworm-hunter update --force

# Вывести версию
glassworm-hunter version
```

## Коды возврата

| Код | Значение |
|-----|----------|
| 0 | Находок нет |
| 1 | Находки обнаружены |
| 2 | Ошибка сканера |

## Если вы что-то нашли

1. **Не паникуйте.** Сканер нашёл индикатор, а не подтверждённую утечку. Некоторые обнаружения могут быть ложными срабатываниями, и наша команда постоянно работает над их уменьшением и повышением точности.
2. **Не выполняйте помеченный код.** Не запускайте, не собирайте и не тестируйте затронутый проект до устранения проблемы.
3. **Критические находки:** Немедленно удалите расширение/пакет. Смените свои токены NPM, токены GitHub, SSH-ключи и любые другие учетные данные на устройстве.
4. **Высокие находки:** Исследуйте помеченный файл. Если он находится в зависимостях, которые вы не устанавливали явно, удалите его.
5. **Средние находки:** Просмотрите код. Эти шаблоны подозрительны, но в некоторых контекстах могут быть легитимными.

## Интеграция с CI/CD

JSON-вывод для автоматической обработки:

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

SARIF для GitHub Code Scanning:

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

Загрузка SARIF в GitHub:

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

Использование кодов возврата в CI:

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

Исключение артефактов сборки и вендорного кода:

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

## Без сетевого доступа

Этот сканер по умолчанию полностью автономен. Он читает только локальные файлы. Никакой телеметрии, обратных вызовов, автоматических проверок обновлений. Базы данных IOC встроены в пакет.

Единственная команда, которая выполняет сетевой запрос — `glassworm-hunter update`; она загружает последнюю базу IOC из GitHub (или из пользовательского URL `--source`). Она никогда не вызывается автоматически.

## Файл конфигурации

Поместите `.glassworm.yml` в корень проекта, чтобы задать значения по умолчанию:

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

disable_rules:
  - zero-width-chars

severity: medium
```

Флаги командной строки переопределяют значения из файла конфигурации.

## Пользовательские файлы IOC

Используйте `--ioc-file` для загрузки дополнительных индикаторов из JSON-файла. Это полезно для командных или внутренних intelligence-данных:

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

Файл должен соответствовать той же схеме, что и `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]"}]
}
```

Пользовательский файл объединяется поверх всех остальных слоёв IOC (жёстко закодированные → встроенные → пользовательские `~/.glassworm/ioc.json` → `--ioc-file`).

## Слои базы данных IOC

Сканер использует систему из 3+1 слоёв IOC (каждый слой объединяется поверх предыдущего, никогда не удаляет):

1. **Жёстко закодированные** — встроены в исходный код Python, всегда доступны
2. **Встроенные** — `data/ioc.json`, поставляемый с пакетом
3. **Пользовательские** — `~/.glassworm/ioc.json`, обновляется через `glassworm-hunter update`
4. **Пользовательские** — флаг `--ioc-file`, наивысший приоритет

## Авторы

- [Koi Security](https://www.koi.ai) — первоначальное обнаружение GlassWorm (октябрь 2025) и постоянное отслеживание нескольких волн, включая кампанию OpenVSX/VSCode, перенос на Rust и macOS. Данные IOC в этом сканере основаны на их опубликованных исследованиях.
- [Aikido Security](https://www.aikido.dev) — анализ волны GlassWorm марта 2026, нацеленной на репозитории GitHub и пакеты npm, совместно с Socket, Step Security и сообществом OpenSourceMalware.
- [AFINE](https://afine.com) — этот сканер. Читайте полное исследование: [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

Сканер работает в Windows. 4 теста завершаются неудачей, если не запускать командную строку с повышенными привилегиями (Администратор).

## Лицензия

MIT
Популярное

glassworm-hunter
