muad-dib — Rilevamento in tempo reale delle minacce alla catena di fornitura npm/PyPI. Analisi comportamentale della catena, scansione AST, feed IOC e motore di punteggio composito. | 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">Installazione</a> |
  <a href="#usage">Utilizzo</a> |
  <a href="#features">Funzionalità</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 française</a>
</p>

---

## 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 **<!--stat:scanners-->22<!--/stat:scanners--> scanner paralleli** (<!--stat:rulesTotal-->278<!--/stat:rulesTotal--> regole di rilevamento), un **motore di deoffuscamento**, **analisi del flusso dati inter-modulo**, **punteggio composto** (<!--stat:compound-->21<!--/stat:compound--> 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](#evaluation)).

---

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

Non cerca deliberatamente di fare tutto — vedi [Ambito](#scope) 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](https://github.com/dnszlsk/muad-dib/blob/master/docs/threat-model.md).

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

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

### Dal sorgente

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

---

## Utilizzo

### Scansione di base

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

```bash
muaddib
```

### Installazione sicura

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

```bash
muaddib scan . --explain
```

Mostra l'ID della regola, la tecnica MITRE ATT&CK, i riferimenti e il playbook di risposta per ogni rilevamento.

### Esportazione

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

### Soglia di gravità

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

### Modalità paranoica

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

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

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

### Sandbox Docker

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

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

### <!--stat:scanners-->22<!--/stat:scanners--> scanner paralleli

| Scanner | Rilevamento |
|---------|-----------|
| AST Parse (acorn) | eval, Function, furto di credenziali, dropper binari, hook di prototipo |
| Pattern Matching | Comandi shell, reverse shell, interruttore della morte |
| Analisi del flusso dati | Lettura credenziali + invio di rete (intra-file e cross-file) |
| Rilevamento offuscamento | Pattern di offuscamento JS (salta .min.js) |
| Pre-elaborazione deoffuscamento | Concatenazione stringhe, charcode, base64, array hex, propagazione const |
| Flusso dati inter-modulo | Propagazione taint cross-file (catene a 3 hop, metodi di classe) |
| Coerenza dell'intento | Abbinamento source-sink intra-file (credenziali + eval/rete) |
| Typosquatting | npm + PyPI (distanza di Levenshtein) |
| Scanner Python | requirements.txt, setup.py, pyproject.toml, oltre 14.000 IOC PyPI |
| Entropia di Shannon | Stringhe ad alta entropia (minimo 5,5 bit + 50 caratteri) |
| Scanner configurazione AI | Iniezione in .cursorrules, CLAUDE.md, copilot-instructions.md |
| Pacchetti/Dipendenze | Script di ciclo di vita, corrispondenza IOC (oltre 225.000 pacchetti) |
| GitHub Actions | Rilevamento backdoor Shai-Hulud |
| Scanner hash | Hash di file noti come dannosi |
| Stringhe IOC (intel-triage P1.1) | Corrispondenza stringhe stile YARA (Axios 2026, TeamPCP, GlassWorm, CanisterSprawl) |
| AST anti-forense (intel-triage P1.2) | Composto XOR loop + auto-eliminazione + scrittura esca (csec autodelete) |
| Pacchetto stub (intel-triage P1.3) | File main minuscolo + URL dipendenza esterna + hook di ciclo di vita (catena ltidi) |
| Scanner monorepo | Rilevamento Lerna/pnpm-workspace/turbo (audit Sprint 1 fix MR-C2) |
| Diff dipendenze fidate (opt-in) | Diff rispetto ai tarball delle dipendenze fidate dal registro (v2.10.x) |
| Sorgente Python (PYSRC) | Pattern RCE import-time / install-time in `__init__.py` / `setup.py` (v2.11.41 — colma il gap TrapDoor PyPI) |
| AST Python (PYAST) | AST tree-sitter-Python con rilevatori taint-aware (v2.11.42+) |
| Iniezione anti-scanner (ASI) | Testo di prompt injection in commenti/stringhe che induce un revisore di codice LLM a un verdetto pulito o a saltare un payload offuscato (ASI-001..004, campagna Hades 2026-06) |

### <!--stat:rulesTotal-->278<!--/stat:rulesTotal--> regole di rilevamento

Tutte le regole (<!--stat:rulesCore-->273<!--/stat:rulesCore--> RULES + <!--stat:rulesParanoid-->5<!--/stat:rulesParanoid--> PARANOID) sono mappate alle tecniche MITRE ATT&CK. Vedi [SECURITY.md](https://github.com/dnszlsk/muad-dib/blob/master/SECURITY.md#detection-rules) per il riferimento completo delle regole.

### Campagne rilevate

| Campagna | Stato |
|----------|--------|
| GlassWorm (2026, oltre 433 pacchetti) | Rilevata |
| Shai-Hulud v1/v2/v3 (2025) | Rilevata |
| event-stream (2018) | Rilevata |
| eslint-scope (2018) | Rilevata |
| Protestware (node-ipc, colors, faker) | Rilevata |
| Typosquat (crossenv, mongose, babelcli) | Rilevati |

---

## VS Code

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

```bash
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](https://github.com/dnszlsk/muad-dib/blob/master/vscode-extension/README.md) per la documentazione completa.

---

## CI/CD

### GitHub Actions (Marketplace)

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

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

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

**Input**

| Input | Descrizione | Predefinito |
|-------|-------------|---------|
| `path` | Percorso da scansionare | `.` |
| `fail-on` | Gravità minima per fallire (`critical`/`high`/`medium`/`low`/`none`) | `high` |
| `sarif` | Percorso del file di output SARIF — impostalo anche per caricarlo nella scheda Security | |
| `paranoid` | Rilevamento ultra-stretto (FPR più alto) | `false` |
| `version` | Versione npm di `muaddib-scanner` da installare | `latest` |

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

| Output | Descrizione |
|--------|-------------|
| `risk-score` | Punteggio di rischio 0–100 |
| `risk-level` | `SAFE` / `LOW` / `MEDIUM` / `HIGH` / `CRITICAL` |
| `threats-count` | Totale minacce rilevate |
| `critical-count` / `high-count` | Minacce per gravità |
| `exit-code` | `0` = superato il gate `fail-on`, non-zero altrimenti |
| `sarif-file` | Percorso del file SARIF (vuoto se `sarif` non è impostato) |

### Hook pre-commit

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

| Metrica | Risultato |
|--------|--------|
| Tasso di rilevamento (TPR@3) | **95,74%** (90/94) |
| Tasso di avviso (TPR@20) | **88,30%** (83/94) |
| FPR — npm curato (548) | **1,10%** (6/545) |
| FPR — npm casuale (200) | **2,50%** (5/200) |
| FPR — PyPI (132) | **9,68%** (12/124) |
| ADR — avversari + holdout | **96,26%** (103/107) |
| TPR selvaggio (Datadog 17K) | **92,8%** (13.538/14.587) |

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

---

## Contribuire

### Aggiungere IOC

Modifica i file YAML in `iocs/`:

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

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

### Test

- **<!--stat:tests-->4545<!--/stat:tests--> test** su <!--stat:testFiles-->155<!--/stat:testFiles--> 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](https://dnszlsk.github.io/muad-dib/blog/) - Articoli tecnici sul rilevamento delle minacce alla supply chain
- [Carnet de bord](https://github.com/dnszlsk/muad-dib/blob/master/docs/CARNET_DE_BORD_MUADDIB.md) - Diario di sviluppo (in francese)
- [Indice della documentazione](https://github.com/dnszlsk/muad-dib/blob/master/docs/INDEX.md) - Tutta la documentazione in un unico posto
- [Metodologia di valutazione](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md) - Protocollo sperimentale, punteggi holdout
- [Modello di minaccia](https://github.com/dnszlsk/muad-dib/blob/master/docs/threat-model.md) - Cosa MUAD'DIB rileva e cosa non rileva
- [Politica di sicurezza](https://github.com/dnszlsk/muad-dib/blob/master/SECURITY.md) - Riferimento delle regole di rilevamento (<!--stat:rulesTotal-->278<!--/stat:rulesTotal--> regole)
- [Audit di sicurezza](https://github.com/dnszlsk/muad-dib/blob/master/docs/SECURITY_AUDIT.md) - Report di validazione dei bypass
- [Analisi FP](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION.md) - 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](https://github.com/dnszlsk/muad-dib/blob/master/LICENSE) e [NOTICE](https://github.com/dnszlsk/muad-dib/blob/master/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](https://github.com/DNSZLSK)).

Copyright (C) 2026 DNSZLSK.

---

<p align="center">
  <strong>The spice must flow. The worms must die.</strong>
</p>
Più Popolari

muad-dib
