حزمة أدوات Miasma / Shai-Hulud

أدوات تحليل حوادث + كشف/معالجة لدودة Miasma (نسخة Mini Shai-Hulud) التي تحقن حمولات التشغيل التلقائي في إعدادات وكلاء الذكاء الاصطناعي / بيئات التطوير المتكاملة (IDE) ومستودعات npm/GitHub.

⚠️ إخلاء مسؤولية — لا يوجد ضمان. هذه حزمة أدوات دفاعية مجتمعية مقدمة "كما هي"، دون أي ضمان من أي نوع (انظر LICENSE). الماسح الضوئي وقواعد YARA هي للقراءة فقط، لكن purge-history.sh يعيد كتابة تاريخ git وخطافات .claude/ تنقل الملفات إلى الحجر الصحي — وكلاهما يمكن أن يغيّر مستودعًا. اعمل نسخة احتياطية أولاً، وراجع ما تقوم به كل أداة، وقم بتشغيلها على مسؤوليتك الخاصة. الفحص النظيف ليس ضمانًا للسلامة: المؤشرات تتطور وتظهر نسخ متحورة جديدة. استخدمها على الأنظمة والحسابات المصرح لك بفحصها. وجدت ثغرة أو خطأ؟ انظر SECURITY.md وCONTRIBUTING.md.

المحتويات

الملف	ما هو
content/incident-report.fr.md / content/incident-report.en.md	تقرير كامل: كيف يعمل، إزالة تشفير الحمولة، مؤشرات الاختراق (IOCs)، الاستئصال
Scan-Miasma.ps1	ماسح موحّد (محلي + بعيد)، تقرير JSON منظم + تقرير Markdown لكل مستودع — استخدم هذا
iocs.psd1	مؤشرات مشتركة (تجزئات، توقيعات، حزم ضارة، إعدادات) يتم تحميلها بواسطة الماسح — حرّر المؤشرات هنا
Expand-MiasmaPayload.ps1	أداة إزالة التشفير الثابتة لملف setup.js — تزيل طبقة التغليف/رموز الأحرف ← Caesar ← AES-128-GCM وتستخرج خادم القيادة والتحكم (C2)/المؤشرات (لا تنفذ الحمولة أبدًا)
Invoke-MiasmaRotation.ps1	قائمة تدوير الأسرار — تكتشف بيانات الاعتماد القابلة للوصول من هنا وتطبع أوامر الإلغاء (للقراءة فقط؛ لا تلغي شيئًا)
scan-miasma.sh	نسخة Bash من الفحص المحلي لأنظمة Linux/macOS (مجموعة فرعية عبر المنصات)
purge-history.sh	تطهير الملفات الضارة من كل تاريخ git (filter-repo ← filter-branch) + نسخة احتياطية
setup-js.yar	قواعد YARA للبرنامج الحاقن (dropper) وإعدادات المُشغِّل (launcher)
.github/actions/miasma-guard/	إجراء GitHub Actions مركب قابل لإعادة الاستخدام — يرفض البناء إذا وُجد البرنامج الحاقن/المُشغِّل
.claude/	خطافات Claude Code — حماية/حجر صحي فوري + أمر /miasma-scan (انظر أدناه)

المتطلبات الأساسية

الأداة	تُستخدم لـ	مطلوبة؟
PowerShell 7+ (pwsh)	Scan-Miasma.ps1, Expand-MiasmaPayload.ps1, Invoke-MiasmaRotation.ps1	مطلوبة (تلك الأدوات)
bash + coreutils (sha256sum/shasum, awk, find)	scan-miasma.sh (Linux/macOS)	نسخة bash فقط
git	فحوصات تاريخ المستودع المحلي، purge-history.sh	مطلوبة
GitHub CLI (gh, مصادق عليه)	Scan-Miasma.ps1 -Mode Remote	الفحص البعيد فقط
npm	npm audit عن بُعد (ملف القفل فقط)	اختياري (يُتخطى تلقائيًا إذا لم يكن موجودًا)
git-filter-repo	إعادة كتابة التاريخ المفضلة (يتراجع إلى git filter-branch المدمج)	اختياري
YARA (yara)	فحص setup-js.yar	اختياري

تثبيت 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

رمز الخروج 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   # يكتب الطبقات + iocs.txt إلى <Path>.deob/
pwsh -File Expand-MiasmaPayload.ps1 -SelfTest                # التحقق من محرك فك الترميز/فك التشفير

أداة إزالة التشفير تفك طبقة تغليف p,a,c,k,e,d، وتفك ترميز طبقة رموز الأحرف، وتكتشف تلقائيًا وتعكس إزاحة Caesar (يمكن تجاوزها بـ -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 (بالإشارة إلى الإجراء بمسار نسبي). الحارس مستقل عن الموجة ومقيّد بملفات إعدادات المُشغِّل الخاصة بالدودة، لذا لا يُنتج نتائج إيجابية خاطئة أبدًا على المستندات التي تذكر سلسلة المؤشرات فقط.

خطافات Claude Code (.claude/)

حماية فورية للأجهزة التي تشغّل Claude Code في هذا المستودع. تعيد الخطافات استخدام iocs.psd1 (بدون مؤشرات مكررة) وهي مربوطة في .claude/settings.json:

الخطاف	الحدث	الإجراء
Guard-Write.ps1	PreToolUse (Write/Edit/MultiEdit)	يحظر كتابة من شأنها حقن مؤشر دودة (يلغي استدعاء الأداة)
Guard-Bash.ps1	PreToolUse (Bash)	يحظر تنفيذ الدودة — node .github/setup.js, bun/bunx, مثبّت bun.sh عبر أنبوب
Scan-Write.ps1	PostToolUse (Write/Edit/MultiEdit)	ينبّه + يعزل ملفًا مصابًا بعد وصوله
Session-Sweep.ps1	SessionStart	مسح سريع للمستودع؛ يبلّغ عن أي إصابة موجودة مسبقًا في السياق
/miasma-scan	أمر	غلاف عند الطلب حول Scan-Miasma.ps1