muad-dib

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

Versão francesa

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.

MUAD'DIB combina 22 scanners paralelos (277 regras de detecção), um motor de desofuscação, análise de fluxo de dados entre módulos, pontuação composta (21 regras compostas) e uma 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

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 seguido 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 ver exatamente o que ele detecta e o que não detecta.

Escopo

Detecta (npm e PyPI): pacotes maliciosos conhecidos (correspondência de IOC nome + SHA256), typosquats, RCE em tempo de instalação (lifecycle preinstall/postinstall, curl | sh, tempo de importação do 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 apenas de 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 IOC é reativo) e ecossistemas que não sejam npm/PyPI (RubyGems, Maven, Go). Fingerprinting anti-sandbox determinado e payloads remotos multi-estágio são riscos conhecidos de falsos negativos. Detalhes completos: Modelo de Ameaças.

Sem telemetria. Seu código e resultados de varredura nunca saem da sua máquina — 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 de 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 /caminho/para/projeto

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

Modo interativo

muaddib

Instalação segura

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

Escaneia pacotes em busca de ameaças ANTES de instalar. Bloqueia pacotes maliciosos conhecidos.

Pontuação de risco

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

[SCORE] 58/100 [***********---------] HIGH (ALTO)

Modo explicativo

muaddib scan . --explain

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

Exportar

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 CRÍTICO
muaddib scan . --fail-on high       # Falha em ALTO e CRÍTICO (padrão)

Modo paranóico

muaddib scan . --paranoid

Detecção ultra rigorosa 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 de webhook

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

Filtragem rigorosa (v2.1.2): alertas apenas para correspondências de IOC, ameaças confirmadas por sandbox ou exfiltração de token canário. Triagem prioritária (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     # Todas as 4 funcionalidades temporais
muaddib scan . --temporal          # Detecção de script de ciclo de vida repentino
muaddib scan . --temporal-ast      # Diferença de AST entre versões
muaddib scan . --temporal-publish  # Anomalia de frequência de publicação
muaddib scan . --temporal-maintainer # Detecção de alteração de mantenedor

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

Sandbox Docker

muaddib sandbox <nome-do-pacote>
muaddib sandbox <nome-do-pacote> --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 de monkey-patching para detecção de bombas-relógio (múltiplas execuções em deslocamentos [0h, 72h, 7d]).

Outros comandos

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

Recursos

22 scanners paralelos

277 regras de detecção

Todas as regras (272 REGRAS + 5 PARANOICO) são mapeadas para técnicas MITRE ATT&CK. Consulte SECURITY.md para a referência completa das regras.

Campanhas detectadas

VS Code

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

code --install-extension dnszlsk.muaddib-vscode

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

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

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'

Ganchos pré-commit

muaddib init-hooks                        # Auto-detecção (husky/pre-commit/git)
muaddib init-hooks --type husky           # Forçar husky
muaddib init-hooks --mode diff            # Bloquear apenas NOVAS ameaças

Com 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), apenas regras (o classificador ML está inativo — veja abaixo). Verdade fundamental: 94 ataques reais no escopo + 200 npm aleatórios + 124 PyPI + 107 adversariais/holdout.

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

Protocolo completo, histórico por faixa, a ressalva do cap-35 do PyPI, cobertura operacional (denominada GHSA) e metodologia de re-treinamento ML: Metodologia de Avaliação.

Contribuindo

Adicionar IOCs

Edite arquivos YAML em iocs/:

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

Desenvolvimento

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

Testes

• 4545 testes em 152 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 regras (6/545 escaneados), 2,50% em 200 aleatórios, 9,68% em 124/132 PyPI (primeira medição honesta pós-correção de download Track-D). Classificador ML atualmente inativo — consulte Métricas de Avaliação → Classificador 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 MUAD'DIB detecta e não detecta
• Política de Segurança - Referência das regras de detecção (277 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

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 redistribuí-lo — inclusive através de uma 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 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.