dnszlsk/muad-dib실시간 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 import 시, `binding.gyp`), 자격 증명 읽기 후 네트워크 외부 유출(파일 내 및 파일 간), 난독화/고엔트로피/스텁 로더 페이로드, 바이너리 드로퍼(`chmod +x` + exec/spawn), 및 안티 분석 회피 마커.
**범위 외**: 브라우저 전용 공격(DOM/`window`, Node.js API 없음), 네이티브 바이너리/WASM의 *내용*(바이너리 분석 없음), 제로데이 알려지지 않은 패키지(IOC 피드는 반응형), 및 npm/PyPI 이외의 생태계(RubyGems, Maven, Go). 의도적인 안티 샌드박스 핑거프린팅과 다단계 원격 페이로드는 알려진 오탐(false-negative) 위험입니다. 전체 세부 사항: [위협 모델](https://github.com/dnszlsk/muad-dib/blob/master/docs/threat-model.md).
**텔레메트리 없음.** 코드와 스캔 결과는 절대 기기를 떠나지 않습니다. MUAD'DIB는 위협 인텔리전스 피드를 *다운로드*만 하며(`muaddib update`), 점수 산정을 위해 공개 npm 레지스트리 메타데이터를 읽습니다. 웹훅 알림은 선택 사항입니다.
---
## 설치
### 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
```
더 낮은 허용 오차로 초엄격 탐지. 모든 네트워크 액세스, 하위 프로세스 실행, 동적 코드 평가 및 민감한 파일 액세스를 탐지합니다.
### 웹훅 알림
```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, hex 배열, 상수 전파 |
| 모듈 간 데이터 흐름 | 파일 간 오염 전파 (3홉 체인, 클래스 메서드) |
| 의도 일관성 | 파일 내 소스-싱크 페어링 (자격 증명 + eval/네트워크) |
| 타이포스쿼팅 | npm + PyPI (Levenshtein 거리) |
| Python 스캐너 | requirements.txt, setup.py, pyproject.toml, 14K+ PyPI IOC |
| Shannon 엔트로피 | 고엔트로피 문자열 (5.5비트 + 최소 50자) |
| AI 설정 스캐너 | .cursorrules, CLAUDE.md, copilot-instructions.md 주입 |
| 패키지/종속성 | 수명주기 스크립트, IOC 매칭 (225K+ 패키지) |
| 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`의 import 시 / 설치 시 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 (마켓플레이스)
최소 구성 (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 생성을 위해 두 번째 패스 실행):
```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` 게이트 통과, 그 외에는 0이 아님 |
| `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, 유니코드, 바이너리
- **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의 소스 공개 의무 없이 호스팅 서비스로 제공하려면 별도의 상용 라이선스가 제공됩니다. 이슈를 열거나 저자([DNSZLSK](https://github.com/DNSZLSK))에게 문의하세요.
Copyright (C) 2026 DNSZLSK.
---
<p align="center">
<strong>The spice must flow. The worms must die.</strong>
</p>