BBOT TUI Viewer

واجهة طرفية مكتفية ذاتيًا لتصفّح نتائج فحوصات BBOT وتحليلها.

الميزات

• 🚀 إعداد صفري - ملف واحد يثبّت نفسه ذاتيًا، دون أي اعتماديات يدوية
• 🔴 تحديث مباشر - تحديثات تلقائية أثناء تشغيل الفحوصات مع كشف دقيق للحالة
• 🎯 كشف ذكي للحالة - يحدّد بدقة الفحوصات قيد التشغيل (RUNNING) والمنتهية (FINISHED) والمتقطعة (INTERRUPTED)
• 📋 متصفّح الفحوصات - التنقّل بين فحوصات متعددة مع عدّادات منفصلة للثغرات/النتائج ومؤشرات الحالة
• 📦 إدارة الأرشيف - ضغط الفحوصات القديمة لتوفير المساحة واستعادتها عند الحاجة
• 📝 تتبّع العمل - إضافة تعليقات توضيحية للثغرات والنتائج تتضمن الحالة والأولوية والملاحظات
• 🔍 عروض منفصلة - تبويبات مخصصة للثغرات (مرتبة حسب الخطورة) وللنتائج
• 🌳 شجرة الاكتشاف - عرض هرمي يوضح علاقات الأحداث بين الأصل والفرع
• 🌐 شجرة النطاقات الفرعية - عرض هرمي للنطاقات الفرعية المكتشفة (عند توفّرها)
• 📊 إحصاءات غنية - جداول أنيقة تعرض توزيع الأحداث وتحليل النطاق ومقاييس سير العمل
• 🔎 مستكشف الأحداث - تصفية جميع أحداث الفحص والبحث فيها وفحصها
• ⚙️ عارض الإعدادات - عرض إعدادات preset.yml

بدء سريع

# Copy to server and run (auto-installs on first run)
./bbot-ui

# Or specify custom path
./bbot-ui /path/to/scans

ينشئ التشغيل الأول .bbot_ui_venv/ ويُثبّت الاعتماديات، بينما تنطلق عمليات التشغيل اللاحقة فورًا.

الاستخدام

./bbot-ui                          # Default: ~/.bbot/scans
./bbot-ui /path/to/scans          # Browse all scans in directory
./bbot-ui ~/.bbot/scans/scan-name # View specific scan

خيارات سطر الأوامر

./bbot-ui --help                               # Show all options
./bbot-ui --scan-interval 5                    # Refresh scan view every 5 seconds
./bbot-ui --list-interval 10                   # Refresh scan list every 10 seconds

الخيارات المتاحة:

• --scan-interval SECONDS - فترة تحديث عرض تفاصيل الفحص (الافتراضي: 2.0)
• --list-interval SECONDS - فترة تحديث قائمة الفحوصات (الافتراضي: 3.0)

تُحفظ الإعدادات تلقائيًا في ~/.bbot_ui_config.json وتُستخدم كقيم افتراضية للجلسات المستقبلية.

الواجهة

قائمة الفحوصات

• إقلاع فوري - تظهر الواجهة في أقل من 200 مللي ثانية، وتُحمَّل الفحوصات تدريجيًا
• تصفّح جميع الفحوصات في جدول يحتوي الأعمدة: Scan Name وStatus وEvents وVulns وFindings وLast Modified
• يعرض الرأس إجمالي الفحوصات وعدد الثغرات/النتائج وعدد الفحوصات قيد التشغيل
• يعرض عمود Status حالة الفحص في الوقت الفعلي:
  • ● RUNNING (أخضر) - الفحص يعمل بنشاط مع اكتشاف عملية bbot
  • ⚠ INTERRUPTED (أصفر) - تم إيقاف الفحص أو قطعه (لا توجد عملية نشطة)
  • ✓ FINISHED (أزرق) - اكتمل الفحص بنجاح
  • ○ CHECKING... (باهت) - يتم التحقق من الحالة (يظهر أثناء التحميل التدريجي)
• يعرض العمودان Vulns وFindings مؤشر ⚠ للفحوصات التي تحتوي ثغرات/نتائج
• تظهر الفحوصات واحدًا تلو الآخر مع تحديثات مباشرة للحالة أثناء التحميل الأولي
• يتحدّث تلقائيًا كل 3 ثوانٍ لعرض الفحوصات الجديدة وتغيّرات الحالة
• استخدم ↑/↓ أو j/k للتنقّل، وEnter للفتح، وr للتحديث اليدوي، وa للأرشفة، وd للحذف
• اضغط Tab لعرض الفحوصات المؤرشفة

قائمة الأرشيف

• تصفّح جميع الفحوصات المؤرشفة (ملفات .zip مضغوطة)
• يعرض: Archive Name وSize وEvents وVulns وFindings وDate Archived
• استخدم u لإلغاء الأرشفة (استعادة)، وd للحذف نهائيًا
• اضغط Tab أو q أو Escape للعودة إلى قائمة الفحوصات

إدارة الأرشيف

وفّر مساحة القرص بضغط الفحوصات القديمة في أرشيفات ZIP:

أرشفة فحص:

1. انتقل في قائمة الفحوصات إلى الفحص الذي تريد أرشفته
2. اضغط a للأرشفة
3. أكّد العملية
4. يُضغط مجلد الفحص في ملف .zip ويُحذف المجلد الأصلي
5. يظهر الأرشيف في قائمة الأرشيف (اضغط Tab للعرض)

استعادة أرشيف:

1. اضغط Tab لعرض قائمة الأرشيف
2. انتقل إلى الأرشيف الذي تريد استعادته
3. اضغط u لإلغاء الأرشفة
4. أكّد العملية
5. يُستخرج الأرشيف ويُحذف ملف .zip
6. اضغط q للعودة إلى قائمة الفحوصات ورؤية الفحص المُستعاد

ميزات الأمان:

• لا يمكن أرشفة الفحوصات قيد التشغيل (RUNNING)
• يُتحقق من سلامة الأرشيف قبل حذف المجلد المصدر
• يُتحقق من الاستخراج قبل حذف الأرشيف
• تتطلب جميع العمليات تأكيدًا
• إذا فشلت أي خطوة، تُتراجع العملية بأمان

حذف الفحوصات/الأرشيفات:

• من قائمة الفحوصات: اضغط d لحذف مجلد الفحص نهائيًا
• من قائمة الأرشيف: اضغط d لحذف ملف الأرشيف نهائيًا
• لا يمكن حذف الفحوصات قيد التشغيل (RUNNING)
• يتطلب تأكيدًا (الإجراء نهائي ولا يمكن التراجع عنه)
• ستُفقد جميع بيانات الفحص

تتبّع العمل والتعليقات التوضيحية

تتبّع سير عملك الأمني بإضافة تعليقات توضيحية للثغرات والنتائج تتضمن الحالة والأولوية والملاحظات.

كيف يعمل:

• تُخزَّن التعليقات التوضيحية في .bbot_ui_annotations.json بجوار كل فحص
• تشير إلى الأحداث عبر UUID - ولا تعدّل أبدًا ملف output.json الأصلي الخاص بـ BBOT
• تُضمَّن تلقائيًا في الأرشيفات للنسخ الاحتياطي والاستعادة
• تبقى محفوظة عند إعادة فحص الهدف نفسه

إضافة تعليق توضيحي لثغرة/نتيجة:

1. انتقل إلى تبويب Vulnerabilities أو Findings
2. حدد عنصرًا (بمفاتيح الأسهم أو j/k)
3. اضغط t لفتح نافذة التعليق التوضيحي
4. اضبط الحالة والأولوية (اختياري) والملاحظات
5. انقر Save أو اضغط Enter

اختصارات سريعة:

• اضغط x لتحديد العنصر المحدد كـ False Positive
• اضغط i لتحديد العنصر المحدد كـ Accepted Risk
• يحافظان على الأولوية والملاحظات الحالية أثناء تحديث الحالة

خيارات الحالة:

• 🆕 New - الحالة الافتراضية للعناصر غير المُعلَّق عليها
• 🔍 Investigating - قيد التحليل حاليًا
• ✓ Confirmed - تم التحقق من كونه مشكلة حقيقية
• ✗ False Positive - ليس ثغرة حقيقية
• 📢 Reported - تم إرساله إلى فريق الأمان
• 🔧 Fixed - تم حل المشكلة
• ⚠ Accepted Risk - معروف لكنه مقبول

مستويات الأولوية (اختياري):

• 🔴 Critical - يتطلب اهتمامًا فوريًا
• 🟠 High - مهم، يجب معالجته قريبًا
• 🟡 Medium - أولوية عادية
• 🟢 Low - مشكلة بسيطة

الميزات:

• عمودا Status وPriority في جدولي Vulnerabilities/Findings
• قائمة منسدلة لتصفية الحالة - تصفية حسب حالة محددة أو عناصر "Actionable" (الافتراضي)
• اختصارات لوحة مفاتيح سريعة (x/i) للفرز السريع
• مخططات حالة سير العمل في تبويب Statistics
• حقل ملاحظات لتوفير سياق تفصيلي
• زر مسح التعليق التوضيحي لإعادة التعيين
• تستمر التعليقات التوضيحية عبر الجلسات والأرشيفات

تصفية الحالة:

• Actionable (الافتراضي) - يعرض فقط العناصر التي تحتاج إلى انتباه (new، investigating، confirmed، reported)
• All - يعرض جميع الثغرات/النتائج بغض النظر عن الحالة
• حالات محددة - تصفية حسب حالة فردية (false-positive، fixed، وما إلى ذلك)
• تتحدّث التصفية تلقائيًا عند وضع علامات على العناصر عبر اختصارات لوحة المفاتيح

تبويبات عارض الفحص

• شريط الحالة: يعرض حالة الفحص مع عدد الأحداث في الوقت الفعلي
  • ● RUNNING (أخضر) - يتحدّث بنشاط مع الأحداث الجديدة
  • ✓ FINISHED (أزرق) - اكتمل الفحص، لا مزيد من التحديثات
  • ⚠ INTERRUPTED (أصفر) - تم إيقاف الفحص أو قطعه
• تحديث تلقائي: تتحدّث جميع التبويبات كل ثانيتين عندما يكون الفحص قيد التشغيل (RUNNING)
• كشف ذكي: يتوقف تلقائيًا عن استقصاء الفحوصات المنتهية (FINISHED) والمتقطعة (INTERRUPTED)
• اضغط r للتحديث يدويًا ورؤية إشعار بعدد الأحداث الجديدة

1. Vulnerabilities - أحداث VULNERABILITY مرتبة حسب الخطورة (CRITICAL→HIGH→MEDIUM→LOW→INFO→UNKNOWN)، مع الحالة والأولوية والتعليقات التوضيحية (تحديثات مباشرة) 2. Findings - أحداث FINDING مع الحالة والأولوية والتعليقات التوضيحية (تحديثات مباشرة) 3. Events - جميع الأحداث مع تصفية حسب النوع وتصفية حسب مسافة النطاق وبحث متعدد المصطلحات وتفاصيل JSON (تحديثات مباشرة) 4. Tree - وضعا عرض (تحديثات مباشرة):

• Discovery: يعرض كيفية العثور على الأحداث عبر وحدات الفحص (علاقات الأصل-الفرع)
• Topology: التدرج الهرمي المنطقي للشبكة (IP_RANGE → IP → OPEN_TCP_PORT) 5. Statistics - توزيع الأحداث وأفضل 15 وحدة (مرتبة) ومخططات مسافة النطاق وحالة سير العمل وتوزيع الأولويات (تحديثات مباشرة) 6. Subdomains - عرض شجري هرمي للنطاقات الفرعية المكتشفة (يظهر فقط عند وجود subdomains.txt، وعادةً من الإعداد المسبق subdomain-enum) 7. Configuration - عرض preset.yml مع تلوين الصيغة

البحث متعدد المصطلحات

يدعم تبويب Events بحثًا قويًا متعدد المصطلحات:

• مصطلحات مفصولة بمسافات: استخدم المسافات للبحث عن مصطلحات متعددة (مثل httpx in-scope)
• منطق AND: يجب أن تطابق الأحداث جميع المصطلحات لتظهر في النتائج
• الحقول التي يتم البحث فيها: data، type، module، host، tags، discovery_context
• الدمج مع عوامل التصفية: يعمل جنبًا إلى جنب مع عاملي تصفية Type وScope distance

أمثلة:

• httpx in-scope - الأحداث الصادرة عن وحدة httpx مع وسم in-scope
• k11h HIGH - الأحداث المتعلقة بالنطاق k11h.de بخطورة HIGH
• nuclei VULNERABILITY - الثغرات المكتشفة بواسطة وحدة nuclei

عرض شجرة النطاقات الفرعية

عند تشغيل BBOT مع الإعداد المسبق subdomain-enum (أو أي فحص يُنشئ ملف subdomains.txt)، يظهر تبويب Subdomains تلقائيًا في عارض الفحص، ويعرض شجرة هرمية للنطاقات الفرعية المكتشفة.

الميزات:

• عرض هرمي: النطاقات الفرعية منظمة وفق بنية النطاق (مثل api.example.com ضمن example.com)
• شجرة قابلة للتوسيع: تنقّل بين مستويات النطاق عبر تنقّل شجري بديهي
• مؤشر العدد: يعرض عنوان التبويب إجمالي عدد النطاقات الفرعية (مثل "Subdomains (42)")
• كشف تلقائي: يظهر التبويب فقط عند وجود subdomains.txt في مجلد الفحص

مثال على التدرج الهرمي:

example.com
  ├─ api.example.com
  ├─ dev.example.com
  └─ www.example.com

اختصارات لوحة المفاتيح

التنقّل: ↑/↓ أو j/k | إضافة تعليق: t (Vulns/Findings فقط) | False Positive: x (Vulns/Findings فقط) | Accepted Risk: i (Vulns/Findings فقط) | عرض الأرشيفات: Tab (من قائمة الفحوصات) | البحث: f | التحديث: r | الأرشفة: a (قائمة الفحوصات) | إلغاء الأرشفة: u (قائمة الأرشيف) | الحذف: d | ضبط تقسيم الشاشة: ←/→ | رجوع/خروج: q أو Escape

ملاحظة: تظهر اختصارات التعليق (t، x، i) في التذييل فقط عند عرض تبويبي Vulnerabilities أو Findings.

التحديث المباشر وكشف الحالة

يكتشف bbot-ui تلقائيًا التحديثات الصادرة عن الفحوصات قيد التشغيل ويعرضها في الوقت الفعلي:

الكشف الذكي للحالة

تستخدم الواجهة سلسلة كشف متعددة الأساليب لتحديد حالة الفحص بدقة:

1. تحليل حدث SCAN: يقرأ حقل status لآخر حدث SCAN من output.json

   • "FINISHED" → اكتمل الفحص (يحتوي على حقلي finished_at وduration)
   • "RUNNING" → تحقق مما إذا كان يعمل فعليًا (انتقل إلى الخطوة 2)

2. كشف العملية النشطة (لحالة RUNNING):

   • psutil (يُثبَّت تلقائيًا، ويعمل عبر المنصات) - يتحقق مما إذا كانت أي عملية تفتح output.json

3. الحالة النهائية:

   • RUNNING: حدث SCAN يقول RUNNING + العملية تفتح الملف بنشاط
   • INTERRUPTED: حدث SCAN يقول RUNNING + لا توجد عملية تفتح الملف (تم إيقاف الفحص عبر Ctrl+C)
   • FINISHED: حدث SCAN يقول FINISHED (يحتوي على بيانات الإكمال)

الميزات

• تحميل تدريجي: تظهر الفحوصات واحدًا تلو الآخر مع تحديثات مباشرة للحالة أثناء بدء التشغيل
• كشف دقيق: يحدد الفحوصات المتقطعة فورًا دون انتظار انتهاء المهلة
• محسّن للأداء:
  • التنقّل التدريجي عبر الأدلة (غير حاجب، 1 مللي ثانية لكل دليل)
  • تحميل فحص واحد لكل نبضة مؤقّت (10 مللي ثانية)
  • يخزّن فحوصات العمليات مؤقتًا لمدة 5 ثوانٍ (يتجنب فحص جميع العمليات مرارًا)
  • يفحص الفحوصات قيد التشغيل (RUNNING) فقط (يتخطى الفحوصات المكلفة للفحوصات المنتهية FINISHED)
  • يتوقف الاستقصاء الذكي عن فحص الفحوصات المنتهية (FINISHED) والمتقطعة (INTERRUPTED)
• تحميل تزايدي: يقرأ الأحداث الجديدة فقط من output.json بكفاءة
• غير حاجب: تبقى الواجهة مستجيبة بالكامل أثناء التحديثات
• الحفاظ على المؤشر: يحافظ على موضعك في الجداول أثناء التحديث
• معالجة سلسة: يتخطى أسطر JSON غير المكتملة/غير الصالحة من الفحوصات قيد التشغيل
• فترات قابلة للتخصيص: خصص معدلات التحديث وفقًا لاحتياجاتك

الإعدادات

يمكنك تخصيص سلوك التحديث المباشر:

عبر سطر الأوامر:

./bbot-ui --scan-interval 5 --list-interval 10

القيم الافتراضية:

• يتحدّث عرض تفاصيل الفحص كل ثانيتين
• تتحدّث قائمة الفحوصات كل 3 ثوانٍ

حالات الاستخدام:

• شبكات سريعة/فحوصات محلية: استخدم فترات أقصر (مثل --scan-interval 1)
• أنظمة بعيدة/بطيئة: استخدم فترات أطول (مثل --scan-interval 5)
• تقليل استخدام المعالج: زد جميع الفترات لإجراء فحوصات أقل تكرارًا

تُحفظ الإعدادات في ~/.bbot_ui_config.json وتستمر عبر الجلسات.

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

لم يكتمل الإعداد بشكل صحيح؟

rm -rf ~/.bbot_ui_venv && ./bbot-ui

تحذير بخصوص عدم تثبيت psutil؟

إذا رأيت تحذيرًا يفيد بأن psutil مفقود، فبيئتك الافتراضية (venv) من إصدار أقدم. أعد التثبيت:

rm -rf ~/.bbot_ui_venv && ./bbot-ui

لا يوجد ملف output.json؟

تأكد من أن دليل الفحص يحتوي على output.json (يُنشئه BBOT تلقائيًا)

لم يتم العثور على Python؟

# Ubuntu/Debian
sudo apt install python3 python3-venv

# macOS
brew install python3

المتطلبات

• Python 3.8+
• يُثبَّت تلقائيًا: textual>=0.47.0، rich>=13.0.0، psutil>=5.9.0

ملاحظة: يُستخدم psutil للكشف الدقيق عن حالة الفحص عن طريق التحقق مما إذا كانت أي عملية تفتح ملف الفحص.

الأداء

الواجهة محسّنة للفحوصات الكبيرة والأدلة المتعددة:

أداء بدء التشغيل:

• تحميل تدريجي - تُعرض الواجهة فورًا (أقل من 200 مللي ثانية)، وتُحمَّل الفحوصات واحدًا تلو الآخر
• يتم تعداد الأدلة بشكل تزايدي (1 مللي ثانية لكل دليل)
• يعمل بكفاءة على أنظمة الملفات الشبكية والوحدات المثبتة عن بُعد
• لا توجد عمليات حاجبة أثناء بدء التشغيل

حدود العرض:

• تبويب Vulnerabilities: 1000 صف كحد أقصى (مرتبة حسب الخطورة)
• تبويب Findings: 1000 صف كحد أقصى
• تبويب Events: 1000 صف كحد أقصى (استخدم عوامل التصفية للفحوصات الكبيرة)
• عروض الشجرة: 500 عقدة كحد أقصى (استخدم عوامل التصفية للتركيز على مناطق محددة)
• قائمة الفحوصات: يعرض التحميل التدريجي الفحوصات عند اكتشافها

قراءة الملف:

• يقرأ من طرفَي الملف للعثور على أحداث SCAN (يتعامل مع أدلة الفحص المُعاد استخدامها)
• يكتشف أحدث فحص حسب الطابع الزمني (يدعم عمليات تشغيل متعددة في نفس الدليل)
• يقدّر أعداد الأحداث للفحوصات الكبيرة باستخدام حجم الملف وأخذ العينات
• يخزّن فحوصات الحالة مؤقتًا لتجنب عمليات فحص العمليات المتكررة

التحديث التلقائي:

• يتوقف المؤقّت تلقائيًا للفحوصات المنتهية (FINISHED)/المتقطعة (INTERRUPTED)
• يفحص الفحوصات قيد التشغيل (RUNNING) فقط بحثًا عن التحديثات
• تُخزَّن النتائج مؤقتًا لمدة 5 ثوانٍ
• تمنع علامة initial_load_phase تعارضات التحديث أثناء بدء التشغيل

نصائح

• استخدم عوامل التصفية (النوع، مسافة النطاق) للتركيز على أحداث محددة في الفحوصات الكبيرة
• أعداد الأحداث للفحوصات الكبيرة (>1MB) هي تقديرات لتحسين الأداء
• اختصارات التعليق (t، x، i) حساسة للسياق ولا تظهر إلا في التبويبات ذات الصلة
• يعني التحميل التدريجي أنه يمكنك بدء العمل فورًا - لا حاجة لانتظار تحميل جميع الفحوصات
• على أنظمة الملفات الشبكية البطيئة، ستظهر الفحوصات تدريجيًا - وهذا سلوك طبيعي
• احذف ~/.bbot_ui_venv/ لإجبار إعادة تثبيت نظيفة

الترخيص

MIT