Miasma / Shai-Hulud 툴킷

Miasma 웜(Mini Shai-Hulud 변종)에 대한 사고 분석 + 탐지/복구 도구입니다. 이 웜은 AI 에이전트/IDE 설정 및 npm/GitHub 리포지토리에 자동 실행 페이로드를 주입합니다.

⚠️ 면책 조항 — 보증 없음. 이 도구는 "있는 그대로" 제공되는 커뮤니티 방어용 툴킷으로, 어떠한 종류의 보증도 없습니다(LICENSE 참조). 스캐너와 YARA 규칙은 읽기 전용이지만, purge-history.sh는 git 기록을 다시 쓰고 .claude/ 훅은 파일을 격리로 이동하므로 둘 다 리포지토리를 변경할 수 있습니다. 먼저 백업하고, 각 도구가 무엇을 하는지 검토한 후, 자신의 책임 하에 실행하십시오. 깨끗한 스캔 결과가 안전을 보장하지는 않습니다. 지표는 진화하고 새로운 변종이 나타납니다. 권한이 있는 시스템 및 계정에서만 사용하십시오. 누락된 부분이나 버그를 발견하셨나요? SECURITY.md 및 CONTRIBUTING.md를 참조하세요.

목차

전제 조건

YARA 설치 (Windows): winget install VirusTotal.YARA — 또는 choco install yara / scoop install yara. Linux/macOS: apt install yara / brew install yara. yara --version으로 확인합니다.

빠른 사용법

참고: -Mode Local은 기본적으로 $env:USERPROFILE만 스캔합니다. 다른 곳의 리포지토리를 포함하려면 -CodeRoots를 전달하세요(예: -CodeRoots E:\Sources,D:\work).

# 로컬 시스템 + 로컬 리포지토리 스캔 (+ CVE-2026-35603 ProgramData)
pwsh -File Scan-Miasma.ps1 -Mode Local
pwsh -File Scan-Miasma.ps1 -Mode Local -CodeRoots E:\Sources,D:\work

# 원격 GitHub 리포지토리 스캔 (비공개 리포지토리/비밀 키를 위해 대상 계정에 먼저 인증)
gh auth login
pwsh -File Scan-Miasma.ps1 -Mode Remote -Owners your-org,your-user -OutReport report.md

# 모든 항목 + JSON + Markdown 보고서
pwsh -File Scan-Miasma.ps1 -OutJson findings.json -OutReport report.md

INFECTED 발견 시 종료 코드 1 (CI 친화적).

# 감염된 리포지토리의 기록 제거 (스크립트에서 PATHS 검토 후)
./purge-history.sh /path/to/repo
# 그런 다음 검증 후:
git push origin --force --all && git push origin --force --tags

# YARA 스캔
yara -r setup-js.yar /path/to/scan

# Linux/macOS: 로컬 스캔 (bash 포트 — 기본값은 $HOME; 확장하려면 루트 전달)
./scan-miasma.sh
./scan-miasma.sh ~/src /opt/work

# 캡처된 드로퍼를 정적으로 디난독화 (읽기 전용 — 절대 실행하지 않음)
pwsh -File Expand-MiasmaPayload.ps1 -Path .github/setup.js   # layers + iocs.txt를 <Path>.deob/에 씁니다
pwsh -File Expand-MiasmaPayload.ps1 -SelfTest                # 디코드/복호화 엔진 확인

디난독화 도구는 p,a,c,k,e,d 패커 웨이브를 풀고, 문자 코드 웨이브를 디코딩하며, 시저 시프트를 자동 감지 및 역변환하고(-Shift로 재정의 가능), 모든 내장 AES-128-GCM 블롭(_b 부트스트래퍼, _p 스틸러)을 복호화한 후 복구된 코드에서 URL, IP 및 데드 드롭 계정을 스캔합니다.

# 제거 후: 우선 순위가 지정된 비밀 키 순환 체크리스트 생성 (아무것도 해지하지 않음)
pwsh -File Invoke-MiasmaRotation.ps1                       # 여기서 접근 가능한 자격 증명 감지
pwsh -File Invoke-MiasmaRotation.ps1 -OutReport rotation.md

CI 가드 (드로퍼/실행기가 있으면 빌드 거부)

번들된 복합 액션을 모든 워크플로의 첫 번째 단계로 사용하세요:

# 다른 리포지토리에서 (공급망 안전을 위해 태그/SHA로 고정):
- uses: actions/checkout@v4
- uses: jchable/miasma-toolkit/.github/actions/miasma-guard@main
  # with:
  #   full-scan: 'true'   # Scan-Miasma.ps1 -Mode Local도 실행 (pwsh 필요)

이 툴킷은 .github/workflows/miasma-ci.yml을 통해 자체적으로 동일한 가드를 실행합니다(상대 경로로 액션 참조). 가드는 웨이브에 구애받지 않으며 웜의 실행기 설정 파일에 한정되므로, IOC 문자열을 언급하는 문서에서 오탐을 발생시키지 않습니다.

Claude Code 훅 (.claude/)

이 리포지토리에서 Claude Code를 실행하는 시스템을 위한 실시간 보호입니다. 훅은 iocs.psd1을 재사용하며(중복 지표 없음), .claude/settings.json에 연결됩니다:

• 격리는 되돌릴 수 있습니다: 감염된 파일은 .miasma-quarantine/<timestamp>/…로 이동되고(git-ignore 됨) .miasma-quarantine/quarantine.log에 기록됩니다 — Move-Item으로 복원하세요. 하드 삭제는 없습니다.
• 자체 제외 (Miasma.Common.ps1의 Test-MiasmaExcluded): 툴킷 자체 파일은 합법적으로 IOC 문자열을 포함하며(iocs.psd1, Scan-Miasma.ps1, scan-miasma.sh, Expand-MiasmaPayload.ps1, Invoke-MiasmaRotation.ps1, purge-history.sh, setup-js.yar, content/, .claude/hooks|commands, , ) 차단/격리되지 않습니다.

심각도 모델 (Scan-Miasma.ps1)

• INFECTED — DROPPER, INJECT, FORGED, BADDEP, WORKFLOW, RUNNER, PAYLOAD, BUN-DROP, PROGRAMDATA
• REVIEW — NPM-AUDIT, SECRETS (순환 인벤토리), SIGNATURE, PERSIST, PROGRAMDATA-CFG

이미 수정된 알려진 버그 (재작업 시 유의)

• gh api <404> --jq 오류 본문을 stdout으로 덤프 → 출력 진위를 신뢰하지 말 것; $LASTEXITCODE 확인 + 형식 검증(숫자 크기, 정확한 브랜치 이름).
• GitHub는 이름 변경 후 master→main 리디렉션을 유지 → branches/master가 200 반환; 반환된 이름 == 요청한 이름인 경우에만 브랜치를 수락.
• npm audit은 **--package-lock-only**를 유지해야 함(npm install 없음, 스크립트 실행 없음).

TODO / 재작업 백로그

원래 백로그(bash 포트, 심각도 배지, 패커 웨이브 디난독화, 순환 도우미)는 완료되었습니다. 향후 아이디어:

1. scan-miasma.sh: 원격/GitHub 모드 추가(현재 로컬 전용).
2. 디난독화 도구: ROT-4/ROT-9 멀티바이트 및 비-AES-128-GCM 변종이 관찰되면 처리.
3. 순환 도우미: 선택적 --revoke 모드(게이트, 확인 포함) (gh/npm/aws용).

참고 자료

• The bot that never was — icflorescu (dev.to)
• Miasma worm: AI coding agent config injection — safedep.io
• CVE-2026-35603: AI coding tools privilege escalation — Cymulate