سكربت الإرسال الدفعي لتحليل Hybrid Analysis

يقوم هذا السكربت بلغة Python بمسح مجلد بشكل متكرر وإرسال الملفات التنفيذية والنصية والمستندات والملفات الأخرى ذات الصلة إلى Hybrid Analysis (Falcon Sandbox) لتحليل البرامج الضارة تلقائيًا.

الميزات

• يتجول في المجلدات بشكل متكرر
• يرسل فقط أنواع الملفات المدعومة (انظر القائمة أدناه)
• يتجاوز الملفات الفارغة أو كبيرة الحجم أو التي تم إرسالها من قبل
• يمنع هجمات اجتياز المسار – يضمن أن الملفات داخل جذر المسح
• يتجاوز الروابط الرمزية لتجنب الإرسالات المكررة أو غير المقصودة
• يستخدم جلسة طلبات دائمة للتواصل الفعال مع واجهة API
• يخزن ذاكرة تخزين مؤقت في دليل مستخدم مخصص (~/.hybrid_analysis_submitter/) لتجنب تلويث المجلدات الممسوحة
• يستخدم ذاكرة تخزين مؤقت محلية SHA‑256 لتجنب الإرسالات المكررة
• يعالج حدود معدل API (أخطاء 429) بلطف
• يتوقف تلقائيًا عند استنفاد حصة API
• يدعم التكوين عبر سطر الأوامر للمجلد، حد حجم الملف، معرف البيئة، واسم ملف ذاكرة التخزين المؤقت
• يقرأ مفتاح API من ملف .env للأمان

المتطلبات

• Python 3.6+
• مفتاح API ساري لـ Hybrid Analysis (الطبقة المجانية متاحة)

التثبيت

1. استنساخ أو تنزيل هذا السكربت إلى جهازك المحلي.

2. تثبيت الحزم المطلوبة:

pip install requests python-dotenv

3. إنشاء ملف .env في نفس دليل السكربت مع مفتاح API الخاص بك:

HYBRID_API_KEY=your_api_key_here

يمكنك الحصول على مفتاح API عن طريق التسجيل في Hybrid Analysis.

الاستخدام

قم بتشغيل السكربت من سطر الأوامر، مع تحديد المجلد المراد مسحه:

python submit_to_hybrid.py /path/to/folder

وسائط سطر الأوامر

أمثلة

مسح مجلد بالإعدادات الافتراضية:

python submit_to_hybrid.py C:\suspicious_files

مسح مجلد مع زيادة حد الحجم إلى 200 ميجابايت واستخدام بيئة مختلفة (مثل Android):

python submit_to_hybrid.py /home/user/samples --max-file-size 200 --environment-id 300

استخدام اسم ملف ذاكرة تخزين مؤقت مخصص:

python submit_to_hybrid.py ./malware --cache-file my_cache.json

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

Scanning folder: C:\suspicious_files

Submitting: C:\suspicious_files\malware.exe (2.34 MB)
 -> Success! Job ID: 5f8a9c2d3e4f5a6b7c8d9e0f
Submitting: C:\suspicious_files\document.pdf (0.12 MB)
 -> Success! Job ID: 6g9b0c1d2e3f4a5b6c7d8e9f
Skipping already submitted: C:\suspicious_files\malware.exe
Skipping symlink: C:\suspicious_files\link_to_malware.exe

Finished.
Files found:      42
Files submitted:  35
Files skipped:    6
Files failed:     1

أنواع الملفات المدعومة

• ملفات ويندوز التنفيذية (PE): .exe, .scr, .pif, .dll, .com, .cpl
• برامج التثبيت والحزم: .msi
• نصوص ويندوز النصية: .bat, .cmd, .ps1, .psd1, .psm1, .js, .vbs, .vbe, .wsf, ,

للحصول على القائمة الرسمية لجميع أنواع الملفات المدعومة، راجع أسئلة وأجوبة Hybrid Analysis.

كيف يعمل

1. مسح متكرر – يستخدم السكربت os.walk() لاجتياز كل مجلد فرعي.
2. فحوصات أمنية – يتحقق من أن كل ملف يحل إلى مسار داخل جذر المسح (يمنع اجتياز المسار) ويتجاوز الروابط الرمزية.
3. تصفية الملفات – يتحقق من امتداد الملف، الحجم (يتم تجاوز الملفات ذات 0 بايت أو أكبر من --max-file-size)، وما إذا كان الملف قد تم إرساله من قبل (ذاكرة تخزين مؤقت SHA‑256).
4. الإرسال – يتم رفع كل ملف إلى نقطة النهاية https://hybrid-analysis.com/api/v2/submit/file باستخدام جلسة طلبات دائمة مع مفتاح API الخاص بك.
5. تحديد المعدل – بعد كل إرسال، ينام السكربت لمدة 2 ثانية. إذا تلقى استجابة HTTP 429 (طلبات كثيرة جدًا)، يقوم بحساب الخطأ. بعد 3 أخطاء متتالية 429، يتوقف المسح تلقائيًا.
6. استمرارية ذاكرة التخزين المؤقت – يتم تخزين الملفات التي تم إرسالها بنجاح في ملف JSON داخل ~/.hybrid_analysis_submitter/ بحيث لا يتم إعادة إرسالها في عمليات التشغيل المستقبلية. يتم حفظ ذاكرة التخزين المؤقت مرتبة لسهولة القراءة البشرية.

تحديد المعدل والحصص

• حسابات Hybrid Analysis المجانية لها حدود إرسال كل ساعة/يوم.
• يكتشف السكربت استجابات HTTP 429 ويتوقف بعد 3 أخطاء من هذا القبيل لتجنب إعادة المحاولة بلا نهاية.
• تتم إضافة تأخير لمدة ثانيتين بين الإرسالات لمراعاة واجهة API.

ملاحظات مهمة

• تتم قراءة مفتاح API فقط من ملف .env – لا تقم بتضمينه في الكود.
• يتم دائمًا تجاوز الملفات الفارغة (0 بايت).
• يتم تجاوز الملفات الأكبر من --max-file-size.
• يتم إرسال الملفات ذات الامتدادات الموجودة في ALLOWED_EXTENSIONS فقط.
• يتم تجاوز الروابط الرمزية لمنع الإرسالات المكررة والارتباك في المسار.
• يتم منع اجتياز المسار – سيتجاوز السكربت أي ملف يحل خارج دليل المسح المحدد.
• تمنع ذاكرة التخزين المؤقت إعادة إرسال الملفات المتطابقة عبر عمليات تشغيل متعددة ويتم تخزينها في دليل المستخدم الخاص بك (~/.hybrid_analysis_submitter/).
• يستخدم السكربت مهلة 120 ثانية لكل طلب HTTP.
• يتم تخزين ملفات ذاكرة التخزين المؤقت في دليل مخصص – وليس مختلطًا بالمحتوى الممسوح ضوئيًا.

استكشاف الأخطاء وإصلاحها

الترخيص

يتم توفير هذا السكربت كما هو لأغراض تعليمية وتحليل أمني. استخدمه بمسؤولية ووفقًا لـ شروط خدمة Hybrid Analysis.

إخلاء مسؤولية

قد يؤدي إرسال الملفات إلى بيئة اختبار تابعة لجهة خارجية إلى كشف محتوى حساس محتمل. تأكد من أن لديك الحق في مشاركة الملفات قبل التحميل.