Detecção de ameaças em tempo real na cadeia de suprimentos npm/PyPI. Análise comportamental de cadeia, varredura de AST, feeds de IOC e mecanismo de pontuação composta.
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).
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.
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.
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
Varre dependências npm (package.json, node_modules) e Python (requirements.txt, setup.py, pyproject.toml).
muaddib
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.
Cada varredura exibe uma pontuação de risco de 0 a 100:
[SCORE] 58/100 [***********---------] HIGH
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.
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 # Falha apenas em CRITICAL
muaddib scan . --fail-on high # Falha em HIGH e CRITICAL (padrão)
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.
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).
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.
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]).
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)
| Scanner | Detecção |
|---|---|
| Análise AST (acorn) | eval, Function, roubo de credenciais, droppers binários, hooks de protótipo |
| Correspondência de padrões | Comandos de shell, reverse shells, dead man's switch |
| Análise de fluxo de dados | Leitura de credenciais + envio de rede (intra-arquivo e entre arquivos) |
| Detecção de ofuscação | Padrões de ofuscação JS (ignora .min.js) |
| Pré-processamento de desofuscação | Concatenação de strings, charcode, base64, array hex, propagação de constantes |
| Fluxo de dados entre módulos | Propagação de taint entre arquivos (cadeias de 3 saltos, métodos de classe) |
| Coerência de intenção | Pareamento fonte-destino intra-arquivo (credencial + eval/rede) |
| Typosquatting | npm + PyPI (distância de Levenshtein) |
| Scanner Python | requirements.txt, setup.py, pyproject.toml, mais de 14 mil IOCs PyPI |
| Entropia de Shannon | Strings de alta entropia (mínimo de 5,5 bits + 50 caracteres) |
| Scanner de configuração de IA | Injeção em .cursorrules, CLAUDE.md, copilot-instructions.md |
| Pacote/Dependências | Scripts de ciclo de vida, correspondência de IOC (mais de 225 mil pacotes) |
| GitHub Actions | Detecção de backdoor Shai-Hulud |
| Scanner de hashes | Hashes de arquivos maliciosos conhecidos |
| Strings IOC (intel-triage P1.1) | Correspondência de strings estilo YARA (Axios 2026, TeamPCP, GlassWorm, CanisterSprawl) |
| AST anti-forense (intel-triage P1.2) | Composto de loop XOR + auto-exclusão + escrita de isca (csec autodelete) |
| Pacote stub (intel-triage P1.3) | Arquivo main minúsculo + URL de dependência externa + hook de ciclo de vida (cadeia ltidi) |
| Scanner Monorepo | Detecção de Lerna/pnpm-workspace/turbo (correção de auditoria MR-C2 do Sprint 1) |
| Diff de dependência confiável (opcional) | Diff contra tarballs de dependências confiáveis do registro (v2.10.x) |
| Código-fonte Python (PYSRC) | Padrões de RCE em tempo de importação/instalação em __init__.py / setup.py (v2.11.41 — fecha a lacuna TrapDoor PyPI) |
| AST Python (PYAST) | AST Tree-sitter-Python com detectores cientes de taint (v2.11.42+) |
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.
| Campanha | Status |
|---|---|
| GlassWorm (2026, mais de 433 pacotes) | Detectada |
| Shai-Hulud v1/v2/v3 (2025) | Detectada |
| event-stream (2018) | Detectada |
| eslint-scope (2018) | Detectada |
| Protestware (node-ipc, colors, faker) | Detectado |
| Typosquats (crossenv, mongose, babelcli) | Detectados |
A extensão do VS Code varre automaticamente seus projetos npm.
code --install-extension dnszlsk.muaddib-vscode
MUAD'DIB: Scan Project - Varre o projeto inteiroMUAD'DIB: Scan Current File - Varre o arquivo atualmuaddib.autoScan, muaddib.webhookUrl, muaddib.failLevelConsulte vscode-extension/README.md para a documentação completa.
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
| Entrada | Descrição | Padrão |
|---|---|---|
path | Caminho a ser varrido | . |
fail-on | Severidade mínima para falhar (critical/high/medium/low/none) | high |
sarif | Caminho do arquivo de saída SARIF — defina para também enviar para a aba Security | |
paranoid | Detecção ultra-estrita (maior FPR) | false |
version | Versão npm do muaddib-scanner a ser instalada | latest |
Saídas (consuma em etapas posteriores via steps.<id>.outputs.*)
| Saída | Descrição |
|---|---|
risk-score | Pontuação de risco de 0 a 100 |
risk-level | SAFE / LOW / MEDIUM / HIGH / CRITICAL |
threats-count | Total de ameaças detectadas |
critical-count / high-count | Ameaças por severidade |
exit-code | 0 = passou no limite fail-on, diferente de zero caso contrário |
sarif-file | Caminho para o arquivo SARIF (vazio se sarif não estiver definido) |
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
Ú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.
| Métrica | Resultado |
|---|---|
| Taxa de detecção (TPR@3) | 95,74% (90/94) |
| Taxa de alerta (TPR@20) | 88,30% (83/94) |
| FPR — npm curado (548) | 1,10% (6/545) |
| FPR — npm aleatório (200) | 2,50% (5/200) |
| FPR — PyPI (132) | 9,68% (12/124) |
| ADR — adversariais + holdout | 96,26% (103/107) |
| TPR selvagem (Datadog 17K) | 92,8% (13.538/14.587) |
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.
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
git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm test
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.
| Injeção anti-scanner (ASI) | Texto de injeção de prompt em comentários/strings que coage um revisor de código LLM a dar um veredito limpo ou a pular um payload ofuscado (ASI-001..004, campanha Hades 2026-06) |