muad-dib v2.12.0

インストール | 使い方 | 機能 | VS Code | CI/CD

Version francaise

MUAD'DIB とは？

npm と PyPI のサプライチェーン攻撃が急増しています。Shai-Hulud は 2025 年に 25,000 以上のリポジトリを侵害しました。既存のツールは脅威を検出しますが、対応には役立ちません。

MUAD'DIB は、22 の並列スキャナー（278 の検出ルール）、難読化解除エンジン、モジュール間データフロー解析、複合スコアリング（21 の複合ルール）、および gVisor/Docker サンドボックスを組み合わせて、npm および PyPI パッケージの既知の脅威と疑わしい動作パターンを検出します。XGBoost 分類器がコードベースに存在しますが、現在は無効です（評価 を参照）。

位置付け

MUAD'DIB は、npm と PyPI 向けの無料・オープン・完全監査可能なサプライチェーンスキャナーです。既知の脅威（225,000 以上の IOC）、インストール時 RCE、認証情報窃取後の外部送信フロー、難読化されたペイロード、その他の疑わしい動作パターンを、テレメトリなしでローカルに検出します。

AGPL-3.0 ライセンスで提供されています。プロプライエタリ製品への組み込みや、クローズドなホステッドサービスとして実行する必要がある組織向けに、商用ライセンスも利用可能です（ライセンス を参照）。

意図的にすべてを網羅しようとはしていません。何を検出し、何を検出しないかの正確な範囲は スコープ を参照してください。

スコープ

検出対象（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）。意図的なアンチサンドボックスフィンガープリンティングや多段階リモートペイロードは、既知の偽陰性リスクです。詳細：脅威モデル。

テレメトリなし。 コードとスキャン結果がマシンから出ることはありません。MUAD'DIB は脅威インテルフィードのダウンロード（muaddib update）と、スコアリングのための公開 npm レジストリメタデータの読み取りのみを行います。Webhook アラートはオプトインです。

インストール

npm（推奨）

npm install -g muaddib-scanner

ソースから

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

使い方

基本スキャン

muaddib scan .
muaddib scan /path/to/project

npm（package.json、node_modules）と Python（requirements.txt、setup.py、pyproject.toml）の両方の依存関係をスキャンします。

対話モード

muaddib

安全なインストール

muaddib install <package>
muaddib install lodash axios --save-dev
muaddib install suspicious-pkg --force    # 脅威があっても強制インストール

インストール前にパッケージの脅威をスキャンします。既知の悪意のあるパッケージをブロックします。

リスクスコア

各スキャンで 0〜100 のリスクスコアが表示されます：

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

説明モード

muaddib scan . --explain

各検出について、ルール ID、MITRE ATT&CK 手法、参照、対応プレイブックを表示します。

エクスポート

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

重大度しきい値

muaddib scan . --fail-on critical  # CRITICAL のみで失敗
muaddib scan . --fail-on high      # HIGH と CRITICAL で失敗（デフォルト）

パラノイドモード

muaddib scan . --paranoid

許容度を低くした超厳格な検出。ネットワークアクセス、サブプロセス実行、動的コード評価、機密ファイルアクセスをすべて検出します。

Webhook アラート

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

厳格なフィルタリング（v2.1.2）：IOC マッチ、サンドボックスで確認された脅威、またはカナリアトークンの外部送信のみアラートを送信します。優先トリアージ（v2.10.21）：P1（赤、IOC/サンドボックス/カナリア）、P2（オレンジ、高スコア/複合）、P3（黄、その他）。

行動異常検出（v2.0）

muaddib scan . --temporal-full     # 4 つの時間的特徴すべて
muaddib scan . --temporal          # 突発的なライフサイクルスクリプト検出
muaddib scan . --temporal-ast      # バージョン間の AST 差分
muaddib scan . --temporal-publish  # 公開頻度の異常
muaddib scan . --temporal-maintainer # メンテナー変更の検出

パッケージバージョン間の変更を分析することで、IOC データベースに登場する前にサプライチェーン攻撃を検出します。詳細は 評価方法論 を参照してください。

Docker サンドボックス

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

分離された Docker コンテナでの動的解析：strace、tcpdump、ファイルシステム差分、カナリアトークン、CI 認識環境、タイムボム検出のためのモンキーパッチプリロード（[0h、72h、7d] オフセットでの複数回実行）。

その他のコマンド

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）

機能

22 の並列スキャナー

278 の検出ルール

すべてのルール（273 RULES + 5 PARANOID）は MITRE ATT&CK 手法にマッピングされています。完全なルールリファレンスは SECURITY.md を参照してください。

検出されたキャンペーン

VS Code

VS Code 拡張機能が npm プロジェクトを自動的にスキャンします。

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 を参照してください。

CI/CD

GitHub Actions（Marketplace）

最小構成（HIGH 以上の脅威でビルドを失敗させる、単一スキャン）：

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 回目のパスを実行）：

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'

入力

出力（後続のステップで steps.<id>.outputs.* を使用して利用）

プリコミットフック

muaddib init-hooks                        # 自動検出（husky/pre-commit/git）
muaddib init-hooks --type husky           # husky を強制
muaddib init-hooks --mode diff            # 新しい脅威のみをブロック

pre-commit フレームワークの場合：

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 件。

ML 分類器：無効。 XGBoost モデルが src/ml/ に存在しますが、muaddib scan には配線されておらず、2026-04-08 以降モニターで LOG-ONLY として実行されています（トレーニング済みモデルが崩壊し、再トレーニング待ち）。上記の数値はすべてルールのみです。

完全なプロトコル、トラック別履歴、PyPI cap-35 の注意点、運用（GHSA ベース）カバレッジ、ML 再トレーニング方法論：評価方法論。

コントリビューション

IOC の追加

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

開発

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

テスト

• 4545 のテストが 155 のモジュール式テストファイルに分散
• 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

ドキュメント

• ブログ - サプライチェーン脅威検出に関する技術記事
• Carnet de bord - 開発日誌（フランス語）
• ドキュメント索引 - すべてのドキュメントを一箇所に
• 評価方法論 - 実験プロトコル、ホールドアウトスコア
• 脅威モデル - MUAD'DIB が検出するものとしないもの
• セキュリティポリシー - 検出ルールリファレンス（278 ルール）
• セキュリティ監査 - バイパス検証レポート
• FP 分析 - 過去の偽陽性分析

ライセンス

MUAD'DIB は GNU Affero General Public License v3.0 only（AGPL-3.0-only）でライセンスされています — LICENSE および NOTICE を参照してください。

派生作品およびネットワーク展開された変更が同じライセンスでリリースされることを条件に、ネットワーク経由を含め、自由に使用、研究、変更、再配布できます。

商用ライセンス： MUAD'DIB をプロプライエタリ / クローズドソース製品に組み込む場合、または AGPL のソース開示義務なしにホステッドサービスとして提供する場合は、別途商用ライセンスが利用可能です。Issue を開くか、作者（DNSZLSK）に連絡してください。

Copyright (C) 2026 DNSZLSK.

The spice must flow. The worms must die.