muad-dib

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

Version française

Зачем MUAD'DIB?

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

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

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

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

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

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

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

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

Не входит в область: атаки только в браузере (DOM/window, без API Node.js), содержимое нативных бинарников/WASM (без анализа бинарников), нулевые неизвестные пакеты (поток IOC реактивен) и экосистемы, отличные от npm/PyPI (RubyGems, Maven, Go). Целенаправленная антипесочница и многоступенчатые удалённые полезные нагрузки являются известными рисками ложных отрицаний. Полная информация: Модель угроз.

Нет телеметрии. Ваш код и результаты сканирования никогда не покидают ваш компьютер — MUAD'DIB только загружает разведывательные фиды угроз (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, diff файловой системы, canary-токены, окружение с учётом CI и monkey-patching preload для обнаружения бомб замедленного действия (многократный запуск со смещением [0h, 72h, 7d]).

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

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 параллельных сканера

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

Все правила (272 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)

name: Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: DNSZLSK/muad-dib@v1
        with:
          path: '.'
          fail-on: 'high'
          sarif: 'results.sarif'

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 adversarial/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: "Описание угрозы"
  references:
    - https://example.com/article
  mitre: T1195.002

Разработка

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

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

• 4545 тестов в 152 модульных тестовых файлах
• 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 обнаруживает и не обнаруживает
• Политика безопасности — Справочник правил обнаружения (277 правил)
• Аудит безопасности — Отчёт о валидации обхода защит
• Анализ ЛП — Исторический анализ ложных срабатываний

Лицензия

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.

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