リアルタイム npm/PyPI サプライチェーン脅威検出。動作チェーン分析、ASTスキャン、IOCフィード、複合スコアリングエンジン。
<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">インストール</a> |
<a href="#usage">使い方</a> |
<a href="#features">機能</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>
---
## MUAD'DIB とは？
npm と PyPI のサプライチェーン攻撃が急増しています。Shai-Hulud は 2025 年に 25,000 以上のリポジトリを侵害しました。既存のツールは脅威を検出しますが、対応には役立ちません。
MUAD'DIB は、**<!--stat:scanners-->22<!--/stat:scanners--> の並列スキャナー**（<!--stat:rulesTotal-->278<!--/stat:rulesTotal--> の検出ルール）、**難読化解除エンジン**、**モジュール間データフロー解析**、**複合スコアリング**（<!--stat:compound-->21<!--/stat:compound--> の複合ルール）、および gVisor/Docker サンドボックスを組み合わせて、npm および PyPI パッケージの既知の脅威と疑わしい動作パターンを検出します。XGBoost 分類器がコードベースに存在しますが、**現在は無効**です（[評価](#evaluation) を参照）。
---
## 位置付け
MUAD'DIB は、npm と PyPI 向けの無料・オープン・完全監査可能なサプライチェーンスキャナーです。**既知**の脅威（225,000 以上の IOC）、インストール時 RCE、認証情報窃取後の外部送信フロー、難読化されたペイロード、その他の疑わしい動作パターンを、テレメトリなしでローカルに検出します。
**AGPL-3.0** ライセンスで提供されています。プロプライエタリ製品への組み込みや、クローズドなホステッドサービスとして実行する必要がある組織向けに、**商用ライセンス**も利用可能です（[ライセンス](#license) を参照）。
意図的にすべてを網羅しようとはしていません。何を検出し、何を検出しないかの正確な範囲は [スコープ](#scope) を参照してください。
---
## スコープ
**検出対象**（npm & PyPI）：既知の悪意のあるパッケージ（名前 + SHA256 IOC マッチ）、タイポスクワッティング、インストール時 RCE（ライフサイクル `preinstall`/`postinstall`、`curl | sh`、Python インポート時、`binding.gyp`）、認証情報読み取り後のネットワーク外部送信（ファイル内およびファイル間）、難読化 / 高エントロピー / スタブローダーペイロード、バイナリドロッパー（`chmod +x` + exec/spawn）、および分析回避の痕跡。
**対象外**：ブラウザのみの攻撃（DOM/`window`、Node.js API なし）、ネイティブバイナリ / WASM の*内容*（バイナリ解析なし）、ゼロデイ未知パッケージ（IOC フィードは事後対応型）、および npm/PyPI 以外のエコシステム（RubyGems、Maven、Go）。意図的なアンチサンドボックスフィンガープリンティングや多段階リモートペイロードは、既知の偽陰性リスクです。詳細：[脅威モデル](https://github.com/dnszlsk/muad-dib/blob/master/docs/threat-model.md)。
**テレメトリなし。** コードとスキャン結果がマシンから出ることはありません。MUAD'DIB は脅威インテルフィードの*ダウンロード*（`muaddib update`）と、スコアリングのための公開 npm レジストリメタデータの読み取りのみを行います。Webhook アラートはオプトインです。
---
## インストール
### npm（推奨）
```bash
npm install -g muaddib-scanner
```
### ソースから
```bash
git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm link
```
---
## 使い方
### 基本スキャン
```bash
muaddib scan .
muaddib scan /path/to/project
```
npm（package.json、node_modules）と Python（requirements.txt、setup.py、pyproject.toml）の両方の依存関係をスキャンします。
### 対話モード
```bash
muaddib
```
### 安全なインストール
```bash
muaddib install <package>
muaddib install lodash axios --save-dev
muaddib install suspicious-pkg --force # 脅威があっても強制インストール
```
インストール*前*にパッケージの脅威をスキャンします。既知の悪意のあるパッケージをブロックします。
### リスクスコア
各スキャンで 0〜100 のリスクスコアが表示されます：
```
[SCORE] 58/100 [***********---------] HIGH
```
### 説明モード
```bash
muaddib scan . --explain
```
各検出について、ルール ID、MITRE ATT&CK 手法、参照、対応プレイブックを表示します。
### エクスポート
```bash
muaddib scan . --json > results.json # JSON
muaddib scan . --html report.html # HTML
muaddib scan . --sarif results.sarif # SARIF（GitHub Security）
```
### 重大度しきい値
```bash
muaddib scan . --fail-on critical # CRITICAL のみで失敗
muaddib scan . --fail-on high # HIGH と CRITICAL で失敗（デフォルト）
```
### パラノイドモード
```bash
muaddib scan . --paranoid
```
許容度を低くした超厳格な検出。ネットワークアクセス、サブプロセス実行、動的コード評価、機密ファイルアクセスをすべて検出します。
### Webhook アラート
```bash
muaddib scan . --webhook "https://discord.com/api/webhooks/..."
```
厳格なフィルタリング（v2.1.2）：IOC マッチ、サンドボックスで確認された脅威、またはカナリアトークンの外部送信のみアラートを送信します。優先トリアージ（v2.10.21）：P1（赤、IOC/サンドボックス/カナリア）、P2（オレンジ、高スコア/複合）、P3（黄、その他）。
### 行動異常検出（v2.0）
```bash
muaddib scan . --temporal-full # 4 つの時間的特徴すべて
muaddib scan . --temporal # 突発的なライフサイクルスクリプト検出
muaddib scan . --temporal-ast # バージョン間の AST 差分
muaddib scan . --temporal-publish # 公開頻度の異常
muaddib scan . --temporal-maintainer # メンテナー変更の検出
```
パッケージバージョン間の変更を分析することで、IOC データベースに登場する**前**にサプライチェーン攻撃を検出します。詳細は [評価方法論](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md) を参照してください。
### Docker サンドボックス
```bash
muaddib sandbox <package-name>
muaddib sandbox <package-name> --strict
```
分離された Docker コンテナでの動的解析：strace、tcpdump、ファイルシステム差分、カナリアトークン、CI 認識環境、タイムボム検出のためのモンキーパッチプリロード（[0h、72h、7d] オフセットでの複数回実行）。
### その他のコマンド
```bash
muaddib watch . # リアルタイム監視
muaddib daemon # デーモンモード（npm install を自動スキャン）
muaddib update # IOC の更新（高速、約 5 秒）
muaddib scrape # 完全な IOC リフレッシュ（約 5 分）
muaddib diff HEAD~1 # 前回のコミットと脅威を比較
muaddib init-hooks # プリコミットフック（husky/pre-commit/git）
muaddib scan . --breakdown # 説明可能なスコア分解
muaddib replay # グラウンドトゥルース検証（90/94 TPR@3、v2.11.48）
```
---
## 機能
### <!--stat:scanners-->22<!--/stat:scanners--> の並列スキャナー
| スキャナー | 検出 |
|---------|-----------|
| AST パース（acorn） | eval、Function、認証情報窃取、バイナリドロッパー、プロトタイプフック |
| パターンマッチング | シェルコマンド、リバースシェル、デッドマンズスイッチ |
| データフロー解析 | 認証情報読み取り + ネットワーク送信（ファイル内およびファイル間） |
| 難読化検出 | JS 難読化パターン（.min.js をスキップ） |
| 難読化解除前処理 | 文字列連結、charcode、base64、16 進配列、定数伝播 |
| モジュール間データフロー | ファイル間の汚染伝播（3 ホップチェーン、クラスメソッド） |
| 意図整合性 | ファイル内のソース・シンクペアリング（認証情報 + eval/ネットワーク） |
| タイポスクワッティング | npm + PyPI（レーベンシュタイン距離） |
| Python スキャナー | requirements.txt、setup.py、pyproject.toml、14,000 以上の PyPI IOC |
| シャノンエントロピー | 高エントロピー文字列（5.5 ビット + 最小 50 文字） |
| AI 設定スキャナー | .cursorrules、CLAUDE.md、copilot-instructions.md インジェクション |
| パッケージ/依存関係 | ライフサイクルスクリプト、IOC マッチング（225,000 以上のパッケージ） |
| GitHub Actions | Shai-Hulud バックドア検出 |
| ハッシュスキャナー | 既知の悪意のあるファイルハッシュ |
| IOC 文字列（intel-triage P1.1） | YARA スタイルの文字列マッチング（Axios 2026、TeamPCP、GlassWorm、CanisterSprawl） |
| アンチフォレンジック AST（intel-triage P1.2） | XOR ループ + 自己削除 + デコイ書き込み複合（csec autodelete） |
| スタブパッケージ（intel-triage P1.3） | 小さなメインファイル + 外部依存 URL + ライフサイクルフック（ltidi チェーン） |
| モノレポスキャナー | Lerna/pnpm-workspace/turbo 検出（Sprint 1 監査 MR-C2 修正） |
| 信頼済み依存差分（オプトイン） | レジストリからの信頼済み依存 tarball との差分（v2.10.x） |
| Python ソース（PYSRC） | `__init__.py` / `setup.py` のインポート時 / インストール時 RCE パターン（v2.11.41 — TrapDoor PyPI ギャップを解消） |
| Python AST（PYAST） | 汚染認識検出器を備えた Tree-sitter-Python AST（v2.11.42+） |
| アンチスキャナーインジェクション（ASI） | LLM コードレビュアーにクリーンな判定を強制したり、難読化されたペイロードをスキップさせたりするコメント/文字列内のプロンプトインジェクションテキスト（ASI-001..004、Hades キャンペーン 2026-06） |
### <!--stat:rulesTotal-->278<!--/stat:rulesTotal--> の検出ルール
すべてのルール（<!--stat:rulesCore-->273<!--/stat:rulesCore--> RULES + <!--stat:rulesParanoid-->5<!--/stat:rulesParanoid--> PARANOID）は MITRE ATT&CK 手法にマッピングされています。完全なルールリファレンスは [SECURITY.md](https://github.com/dnszlsk/muad-dib/blob/master/SECURITY.md#detection-rules) を参照してください。
### 検出されたキャンペーン
| キャンペーン | ステータス |
|----------|--------|
| GlassWorm（2026、433 以上のパッケージ） | 検出済み |
| Shai-Hulud v1/v2/v3（2025） | 検出済み |
| event-stream（2018） | 検出済み |
| eslint-scope（2018） | 検出済み |
| Protestware（node-ipc、colors、faker） | 検出済み |
| タイポスクワット（crossenv、mongose、babelcli） | 検出済み |
---
## VS Code
VS Code 拡張機能が npm プロジェクトを自動的にスキャンします。
```bash
code --install-extension dnszlsk.muaddib-vscode
```
- `MUAD'DIB: Scan Project` - プロジェクト全体をスキャン
- `MUAD'DIB: Scan Current File` - 現在のファイルをスキャン
- 設定：`muaddib.autoScan`、`muaddib.webhookUrl`、`muaddib.failLevel`
完全なドキュメントは [vscode-extension/README.md](https://github.com/dnszlsk/muad-dib/blob/master/vscode-extension/README.md) を参照してください。
---
## CI/CD
### GitHub Actions（Marketplace）
最小構成（HIGH 以上の脅威でビルドを失敗させる、単一スキャン）：
```yaml
name: Security Scan
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: DNSZLSK/[email protected] # リリースされたタグに固定
with:
fail-on: 'high'
```
SARIF を **Security** タブにアップロードする場合（`security-events: write` が必要。SARIF を生成するために 2 回目のパスを実行）：
```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'
```
**入力**
| 入力 | 説明 | デフォルト |
|-------|-------------|---------|
| `path` | スキャンするパス | `.` |
| `fail-on` | 失敗する最小重大度（`critical`/`high`/`medium`/`low`/`none`） | `high` |
| `sarif` | SARIF 出力ファイルパス — 設定すると Security タブにもアップロード | |
| `paranoid` | 超厳格な検出（FPR が高くなる） | `false` |
| `version` | インストールする `muaddib-scanner` npm バージョン | `latest` |
**出力**（後続のステップで `steps.<id>.outputs.*` を使用して利用）
| 出力 | 説明 |
|--------|-------------|
| `risk-score` | リスクスコア 0〜100 |
| `risk-level` | `SAFE` / `LOW` / `MEDIUM` / `HIGH` / `CRITICAL` |
| `threats-count` | 検出された脅威の総数 |
| `critical-count` / `high-count` | 重大度別の脅威数 |
| `exit-code` | `0` = `fail-on` ゲートを通過、それ以外は非ゼロ |
| `sarif-file` | SARIF ファイルへのパス（`sarif` が設定されていない場合は空） |
### プリコミットフック
```bash
muaddib init-hooks # 自動検出（husky/pre-commit/git）
muaddib init-hooks --type husky # husky を強制
muaddib init-hooks --mode diff # 新しい脅威のみをブロック
```
pre-commit フレームワークの場合：
```yaml
repos:
- repo: https://github.com/DNSZLSK/muad-dib
rev: v2.11.139
hooks:
- id: muaddib-scan
```
---
## 評価
最終測定 **v2.11.48**（2026-05-26）、**ルールのみ**（ML 分類器は無効 — 下記参照）。グラウンドトゥルース：スコープ内の実世界攻撃 94 件 + ランダム npm 200 件 + PyPI 124 件 + 敵対的/ホールドアウト 107 件。
| 指標 | 結果 |
|--------|--------|
| 検出率（TPR@3） | **95.74%**（90/94） |
| アラート率（TPR@20） | **88.30%**（83/94） |
| FPR — キュレーション済み npm（548） | **1.10%**（6/545） |
| FPR — ランダム npm（200） | **2.50%**（5/200） |
| FPR — PyPI（132） | **9.68%**（12/124） |
| ADR — 敵対的 + ホールドアウト | **96.26%**（103/107） |
| ワイルド TPR（Datadog 17K） | **92.8%**（13,538/14,587） |
**ML 分類器：無効。** XGBoost モデルが `src/ml/` に存在しますが、`muaddib scan` には配線されておらず、2026-04-08 以降モニターで LOG-ONLY として実行されています（トレーニング済みモデルが崩壊し、再トレーニング待ち）。上記の数値はすべてルールのみです。
完全なプロトコル、トラック別履歴、PyPI cap-35 の注意点、運用（GHSA ベース）カバレッジ、ML 再トレーニング方法論：[評価方法論](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md)。
---
## コントリビューション
### IOC の追加
`iocs/` 内の YAML ファイルを編集します：
```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
```
### 開発
```bash
git clone https://github.com/DNSZLSK/muad-dib
cd muad-dib
npm install
npm test
```
### テスト
- **<!--stat:tests-->4545<!--/stat:tests--> のテスト**が <!--stat:testFiles-->155<!--/stat:testFiles--> のモジュール式テストファイルに分散
- **56 のファズテスト** - 不正な入力、ReDoS、Unicode、バイナリ
- **Datadog 17K ベンチマーク** - 14,587 件の確認済みマルウェアサンプル（スコープ内）
- **グラウンドトゥルース検証** - 96 件の実世界攻撃（95.74% TPR@3、88.30% TPR@20 — v2.11.48 のスコープ内 94 件での完全測定）
- **偽陽性検証**（v2.11.48 測定） - 1.10% FPR ルール（スキャン 545 件中 6 件）、ランダム 200 件で 2.50%、PyPI 124/132 件で 9.68%（Track-D ダウンロード修正後の初の正直な測定）。ML 分類器は現在無効 — 評価指標 → ML 分類器を参照。
---
## コミュニティ
- Discord: https://discord.gg/y8zxSmue
---
## ドキュメント
- [ブログ](https://dnszlsk.github.io/muad-dib/blog/) - サプライチェーン脅威検出に関する技術記事
- [Carnet de bord](https://github.com/dnszlsk/muad-dib/blob/master/docs/CARNET_DE_BORD_MUADDIB.md) - 開発日誌（フランス語）
- [ドキュメント索引](https://github.com/dnszlsk/muad-dib/blob/master/docs/INDEX.md) - すべてのドキュメントを一箇所に
- [評価方法論](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION_METHODOLOGY.md) - 実験プロトコル、ホールドアウトスコア
- [脅威モデル](https://github.com/dnszlsk/muad-dib/blob/master/docs/threat-model.md) - MUAD'DIB が検出するものとしないもの
- [セキュリティポリシー](https://github.com/dnszlsk/muad-dib/blob/master/SECURITY.md) - 検出ルールリファレンス（<!--stat:rulesTotal-->278<!--/stat:rulesTotal--> ルール）
- [セキュリティ監査](https://github.com/dnszlsk/muad-dib/blob/master/docs/SECURITY_AUDIT.md) - バイパス検証レポート
- [FP 分析](https://github.com/dnszlsk/muad-dib/blob/master/docs/EVALUATION.md) - 過去の偽陽性分析
---
## ライセンス
MUAD'DIB は **GNU Affero General Public License v3.0 only**（`AGPL-3.0-only`）でライセンスされています — [LICENSE](https://github.com/dnszlsk/muad-dib/blob/master/LICENSE) および [NOTICE](https://github.com/dnszlsk/muad-dib/blob/master/NOTICE) を参照してください。
派生作品およびネットワーク展開された変更が同じライセンスでリリースされることを条件に、ネットワーク経由を含め、自由に使用、研究、変更、再配布できます。
**商用ライセンス：** MUAD'DIB をプロプライエタリ / クローズドソース製品に組み込む場合、または AGPL のソース開示義務なしにホステッドサービスとして提供する場合は、別途商用ライセンスが利用可能です。Issue を開くか、作者（[DNSZLSK](https://github.com/DNSZLSK)）に連絡してください。
Copyright (C) 2026 DNSZLSK.
---
<p align="center">
<strong>The spice must flow. The worms must die.</strong>
</p>