CyclePatrol

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

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

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

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

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

---

الحقائق

العنصر	القيمة	المصدر
اسم الأداة	CyclePatrol	TOOL_NAME
الإصدار	1.3	VERSION
إصدار SAR / التقرير	1 / 4	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	جذر المستودع
الاختبارات / CI	لا يوجد في المستودع	جذر المستودع
الإعدادات	متغيرات البيئة + أعلام 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
./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 هو منسّق. يستدعي أدوات Linux اللاسلكية القياسية كعمليات فرعية.

الأداة	تُستخدم بواسطة	الغرض
iw، ip، nmcli، macchanger	الواجهة + التخفي	الفحص، الوضع، القناة، MAC
reaver	attack_pixie، attack_vendor، attack_null، attack_empty، attack_user_pin	تبادل WPS registrar
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	التقاط بيانات اعتماد evil-twin لـ 802.1X
dragondrain، dragontime	sae_dos_dragondrain، sae_timing_dragontime	فحوصات WPA3 / SAE — الدوال معرّفة لكن لا تُستدعى أبدًا (كود ميت)، راجع docs/security.md O6
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/handshake_*.cap	handshake رباعي الاتجاهات ملتقط
proof/pmkid_*.22000	PMKID بصيغة hashcat 22000
proof/eapol_*.pcap	التقاط EAPOL
known_bssids.txt، processed_bssids.txt	الحالة (تخطي ما تم إنجازه)
recon_reported.txt، vuln_reported.txt	حالة إزالة تكرار التقارير

درجات خطورة التقرير: Critical / High / Medium / Low. حالات النتائج: confirmed / potential / beacon-based / config-based. تُقنَّع الأسرار في متن التقرير ما لم يكن REVEAL_CREDS=1. مخطط الحقول ونموذج التقرير: docs/outputs.md.

---

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