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 import 시, binding.gyp), 자격 증명 읽기 후 네트워크 외부 유출(파일 내 및 파일 간), 난독화/고엔트로피/스텁 로더 페이로드, 바이너리 드로퍼(chmod +x + exec/spawn), 및 안티 분석 회피 마커.

범위 외: 브라우저 전용 공격(DOM/window, Node.js API 없음), 네이티브 바이너리/WASM의 내용(바이너리 분석 없음), 제로데이 알려지지 않은 패키지(IOC 피드는 반응형), 및 npm/PyPI 이외의 생태계(RubyGems, Maven, Go). 의도적인 안티 샌드박스 핑거프린팅과 다단계 원격 페이로드는 알려진 오탐(false-negative) 위험입니다. 전체 세부 사항: 위협 모델.

텔레메트리 없음. 코드와 스캔 결과는 절대 기기를 떠나지 않습니다. MUAD'DIB는 위협 인텔리전스 피드를 다운로드만 하며(muaddib update), 점수 산정을 위해 공개 npm 레지스트리 메타데이터를 읽습니다. 웹훅 알림은 선택 사항입니다.

설치

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

더 낮은 허용 오차로 초엄격 탐지. 모든 네트워크 액세스, 하위 프로세스 실행, 동적 코드 평가 및 민감한 파일 액세스를 탐지합니다.

웹훅 알림

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 (마켓플레이스)

최소 구성 (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 생성을 위해 두 번째 패스 실행):

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, 유니코드, 바이너리
• 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의 소스 공개 의무 없이 호스팅 서비스로 제공하려면 별도의 상용 라이선스가 제공됩니다. 이슈를 열거나 저자(DNSZLSK)에게 문의하세요.

Copyright (C) 2026 DNSZLSK.

The spice must flow. The worms must die.