muad-dib

Installazione | Utilizzo | Funzionalità | VS Code | CI/CD

Versione francese

Perché MUAD'DIB?

Gli attacchi alla supply chain di npm e PyPI stanno esplodendo. Shai-Hulud ha compromesso oltre 25.000 repository nel 2025. Gli strumenti esistenti rilevano le minacce ma non aiutano a rispondere.

MUAD'DIB combina 22 scanner paralleli (277 regole di rilevamento), un motore di deoffuscazione, analisi del flusso dati inter-modulo, punteggio composto (21 regole composte) e un sandbox gVisor/Docker per rilevare minacce note e modelli comportamentali sospetti in pacchetti npm e PyPI. Un classificatore XGBoost esiste nel codice ma è attualmente inattivo (vedere Valutazione).

Posizionamento

MUAD'DIB è uno scanner gratuito, aperto e completamente verificabile per la supply chain di npm e PyPI. Rileva minacce note (oltre 225.000 IOCs), RCE al momento dell'installazione, flussi di furto di credenziali e successiva esfiltrazione, payload offuscati e altri modelli comportamentali sospetti — localmente, senza telemetria.

È concesso in licenza AGPL-3.0; una licenza commerciale è disponibile per le organizzazioni che necessitano di incorporarlo in un prodotto proprietario o eseguirlo come servizio ospitato chiuso (vedere Licenza).

Non cerca deliberatamente di fare tutto — vedere Ambito per sapere esattamente cosa rileva e cosa non rileva.

Ambito

Rileva (npm e PyPI): pacchetti noti come dannosi (corrispondenza nome + SHA256 IOC), typosquat, RCE all'installazione (lifecycle preinstall/postinstall, curl | sh, tempo di import Python, binding.gyp), lettura di credenziali seguita da esfiltrazione di rete (intra-file e cross-file), payload offuscati / ad alta entropia / stub-loader, dropper binari (chmod +x + exec/spawn) e marcatori di evasione anti-analisi.

Fuori ambito: attacchi solo browser (DOM/window, nessuna API Node.js), il contenuto di binari nativi / WASM (nessuna analisi binaria), pacchetti sconosciuti zero-day (il feed IOC è reattivo) ed ecosistemi non npm/PyPI (RubyGems, Maven, Go). Il fingerprinting anti-sandbox determinato e i payload remoti multistadio sono rischi noti di falsi negativi. Dettaglio completo: Modello di minaccia.

Nessuna telemetria. Il tuo codice e i risultati della scansione non lasciano mai la tua macchina — MUAD'DIB scarica solo feed di threat intelligence (muaddib update) e, per il punteggio, legge i metadati pubblici del registro npm. Gli avvisi webhook sono facoltativi.

Installazione

npm (consigliato)

npm install -g muaddib-scanner

Da sorgente

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

Utilizzo

Scansione di base

muaddib scan .
muaddib scan /path/to/project

Scansiona sia le dipendenze npm (package.json, node_modules) che Python (requirements.txt, setup.py, pyproject.toml).

Modalità interattiva

muaddib

Installazione sicura

muaddib install <package>
muaddib install lodash axios --save-dev
muaddib install suspicious-pkg --force    # Forza l'installazione nonostante le minacce

Scansiona i pacchetti per minacce PRIMA di installare. Blocca i pacchetti noti come dannosi.

Punteggio di rischio

Ogni scansione mostra un punteggio di rischio 0-100:

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

Modalità spiegazione

muaddib scan . --explain

Mostra ID regola, tecnica MITRE ATT&CK, riferimenti e playbook di risposta per ogni rilevamento.

Esportazione

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

Soglia di gravità

muaddib scan . --fail-on critical  # Fallisce solo su CRITICAL
muaddib scan . --fail-on high      # Fallisce su HIGH e CRITICAL (predefinito)

Modalità paranoica

muaddib scan . --paranoid

Rilevamento ultra-stretto con tolleranza ridotta. Rileva qualsiasi accesso di rete, esecuzione di subprocessi, valutazione di codice dinamico e accesso a file sensibili.

Avvisi webhook

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

Filtraggio rigoroso (v2.1.2): avvisi solo per corrispondenze IOC, minacce confermate dal sandbox o esfiltrazione di canary token. Triaging per priorità (v2.10.21): P1 (rosso, IOC/sandbox/canary), P2 (arancione, punteggio alto/composti), P3 (giallo, resto).

Rilevamento anomalie comportamentali (v2.0)

muaddib scan . --temporal-full     # Tutte e 4 le caratteristiche temporali
muaddib scan . --temporal          # Rilevamento script lifecycle improvviso
muaddib scan . --temporal-ast      # Diff AST tra versioni
muaddib scan . --temporal-publish  # Anomalia frequenza pubblicazione
muaddib scan . --temporal-maintainer # Rilevamento cambio manutentore

Rileva attacchi alla supply chain prima che appaiano nei database IOC analizzando le modifiche tra le versioni dei pacchetti. Vedi Metodologia di Valutazione per i dettagli.

Sandbox Docker

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

Analisi dinamica in un contenitore Docker isolato: strace, tcpdump, diff filesystem, canary token, ambiente CI-aware e monkey-patching preload per il rilevamento di time-bomb (esecuzioni multiple a offset [0h, 72h, 7d]).

Altri comandi

muaddib watch .                    # Monitoraggio in tempo reale
muaddib daemon                     # Modalità demone (scansione automatica di npm install)
muaddib update                     # Aggiornamento IOCs (veloce, ~5s)
muaddib scrape                     # Refresh completo IOC (~5min)
muaddib diff HEAD~1                # Confronta minacce con il commit precedente
muaddib init-hooks                 # Hook pre-commit (husky/pre-commit/git)
muaddib scan . --breakdown         # Scomposizione del punteggio spiegabile
muaddib replay                     # Validazione ground truth (90/94 TPR@3, v2.11.48)

Funzionalità

22 scanner paralleli

277 regole di rilevamento

Tutte le regole (272 REGOLE + 5 PARANOICHE) sono mappate a tecniche MITRE ATT&CK. Vedi SECURITY.md per il riferimento completo alle regole.

Campagne rilevate

VS Code

L'estensione VS Code scansiona automaticamente i tuoi progetti npm.

code --install-extension dnszlsk.muaddib-vscode

• MUAD'DIB: Scan Project - Scansione dell'intero progetto
• MUAD'DIB: Scan Current File - Scansione del file corrente
• Impostazioni: muaddib.autoScan, muaddib.webhookUrl, muaddib.failLevel

Vedi vscode-extension/README.md per la documentazione 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'

Hook pre-commit

muaddib init-hooks                        # Rilevamento automatico (husky/pre-commit/git)
muaddib init-hooks --type husky           # Forza husky
muaddib init-hooks --mode diff            # Blocca solo NUOVE minacce

Con framework pre-commit:

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

Valutazione

Ultima misurazione v2.11.48 (2026-05-26), solo regole (il classificatore ML è inattivo — vedi sotto). Ground truth: 94 attacchi reali in ambito + 200 npm casuali + 124 PyPI + 107 avversari/holdout.

Classificatore ML: inattivo. Un modello XGBoost risiede in src/ml/ ma non è mai collegato a muaddib scan, e viene eseguito in modalità LOG-ONLY nel monitor dal 2026-04-08 (il modello addestrato è collassato, in attesa di riaddestramento). Tutti i numeri sopra sono solo regole.

Protocollo completo, cronologia per tracciato, l'avvertenza PyPI cap-35, copertura operativa (denominata GHSA) e metodologia di riaddestramento ML: Metodologia di Valutazione.

Contribuire

Aggiungere IOCs

Modifica i file YAML in iocs/:

- id: NEW-MALWARE-001
  name: "malicious-package"
  version: "*"
  severity: critical
  confidence: high
  source: community
  description: "Threat description"
  references:
    - https://example.com/article
  mitre: T1195.002

Sviluppo

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

Test

• 4545 test su 152 file di test modulari
• 56 fuzz test - Input malformati, ReDoS, unicode, binario
• Benchmark Datadog 17K - 14.587 campioni malware confermati (in ambito)
• Validazione ground truth - 96 attacchi reali (95.74% TPR@3, 88.30% TPR@20 — misura completa v2.11.48 su 94 in ambito)
• Validazione falsi positivi (misura v2.11.48) - 1.10% FPR regole (6/545 scansionati), 2.50% su 200 casuali, 9.68% su 124/132 PyPI (prima misurazione onesta dopo la correzione del download Track-D). Classificatore ML attualmente inattivo — vedi Metriche di Valutazione → Classificatore ML.

Community

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

Documentazione

• Blog - Articoli tecnici sul rilevamento delle minacce alla supply chain
• Carnet de bord - Diario di sviluppo (in francese)
• Indice della documentazione - Tutta la documentazione in un unico posto
• Metodologia di Valutazione - Protocollo sperimentale, punteggi holdout
• Modello di minaccia - Cosa MUAD'DIB rileva e non rileva
• Politica di sicurezza - Riferimento alle regole di rilevamento (277 regole)
• Audit di sicurezza - Report di validazione bypass
• Analisi FP - Analisi storica dei falsi positivi

Licenza

MUAD'DIB è concesso in licenza secondo la GNU Affero General Public License v3.0 only (AGPL-3.0-only) — vedi LICENSE e NOTICE.

Sei libero di usare, studiare, modificare e ridistribuirlo — anche su rete — a condizione che le opere derivate e le modifiche distribuite su rete siano rilasciate sotto la stessa licenza.

Licenza commerciale: per incorporare MUAD'DIB in un prodotto proprietario / closed-source, o per offrirlo come servizio ospitato senza gli obblighi di divulgazione del codice sorgente dell'AGPL, è disponibile una licenza commerciale separata. Apri una issue o contatta l'autore (DNSZLSK).

Copyright (C) 2026 DNSZLSK.

La spezia deve fluire. I vermi devono morire.