Sparkplug B MQTT Security Fuzzer

أداة تقييم أمان شاملة لاختبار تطبيقات بروتوكول MQTT الخاص بـ Sparkplug B. يختبر المُختبر بشكل منهجي جميع حقول البروتوكول عبر جميع أنواع الرسائل التسعة، ويكتشف الأجهزة النشطة على الشبكة، وينتج سجلات مفصّلة للتحليل.

الاستخدام المسؤول

ترسل هذه الأداة رسائل MQTT تالفة، وحقنًا، ومخالفة للبروتوكول إلى وسيط (Broker) مستهدف. قم بتشغيلها فقط ضد الأنظمة التي تملكها أو لديك إذن كتابي صريح لاختبارها. غالبًا ما تتواجد وسطاء Sparkplug B في بيئات OT/ICS حيث يمكن أن تؤدي الحمولات غير المتوقعة إلى تعطيل العمليات الفيزيائية — افترض أن كل هدف قريب من بيئة الإنتاج ما لم يُثبت خلاف ذلك.

إذا اكتشفت ثغرة أمنية في تطبيق Sparkplug B باستخدام هذه الأداة، فيُرجى اتباع الإفصاح المنسّق مع البائع المتأثر. للإبلاغ عن مشكلة أمنية في هذه الأداة نفسها، راجع SECURITY.md.

جدول المحتويات

• نظرة عامة
• المتطلبات الأساسية
• التثبيت
• بدء سريع
• الاستخدام
  • خيارات سطر الأوامر
  • فئات الفحص (Fuzz Categories)
  • أمثلة
• كيف تعمل
  • تدفق التنفيذ
  • اكتشاف الشبكة
  • تقييم المصادقة
  • الفحص الموجّه
• تشغيل الاختبارات
• تحليل المخرجات والسجلات
  • تنسيق السجل
  • تحليل النتائج
• التغطية البروتوكولية
  • أنواع الرسائل
  • أنواع البيانات
  • تغطية الحقول
• البنية المعمارية

نظرة عامة

تحدد مواصفات Sparkplug B مساحة أسماء للموضوعات (Topic Namespace) وتنسيق حمولة مبني على MQTT وGoogle Protocol Buffers لبيئات إنترنت الأشياء الصناعي (IIoT). يقيّم هذا المُختبر أمان ومتانة تطبيقات Sparkplug B من خلال:

• اختبار جميع أنواع البيانات المترية التسعة عشر بقيم حدّية وظروف تجاوز
• حقن سلاسل ضارة (XSS وSQLi وسلاسل التنسيق وتسليم المسار وحقن الأوامر)
• إنشاء عدم تطابق في الأنواع بين أنواع البيانات المُعلنة وحقول قيم protobuf الفعلية
• مخالفة ترتيب آلة الحالة للبروتوكول (بيانات قبل الميلاد، ولادات مزدوجة، بيانات بعد الوفاة)
• إتلاف حمولات protobuf المتسلسلة على المستوى الثنائي
• انتحال شهادات الميلاد/الوفاة للأجهزة المكتشفة على الشبكة
• فحص مساحات أسماء موضوعات MQTT بأحرف خاصة وتباينات في حالة الأحرف وانتهاكات بنيوية

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

• Python 3.8+
• وسيط MQTT — النظام المستهدف قيد الاختبار (مثل Mosquitto أو HiveMQ أو EMQX أو أي وسيط يدعم Sparkplug B)
• التفويض — هذه الأداة مخصصة لاختبار الأمان المصرّح به فقط

التثبيت

على أنظمة Debian/Ubuntu/Kali الحديثة (أنظمة PEP-668)، لا يمكن لـ --setup تنفيذ pip install داخل Python الخاص بالنظام — استخدم بيئة افتراضية أو pipx أولاً. المسار الموصى به:```bash python3 -m venv .venv source .venv/bin/activate python3 sparkplug-fuzzer.py --setup

أو يمكنك التشغيل عبر `pipx run` إذا كنت تفضّل عدم إدارة البيئة الافتراضية (venv) بنفسك. على الأنظمة الأقدم التي لا تفرض PEP-668، يعمل الأمر `python3 sparkplug-fuzzer.py --setup` مباشرةً.

`--setup` سيقوم بما يلي:
1. تثبيت تبعيات pip (`paho-mqtt`، `protobuf`)
2. استنساخ علامة إصدار مثبّتة من مستودع [Eclipse Tahu](https://github.com/eclipse/tahu) (انظر `TAHU_REF` في السكربت)
3. نسخ الوحدات المساعدة `sparkplug_b.py` و`array_packer.py`
4. ترجمة `sparkplug_b.proto` إلى روابط Python (يستخدم `protoc` إذا كان متاحًا، وإلا يعتمد على `grpcio-tools`)
5. تنظيف نسخة Tahu المستنسخة

بعد الإعداد، يجب أن يحتوي دليلك على:```
sparkplug-fuzzer.py     # The fuzzer
sparkplug_b.py          # Sparkplug B helper module (from Tahu)
array_packer.py         # Array packing helper (from Tahu)
sparkplug_b_pb2.py      # Generated protobuf bindings
requirements.txt        # Python dependencies

الإعداد اليدوي (إذا لم يعمل --setup)

```bash pip install -r requirements.txt git clone https://github.com/eclipse/tahu.git cp tahu/python/core/sparkplug_b.py . cp tahu/python/core/array_packer.py . protoc --python_out=. sparkplug_b.proto rm -rf tahu ```

البدء السريع```bash

python3 sparkplug-fuzzer.py --setup # first-time setup python3 sparkplug-fuzzer.py -H localhost -p 1883 -v # run fuzzer

سيقوم هذا بـ:
1. الاتصال بالوسيط على `localhost:1883`
2. الاستماع لمدة 10 ثوانٍ لاكتشاف أجهزة Sparkplug الموجودة
3. تأسيس أداة الفازينغ كعقدة/جهاز Sparkplug
4. تشغيل جميع فئات الفازينغ الـ12 (~635+ حالة اختبار)
5. استهداف أي أجهزة تم اكتشافها برسائل مزيفة
6. كتابة النتائج إلى `sparkplug_fuzz.jsonl`

## الاستخدام

### خيارات سطر الأوامر```
python3 sparkplug-fuzzer.py [OPTIONS]

الخيار	الافتراضي	الوصف
-H، --host	localhost	اسم مضيف وسيط MQTT أو عنوان IP
-p، --port	1883 (أو 8883 مع --tls)	منفذ وسيط MQTT
-u، --username	لا شيء	اسم مستخدم MQTT (يقرأ أيضًا متغير البيئة MQTT_USERNAME)
-P، --password	لا شيء	كلمة مرور MQTT (يقرأ أيضًا MQTT_PASSWORD؛ مرّر - للقراءة من stdin بدون صدى)
--tls	off (مغلق)	الاتصال عبر TLS؛ يصبح المنفذ الافتراضي 8883 إذا لم يتم تعيين -p
--cafile	لا شيء	حزمة CA للتحقق من شهادة خادم TLS
--insecure	off (مغلق)	تجاوز التحقق من اسم مضيف/شهادة TLS (لأغراض الاختبار فقط)
-g، --group	Sparkplug B Devices	معرّف مجموعة Sparkplug الذي يسجّل تحته المدعّم (fuzzer)
-n، --node	FuzzNode	معرّف عقدة حافة Sparkplug للمدعّم
-d، --device	FuzzDevice	معرّف جهاز Sparkplug للمدعّم
-c، --categories	all	قائمة مفصولة بمسافات من فئات الدعم (fuzz categories) لتشغيلها
--discovery-time	10	الثواني المستغرقة للاستماع السلبي لاكتشاف الشبكة
--delay	0.1	التأخير بالثواني بين رسائل الدعم (fuzz messages)
--probe-anon-write	off (مغلق)	أثناء الاكتشاف، إرسال رسالة نشر واحدة بـ QoS=1 للتأكد مما إذا كان الوسيط يقبل النشر غير المصادَق
-l، --log	sparkplug_fuzz.jsonl	اسم ملف سجل الإخراج (المسارات النسبية تقع داخل --output-dir؛ المسارات المطلقة تُحترم كما هي)
--output-dir	./sparkplug-runs/<UTC-ts>_<host>/	دليل الإخراج لكل تشغيل. يُنشأ في حال عدم وجوده.
-v، --verbose	0	زيادة وضوح الإخراج على وحدة التحكم (-v = معلومات، -vv = تصحيح). مع -vv تُعرض أيضًا حالات تخطي مولّد الدعم (fuzz-generator skips)، ويتم رفع مستوى تسجيل paho.mqtt المُقيّد إلى INFO/DEBUG وفقًا لمستوى الوضوح.
--setup	—	تثبيت جميع التبعيات والخروج
--tahu-path	—	المسار إلى نسخة محلية من eclipse/tahu (أو دليل python/core الخاص بها). يُستخدم بواسطة --setup في البيئات المعزولة عن الشبكة بدلاً من git clone.
--extra-string-payloads	—	مسار إلى ملف يحتوي حمولات إضافية لحقن النصوص (سطر واحد لكل حمولة، UTF-8). تُلحق بالقيم المدمجة STRING_FUZZ_VALUES ولا تحل محلها. الحد الأقصى 10 ميغابايت / 10,000 حمولة. انظر مجاميع النصوص المخصصة.

فئات الدعم (Fuzz Categories)