muad-dib v2.12.0

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

Version française

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 (278 regole di rilevamento), un motore di deoffuscamento, analisi del flusso dati inter-modulo, punteggio composto (21 regole composte) e una sandbox gVisor/Docker per rilevare minacce note e modelli comportamentali sospetti nei pacchetti npm e PyPI. Un classificatore XGBoost esiste nel codebase ma è attualmente inattivo (vedi Valutazione).

Posizionamento

MUAD'DIB è uno scanner di supply chain gratuito, aperto e completamente verificabile per npm e PyPI. Rileva minacce note (oltre 225.000 IOC), RCE al momento dell'installazione, flussi di esfiltrazione di credenziali, 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 integrarlo in un prodotto proprietario o di eseguirlo come servizio hosted chiuso (vedi Licenza).

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

Ambito

Rileva (npm e PyPI): pacchetti noti come dannosi (corrispondenza IOC nome + SHA256), typosquat, RCE al momento dell'installazione (script di ciclo di vita preinstall/postinstall, curl | sh, import-time Python, binding.gyp), lettura di credenziali seguita da esfiltrazione di rete (intra- 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 multi-stadio sono rischi noti di falsi negativi. Dettagli completi: Modello di minaccia.

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

Installazione

npm (consigliato)

npm install -g muaddib-scanner

Dal 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 individuare minacce PRIMA dell'installazione. Blocca i pacchetti noti come dannosi.

Punteggio di rischio

Ogni scansione mostra un punteggio di rischio da 0 a 100:

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

Modalità spiegazione

muaddib scan . --explain

Mostra l'ID della regola, la tecnica MITRE ATT&CK, i riferimenti e il 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 inferiore. Rileva qualsiasi accesso di rete, esecuzione di sottoprocessi, valutazione dinamica del codice 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 dalla sandbox o esfiltrazione di canary token. Triage prioritario (v2.10.21): P1 (rosso, IOC/sandbox/canary), P2 (arancione, punteggi alti/composti), P3 (giallo, resto).

Rilevamento anomalie comportamentali (v2.0)

muaddib scan . --temporal-full     # Tutte e 4 le funzionalità temporali
muaddib scan . --temporal          # Rilevamento script di ciclo di vita improvvisi
muaddib scan . --temporal-ast      # Diff AST tra versioni
muaddib scan . --temporal-publish  # Anomalia frequenza di pubblicazione
muaddib scan . --temporal-maintainer # Rilevamento cambio di maintainer

Rileva gli attacchi alla supply chain prima che compaiano nei database IOC analizzando i cambiamenti 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 del filesystem, canary token, ambiente CI-aware e preload di monkey-patching per il rilevamento di time-bomb (esecuzioni multiple a offset [0h, 72h, 7d]).

Altri comandi

muaddib watch .                    # Monitoraggio in tempo reale
muaddib daemon                     # Modalità daemon (auto-scan di npm install)
muaddib update                     # Aggiorna gli IOC (veloce, ~5s)
muaddib scrape                     # Aggiornamento completo IOC (~5min)
muaddib diff HEAD~1                # Confronta le 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

278 regole di rilevamento

Tutte le regole (273 RULES + 5 PARANOID) sono mappate alle tecniche MITRE ATT&CK. Vedi SECURITY.md per il riferimento completo delle 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 - Scansiona l'intero progetto
• MUAD'DIB: Scan Current File - Scansiona il file corrente
• Impostazioni: muaddib.autoScan, muaddib.webhookUrl, muaddib.failLevel

Vedi vscode-extension/README.md per la documentazione completa.

CI/CD

GitHub Actions (Marketplace)

Minimale (fallisce la build su minacce HIGH+, scansione singola):

name: Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: DNSZLSK/[email protected]   # pin a released tag
        with:
          fail-on: 'high'

Con SARIF caricato nella scheda Security (richiede security-events: write; esegue un secondo passaggio per emettere 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'

Input

Output (consumabili nei passaggi successivi tramite steps.<id>.outputs.*)

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 le NUOVE minacce

Con il 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 vive in src/ml/ ma non è mai collegato a muaddib scan ed esegue SOLO LOG 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 traccia, avvertenza PyPI cap-35, copertura operativa (denominata GHSA) e metodologia di riaddestramento ML: Metodologia di valutazione.

Contribuire

Aggiungere IOC

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 155 file di test modulari
• 56 fuzz test - Input malformati, ReDoS, unicode, binari
• Benchmark Datadog 17K - 14.587 campioni di 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 post-fix 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 cosa non rileva
• Politica di sicurezza - Riferimento delle regole di rilevamento (278 regole)
• Audit di sicurezza - Report di validazione dei bypass
• Analisi FP - Analisi storica dei falsi positivi

Licenza

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

Sei libero di usarlo, studiarlo, modificarlo e ridistribuirlo — anche su rete — a condizione che le opere derivate e le modifiche distribuite in rete siano rilasciate sotto la stessa licenza.

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

Copyright (C) 2026 DNSZLSK.

The spice must flow. The worms must die.