CyclePatrol is one Bash script, cp.sh. It is a Wi-Fi security assessment tool for the terminal.
It runs on Linux and Android (Kali NetHunter). It needs root.
The tool runs in a loop. In each round it:
- scans nearby Wi-Fi networks,
- parses each beacon and reads the security facts,
- runs the enabled assessment modules (WPS, PMKID, handshake, WPA2 dictionary, WPA3/SAE, DPP, enterprise EAP),
- saves facts, evidence (proof files) and an HTML report.
Authorized use only. CyclePatrol runs active wireless attacks. Use it only on networks you own or have written permission to test.
This documentation is written from the source code. It does not teach how to attack networks. It explains how the tool is built, how data moves, and where the security logic lives.
| Item | Value | Source |
|---|---|---|
| Tool name | CyclePatrol |
TOOL_NAME |
| Version | 1.6 |
VERSION |
| SAR / report version | 1 / 5 |
SAR_VERSION / REPORT_VERSION |
| Language | Bash 5+ | script header |
| Privilege | root required | run_precheck |
| Default interface | wlan2 |
DEF_IFACE |
| Default log dir | /sdcard/Download/wifi |
DEF_LOG_DIR |
| Tracked files | cp.sh, vendor/oui.json, vendor/vendors.json, README.md, LICENSE, docs/ |
repo root |
| Config | environment variables + CLI flags only | 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.shHelp and the full option list:
./cp.sh --helpflowchart 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
See docs/architecture.md and docs/data-flow.md for detail.
| Component | Functions (examples) | Job |
|---|---|---|
| Startup / config | main, validate_env, run_precheck, auto_install_deps |
parse flags, check root + interface + tools, build temp dirs |
| Interface control | ensure_mode, iface_set_type, iface_set_channel, iface_do_scan |
monitor/managed mode, channel, iw scan |
| Stealth | stealth_mac_rotate, stealth_gen_mac, stealth_wps_id_block |
random MAC, random WPS UUID |
| Scan + parse | scan_band, parse_scan |
collect iw scan output, parse beacons into fields |
| Enrichment | get_chip, get_cves, detect_dpp_vulns, vendor KB lookups |
OUI → vendor → chipset, CVE hints, DPP checks |
| Scope gate | active_attack_permitted, allowlist_init_active |
decide if an active module may run on a BSSID |
| Assessment modules | attack_pixie, attack_vendor, attack_pmkid, attack_deauth_handshake, attack_wpa_psk_brute, attack_wpa_enterprise_eviltwin |
the wireless tests (wrap external tools) |
| Offline crack | offline_crack, _hashcat_22000, _aircrack_cap |
crack captured PMKID / handshake |
| Evidence + output | sar_store_record, save_proof, make_report, recon_report |
JSONL facts, proof files, HTML reports |
| Location | location_fix, location_nmea_feeder |
GPS tagging for war-driving (Android / gpsd) |
Full function map: docs/project-structure.md.
CyclePatrol is an orchestrator. It calls standard Linux wireless tools as subprocesses.
| Tool | Used by | Purpose |
|---|---|---|
iw, ip, nmcli, macchanger |
interface + stealth | scan, mode, channel, MAC |
reaver |
attack_pixie, attack_vendor, attack_null, attack_empty, attack_user_pin |
WPS registrar exchange |
pixiewps |
attack_pixie |
WPS offline PIN recovery |
wpa_supplicant, wpa_cli, wpa_passphrase |
WPS, verify_psk_live, attack_wpa_psk_brute |
association, live key check |
hcxdumptool, hcxpcapngtool |
attack_pmkid, attack_pmkid_active |
PMKID capture → hashcat 22000 |
tcpdump |
eapol_passive_capture |
passive EAPOL capture |
airodump-ng, aireplay-ng, mdk4 |
attack_deauth_handshake, run_recon |
capture, deauth, recon |
hashcat, aircrack-ng |
offline_crack |
offline crack of captures |
eaphammer, hostapd-wpe |
attack_wpa_enterprise_eviltwin |
802.1X evil-twin credential capture |
dragondrain, dragontime |
sae_dos_dragondrain, sae_timing_dragontime |
WPA3 / SAE checks. Functions defined but never called (dead code), see docs/security.md |
tshark, airgraph-ng |
recon_report |
uptime parse, graphs |
gpsd, termux-location, gpspipe |
location | GPS fix / tagging |
jq |
vendor KB | JSON lookup (optional) |
Module detail and gating: docs/modules.md.
Everything is written under LOG_DIR (default /sdcard/Download/wifi).
The directory is made with chmod 700. Output files use chmod 600.
| Path | What |
|---|---|
sar.jsonl |
per-AP facts, one JSON object per line |
cp_audit.log |
audit log: AP, method, result |
report_*.html |
assessment report (findings, severity, evidence) |
report_recon_*.html |
passive recon survey report |
proof/proof_*.conf |
proof of a confirmed finding: PIN, PSK, SHA-256, live-verify |
proof/proofs.jsonl |
chain-of-custody manifest: one line per proof file, with its SHA-256 |
proof/handshake_*.cap |
captured 4-way handshake |
proof/pmkid_*.22000 |
PMKID in hashcat 22000 form |
known_bssids.txt, processed_bssids.txt |
state (skip already done) |
The report severities are Critical / High / Medium / Low / Info. A finding is Critical only
when a key was actually recovered and a proof file exists for it. The report opens in a Simple
view that shows the proof-backed findings. A Technical view toggle adds the posture findings,
the evidence table, and the diagnostic log. Posture findings (Medium / Low / Info) carry the
measured beacon facts that back their rating. Field schema and the report model are in
docs/outputs.md.
| File | Content |
|---|---|
docs/architecture.md |
components, control flow, trust boundaries, diagrams |
docs/data-flow.md |
scan → parse → process → report, field pipeline, scope flow |
docs/modules.md |
every assessment module, the tool it wraps, and its scope gate |
docs/configuration.md |
all environment variables and CLI flags |
docs/outputs.md |
sar.jsonl schema, proof files, report model |
docs/security.md |
scope model, default posture, secrets on disk, confirmed observations |
docs/attack-surface.md |
entry points, external dependency map, runtime diagram, what does not apply |
docs/setup-and-testing.md |
requirements, install, run, verify commands |
docs/project-structure.md |
files and full function map |
Aliaksandr Zasinets (BITART).
MIT. See LICENSE. Copyright (c) 2026 Aliaksandr Zasinets.