Обнаружение угроз цепочки поставок npm/PyPI в реальном времени. Анализ поведенческих цепочек, сканирование AST, фиды IOC и комплексный механизм оценки.
<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/10373/84132538a800a2879cff088259fe9e98e975a3fe37f8462fe731d6a06f82314a.png" alt="MUAD'DIB Logo" width="700">
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/muaddib-scanner"><img src="https://img.shields.io/npm/v/muaddib-scanner" alt="npm version"></a>
  <a href="https://github.com/DNSZLSK/muad-dib/actions/workflows/scan.yml"><img src="https://github.com/DNSZLSK/muad-dib/actions/workflows/scan.yml/badge.svg" alt="CI"></a>
  <a href="https://codecov.io/gh/DNSZLSK/muad-dib"><img src="https://codecov.io/gh/DNSZLSK/muad-dib/branch/master/graph/badge.svg" alt="Coverage"></a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/DNSZLSK/muad-dib"><img src="https://api.scorecard.dev/projects/github.com/DNSZLSK/muad-dib/badge" alt="OpenSSF Scorecard"></a>
  <img src="https://img.shields.io/badge/license-AGPL--3.0--only-blue" alt="License">
  <img src="https://img.shields.io/badge/node-%3E=18-brightgreen" alt="Node">
  <img src="https://img.shields.io/badge/IOCs-225,000+-red" alt="IOCs">
</p>

<p align="center">
  <a href="#installation">Установка</a> |
  <a href="#usage">Использование</a> |
  <a href="#features">Возможности</a> |
  <a href="#vs-code">VS Code</a> |
  <a href="#cicd">CI/CD</a>
</p>

<p align="center">
  <a href="https://github.com/dnszlsk/muad-dib/blob/master/docs/README.fr.md">Version francaise</a>
</p>

---

## Зачем нужен MUAD'DIB?

Атаки на цепочки поставок npm и PyPI взрываются. Shai-Hulud скомпрометировал более 25 тыс. репозиториев в 2025 году. Существующие инструменты обнаруживают угрозы, но не помогают реагировать на них.

MUAD'DIB объединяет **<!--stat:scanners-->22<!--/stat:scanners--> параллельных сканеров** (<!--stat:rulesTotal-->278<!--/stat:rulesTotal--> правил обнаружения), **движок деобфускации**, **межмодульный анализ потоков данных**, **составное скорингование** (<!--stat:compound-->21<!--/stat:compound--> составное правило) и песочницу gVisor/Docker для обнаружения известных угроз и подозрительных поведенческих паттернов в пакетах npm и PyPI. Классификатор XGBoost существует в кодовой базе, но **в настоящее время неактивен** (см. [Оценка](#evaluation)).

---

## Позиционирование

MUAD'DIB — это бесплатный, открытый и полностью проверяемый сканер цепочек поставок для npm и PyPI. Он обнаруживает **известные** угрозы (225 000+ IOCs), RCE во время установки, потоки «кража учётных данных — затем эксфильтрация», обфусцированные полезные нагрузки и другие подозрительные поведенческие паттерны — локально, без телеметрии.

Он распространяется под лицензией **AGPL-3.0**; **коммерческая лицензия** доступна для организаций, которым необходимо встроить его в проприетарный продукт или запускать как закрытый хостинг-сервис (см. [Лицензия](#license)).

Он намеренно не пытается делать всё — см. [Область применения](#scope), чтобы узнать, что именно он обнаруживает, а что нет.

---

## Область применения

**Обнаруживает** (npm и PyPI): известные вредоносные пакеты (совпадение по имени + SHA256 IOC), typosquatting, RCE во время установки (жизненный цикл `preinstall`/`postinstall`, `curl | sh`, время импорта Python, `binding.gyp`), чтение учётных данных с последующей сетевой эксфильтрацией (внутри и между файлами), обфусцированные / высокоэнтропийные / заглушечные полезные нагрузки, бинарные дропперы (`chmod +x` + exec/spawn) и маркеры уклонения от анти-анализа.

**Вне области применения**: атаки только через браузер (DOM/`window`, без Node.js API), *содержимое* нативных бинарников / WASM (без бинарного анализа), неизвестные zero-day пакеты (канал IOC реактивен) и экосистемы, отличные от npm/PyPI (RubyGems, Maven, Go). Целенаправленный анти-песочничный фингерпринтинг и многоэтапные удалённые полезные нагрузки — известные риски ложных отрицательных результатов. Полные детали: [Модель угроз](https://github.com/dnszlsk/muad-dib/blob/master/docs/threat-model.md).

**Без телеметрии.** Ваш код и результаты сканирования никогда не покидают вашу машину — MUAD'DIB только *загружает* каналы threat-intel (`muaddib update`) и, для скоринга, читает публичные метаданные реестра npm. Вебхук-оповещения — по желанию.

---

## Установка

### npm (рекомендуется)

```bash
npm install -g muaddib-scanner
```

### Из исходников

```bash
git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm link
```

---

## Использование

### Базовое сканирование

```bash
muaddib scan .
muaddib scan /path/to/project
```

Сканирует зависимости как npm (package.json, node_modules), так и Python (requirements.txt, setup.py, pyproject.toml).

### Интерактивный режим

```bash
muaddib
```

### Безопасная установка

```bash
muaddib install <package>
muaddib install lodash axios --save-dev
muaddib install suspicious-pkg --force    # Принудительная установка, несмотря на угрозы
```

Сканирует пакеты на угрозы ДО установки. Блокирует известные вредоносные пакеты.

### Оценка риска

Каждое сканирование отображает оценку риска от 0 до 100:

```
[SCORE] 58/100 [***********---------] HIGH
```

### Режим объяснения

```bash
muaddib scan . --explain
```

Показывает ID правила, технику MITRE ATT&CK, ссылки и плейбук реагирования для каждого обнаружения.

### Экспорт

```bash
muaddib scan . --json > results.json     # JSON
muaddib scan . --html report.html        # HTML
muaddib scan . --sarif results.sarif     # SARIF (GitHub Security)
```

### Порог серьёзности

```bash
muaddib scan . --fail-on critical  # Ошибка только при CRITICAL
muaddib scan . --fail-on high      # Ошибка при HIGH и CRITICAL (по умолчанию)
```

### Параноидальный режим

```bash
muaddib scan . --paranoid
```

Сверхстрогое обнаружение с более низким допуском. Обнаруживает любой сетевой доступ, выполнение подпроцессов, динамическую оценку кода и доступ к чувствительным файлам.

### Вебхук-оповещения

```bash
muaddib scan . --webhook "https://discord.com/api/webhooks/..."
```

Строгая фильтрация (v2.1.2): оповещения только при совпадении IOC, подтверждённых песочницей угрозах или эксфильтрации canary-токенов. Приоритетная триаж (v2.10.21): P1 (красный, IOC/песочница/canary), P2 (оранжевый, высокий балл/составные), P3 (жёлтый, остальное).

### Обнаружение поведенческих аномалий (v2.0)

```bash
muaddib scan . --temporal-full     # Все 4 временных признака
muaddib scan . --temporal          # Обнаружение внезапных скриптов жизненного цикла
muaddib scan . --temporal-ast      # Разница AST между версиями
muaddib scan . --temporal-publish  # Аномалия частоты публикаций
muaddib scan . --temporal-maintainer # Обнаружение смены мейнтейнера
```

Обнаруживает атаки на цепочки поставок **до** их появления в базах IOC, анализируя изменения между версиями пакетов. Подробности см. в [Методология оценки](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md).

### Песочница Docker

```bash
muaddib sandbox <package-name>
muaddib sandbox <package-name> --strict
```

Динамический анализ в изолированном Docker-контейнере: strace, tcpdump, разница файловых систем, canary-токены, среда с поддержкой CI и предзагрузка monkey-patching для обнаружения бомб замедленного действия (многократный запуск со смещениями [0ч, 72ч, 7д]).

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

```bash
muaddib watch .                    # Мониторинг в реальном времени
muaddib daemon                     # Режим демона (автосканирование npm install)
muaddib update                     # Обновление IOC (быстро, ~5с)
muaddib scrape                     # Полное обновление IOC (~5мин)
muaddib diff HEAD~1                # Сравнение угроз с предыдущим коммитом
muaddib init-hooks                 # Pre-commit хуки (husky/pre-commit/git)
muaddib scan . --breakdown         # Объяснимая декомпозиция оценки
muaddib replay                     # Проверка на основе истины (90/94 TPR@3, v2.11.48)
```

---

## Возможности

### <!--stat:scanners-->22<!--/stat:scanners--> параллельных сканера

| Сканер | Обнаружение |
|---------|-----------|
| AST Parse (acorn) | eval, Function, кража учётных данных, бинарные дропперы, хуки прототипов |
| Pattern Matching | Shell-команды, reverse shell, «мёртвый переключатель» |
| Dataflow Analysis | Чтение учётных данных + сетевая отправка (внутри файла и между файлами) |
| Obfuscation Detection | Паттерны обфускации JS (пропуск .min.js) |
| Deobfuscation Pre-processing | Конкатенация строк, charcode, base64, hex-массив, распространение констант |
| Inter-module Dataflow | Распространение заражения между файлами (цепочки из 3 переходов, методы классов) |
| Intent Coherence | Сопряжение источник-приёмник внутри файла (учётные данные + eval/сеть) |
| Typosquatting | npm + PyPI (расстояние Левенштейна) |
| Python Scanner | requirements.txt, setup.py, pyproject.toml, 14K+ PyPI IOCs |
| Shannon Entropy | Строки с высокой энтропией (мин. 5.5 бит + 50 символов) |
| AI Config Scanner | Инъекции в .cursorrules, CLAUDE.md, copilot-instructions.md |
| Package/Dependencies | Скрипты жизненного цикла, сопоставление IOC (225K+ пакетов) |
| GitHub Actions | Обнаружение бэкдора Shai-Hulud |
| Hash Scanner | Известные вредоносные хэши файлов |
| IOC Strings (intel-triage P1.1) | Сопоставление строк в стиле YARA (Axios 2026, TeamPCP, GlassWorm, CanisterSprawl) |
| Anti-Forensic AST (intel-triage P1.2) | Составной XOR-цикл + самоудаление + запись-приманка (csec autodelete) |
| Stub Package (intel-triage P1.3) | Крошечный main-файл + внешний URL зависимости + хук жизненного цикла (цепочка ltidi) |
| Monorepo Scanner | Обнаружение Lerna/pnpm-workspace/turbo (аудит Sprint 1, исправление MR-C2) |
| Trusted-Dep-Diff (по желанию) | Разница с доверенными tarball-зависимостями из реестра (v2.10.x) |
| Python Source (PYSRC) | Паттерны RCE во время импорта/установки в `__init__.py` / `setup.py` (v2.11.41 — закрывает пробел TrapDoor PyPI) |
| Python AST (PYAST) | Tree-sitter-Python AST с детекторами с учётом заражения (v2.11.42+) |
| Anti-Scanner Injection (ASI) | Текст prompt-инъекции в комментариях/строках, который принуждает LLM-ревьюера кода к чистому вердикту или к пропуску обфусцированной полезной нагрузки (ASI-001..004, кампания Hades 2026-06) |

### <!--stat:rulesTotal-->278<!--/stat:rulesTotal--> правил обнаружения

Все правила (<!--stat:rulesCore-->273<!--/stat:rulesCore--> RULES + <!--stat:rulesParanoid-->5<!--/stat:rulesParanoid--> PARANOID) сопоставлены с техниками MITRE ATT&CK. Полный справочник правил см. в [SECURITY.md](https://github.com/dnszlsk/muad-dib/blob/master/SECURITY.md#detection-rules).

### Обнаруженные кампании

| Кампания | Статус |
|----------|--------|
| GlassWorm (2026, 433+ пакетов) | Обнаружена |
| Shai-Hulud v1/v2/v3 (2025) | Обнаружена |
| event-stream (2018) | Обнаружена |
| eslint-scope (2018) | Обнаружена |
| Protestware (node-ipc, colors, faker) | Обнаружена |
| Typosquats (crossenv, mongose, babelcli) | Обнаружены |

---

## VS Code

Расширение VS Code автоматически сканирует ваши npm-проекты.

```bash
code --install-extension dnszlsk.muaddib-vscode
```

- `MUAD'DIB: Scan Project` — Сканировать весь проект
- `MUAD'DIB: Scan Current File` — Сканировать текущий файл
- Настройки: `muaddib.autoScan`, `muaddib.webhookUrl`, `muaddib.failLevel`

Полную документацию см. в [vscode-extension/README.md](https://github.com/dnszlsk/muad-dib/blob/master/vscode-extension/README.md).

---

## CI/CD

### GitHub Actions (Marketplace)

Минимальный вариант (остановить сборку при угрозах HIGH+, одно сканирование):

```yaml
name: Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: DNSZLSK/[email protected]   # закрепить за выпущенным тегом
        with:
          fail-on: 'high'
```

С загрузкой SARIF на вкладку **Security** (требуется `security-events: write`; выполняется второй проход для генерации SARIF):

```yaml
jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: DNSZLSK/[email protected]
        with:
          path: '.'
          fail-on: 'high'
          sarif: 'results.sarif'
```

**Входные параметры**

| Входной параметр | Описание | По умолчанию |
|-------|-------------|---------|
| `path` | Путь для сканирования | `.` |
| `fail-on` | Минимальная серьёзность для остановки (`critical`/`high`/`medium`/`low`/`none`) | `high` |
| `sarif` | Путь к выходному файлу SARIF — укажите, чтобы также загрузить на вкладку Security | |
| `paranoid` | Сверхстрогое обнаружение (выше FPR) | `false` |
| `version` | Версия npm-пакета `muaddib-scanner` для установки | `latest` |

**Выходные параметры** (используйте на последующих шагах через `steps.<id>.outputs.*`)

| Выходной параметр | Описание |
|--------|-------------|
| `risk-score` | Оценка риска 0–100 |
| `risk-level` | `SAFE` / `LOW` / `MEDIUM` / `HIGH` / `CRITICAL` |
| `threats-count` | Общее количество обнаруженных угроз |
| `critical-count` / `high-count` | Угрозы по серьёзности |
| `exit-code` | `0` = прошёл порог `fail-on`, иначе ненулевой |
| `sarif-file` | Путь к файлу SARIF (пусто, если `sarif` не задан) |

### Pre-commit хуки

```bash
muaddib init-hooks                        # Автоопределение (husky/pre-commit/git)
muaddib init-hooks --type husky           # Принудительно husky
muaddib init-hooks --mode diff            # Блокировать только НОВЫЕ угрозы
```

С фреймворком pre-commit:
```yaml
repos:
  - repo: https://github.com/DNSZLSK/muad-dib
    rev: v2.11.139
    hooks:
      - id: muaddib-scan
```

---

## Оценка

Последнее измерение **v2.11.48** (2026-05-26), **только правила** (ML-классификатор неактивен — см. ниже). Истина: 94 реальные атаки в области применения + 200 случайных npm + 124 PyPI + 107 состязательных/holdout.

| Метрика | Результат |
|--------|--------|
| Доля обнаружения (TPR@3) | **95.74%** (90/94) |
| Доля оповещений (TPR@20) | **88.30%** (83/94) |
| FPR — курируемый npm (548) | **1.10%** (6/545) |
| FPR — случайный npm (200) | **2.50%** (5/200) |
| FPR — PyPI (132) | **9.68%** (12/124) |
| ADR — состязательные + holdout | **96.26%** (103/107) |
| Wild TPR (Datadog 17K) | **92.8%** (13,538/14,587) |

**ML-классификатор: неактивен.** Модель XGBoost находится в `src/ml/`, но никогда не подключается к `muaddib scan` и работает в режиме LOG-ONLY в мониторе с 2026-04-08 (обученная модель схлопнулась, ожидается переобучение). Все приведённые выше цифры — только правила.

Полный протокол, история по трекам, оговорка PyPI cap-35, операционное (в номинации GHSA) покрытие и методология переобучения ML: [Методология оценки](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md).

---

## Вклад в проект

### Добавление IOC

Редактируйте YAML-файлы в `iocs/`:

```yaml
- id: NEW-MALWARE-001
  name: "malicious-package"
  version: "*"
  severity: critical
  confidence: high
  source: community
  description: "Threat description"
  references:
    - https://example.com/article
  mitre: T1195.002
```

### Разработка

```bash
git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm test
```

### Тестирование

- **<!--stat:tests-->4545<!--/stat:tests--> тестов** в <!--stat:testFiles-->155<!--/stat:testFiles--> модульных тестовых файлах
- **56 фаззинг-тестов** — Некорректные входные данные, ReDoS, unicode, бинарные данные
- **Бенчмарк Datadog 17K** — 14 587 подтверждённых образцов вредоносного ПО (в области применения)
- **Проверка на основе истины** — 96 реальных атак (95.74% TPR@3, 88.30% TPR@20 — полное измерение v2.11.48 на 94 в области применения)
- **Проверка ложных срабатываний** (измерение v2.11.48) — 1.10% FPR правил (6/545 просканировано), 2.50% на 200 случайных, 9.68% на 124/132 PyPI (первое честное измерение после исправления загрузки Track-D). ML-классификатор в настоящее время неактивен — см. Метрики оценки → ML-классификатор.

---

## Сообщество

- Discord: https://discord.gg/y8zxSmue

---

## Документация

- [Блог](https://dnszlsk.github.io/muad-dib/blog/) — Технические статьи об обнаружении угроз цепочкам поставок
- [Carnet de bord](https://github.com/dnszlsk/muad-dib/blob/master/docs/CARNET_DE_BORD_MUADDIB.md) — Журнал разработки (на французском)
- [Индекс документации](https://github.com/dnszlsk/muad-dib/blob/master/docs/INDEX.md) — Вся документация в одном месте
- [Методология оценки](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md) — Экспериментальный протокол, оценки holdout
- [Модель угроз](https://github.com/dnszlsk/muad-dib/blob/master/docs/threat-model.md) — Что MUAD'DIB обнаруживает и не обнаруживает
- [Политика безопасности](https://github.com/dnszlsk/muad-dib/blob/master/SECURITY.md) — Справочник правил обнаружения (<!--stat:rulesTotal-->278<!--/stat:rulesTotal--> правил)
- [Аудит безопасности](https://github.com/dnszlsk/muad-dib/blob/master/docs/SECURITY_AUDIT.md) — Отчёт о проверке обхода
- [Анализ FP](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION.md) — Исторический анализ ложных срабатываний

---

## Лицензия

MUAD'DIB распространяется под лицензией **GNU Affero General Public License v3.0 only** (`AGPL-3.0-only`) — см. [LICENSE](https://github.com/dnszlsk/muad-dib/blob/master/LICENSE) и [NOTICE](https://github.com/dnszlsk/muad-dib/blob/master/NOTICE).

Вы можете свободно использовать, изучать, модифицировать и распространять его — в том числе через сеть — при условии, что производные работы и модификации, развёрнутые в сети, выпускаются под той же лицензией.

**Коммерческое лицензирование:** для встраивания MUAD'DIB в проприетарный / закрытый продукт или предоставления его как хостинг-сервиса без обязательств AGPL по раскрытию исходного кода доступна отдельная коммерческая лицензия. Откройте issue или свяжитесь с автором ([DNSZLSK](https://github.com/DNSZLSK)).

Copyright (C) 2026 DNSZLSK.

---

<p align="center">
  <strong>Пряность должна течь. Черви должны умереть.</strong>
</p>
Популярное

muad-dib
