muad-dib v2.12.0

Установка | Использование | Возможности | VS Code | CI/CD

Version francaise

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

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

MUAD'DIB объединяет 22 параллельных сканеров (278 правил обнаружения), движок деобфускации, межмодульный анализ потоков данных, составное скорингование (21 составное правило) и песочницу gVisor/Docker для обнаружения известных угроз и подозрительных поведенческих паттернов в пакетах npm и PyPI. Классификатор XGBoost существует в кодовой базе, но в настоящее время неактивен (см. Оценка).

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

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

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

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

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

Обнаруживает (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). Целенаправленный анти-песочничный фингерпринтинг и многоэтапные удалённые полезные нагрузки — известные риски ложных отрицательных результатов. Полные детали: Модель угроз.

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

Установка

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

npm install -g muaddib-scanner

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

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

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

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

muaddib scan .
muaddib scan /path/to/project

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

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

muaddib

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

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

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

Оценка риска

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

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

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

muaddib scan . --explain

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

Экспорт

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

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

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

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

muaddib scan . --paranoid

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

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

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

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

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

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

Обнаруживает атаки на цепочки поставок до их появления в базах IOC, анализируя изменения между версиями пакетов. Подробности см. в Методология оценки.

Песочница Docker

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

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

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

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)

Возможности

22 параллельных сканера

278 правил обнаружения

Все правила (273 RULES + 5 PARANOID) сопоставлены с техниками MITRE ATT&CK. Полный справочник правил см. в SECURITY.md.

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

VS Code

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

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.

CI/CD

GitHub Actions (Marketplace)

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

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

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'

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

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

Pre-commit хуки

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

С фреймворком pre-commit:

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.

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

Полный протокол, история по трекам, оговорка PyPI cap-35, операционное (в номинации GHSA) покрытие и методология переобучения ML: Методология оценки.

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

Добавление IOC

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

- 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

Разработка

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

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

• 4545 тестов в 155 модульных тестовых файлах
• 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

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

• Блог — Технические статьи об обнаружении угроз цепочкам поставок
• Carnet de bord — Журнал разработки (на французском)
• Индекс документации — Вся документация в одном месте
• Методология оценки — Экспериментальный протокол, оценки holdout
• Модель угроз — Что MUAD'DIB обнаруживает и не обнаруживает
• Политика безопасности — Справочник правил обнаружения (278 правил)
• Аудит безопасности — Отчёт о проверке обхода
• Анализ FP — Исторический анализ ложных срабатываний

Лицензия

MUAD'DIB распространяется под лицензией GNU Affero General Public License v3.0 only (AGPL-3.0-only) — см. LICENSE и NOTICE.

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

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

Copyright (C) 2026 DNSZLSK.

Пряность должна течь. Черви должны умереть.