muad-dib — 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. | Kitploit
<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/10373/84132538a800a2879cff088259fe9e98e975a3fe37f8462fe731d6a06f82314a.png" alt="MUAD'DIB Logo" width="700">
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/muaddib-scanner"><img src="https://img.shields.io/npm/v/muaddib-scanner" alt="npm version"></a>
  <a href="https://github.com/DNSZLSK/muad-dib/actions/workflows/scan.yml"><img src="https://github.com/DNSZLSK/muad-dib/actions/workflows/scan.yml/badge.svg" alt="CI"></a>
  <a href="https://codecov.io/gh/DNSZLSK/muad-dib"><img src="https://codecov.io/gh/DNSZLSK/muad-dib/branch/master/graph/badge.svg" alt="Coverage"></a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/DNSZLSK/muad-dib"><img src="https://api.scorecard.dev/projects/github.com/DNSZLSK/muad-dib/badge" alt="OpenSSF Scorecard"></a>
  <img src="https://img.shields.io/badge/license-AGPL--3.0--only-blue" alt="License">
  <img src="https://img.shields.io/badge/node-%3E=18-brightgreen" alt="Node">
  <img src="https://img.shields.io/badge/IOCs-225,000+-red" alt="IOCs">
</p>

<p align="center">
  <a href="#installation">Instalação</a> |
  <a href="#usage">Uso</a> |
  <a href="#features">Recursos</a> |
  <a href="#vs-code">VS Code</a> |
  <a href="#cicd">CI/CD</a>
</p>

<p align="center">
  <a href="https://github.com/dnszlsk/muad-dib/blob/master/docs/README.fr.md">Version francaise</a>
</p>

---

## 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 **<!--stat:scanners-->22<!--/stat:scanners--> scanners paralelos** (<!--stat:rulesTotal-->278<!--/stat:rulesTotal--> regras de detecção), um **mecanismo de desofuscação**, **análise de fluxo de dados entre módulos**, **pontuação composta** (<!--stat:compound-->21<!--/stat:compound--> 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](#evaluation)).

---

## 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](#license)).

Ele deliberadamente não tenta fazer tudo — consulte [Escopo](#scope) 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](https://github.com/dnszlsk/muad-dib/blob/master/docs/threat-model.md).

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

```bash
npm install -g muaddib-scanner
```

### A partir do código-fonte

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

---

## Uso

### Varredura básica

```bash
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

```bash
muaddib
```

### Instalação segura

```bash
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

```bash
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

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

### Limite de severidade

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

### Modo paranóico

```bash
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

```bash
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)

```bash
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](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md) para detalhes.

### Sandbox Docker

```bash
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

```bash
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

### <!--stat:scanners-->22<!--/stat:scanners--> scanners paralelos

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

### <!--stat:rulesTotal-->278<!--/stat:rulesTotal--> regras de detecção

Todas as regras (<!--stat:rulesCore-->273<!--/stat:rulesCore--> RULES + <!--stat:rulesParanoid-->5<!--/stat:rulesParanoid--> PARANOID) são mapeadas para técnicas MITRE ATT&CK. Consulte [SECURITY.md](https://github.com/dnszlsk/muad-dib/blob/master/SECURITY.md#detection-rules) para a referência completa de regras.

### Campanhas detectadas

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

---

## VS Code

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

```bash
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](https://github.com/dnszlsk/muad-dib/blob/master/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):

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

```yaml
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) |

### Hooks de pré-commit

```bash
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:
```yaml
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.

| 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](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md).

---

## Contribuindo

### Adicionar IOCs

Edite arquivos YAML em `iocs/`:

```yaml
- 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

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

### Testes

- **<!--stat:tests-->4545<!--/stat:tests--> testes** em <!--stat:testFiles-->155<!--/stat:testFiles--> 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](https://dnszlsk.github.io/muad-dib/blog/) - Artigos técnicos sobre detecção de ameaças na cadeia de suprimentos
- [Carnet de bord](https://github.com/dnszlsk/muad-dib/blob/master/docs/CARNET_DE_BORD_MUADDIB.md) - Diário de desenvolvimento (em francês)
- [Índice de Documentação](https://github.com/dnszlsk/muad-dib/blob/master/docs/INDEX.md) - Toda a documentação em um só lugar
- [Metodologia de Avaliação](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md) - Protocolo experimental, pontuações holdout
- [Modelo de Ameaças](https://github.com/dnszlsk/muad-dib/blob/master/docs/threat-model.md) - O que o MUAD'DIB detecta e não detecta
- [Política de Segurança](https://github.com/dnszlsk/muad-dib/blob/master/SECURITY.md) - Referência de regras de detecção (<!--stat:rulesTotal-->278<!--/stat:rulesTotal--> regras)
- [Auditoria de Segurança](https://github.com/dnszlsk/muad-dib/blob/master/docs/SECURITY_AUDIT.md) - Relatório de validação de bypass
- [Análise de FP](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION.md) - 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](https://github.com/dnszlsk/muad-dib/blob/master/LICENSE) e [NOTICE](https://github.com/dnszlsk/muad-dib/blob/master/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](https://github.com/DNSZLSK)).

Copyright (C) 2026 DNSZLSK.

---

<p align="center">
  <strong>A especiaria deve fluir. Os vermes devem morrer.</strong>
</p>
Mais Populares

muad-dib
