Seclab Taskflows Fuzzing

خط أنابيب fuzzing مدفوع بنماذج اللغة الكبيرة (LLM) بأسلوب OSS-Fuzz لمشاريع C/C++ الأصلية. AFL++ للتنفيذ، clang+lcov للتغطية، وكيل LLM لكتابة الـ harness، وقرارات التغذية الراجعة للتغطية، والفرز، وإعداد التقارير.

• مستقل بالكامل: أعطِه مستودع GitHub وسيتولى كل شيء من تحديد الهدف إلى تقارير الثغرات.
• تقنيات بأسلوب OSS-Fuzz: مُحوِّلات/قواميس لكل صيغة، وربط الرموز المدرك للبنية، وتحسينات الـ harness المدفوعة بالتغطية.
• يُنتج تقارير أعطال قابلة للقراءة آليًا مع أحكام قابلية الاستغلال وتصحيحات مقترحة.
• لوحة تحكم HTML مباشرة لمراقبة الحملة في الوقت الفعلي.
• مكتوب بلغة Python (taskflows/toolboxes/configs) مع توليد harness بلغة C لـ AFL++.
• الحالة: تطوير نشط.

الخلفية

يحتوي هذا المستودع على fuzzing taskflow الخاص بـ GitHub Security Lab Taskflow Agent. يعتمد على المستودع المرافق seclab-taskflows لبعض اللبنات المشتركة (taskflow الخاص بـ fetch_source_code، وصناديق أدوات local_file_viewer / gh_file_viewer، وmodel_config الافتراضي) — يتم تثبيت تلك تلقائيًا كاعتمادية Python.

المساهمات مرحّب بها! يُرجى الاطلاع على CONTRIBUTING.md للإرشادات.

المتطلبات

• Python 3.11+
• بيئة Linux (أو Codespace) مع إمكانية الوصول إلى apt
• AFL++، clang، lcov، ctags، cscope، graphviz (يتم تثبيتها تلقائيًا بواسطة خط الأنابيب إذا كانت مفقودة)
• Git وGitHub CLI (gh)

التثبيت

pip install git+https://github.com/GitHubSecurityLab/seclab-taskflows-fuzzing

يستدعي هذا الحزمتين seclab-taskflow-agent و seclab-taskflows (الحزمة الأم) بشكل تتابعي، لذا فإن كل إشارة نقطية بالصيغة seclab_taskflows.taskflows.audit.*، seclab_taskflows.toolboxes.local_file_viewer، seclab_taskflows.toolboxes.gh_file_viewer، و seclab_taskflows.configs.model_config تُحلّ من توزيعة الحزمة الأم عند التشغيل.

---

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

1. ما هذا
2. البدء السريع
3. البنية المعمارية
4. خط المعالجة، مرحلة بمرحلة
5. حلقة التغذية الراجعة للتغطية
6. التهيئة الواعية بالبنية
7. المدوّنة الدائمة عبر التكرارات والحملات
8. الفرز وتقارير الثغرات
9. لوحة المعلومات المباشرة
10. ملفات الإخراج
11. مخطط قاعدة البيانات
12. أدوات MCP (مفردات الوكيل)
13. المقابض القابلة للضبط (متغيرات البيئة)
14. توسيع خط المعالجة
15. مشاريع القياس والنتائج
16. القيود والمزالق
17. تحذير أمني
18. التطوير: الاختبار، والتدقيق، والمساهمة
19. المعجم

---

ما هذا

خط المعالجة هذا هو خط تهيئة (fuzzing) مستقل بالكامل. عند إعطائه مستودع GitHub لمشروع أصلي بلغة C/C++، فإنه سيقوم بما يلي:

1. تثبيت AFL++ + clang/llvm/lcov + ctags/cscope/graphviz إذا كانت مفقودة،
2. جلب المصدر،
3. تحديد أهداف التهيئة المرشحة (المحلّلات، وفكّ الترميز، والمدقّقات، …)،
4. تحليل نظام البناء وبناء المكتبة الهدف ثلاث مرات: مع توجيه تغطية حواف AFL++ بالإضافة إلى المُطهِّرات (sanitizers)، ومع توجيه AFL++ CMPLOG، ومع توجيه التغطية المصدرية من clang،
5. كتابة مرشح واحد أو أكثر من مرشحات الحاضنة (harness) لكل هدف، وبناء كل منها كملف ثنائي .afl موجّه بـ AFL++، وملف ثنائي .cmplog موجّه بـ AFL++ CMPLOG، وملف ثنائي .cov موجّه بتغطية clang،
6. (اختياريًا) تأهيل المرشحين عبر تغطية مدتها 60 ثانية والاحتفاظ بالأفضل،
7. تشغيل حلقة تهيئة/تغطية/تحسين مع مضاعفة ميزانيات الوقت،
8. فرز كل انهيار، والتأكد من أن الانهيارات المعروفة سابقًا لا تزال قابلة لإعادة الإنتاج، وكتابة تقارير ثغرات markdown لكل انهيار مع الأحكام، وقابلية الاستغلال، والتصحيحات المقترحة، ومخططات اختبارات الانحدار،
9. بناء رسم بياني للاستدعاءات بأسلوب Fuzz-Introspector + تقرير واجهات API غير الملموسة للحملة التالية،
10. نشر كل شيء على لوحة معلومات HTML مباشرة.

خط المعالجة هذا بأسلوب OSS-Fuzz من حيث الجوهر: فهو يستخدم العديد من التقنيات نفسها (مُحوِّلات وقواميس خاصة بكل صيغة، وربط الرموز الواعي بالبنية، وتحسينات الحاضنة المدفوعة بالتغطية، وتقارير قابلة للقراءة آليًا، والانهيارات المُزالة التكرار عبر تجزئة المكدس) لكنه أصغر بكثير ومكتفٍ ذاتيًا.

---

البدء السريع

# Inside the codespace (or a host with python + git available):
./scripts/fuzzing/run_fuzzing.sh tukaani-project/xz

هذه هي الواجهة بأكملها. البرنامج النصي مستقل؛ سيقوم بتثبيت AFL++ عند التشغيل الأول، ثم يدير بقية سير المهام. تُكتب ملفات الإخراج إلى ~/.local/share/seclab-taskflow-agent/seclab-taskflows/.

تبدأ لوحة المعلومات تلقائيًا في الخلفية؛ في Codespace، يتم إعادة توجيه المنفذ 8765 تلقائيًا — افتحه في أي متصفح لمشاهدة التقدم مباشرةً.

لإجراء اختبار سريع، استخدم هدفًا صغيرًا:

./scripts/fuzzing/run_fuzzing.sh DaveGamble/cJSON

---

البنية المعمارية

ثلاث طبقات، من الأعلى إلى الأسفل:

┌────────────────────────────────────────────────────────────────────┐
│  scripts/fuzzing/run_fuzzing.sh                                    │
│      shell driver; chains the taskflow stages with `set +e`        │
└────────────────────┬───────────────────────────────────────────────┘
                     │
                     ▼
┌────────────────────────────────────────────────────────────────────┐
│  src/seclab_taskflows/taskflows/fuzzing/*.yaml                     │
│      LLM agent prompts; one YAML per pipeline stage                │
└────────────────────┬───────────────────────────────────────────────┘
                     │  (calls MCP tools)
                     ▼
┌────────────────────────────────────────────────────────────────────┐
│  src/seclab_taskflows/mcp_servers/                                 │
│   ├ fuzz_context.py    persistence (SQLite via SQLAlchemy)         │
│   └ fuzz_runner.py     subprocess wrappers (AFL, clang, lcov, ...) │
│                                                                    │
│  scripts/fuzzing/dashboard.py                                      │
│   read-only HTML view of fuzz_context.db                           │
└────────────────────────────────────────────────────────────────────┘

قواعد التصميم الأساسية:

• لا حالة عامة في أدوات MCP. كل دالة أداة تأخذ وسائط صريحة؛ الحالة الدائمة تعيش في fuzz_context.db.
• وكلاء LLM يملكون القرارات، وأدوات MCP تملك التنفيذ. الوكيل يقرر ماذا يُفحص عشوائياً، أي harness يُكتب، أي فجوة تُتبع بعد ذلك؛ أدوات MCP فقط تكشف run_afl_for، compile_harness، store_crash، إلخ.
• التماثل (Idempotency) حيثما كان ذلك رخيصاً. إعادة تشغيل خط الأنابيب على نفس المستودع تُحدّث الأهداف/الـ harnesses/التشغيلات بدلاً من تكرارها. هذا هو ما يجعل المجموعة الدائمة والانتقال بين الحملات يعملان.
• ثلاثة ملفات ثنائية لكل harness. أداة تتبع الحواف في AFL غير مناسبة لتقارير التغطية القابلة للقراءة البشرية، لذا يُبنى كل harness باستخدام afl-clang-lto++ -fsanitize=address,undefined (الملف الثنائي .afl) و باستخدام clang++ -fprofile-instr-generate -fcoverage-mapping (الملف الثنائي .cov). الملف الثنائي .afl يقوم بالفحص العشوائي؛ الملف الثنائي .cov يعيد تشغيل طابور AFL لإنتاج تغطية حقيقية لأسطر المصدر/الدوال/الفروع. ملف ثالث، خالٍ من الـ sanitizer وهو .cmplog (afl-clang-lto++ مع AFL_LLVM_CMPLOG=1) يُمرَّر إلى afl-fuzz -c حتى تتمكن مرحلة CMPLOG/RedQueen في AFL++ من حل القيم السحرية والمجاميع الاختبارية. جميع البناءات الثلاثة إلزامية: فشل بناء CMPLOG يُفشل بناء الـ harness، و run_afl_for يرفض التشغيل بدون ملف ثنائي .cmplog. إذا لم يكن afl-clang-lto++ مثبتاً، تستخدم بناءات AFL++ الأمر afl-clang-fast++ بدلاً منه ويُرجع compile_harness تحذيراً. برامج التشغيل C++ تربط مكتبة C++ القياسية، لذا تعمل harnesses ومكتبات C و C++ معاً؛ لا تزال ملفات .c تُترجم كـ C (-x c).

---