muaddib-scanner 1.0.0

package/.github/workflows/scan.yml

@@ -0,0 +1,33 @@
+name: MUADDIB Security Scan
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run MUADDIB scan
+        run: node bin/muaddib.js scan . --sarif results.sarif || true
+
+      - name: Upload SARIF to GitHub Security
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MUAD'DIB Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+<p align="center">
+  <img src="MUADDIBLOGO.png" alt="MUAD'DIB Logo" width="200">
+</p>
+
+<h1 align="center">MUAD'DIB</h1>
+
+<p align="center">
+  <strong>Supply-chain threat detection & response for npm</strong>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-1.0.0-blue" alt="Version">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node">
+  <img src="https://img.shields.io/badge/IOCs-58%2B%20packages-red" alt="IOCs">
+</p>
+
+---
+
+## Pourquoi MUAD'DIB ?
+
+Les attaques supply chain npm explosent. Shai-Hulud a compromis 25K+ repos en 2025. Les outils existants detectent, mais n'aident pas a repondre.
+
+MUAD'DIB detecte ET guide la reponse.
+
+| Feature | MUAD'DIB | Socket | Snyk |
+|---------|----------|--------|------|
+| Detection IOCs | Oui | Oui | Oui |
+| Analyse AST | Oui | Oui | Non |
+| Analyse Dataflow | Oui | Non | Non |
+| Playbooks reponse | Oui | Non | Non |
+| SARIF / GitHub Security | Oui | Oui | Oui |
+| MITRE ATT&CK mapping | Oui | Non | Non |
+| 100% Open Source | Oui | Non | Non |
+
+---
+
+## Installation
+```bash
+git clone https://github.com/DNSZLSK/muad-dib.git
+cd muad-dib
+npm install
+```
+
+---
+
+## Utilisation
+
+### Scan basique
+```bash
+node bin/muaddib.js scan .
+node bin/muaddib.js scan /chemin/vers/projet
+```
+
+### Mode explain (details complets)
+```bash
+node bin/muaddib.js scan . --explain
+```
+
+Affiche pour chaque detection :
+- Rule ID
+- MITRE ATT&CK technique
+- References (articles, CVEs)
+- Playbook de reponse
+
+### Export JSON
+```bash
+node bin/muaddib.js scan . --json > results.json
+```
+
+### Rapport HTML
+```bash
+node bin/muaddib.js scan . --html rapport.html
+```
+
+### Rapport SARIF (GitHub Security)
+```bash
+node bin/muaddib.js scan . --sarif results.sarif
+```
+
+### Seuil de severite
+```bash
+node bin/muaddib.js scan . --fail-on critical  # Fail seulement sur CRITICAL
+node bin/muaddib.js scan . --fail-on high      # Fail sur HIGH et CRITICAL (defaut)
+node bin/muaddib.js scan . --fail-on medium    # Fail sur MEDIUM, HIGH, CRITICAL
+```
+
+### Surveillance temps reel
+```bash
+node bin/muaddib.js watch .
+```
+
+### Mise a jour des IOCs
+```bash
+node bin/muaddib.js update
+```
+
+---
+
+## Detection
+
+### Attaques detectees
+
+| Campagne | Packages | Status |
+|----------|----------|--------|
+| Shai-Hulud v1 | @ctrl/tinycolor, ng2-file-upload | Detecte |
+| Shai-Hulud v2 | @asyncapi/specs, posthog-node, kill-port | Detecte |
+| Shai-Hulud v3 | @vietmoney/react-big-calendar | Detecte |
+| event-stream (2018) | flatmap-stream, event-stream | Detecte |
+| eslint-scope (2018) | eslint-scope | Detecte |
+| Protestware | node-ipc, colors, faker | Detecte |
+| Typosquats | crossenv, mongose, babelcli | Detecte |
+
+### Techniques detectees
+
+| Technique | MITRE | Detection |
+|-----------|-------|-----------|
+| Vol credentials (.npmrc, .ssh) | T1552.001 | AST |
+| Exfiltration env vars | T1552.001 | AST |
+| Execution code distant | T1105 | Pattern |
+| Reverse shell | T1059.004 | Pattern |
+| Dead man's switch | T1485 | Pattern |
+| Code obfusque | T1027 | Heuristiques |
+| Supply chain compromise | T1195.002 | IOC matching |
+
+---
+
+## Integration CI/CD
+
+### GitHub Actions
+```yaml
+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: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install
+      - run: node bin/muaddib.js scan . --sarif results.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif
+```
+
+Les alertes apparaissent dans Security > Code scanning alerts.
+
+---
+
+## Architecture
+```
+MUAD'DIB Scanner
+|
++-- IOC Match (YAML DB)
++-- AST Parse (acorn)
++-- Pattern Matching (shell, scripts)
+|
+v
+Dataflow Analysis (credential read -> network send)
+|
+v
+Threat Enrichment (rules, MITRE ATT&CK, playbooks)
+```
+
+---
+
+## Contribuer
+
+### Ajouter des IOCs
+
+Editez les fichiers YAML dans `iocs/` :
+```yaml
+- id: NEW-MALWARE-001
+  name: "malicious-package"
+  version: "*"
+  severity: critical
+  confidence: high
+  source: community
+  description: "Description de la menace"
+  references:
+    - https://example.com/article
+  mitre: T1195.002
+```
+
+### Developper
+```bash
+git clone https://github.com/DNSZLSK/muad-dib.git
+cd muad-dib
+npm install
+node bin/muaddib.js scan test/samples --explain
+```
+
+---
+
+## Documentation
+
+- [Threat Model](docs/threat-model.md) - Ce que MUAD'DIB detecte et ne detecte pas
+- [IOCs YAML](iocs/) - Base de donnees des menaces
+
+---
+
+## Licence
+
+MIT
+
+---
+
+<p align="center">
+  <strong>The spice must flow. The worms must die.</strong>
+</p>

package/action/action.yml

@@ -0,0 +1,28 @@
+name: 'MUADDIB Scanner'
+description: 'Detection et reponse aux attaques supply chain npm'
+author: 'MUADDIB Contributors'
+
+inputs:
+  path:
+    description: 'Chemin du projet a scanner'
+    required: false
+    default: '.'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+
+    - name: Install MUADDIB
+      shell: bash
+      run: |
+        cd ${{ github.action_path }}
+        npm install
+
+    - name: Run MUADDIB scan
+      shell: bash
+      run: |
+        node ${{ github.action_path }}/bin/muaddib.js scan ${{ inputs.path }}

package/bin/muaddib.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+const { run } = require('../src/index.js');
+const { updateIOCs } = require('../src/ioc/updater.js');
+const { watch } = require('../src/watch.js');
+
+const args = process.argv.slice(2);
+const command = args[0];
+const options = args.slice(1);
+
+let target = '.';
+let jsonOutput = false;
+let htmlOutput = null;
+let sarifOutput = null;
+let explainMode = false;
+let failLevel = 'high'; // Par defaut, fail sur HIGH et CRITICAL
+
+for (let i = 0; i < options.length; i++) {
+  if (options[i] === '--json') {
+    jsonOutput = true;
+  } else if (options[i] === '--html') {
+    htmlOutput = options[i + 1] || 'muaddib-report.html';
+    i++;
+  } else if (options[i] === '--sarif') {
+    sarifOutput = options[i + 1] || 'muaddib-results.sarif';
+    i++;
+  } else if (options[i] === '--explain') {
+    explainMode = true;
+  } else if (options[i] === '--fail-on') {
+    failLevel = options[i + 1] || 'high';
+    i++;
+  } else if (!options[i].startsWith('-')) {
+    target = options[i];
+  }
+}
+
+if (!command) {
+  console.log(`
+  MUAD'DIB - Chasseur de vers npm
+  
+  Usage:
+    muaddib scan [path] [options]   Analyse un projet
+    muaddib watch [path]            Surveille un projet en temps reel
+    muaddib update                  Met a jour les IOCs
+    muaddib help                    Affiche l'aide
+  
+  Options:
+    --json              Sortie au format JSON
+    --html [file]       Genere un rapport HTML
+    --sarif [file]      Genere un rapport SARIF (GitHub Security)
+    --explain           Affiche les details de chaque detection
+    --fail-on [level]   Niveau de severite pour exit code (critical|high|medium|low)
+                        Defaut: high (fail sur HIGH et CRITICAL)
+  `);
+  process.exit(0);
+}
+
+if (command === 'scan') {
+  run(target, { 
+    json: jsonOutput, 
+    html: htmlOutput, 
+    sarif: sarifOutput,
+    explain: explainMode,
+    failLevel: failLevel
+  }).then(exitCode => {
+    process.exit(exitCode);
+  });
+} else if (command === 'watch') {
+  watch(target);
+} else if (command === 'update') {
+  updateIOCs().then(() => {
+    process.exit(0);
+  }).catch(err => {
+    console.error('[ERREUR]', err.message);
+    process.exit(1);
+  });
+} else if (command === 'help') {
+  console.log('muaddib scan [path] [--json] [--html file] [--sarif file] [--explain] [--fail-on level]');
+  console.log('muaddib watch [path] - Surveille un projet en temps reel');
+  console.log('muaddib update - Met a jour les IOCs');
+} else {
+  console.log(`Commande inconnue: ${command}`);
+  process.exit(1);
+}

package/data/iocs.json

@@ -0,0 +1,38 @@
+{
+  "version": "1.1.0",
+  "updated": "2026-01-01",
+  "description": "IOCs communautaires MUAD'DIB - Contribuez via PR",
+  "packages": [
+    { "name": "ua-parser-js", "version": "0.7.29", "source": "community", "description": "Compromis octobre 2021 - crypto miner" },
+    { "name": "coa", "version": "2.0.3", "source": "community", "description": "Compromis novembre 2021" },
+    { "name": "coa", "version": "2.0.4", "source": "community", "description": "Compromis novembre 2021" },
+    { "name": "rc", "version": "1.2.9", "source": "community", "description": "Compromis novembre 2021" },
+    { "name": "rc", "version": "1.3.9", "source": "community", "description": "Compromis novembre 2021" },
+    { "name": "left-pad", "version": "*", "source": "community", "description": "Incident 2016 - supply chain" },
+    { "name": "lodash-merge", "version": "*", "source": "typosquat", "description": "Typosquat de lodash.merge" },
+    { "name": "loadash", "version": "*", "source": "typosquat", "description": "Typosquat de lodash" },
+    { "name": "electorn", "version": "*", "source": "typosquat", "description": "Typosquat de electron" },
+    { "name": "discord.js-selfbot-v11", "version": "*", "source": "community", "description": "Token stealer Discord" },
+    { "name": "discord-selfbot-tools", "version": "*", "source": "community", "description": "Token stealer Discord" },
+    { "name": "discordsystem", "version": "*", "source": "community", "description": "Token stealer Discord" },
+    { "name": "discord-lofy", "version": "*", "source": "community", "description": "Token stealer Discord" },
+    { "name": "prerequests", "version": "*", "source": "typosquat", "description": "Typosquat de prerequests" },
+    { "name": "requstes", "version": "*", "source": "typosquat", "description": "Typosquat de requests" }
+  ],
+  "hashes": [
+    "8f3c4e2a1b5d6c7e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e",
+    "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b"
+  ],
+  "files": [
+    "discord-webhook.js",
+    "token-grabber.js",
+    "stealer.js",
+    "inject.js"
+  ],
+  "markers": [
+    "discord.com/api/webhooks",
+    "token grabber",
+    "crypto miner",
+    "xmrig"
+  ]
+}

package/docs/threat-model.md

@@ -0,0 +1,116 @@
+# MUAD'DIB Threat Model
+
+## Ce que MUAD'DIB detecte
+
+### Attaques Supply Chain npm
+
+| Technique | Detection | Confidence |
+|-----------|-----------|------------|
+| Packages malveillants connus | Hash SHA256 + nom | HIGH |
+| Shai-Hulud v1/v2/v3 | Marqueurs + fichiers + comportements | HIGH |
+| event-stream (2018) | Nom + version | HIGH |
+| Typosquatting | Liste de packages connus | MEDIUM |
+| Protestware (node-ipc, colors) | Nom + version | HIGH |
+
+### Comportements malveillants
+
+| Technique | Detection | Confidence |
+|-----------|-----------|------------|
+| Vol de credentials (.npmrc, .ssh) | Analyse AST | HIGH |
+| Exfiltration via env vars (GITHUB_TOKEN) | Analyse AST | HIGH |
+| Execution de code distant (curl \| sh) | Pattern matching | HIGH |
+| Reverse shell | Pattern matching | HIGH |
+| Dead man's switch (rm -rf $HOME) | Pattern matching | HIGH |
+| Code obfusque | Heuristiques | MEDIUM |
+
+### Flux de donnees suspects
+
+| Technique | Detection | Confidence |
+|-----------|-----------|------------|
+| Lecture credential + envoi reseau | Analyse dataflow | HIGH |
+| Acces process.env + fetch/request | Analyse dataflow | HIGH |
+
+## Ce que MUAD'DIB NE detecte PAS
+
+### Limitations connues
+
+| Technique | Raison |
+|-----------|--------|
+| Malware polymorphe | Pas d'analyse dynamique |
+| Obfuscation avancee | Heuristiques limitees |
+| Zero-day (packages inconnus) | Base IOC reactive |
+| Attaques via binaires natifs | Pas d'analyse binaire |
+| Backdoors subtiles | Pas de review de code semantique |
+| Time bombs (declenchement differe) | Pas d'analyse temporelle |
+
+### Faux negatifs potentiels
+
+- Code malveillant dans des fichiers non-JS (WASM, binaires)
+- Exfiltration via DNS ou autres canaux couverts
+- Malware qui detecte l'environnement d'analyse
+- Attaques multi-etapes avec payload distant
+
+## Hypotheses
+
+1. **Le code source est disponible** — MUAD'DIB analyse le code, pas les binaires
+2. **Les IOCs sont a jour** — La detection depend de la base IOC
+3. **L'attaquant utilise des techniques connues** — Zero-days passent a travers
+4. **Le scan est execute avant l'installation** — Apres `npm install`, c'est trop tard si preinstall a execute
+
+## Architecture de detection
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      MUAD'DIB Scanner                        │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
+│  │  IOC Match  │  │  AST Parse  │  │  Pattern Matching   │  │
+│  │  (hashes,   │  │  (acorn)    │  │  (shell, scripts)   │  │
+│  │  packages)  │  │             │  │                     │  │
+│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
+│         │                │                     │             │
+│         v                v                     v             │
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │                   Dataflow Analysis                      ││
+│  │            (credential read -> network send)             ││
+│  └─────────────────────────────────────────────────────────┘│
+│         │                │                     │             │
+│         v                v                     v             │
+│  ┌─────────────────────────────────────────────────────────┐│
+│  │                   Threat Enrichment                      ││
+│  │         (rules, MITRE ATT&CK, playbooks)                 ││
+│  └─────────────────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Mapping MITRE ATT&CK
+
+| Technique | ID | Detection MUAD'DIB |
+|-----------|----|--------------------|
+| Credentials in Files | T1552.001 | AST analysis |
+| Command and Scripting Interpreter | T1059 | Pattern matching |
+| Supply Chain Compromise | T1195.002 | IOC matching |
+| Obfuscated Files | T1027 | Heuristics |
+| Exfiltration Over C2 Channel | T1041 | Dataflow analysis |
+| Data Destruction | T1485 | Pattern matching |
+| Ingress Tool Transfer | T1105 | Pattern matching |
+
+## Recommandations
+
+### Pour les utilisateurs
+
+1. Executer `muaddib scan .` AVANT `npm install`
+2. Mettre a jour les IOCs regulierement (`muaddib update`)
+3. Utiliser le mode `--explain` pour comprendre les detections
+4. Integrer dans CI/CD avec sortie SARIF
+
+### Pour les equipes securite
+
+1. Completer avec une analyse dynamique (sandbox)
+2. Monitorer les nouveaux packages avant adoption
+3. Utiliser `--sarif` pour integration SIEM
+4. Contribuer des IOCs via PR sur le repo
+
+## Contacts
+
+- Repository: https://github.com/DNSZLSK/muad-dib
+- Issues: https://github.com/DNSZLSK/muad-dib/issues