CyclePatrol (إعادة ابتكار WarDriving للواي فاي)

CyclePatrol هو سكربت Bash واحد، cp.sh. إنه أداة تقييم أمني للواي فاي تعمل في الطرفية. يعمل على Linux وAndroid (Kali NetHunter). يحتاج إلى صلاحيات الجذر (root).

تعمل الأداة في حلقة. في كل جولة تقوم بما يلي:

1. تفحص شبكات الواي فاي القريبة،
2. تحلل كل إطار beacon وتقرأ الحقائق الأمنية،
3. تشغّل وحدات التقييم المفعّلة (WPS، PMKID، handshake، قاموس WPA2، WPA3/SAE، DPP، EAP للمؤسسات)،
4. تحفظ الحقائق والأدلة (ملفات الإثبات) وتقرير HTML.

للاستخدام المصرّح به فقط. يشغّل CyclePatrol هجمات لاسلكية نشطة. استخدمه فقط على الشبكات التي تملكها أو لديك إذن كتابي باختبارها.

هذه الوثائق مكتوبة من الشيفرة المصدرية. وهي لا تعلّم كيفية مهاجمة الشبكات. بل تشرح كيف بُنيت الأداة، وكيف تنتقل البيانات، وأين تكمن منطق الأمان.

---

الحقائق

العنصر	القيمة	المصدر
اسم الأداة	CyclePatrol	TOOL_NAME
الإصدار	1.6	VERSION
إصدار SAR / التقرير	1 / 5	SAR_VERSION / REPORT_VERSION
اللغة	Bash 5+	ترويسة السكربت
الصلاحية	تتطلب root	run_precheck
الواجهة الافتراضية	wlan2	DEF_IFACE
مجلد السجلات الافتراضي	/sdcard/Download/wifi	DEF_LOG_DIR
الملفات المتتبعة	cp.sh، vendor/oui.json، vendor/vendors.json، README.md، LICENSE، docs/	جذر المستودع
الإعدادات	متغيرات البيئة + أعلام CLI فقط	main

---

التثبيت والبدء

# 1. get the code
git clone https://github.com/buybitart/cyclepatrol
cd cyclepatrol

# 2. make it runnable
chmod +x cp.sh

# 3. start (root required)
sudo ./cp.sh

المساعدة وقائمة الخيارات الكاملة:

./cp.sh --help

خط الأنابيب

flowchart TD
    M[main parse CLI] --> AI[auto_install_deps apt]
    AI --> PC[run_precheck validate_env root iface tmp dirs allowlists]
    PC --> RC{recon mode?}
    RC -- "--recon" --> RE[run_recon airodump-ng] --> RPT1[report_recon_*.html] --> END1[exit]
    RC -- default --> R0[run_recon once at start]
    R0 --> LOOP[run_scan_loop]
    LOOP --> MAC[stealth MAC rotate]
    MAC --> SCAN[scan_band 2.4 / 5 / 6E via iw scan]
    SCAN --> PARSE[parse_scan awk -> targets]
    PARSE --> PT[process_target per AP, up to MAX_TARGETS]
    PT --> REP[make_report report_*.html]
    REP --> SLEEP[sleep COOLDOWN] --> LOOP

راجع docs/architecture.md وdocs/data-flow.md للحصول على التفاصيل.

---

المكوّنات الرئيسية

المكوّن	الدوال (أمثلة)	المهمة
بدء التشغيل / الإعداد	main، validate_env، run_precheck، auto_install_deps	تحليل الأعلام، التحقق من root + الواجهة + الأدوات، إنشاء الأدلّة المؤقتة
التحكم بالواجهة	ensure_mode، iface_set_type، iface_set_channel، iface_do_scan	وضع monitor/managed، القناة، فحص iw
التخفّي	stealth_mac_rotate، stealth_gen_mac، stealth_wps_id_block	MAC عشوائي، WPS UUID عشوائي
الفحص + التحليل	scan_band، parse_scan	جمع مخرجات iw scan، تحليل beacons إلى حقول
الإثراء	get_chip، get_cves، detect_dpp_vulns، عمليات البحث في قاعدة معرفة البائع	OUI ← البائع ← الشريحة، تلميحات CVE، فحوصات DPP
بوابة النطاق	active_attack_permitted، allowlist_init_active	تحديد ما إذا كان يمكن لوحدة نشطة أن تعمل على BSSID
وحدات التقييم	attack_pixie، attack_vendor، attack_pmkid، attack_deauth_handshake، attack_wpa_psk_brute، attack_wpa_enterprise_eviltwin	الاختبارات اللاسلكية (تغلّف أدوات خارجية)
الكسر دون اتصال	offline_crack، _hashcat_22000، _aircrack_cap	كسر PMKID / handshake الملتقط
الأدلة + المخرجات	sar_store_record، save_proof، make_report، recon_report	حقائق JSONL، ملفات الإثبات، تقارير HTML
الموقع	location_fix، location_nmea_feeder	وسم GPS لـ war-driving (Android / gpsd)

خريطة الدوال الكاملة: docs/project-structure.md.

---

الأدوات الخارجية المستخدمة

CyclePatrol هو منسّق (orchestrator). يستدعي أدوات لينكس اللاسلكية القياسية كعمليات فرعية.

الأداة	يستخدمها	الغرض
iw، ip، nmcli، macchanger	الواجهة + التخفّي	الفحص، الوضع، القناة، MAC
reaver	attack_pixie، attack_vendor، attack_null، attack_empty، attack_user_pin	تبادل مسجّل WPS
pixiewps	attack_pixie	استرداد PIN الخاص بـ WPS دون اتصال
wpa_supplicant، wpa_cli، wpa_passphrase	WPS، verify_psk_live، attack_wpa_psk_brute	الاقتران، فحص المفتاح الحيّ
hcxdumptool، hcxpcapngtool	attack_pmkid، attack_pmkid_active	التقاط PMKID ← hashcat 22000
tcpdump	eapol_passive_capture	التقاط EAPOL سلبي
airodump-ng، aireplay-ng، mdk4	attack_deauth_handshake، run_recon	الالتقاط، deauth، الاستطلاع
hashcat، aircrack-ng	offline_crack	كسر الالتقاطات دون اتصال
eaphammer، hostapd-wpe	attack_wpa_enterprise_eviltwin	التقاط بيانات اعتماد 802.1X evil-twin
dragondrain، dragontime	sae_dos_dragondrain، sae_timing_dragontime	فحوصات WPA3 / SAE. الدوال معرّفة لكن لا تُستدعى أبدًا (كود ميت)، راجع docs/security.md
tshark، airgraph-ng	recon_report	تحليل مدة التشغيل، الرسوم البيانية
gpsd، termux-location، gpspipe	الموقع	تحديد الموقع / الوسم عبر GPS
jq	قاعدة معرفة البائع	بحث JSON (اختياري)

تفاصيل الوحدات وبواباتها: docs/modules.md.

المخرجات

يُكتب كل شيء تحت LOG_DIR (الافتراضي /sdcard/Download/wifi). يُنشأ الدليل باستخدام chmod 700. تستخدم ملفات المخرجات chmod 600.

المسار	المحتوى
sar.jsonl	حقائق لكل AP، كائن JSON واحد لكل سطر
cp_audit.log	سجل التدقيق: AP، الطريقة، النتيجة
report_*.html	تقرير التقييم (النتائج، الخطورة، الأدلة)
report_recon_*.html	تقرير مسح الاستطلاع السلبي
proof/proof_*.conf	إثبات نتيجة مؤكدة: PIN، PSK، SHA-256، التحقق الحيّ
proof/proofs.jsonl	بيان سلسلة الحيازة: سطر واحد لكل ملف إثبات، مع SHA-256 الخاص به
proof/handshake_*.cap	مصافحة 4-way الملتقطة
proof/pmkid_*.22000	PMKID بصيغة hashcat 22000
known_bssids.txt، processed_bssids.txt	الحالة (تخطّي ما تم إنجازه بالفعل)

درجات خطورة التقرير هي Critical / High / Medium / Low / Info. لا تُصنَّف النتيجة على أنها Critical إلا عندما يُستعاد مفتاح فعليًا وتوجد ملف إثبات خاص به. يُفتح التقرير في عرض مبسّط يعرض النتائج المدعومة بالإثبات. ويضيف مفتاح التبديل العرض التقني نتائج الوضعية، وجدول الأدلة، وسجل التشخيص. تحمل نتائج الوضعية (Medium / Low / Info) حقائق المنارة المقيسة التي تدعم تصنيفها. مخطط الحقول ونموذج التقرير موجودان في docs/outputs.md.

---

خريطة التوثيق