أو يمكنك التشغيل عبر `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

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

## الاستخدام

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

**مرر بيانات الاعتماد دون كشفها في `ps`:**```bash
# Via environment
MQTT_USERNAME=admin MQTT_PASSWORD=secret python3 sparkplug-fuzzer.py -H broker.local

# Or read password from stdin (getpass — no echo)
python3 sparkplug-fuzzer.py -H broker.local -u admin -P -

**تقييم المصادقة السلبي + فحص الكتابة النشط:**```bash
python3 sparkplug-fuzzer.py -H 10.0.1.30 --probe-anon-write -v

**الاكتشاف الموسّع بوتيرة بطيئة (لتقليل حمل الوسيط):**```bash
python3 sparkplug-fuzzer.py -H 192.168.1.100 --discovery-time 60 --delay 0.5

**راقب حركة مرور الوسيط في طرفية منفصلة:**```bash
mosquitto_sub -h <broker_host> -p 1883 -t 'spBv1.0/#' -F '%I %t %x'

**تخطيط المخرجات لكل تشغيل:**```bash
# Default — directory is auto-named under ./sparkplug-runs/
python3 sparkplug-fuzzer.py -H broker.local
# -> creates ./sparkplug-runs/2026-05-05_1830_broker.local/sparkplug_fuzz.jsonl

# Explicit directory:
python3 sparkplug-fuzzer.py -H broker.local --output-dir ./fuzz-runs/acme-2026Q2

تطبع أداة الفيزينغ `[+] Extra string payloads: loaded N from <path>` عند بدء التشغيل، وتُصدَر كل حمولة عبر كل موضع يتكرر فيه `STRING_FUZZ_VALUES` — بشكل أساسي فئة `string`، ولكن أيضًا حالات السلاسل النصية لمولّد عدم تطابق الأنواع.

حدود صارمة: حجم الملف 10 ميجابايت، و10,000 حمولة. عدّل `MAX_EXTRA_PAYLOADS_FILE_SIZE` / `MAX_EXTRA_PAYLOADS_COUNT` في أعلى السكربت إذا احتجت المزيد (ولديك ميزانية وقت تشغيل كافية لذلك).

## ملاحظات الإصدار v0.2

- علم `--output-dir` بالإضافة إلى الافتراضي الذي يُنشأ تلقائيًا `./sparkplug-runs/<UTC-ts>_<host>/` — كل عملية تشغيل تذهب إلى دليل خاص بها حتى لا تتصادم الملفات الناتجة بين عمليات التشغيل.
- علم `--tahu-path` لـ `--setup` — يشير إلى نسخة محلية من `eclipse/tahu` لبيئات الاختبار المعزولة عن الشبكة حيث يكون `git clone` الصادر محظورًا. لا يُحذف المصدر المحلي أبدًا عند التنظيف.
- الطوابع الزمنية في Console + JSONL مُجبَرة على UTC مع لاحقة `Z` صريحة بحيث يكون الربط المتبادل مع سجلات الوسيط خاليًا من العمليات الحسابية على المناطق الزمنية.
- مسجّل `paho.mqtt` مُخفَّض إلى WARNING افتراضيًا؛ يظهر عند INFO مع `-v`، وعند DEBUG مع `-vv`. لم تعد بيانات التتبع لكل حزمة من العميل تطغى على إشارة الفيزينغ.
- منصة اختبار pytest ضمن `tests/` — 23 اختبارًا تغطي FuzzLogger ومساعد المواضيع وتحليل مسار الإخراج والتحقق من `--tahu-path`. انظر [تشغيل الاختبارات](#running-the-tests).

## تشغيل الاختبارات

تغطي منصة الاختبار السطح المستقل عن الشبكة (صحة المسجّل، ومنشئ المواضيع، وتحليل مسار الإخراج، وتحليل `--tahu-path`) وتعمل دون تثبيت وسيط أو paho-mqtt أو protobuf.```bash
pip install -r requirements-dev.txt
pytest tests/

### اكتشاف الشبكة

خلال مرحلة الاكتشاف، يشترك المُختبر في `spBv1.0/#` ويستمع إلى كل حركة مرور Sparkplug. يقوم مكوّن `DeviceTracker` بتحليل الرسائل المرصودة لبناء خريطة شبكة حيّة:

- **NBIRTH** تكشف العقد الطرفية وتعريفات مقاييسها (الاسم، الاسم المستعار، نوع البيانات)
- **DBIRTH** تكشف الأجهزة ومخططات مقاييسها
- **NDEATH/DDEATH** تتبّع حالة دورة حياة العقد/الأجهزة
- **STATE** تكشف التطبيقات المضيفة وحالتها عبر الإنترنت/خارج الخط

تُستخدم هذه الخريطة في مرحلة الاختزال الموجّه لإرسال هجمات ذات صلة بالسياق ضد الأجهزة الحقيقية بمخططات مقاييسها الفعلية.

### تقييم المصادقة

عندما يتصل المُختبر بدون `-u/-P` (و`MQTT_USERNAME`/`MQTT_PASSWORD` غير مضبوطين)، فإنه يستنتج وضع المصادقة الخاص بالوسيط من الاكتشاف السلبي وحده. ينتج عن ذلك حدث `AUTH_ASSESSMENT` واحد في السجل وملخص مطبوع:

| الإشارة | ما تعنيه | كيف تُشتق |
|---|---|---|
| `anon_connect_accepted` | الوسيط قبل CONNECT بدون بيانات اعتماد | اتصال CONNECT الخاص بالمُختبر نجح |
| `anon_subscribe_accepted` | الوسيط يمرر `spBv1.0/#` / `STATE/#` للعملاء المجهولين | وصلت رسالة RX واحدة على الأقل خلال نافذة الاستماع |
| `anon_publish_accepted` | الوسيط يقبل PUBLISH من العملاء المجهولين | يُضبط فقط إذا مُرر `--probe-anon-write`؛ استطلاع QoS=1 + انتظار PUBACK |
| `unauth_endpoints` | العقد/الأجهزة/التطبيقات المضيفة قابلة للملاحظة بدون مصادقة | كل كيان في خريطة الشبكة المكتشفة (لم تُنتج مصادقة أبدًا) |

استطلاع QoS=1 اختياري لأنه ينتقل من السلبي إلى النشط. مع QoS=0 يُسقط الوسيط الرسائل التي قد يرفضها بصمت، لذا فإن تأكيد قبول الكتابة يتطلب قراءة PUBACK.

لا توجد مصادقة لكل نقطة نهاية في MQTT/Sparkplug — فالمصادقة مسألة على مستوى الوسيط. لذا فإن "نقاط النهاية القابلة للملاحظة بدون مصادقة" تُبلغ كقائمة من *الأهداف التي يمكن الوصول إليها بتكلفة صفرية* وليس كخاصية لنقاط النهاية نفسها.

### الاختزال الموجّه

بعد الاختزال المنهجي، تستهدف الأداة كل جهاز مكتشف من خلال:

1. **إشعارات وفاة مزيفة** — تنشر NDEATH/DDEATH لخداع المشتركين وجعلهم يظنون أن الأجهزة أصبحت غير متصلة
2. **شهادات ميلاد مزيفة** — تنشر NBIRTH/DBIRTH للانتحال بهوية العقد/الأجهزة المكتشفة
3. **حقن الأوامر** — ترسل رسائل NCMD/DCMD بقيم حدية لكل مقياس معروف، لاختبار ما إذا كان الهدف يتحقق من صحة الأوامر الواردة
4. **أوامر إعادة الميلاد** — ترسل `Node Control/Rebirth` NCMD لدفع الأجهزة إلى إعادة نشر مواليدها

## المخرجات وتحليل السجل

### تنسيق السجل

يستخدم ملف السجل تنسيق سطور JSON (`.jsonl`) — كائن JSON واحد لكل سطر، مناسب للتحليل باستخدام `jq` أو Python أو أي أداة تدعم JSON.

لا يتم تضمين الحمولات الأكبر من 64 KiB كنص سداسي عشري مباشر؛ بدلاً من ذلك يحمل `payload_hex` قيمة `sha256:<digest>+len=<n>` بحيث يظل السجل محدود الحجم لحالات الاختزال الكبيرة جدًا. `payload_len` موجود دائمًا.

**سجل TX** (رسالة اختزال صادرة):```json
{
  "ts": "2026-04-10T15:30:00.123456Z",
  "dir": "TX",
  "case_id": "BOUNDARY-0042",
  "category": "boundary",
  "topic": "spBv1.0/Sparkplug B Devices/DDATA/FuzzNode/FuzzDevice",
  "payload_hex": "0800120a0a06...",
  "payload_len": 28,
  "payload_decoded": {"timestamp": 1712345678000, "metrics": [{"name": "fuzz/boundary/Int32", "datatype": 3, "int_value": 2147483647}]},
  "description": "Boundary Int32 = 2147483647 (int_value)"
}

**سجل الحدث** (حدث النظام):```json
{
  "ts": "2026-04-10T15:29:50.000000Z",
  "dir": "EVENT",
  "event": "DISCOVERY_COMPLETE",
  "details": {"groups": ["Production"], "node_count": 3, "device_count": 7, "targets": 10}
}

**استخرج جميع حالات حقن السلاسل النصية:**```bash
jq 'select(.category == "string")' sparkplug_fuzz.jsonl

**ابحث عن الحالات التي سببت انقطاع اتصال الوسيط:**```bash
jq 'select(.event == "UNEXPECTED_DISCONNECT" or .event == "RECONNECT_FAIL")' sparkplug_fuzz.jsonl

**سرد نقاط النهاية التي يمكن الوصول إليها دون مصادقة:**```bash
jq -r 'select(.event == "AUTH_ASSESSMENT") | .details.unauth_endpoints[] | [.kind, .group, .node, .device, .host_id, .status] | @tsv' sparkplug_fuzz.jsonl

**تصدير جميع المواضيع التي تم نشرها إلى:**```bash
jq -r 'select(.dir == "TX") | .topic' sparkplug_fuzz.jsonl | sort -u

## تغطية البروتوكول

### أنواع الرسائل

جميع أنواع رسائل Sparkplug B التسعة يتم اختبارها:

| نوع الرسالة | نمط الموضوع | الوصف | استخدام المُشوِّش |
|---|---|---|---|
| NBIRTH | `spBv1.0/{group}/NBIRTH/{node}` | شهادة ميلاد العقدة | يُثبت وجود المُشوِّش؛ يُنتحل للعقد المكتشفة؛ اختبارات الترتيب |
| NDEATH | `spBv1.0/{group}/NDEATH/{node}` | إشعار وفاة العقدة | وصية أخيرة عبر MQTT؛ يُنتحل للعقد المكتشفة؛ اختبارات الترتيب |
| DBIRTH | `spBv1.0/{group}/DBIRTH/{node}/{device}` | شهادة ميلاد الجهاز | يُثبت جهاز المُشوِّش؛ يُنتحل للأجهزة المكتشفة؛ اختبارات الترتيب |
| DDEATH | `spBv1.0/{group}/DDEATH/{node}/{device}` | إشعار وفاة الجهاز | يُنتحل للأجهزة المكتشفة؛ اختبارات الترتيب؛ اختبارات اليتامى |
| NDATA | `spBv1.0/{group}/NDATA/{node}` | تحديث بيانات العقدة | قيم حدّية؛ أرقام تسلسلية؛ اختبارات الترتيب |
| DDATA | `spBv1.0/{group}/DDATA/{node}/{device}` | تحديث بيانات الجهاز | الوسيلة الأساسية لمعظم فئات التشويش |
| NCMD | `spBv1.0/{group}/NCMD/{node}` | أمر العقدة | تشويش موجّه (أوامر إعادة الميلاد)؛ اختبارات اليتامى |
| DCMD | `spBv1.0/{group}/DCMD/{node}/{device}` | أمر الجهاز | تشويش موجّه ضد قياسات الأجهزة المكتشفة؛ اختبارات اليتامى |
| STATE | `STATE/{host_id}` | حالة تطبيق المضيف (JSON) | حقن JSON تالف |

### أنواع البيانات

جميع أنواع بيانات القياسات التسعة عشر في Sparkplug B تُختبر بقيم حدّية خاصة بكل نوع:

| الرمز | النوع | حقل Protobuf | القيم الحدّية المختبرة |
|------|------|---------------|----------------------|
| 1 | Int8 | int_value | 0, -128, 127, 128 (تجاوز), -129 (تجاوز سفلي) |
| 2 | Int16 | int_value | 0, -32768, 32767, تجاوز/تجاوز سفلي |
| 3 | Int32 | int_value | 0, -2^31, 2^31-1, تجاوز/تجاوز سفلي |
| 4 | Int64 | long_value | 0, -2^63, 2^63-1, تجاوز |
| 5 | UInt8 | int_value | 0, 255, 256, -1 |
| 6 | UInt16 | int_value | 0, 65535, 65536, -1 |
| 7 | UInt32 | int_value | 0, 4294967295, -1 |
| 8 | UInt64 | long_value | 0, 2^64-1, -1 |
| 9 | Float | float_value | 0.0, -0.0, max, min, inf, -inf, NaN |
| 10 | Double | double_value | 0.0, -0.0, max, min, inf, -inf, NaN |
| 11 | Boolean | boolean_value | True, False؛ يُختبر أيضًا بقيم int خام (0، 1، 2، 255) |
| 12 | String | string_value | فارغ، طويل (حتى 64 كيلوبايت)، حمولات حقن |
| 13 | DateTime | long_value | Epoch, max, مستقبل بعيد/ماضٍ بعيد |
| 14 | Text | string_value | نفس حمولات الحقن المستخدمة مع String |
| 15 | UUID | string_value | فارغ، صيغة صحيحة، صيغة غير صحيحة، حقن |
| 16 | DataSet | dataset_value | انتهاكات هيكلية عبر فئة مجموعة البيانات |
| 17 | Bytes | bytes_value | فارغ، بايتات فارغة، عشوائية، كبيرة |
| 18 | File | bytes_value | فارغ، بايتات سحرية، كبيرة |
| 19 | Template | template_value | مراجع غير معرّفة، قوالب يتيمة |

### تغطية الحقول

يغطي المُشوِّش 87+ مسار حقل فريد من نوعه في Protobuf، بما في ذلك:

- **حقول جذر الحمولة**: timestamp, seq, uuid, body, metrics
- **حقول القياس**: name, alias, timestamp, datatype, is_historical, is_transient, is_null, metadata, properties، وجميع متغيرات oneof الخاصة بالقيمة
- **حقول البيانات الوصفية**: is_multi_part, content_type, size, seq, file_name, file_type, md5, description
- **PropertySet/PropertyValue**: keys, values, type, is_null، propertyset_value التكراري، propertysets_value
- **DataSet**: num_of_columns, columns, types, rows, elements، وجميع متغيرات DataSetValue
- **Template**: version, template_ref, is_definition, القياسات المتداخلة، المعاملات

## البنية

المُشوِّش هو ملف Python واحد مُنظَّم في المكونات التالية:```
sparkplug-fuzzer.py
    |
    +-- Constants / ALL_METRIC_TYPES / STRING_FUZZ_VALUES
    |       Type definitions and fuzz value tables
    |
    +-- FuzzLogger
    |       JSON-lines file logging + console output
    |       Protobuf payload decoding
    |
    +-- DeviceTracker
    |       Passive network discovery
    |       Tracks groups, nodes, devices, metrics
    |
    +-- PayloadBuilder
    |       Valid payload construction (sparkplug_b helpers)
    |       Raw payload construction (sparkplug_b_pb2 direct)
    |       Binary corruption (truncate, flip, append)
    |
    +-- 12 Fuzz Generators
    |       Each is a Python generator yielding (topic, bytes, desc)
    |       Covers boundary, string, type, seq, timestamp, alias,
    |       orphan, ordering, recursive, dataset, malformed, topic
    |
    +-- SparkplugFuzzer
    |       Orchestration: connect, discover, fuzz, target, report
    |       Centralized publish with logging
    |       Auto-reconnect on disconnect
    |
    +-- CLI (argparse) + main()
            Argument parsing and entry point