muad-dib v2.12.0

Instalação | Uso | Recursos | VS Code | CI/CD

Version francaise

Por que MUAD'DIB?

Os ataques à cadeia de suprimentos do npm e PyPI estão explodindo. Shai-Hulud comprometeu mais de 25 mil repositórios em 2025. As ferramentas existentes detectam ameaças, mas não ajudam você a responder.

O MUAD'DIB combina 22 scanners paralelos (278 regras de detecção), um mecanismo de desofuscação, análise de fluxo de dados entre módulos, pontuação composta (21 regras compostas) e um sandbox gVisor/Docker para detectar ameaças conhecidas e padrões comportamentais suspeitos em pacotes npm e PyPI. Um classificador XGBoost existe no código, mas está atualmente inativo (consulte Avaliação).

Posicionamento

O MUAD'DIB é um scanner de cadeia de suprimentos gratuito, aberto e totalmente auditável para npm e PyPI. Ele detecta ameaças conhecidas (mais de 225.000 IOCs), RCE em tempo de instalação, fluxos de roubo de credenciais seguidos de exfiltração, payloads ofuscados e outros padrões comportamentais suspeitos — localmente, sem telemetria.

Ele é licenciado sob a AGPL-3.0; uma licença comercial está disponível para organizações que precisam incorporá-lo em um produto proprietário ou executá-lo como um serviço hospedado fechado (consulte Licença).

Ele deliberadamente não tenta fazer tudo — consulte Escopo para saber exatamente o que ele detecta e o que não detecta.

Escopo

Detecta (npm e PyPI): pacotes conhecidamente maliciosos (correspondência de nome + IOC SHA256), typosquats, RCE em tempo de instalação (scripts de ciclo de vida preinstall/postinstall, curl | sh, tempo de importação Python, binding.gyp), leitura de credenciais seguida de exfiltração de rede (intra e entre arquivos), payloads ofuscados / de alta entropia / stub-loader, droppers binários (chmod +x + exec/spawn) e marcadores de evasão anti-análise.

Fora do escopo: ataques somente em navegador (DOM/window, sem API Node.js), o conteúdo de binários nativos / WASM (sem análise binária), pacotes desconhecidos de dia zero (o feed de IOCs é reativo) e ecossistemas que não sejam npm/PyPI (RubyGems, Maven, Go). Fingerprinting anti-sandbox determinado e payloads remotos de múltiplos estágios são riscos conhecidos de falso negativo. Detalhes completos: Modelo de Ameaças.

Sem telemetria. Seu código e os resultados da varredura nunca saem da sua máquina — o MUAD'DIB apenas baixa feeds de inteligência de ameaças (muaddib update) e, para pontuação, lê metadados públicos do registro npm. Alertas via webhook são opcionais.

Instalação

npm (recomendado)

npm install -g muaddib-scanner

A partir do código-fonte

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

Uso

Varredura básica

muaddib scan .
muaddib scan /path/to/project

Varre dependências npm (package.json, node_modules) e Python (requirements.txt, setup.py, pyproject.toml).

Modo interativo

muaddib

Instalação segura

muaddib install <package>
muaddib install lodash axios --save-dev
muaddib install suspicious-pkg --force    # Força a instalação apesar das ameaças

Varre pacotes em busca de ameaças ANTES de instalar. Bloqueia pacotes conhecidamente maliciosos.

Pontuação de risco

Cada varredura exibe uma pontuação de risco de 0 a 100:

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

Modo explicativo

muaddib scan . --explain

Mostra o ID da regra, a técnica MITRE ATT&CK, referências e o playbook de resposta para cada detecção.

Exportação

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

Limite de severidade

muaddib scan . --fail-on critical  # Falha apenas em CRITICAL
muaddib scan . --fail-on high      # Falha em HIGH e CRITICAL (padrão)

Modo paranóico

muaddib scan . --paranoid

Detecção ultra-estrita com menor tolerância. Detecta qualquer acesso à rede, execução de subprocessos, avaliação dinâmica de código e acesso a arquivos sensíveis.

Alertas via webhook

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

Filtragem estrita (v2.1.2): alertas apenas para correspondências de IOC, ameaças confirmadas por sandbox ou exfiltração de token canário. Triagem por prioridade (v2.10.21): P1 (vermelho, IOC/sandbox/canário), P2 (laranja, pontuação alta/compostos), P3 (amarelo, restante).

Detecção de anomalias comportamentais (v2.0)

muaddib scan . --temporal-full     # Todos os 4 recursos temporais
muaddib scan . --temporal          # Detecção de script de ciclo de vida repentino
muaddib scan . --temporal-ast      # Diff de AST entre versões
muaddib scan . --temporal-publish  # Anomalia de frequência de publicação
muaddib scan . --temporal-maintainer # Detecção de mudança de mantenedor

Detecta ataques à cadeia de suprimentos antes que eles apareçam nos bancos de dados de IOC, analisando mudanças entre versões de pacotes. Consulte Metodologia de Avaliação para detalhes.

Sandbox Docker

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

Análise dinâmica em um contêiner Docker isolado: strace, tcpdump, diff do sistema de arquivos, tokens canários, ambiente ciente de CI e pré-carregamento com monkey-patching para detecção de bombas-relógio (múltiplas execuções em deslocamentos de [0h, 72h, 7d]).

Outros comandos

muaddib watch .                    # Monitoramento em tempo real
muaddib daemon                     # Modo daemon (varredura automática no npm install)
muaddib update                     # Atualiza IOCs (rápido, ~5s)
muaddib scrape                     # Atualização completa de IOCs (~5min)
muaddib diff HEAD~1                # Compara ameaças com o commit anterior
muaddib init-hooks                 # Hooks de pré-commit (husky/pre-commit/git)
muaddib scan . --breakdown         # Decomposição de pontuação explicável
muaddib replay                     # Validação de verdade fundamental (90/94 TPR@3, v2.11.48)

Recursos

22 scanners paralelos

278 regras de detecção

Todas as regras (273 RULES + 5 PARANOID) são mapeadas para técnicas MITRE ATT&CK. Consulte SECURITY.md para a referência completa de regras.

Campanhas detectadas

VS Code

A extensão do VS Code varre automaticamente seus projetos npm.

code --install-extension dnszlsk.muaddib-vscode

• MUAD'DIB: Scan Project - Varre o projeto inteiro
• MUAD'DIB: Scan Current File - Varre o arquivo atual
• Configurações: muaddib.autoScan, muaddib.webhookUrl, muaddib.failLevel

Consulte vscode-extension/README.md para a documentação completa.

CI/CD

GitHub Actions (Marketplace)

Mínimo (falha o build em ameaças HIGH+, varredura única):

name: Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: DNSZLSK/[email protected]   # fixe em uma tag de release
        with:
          fail-on: 'high'

Com SARIF enviado para a aba Security (requer security-events: write; executa uma segunda passagem para emitir 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'

Entradas

Saídas (consuma em etapas posteriores via steps.<id>.outputs.*)

Hooks de pré-commit

muaddib init-hooks                        # Detecção automática (husky/pre-commit/git)
muaddib init-hooks --type husky           # Força husky
muaddib init-hooks --mode diff            # Bloqueia apenas NOVAS ameaças

Com o framework pre-commit:

repos:
  - repo: https://github.com/DNSZLSK/muad-dib
    rev: v2.11.139
    hooks:
      - id: muaddib-scan

Avaliação

Última medição v2.11.48 (2026-05-26), somente regras (o classificador de ML está inativo — veja abaixo). Verdade fundamental: 94 ataques reais no escopo + 200 npm aleatórios + 124 PyPI + 107 adversariais/holdout.

Classificador de ML: inativo. Um modelo XGBoost vive em src/ml/, mas nunca é conectado ao muaddib scan, e executa apenas em modo LOG no monitor desde 2026-04-08 (o modelo treinado colapsou, aguardando retreinamento). Todos os números acima são somente regras.

Protocolo completo, histórico por trilha, a ressalva do limite de 35 no PyPI, cobertura operacional (denominada GHSA) e a metodologia de retreinamento de ML: Metodologia de Avaliação.

Contribuindo

Adicionar IOCs

Edite arquivos YAML em iocs/:

- id: NEW-MALWARE-001
  name: "malicious-package"
  version: "*"
  severity: critical
  confidence: high
  source: community
  description: "Descrição da ameaça"
  references:
    - https://example.com/article
  mitre: T1195.002

Desenvolvimento

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

Testes

• 4545 testes em 155 arquivos de teste modulares
• 56 testes de fuzzing - Entradas malformadas, ReDoS, unicode, binário
• Benchmark Datadog 17K - 14.587 amostras de malware confirmadas (no escopo)
• Validação de verdade fundamental - 96 ataques reais (95,74% TPR@3, 88,30% TPR@20 — medição completa v2.11.48 em 94 no escopo)
• Validação de falsos positivos (medição v2.11.48) - 1,10% FPR de regras (6/545 varridos), 2,50% em 200 aleatórios, 9,68% em 124/132 PyPI (primeira medição honesta após a correção do download pós-Track-D). Classificador de ML atualmente inativo — consulte Métricas de Avaliação → Classificador de ML.

Comunidade

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

Documentação

• Blog - Artigos técnicos sobre detecção de ameaças na cadeia de suprimentos
• Carnet de bord - Diário de desenvolvimento (em francês)
• Índice de Documentação - Toda a documentação em um só lugar
• Metodologia de Avaliação - Protocolo experimental, pontuações holdout
• Modelo de Ameaças - O que o MUAD'DIB detecta e não detecta
• Política de Segurança - Referência de regras de detecção (278 regras)
• Auditoria de Segurança - Relatório de validação de bypass
• Análise de FP - Análise histórica de falsos positivos

Licença

O MUAD'DIB é licenciado sob a GNU Affero General Public License v3.0 only (AGPL-3.0-only) — consulte LICENSE e NOTICE.

Você é livre para usar, estudar, modificar e redistribuir — inclusive pela rede — desde que trabalhos derivados e modificações implantadas em rede sejam lançados sob a mesma licença.

Licenciamento comercial: para incorporar o MUAD'DIB em um produto proprietário / de código fechado, ou para oferecê-lo como um serviço hospedado sem as obrigações de divulgação de código-fonte da AGPL, uma licença comercial separada está disponível. Abra uma issue ou entre em contato com o autor (DNSZLSK).

Copyright (C) 2026 DNSZLSK.

A especiaria deve fluir. Os vermes devem morrer.