PackageInferno

بسيط بشكل مذهل، ماسح سلسلة توريد npm يعتمد على Docker أولاً. ملف compose واحد يشغّل:

• Enumerator → يبني قائمة انتظار الحزم
• Fetcher → ينزّل الحزم المضغوطة (ويرفعها اختياريًا إلى S3)
• Analyzer → تحليل ثابت + YARA اختياري
• Postgres → قاعدة بيانات محلية للنتائج
• لوحة Streamlit → تصور النتائج على http://localhost:8501

هذه هي النسخة المقتصرة على الحاويات فقط. يمكن بناء المشروع ليتم توسيعه باستخدام EC2 وSQS وRDS. معظم الإعدادات لذلك جاهزة في مجموعة الأدوات.

---

ما الذي ستحصل عليه

• خط أنابيب متكامل في Docker (بدون تثبيتات على المضيف تتجاوز Docker)
• قواعد قابلة للتكوين عبر scan.yml (قوائم السماح، العتبات، YARA)
• مخطط Postgres محلي + سجل الفحص (scan_runs) جاهز للعمل
• رفع اختياري إلى S3 للحزم المضغوطة والنتائج (البيانات الاعتمادية عبر ~/.aws)
• لوحة Streamlit: البحث والتنقيب التفصيلي والتحليلات

---

المحتويات

• docker-compose.yml – الخدمات: db, enumerator, fetcher, analyzer, dashboard, init-db
• enumerator/ – عامل Node يبني قائمة انتظار NDJSON
• fetcher/ – عامل Node ينزّل الحزم المضغوطة (+ يرفع إلى S3 إذا كان مفعلاً)
• analyzer/ – محلل ثابت بلغة Python (+ YARA مضمّن اختياري)
• dashboard/ – تطبيق Streamlit (المنفذ 8501)
• infra/migrations.sql – مخطط قاعدة البيانات الأساسي (packages, versions, findings, scores, indexes)
• infra/20251106_scan_runs.sql – جدول سجل الفحص
• scan.yml – تكوين التحليل (القواعد، التقييم، قوائم السماح، YARA)
• scripts/run_pipeline.sh – تشغيل enumerate → fetch → analyze
• scripts/init_db.sh – تهيئة مخطط قاعدة البيانات
• scripts/test_setup.sh – تحقق آلي من الإعداد
• SCANNING_GUIDE.md – استراتيجيات وأمثلة تفصيلية للفحص

---

البدء السريع (محليًا)

المتطلبات: Docker Desktop (أو المحرك) مع Compose v2.

تثبيت بسطر واحد

curl -fsSL https://raw.githubusercontent.com/MHaggis/Package-Inferno/main/install.sh | bash

يستنسخ هذا المستودع إلى ~/package-inferno ويعطيك تعليمات للبدء.

الخيار أ: استخدام الصور المبنية مسبقًا (الأسرع)

اسحب وشغّل الحاويات المبنية مسبقًا من GitHub Container Registry:

# Clone the repo (for config files and scripts)
git clone https://github.com/MHaggis/Package-Inferno.git
cd Package-Inferno

# Run with pre-built images
docker compose -f docker-compose.ghcr.yml up -d db
./scripts/init_db.sh
SEEDS="lodash,express" docker compose -f docker-compose.ghcr.yml run --rm enumerator
docker compose -f docker-compose.ghcr.yml run --rm fetcher
docker compose -f docker-compose.ghcr.yml run --rm analyzer

الصور المتاحة:

• ghcr.io/mhaggis/package-inferno/enumerator:main
• ghcr.io/mhaggis/package-inferno/fetcher:main
• ghcr.io/mhaggis/package-inferno/analyzer:main

الخيار ب: البناء من المصدر

التحقق الآلي من الإعداد

شغّل سكربت الاختبار للتحقق من تثبيتك:

./scripts/test_setup.sh

سيقوم هذا بما يلي:

• ✓ التحقق من Docker وDocker Compose
• ✓ تشغيل قاعدة البيانات وتهيئتها
• ✓ إجراء فحص تجريبي (حزمتان)
• ✓ التحقق من تخزين النتائج بشكل صحيح

الإعداد اليدوي

1. تشغيل Postgres وتهيئة المخطط:

docker compose up -d db
./scripts/init_db.sh

2. تشغيل خط الأنابيب:

./scripts/run_pipeline.sh

3. تشغيل لوحة المعلومات:

docker compose up -d dashboard
# open http://localhost:8501

تظهر النتائج في ./out/findings/*.findings.json وفي جدول findings عند تفعيل قاعدة البيانات.

---

أوضاع الفحص

يدعم PackageInferno استراتيجيات فحص متعددة حسب أهدافك:

الوضع	حالة الاستخدام	السرعة	التغطية	الأمر
بذور محددة	اختبار/التحقيق في حزم معروفة	الأسرع	مستهدفة	SEEDS="pkg1,pkg2"
دفعة صغيرة	التحقق من الإعداد، فحص عينة	سريع	10-100 حزمة	MAX_CHUNKS=2 CHUNK_LIMIT=10
السجل الكامل	تدقيق شامل لسلسلة التوريد	ساعات-أيام	2M+ حزمة	MAX_CHUNKS=0 CHUNK_LIMIT=100
موجز التغييرات	مراقبة الإصدارات الجديدة (مشمول تلقائيًا)	لحظي	التحديثات الأخيرة	مدمج

1. فحص حزم محددة (موصى به للاختبار)

استهدف حزمًا محددة تريد تحليلها:

# Single command with seeds
export SEEDS="lodash,express,axios"
./scripts/run_pipeline.sh

# Or from a file
echo -e "react\nvue\nangular" > packages.txt
export SEEDS_FILE=packages.txt
./scripts/run_pipeline.sh

كيف اختبرت في البداية: استخدمت SEEDS="is-odd,is-even" للتحقق السريع.

2. الفحص من سجل npm (_all_docs)

فحص الحزم بترقيم الصفحات من سجل npm:

# Clean previous runs
rm -rf downloads/* out/*

# Scan 2 pages of 10 packages each (20 packages)
export MAX_CHUNKS=2        # Number of pages
export CHUNK_LIMIT=10      # Packages per page
unset SEEDS                # Important: disable seeds mode

# Run individual steps for better visibility
docker compose run --rm enumerator  # Discovers and queues
docker compose run --rm fetcher     # Downloads tarballs
docker compose run --rm analyzer    # Scans for threats

مثال على المخرجات:

config: chunkLimit=10, maxChunks=2
checking recent changes feed...
changes feed: enqueued 2 new versions
enumerating via _all_docs (fresh scan)
page 1/2 count: 10
page 2/2 count: 10
done, enqueued 22 (22 new versions)

3. المراقبة المستمرة (فحص غير محدود)

فحص سجل npm بالكامل:

export MAX_CHUNKS=0        # 0 = unbounded
export CHUNK_LIMIT=100     # Larger batches for efficiency
./scripts/run_pipeline.sh

تحذير: سيستمر هذا لساعات/أيام ويفحص مئات الآلاف من الحزم. راقب مساحة القرص وحجم قاعدة البيانات.

4. استئناف الفحوصات المتقطعة

يحفظ الـ enumerator الحالة في ./out/enumerator_state.json مع موضع المؤشر:

{
  "last_seq": "0",
  "last_startkey": "package-name",
  "last_run": "2025-11-23T19:24:49.123Z",
  "last_processed": 22,
  "last_new": 22
}

ببساطة أعد تشغيل خط الأنابيب وسيستأنف من آخر مؤشر:

./scripts/run_pipeline.sh  # Automatically resumes

لفرض فحص جديد:

rm -f out/enumerator_state.json
./scripts/run_pipeline.sh

مثال على نتائج الفحص

من فحص من صفحتين لـ 22 حزمة، إليك ما اكتشفه PackageInferno:

-- Top suspicious packages by score
SELECT p.name, s.score, s.label, COUNT(f.id) as findings 
FROM packages p 
JOIN versions v ON p.id = v.package_id 
JOIN scores s ON v.id = s.version_id 
LEFT JOIN findings f ON v.id = f.version_id 
GROUP BY p.name, s.score, s.label 
ORDER BY s.score DESC;

-- Results:
   name                | score | label      | findings
-----------------------+-------+------------+----------
 rendition             | 606   | malicious  | 153
 vs-deploy             | 454   | malicious  | 119
 --123hoodmane-pyodide | 213   | malicious  | 46

لماذا كانت rendition مشبوهة إلى هذا الحد؟

• 57 × url_outside_allowlist - نطاقات غير مسموح بها
• 46 × suspicious_pattern - أنماط shell/eval
• 12 × advanced_obfuscation - ترميز hex وXOR ومصفوفات سلاسل
• 6 × big_base64_blob - حمولات مشفّرة كبيرة
• 18 × url_in_code - روابط مضمّنة

نظام التقييم (المكوَّن في scan.yml) يجمع هذه النتائج لإنتاج درجة خطر وتصنيف (clean أو suspicious أو malicious).

---

استكشاف النتائج

عبر لوحة المعلومات (موصى به)

افتح http://localhost:8501 بعد تشغيل docker compose up -d dashboard

الميزات:

• 📊 تبويب النظرة العامة: إحصائيات ملخصة، مخططات توزيع الدرجات
• 🔍 تبويب البحث: ابحث عن الحزم بالاسم، صفِّ حسب تصنيف الخطر
• ⚠️ تبويب الخطر العالي: أفضل الحزم الخبيثة مع التنقيب التفصيلي
• 🎯 تحليل C2: الحزم ذات نقاط نهاية استخراج البيانات المعروفة
• 📈 تبويب التحليلات: الاتجاهات، القواعد الشائعة، التحليل الزمني

عبر استعلامات قاعدة البيانات

وصول SQL مباشر للتحليل المخصص:

# Connect to database
docker exec -it pi-postgres psql -U piuser -d packageinferno

استعلامات مفيدة: