CyclePatrol is a bash script that cycles through scan, parse and assessment stages against nearby Wi-Fi networks, generating evidence-backed HTML reports for authorized wireless assessments.

Most Wi-Fi assessment tooling is a pile of separate utilities that an operator chains together by hand, one access point at a time. CyclePatrol (repo buybitart/cyclepatrol, MIT licensed, ~34 stars, written in Shell) takes the opposite approach: it is one bash script, cp.sh, that runs an entire loop — scan, parse, assess, report — over every network in range, repeatedly. The intended platform is Linux or Android under Kali NetHunter, it requires bash 5+, and it demands root via a run_precheck gate before doing anything. The framing in the README is unambiguous: this is an authorized-use tool, and the author says so in bold before any technical detail.

Version 1.3 is documented almost entirely from the source code, which is a refreshing stance — the README explicitly refuses to explain how to attack networks and instead documents architecture, data flow and where the security logic lives. The repository is deliberately small: cp.sh, vendor/oui.json, vendor/vendors.json, the README.md and an MIT LICENSE. There are no tests and no CI, which the facts table admits plainly. Configuration is done exclusively through environment variables and CLI flags parsed in main, with defaults like DEF_IFACE=wlan2 and DEF_LOG_DIR=/sdcard/Download/wifi betraying its Android-on-the-street heritage.

The control flow is worth reading as a design exercise. main parses the CLI, auto_install_deps pulls missing packages via apt, and run_precheck validates environment: root, interface presence, temp directories, and — critically — the allowlists that feed the scope gate. From there a --recon flag short-circuits everything into a passive airodump-ng survey and an HTML report, while the default path enters run_scan_loop. Each iteration rotates the MAC (stealth_mac_rotate with macchanger-style randomization), scans 2.4/5/6E bands via iw scan, parses beacons with awk in parse_scan, and hands each discovered AP to process_target, bounded by MAX_TARGETS, before generating a report and sleeping for COOLDOWN.

Internally CyclePatrol is an orchestrator, not an implementation of any wireless attack itself. Every assessment module is a wrapper around a standard external tool invoked as a subprocess: reaver and pixiewps for WPS registrar interactions, hcxdumptool and hcxpcapngtool for PMKID capture into hashcat 22000 format, wpa_supplicant/wpa_cli for association and live key verification, airodump-ng/aireplay-ng/mdk4 for capture and deauth flows, hashcat and aircrack-ng for offline cracking, and eaphammer/hostapd-wpe for enterprise 802.1X testing. The README maps each module function (attack_pixie, attack_pmkid, attack_deauth_handshake, attack_wpa_psk_brute, attack_wpa_enterprise_eviltwin, and so on) to the tool it wraps, which makes the script a useful index of the Linux wireless toolchain even if you never run it.

The scope gate is the part that distinguishes a disciplined assessment tool from a war-driving toy, and the README gives it first-class treatment. active_attack_permitted and allowlist_init_active decide, per BSSID, whether any active module is allowed to run at all — meaning the operator must explicitly enumerate the networks in scope before anything that transmits against an AP executes. This is the kind of guardrail compliance-minded consultants look for, and its presence in the control flow diagram (before process_target) suggests it is enforced centrally rather than sprinkled through modules. The supporting docs/modules.md documents each module and its gate individually.

Enrichment is another interesting layer. Beyond raw beacon facts, get_chip walks OUI to vendor to chipset using vendor/oui.json and vendor/vendors.json (with optional jq lookups), get_cves attaches CVE hints based on identified chipset, and detect_dpp_vulns performs DPP-related checks. There is also GPS integration — location_fix and location_nmea_feeder support Android termux-location or gpsd/gpspipe — which tags findings with coordinates for survey-style war-driving documentation. For a defensive team doing asset discovery on their own campus, this enrichment plus location data is arguably the most valuable output the tool produces.

The evidence model is unusually formal for a bash project. Everything lands under LOG_DIR, created with chmod 700 while files get chmod 600. Per-AP facts stream into sar.jsonl as one JSON object per line; cp_audit.log records AP, method and result; and make_report emits report_*.html with findings graded Critical/High/Medium/Low and states of confirmed, potential, beacon-based or config-based. Proof artifacts — proof/proof_*.conf with PINs, PSKs, SHA-256 digests and live-verification records, handshake_*.cap, pmkid_*.22000, eapol_*.pcap — back each confirmed finding. Notably, secrets are masked in the report body unless REVEAL_CREDS=1 is set, a sensible default for reports that circulate beyond the assessor.

State management shows the loop is designed for long unattended walks rather than one-shot runs: known_bssids.txt and processed_bssids.txt prevent reprocessing APs already handled, and recon_reported.txt/vuln_reported.txt de-duplicate report entries across iterations. Combined with MAC rotation and a cooldown, this is a set-and-forget patrol pattern — the name is literal. Whether repeated MAC churn and automated module execution fit your engagement's rules of engagement is a judgment call the tool correctly leaves to the human holding the authorization letter.

The README is also candid about defects, which builds credibility. The dragondrain and dragontime WPA3/SAE wrappers (sae_dos_dragondrain, sae_timing_dragontime) are flagged as dead code — defined but never called, cross-referenced to docs/security.md finding O6. That kind of self-audit, extended across a documentation map covering docs/architecture.md, docs/data-flow.md, docs/configuration.md, docs/outputs.md, docs/attack-surface.md, docs/setup-and-testing.md and docs/project-structure.md, is rare in tooling of this size and makes the repo a good read for anyone studying how to structure single-file security tooling.

Getting started is straightforward: git clone https://github.com/buybitart/cyclepatrol, chmod +x cp.sh, and consult ./cp.sh --help for the full flag list before doing anything else. Given the root requirement and the dependency footprint (reaver, hcxdumptool, hashcat, eaphammer, and friends, auto-installed via apt), a lab VM or a dedicated NetHunter device is the sane deployment target — never a shared machine.

From a defender's perspective, the telemetry profile of this class of tool is worth knowing even if you never run it. A patrol loop leaves observable signatures: rapid client MAC churn around monitored BSSIDs, WPS registrar exchange attempts, EAPOL/deauth bursts, and heavy scan activity across bands. CyclePatrol itself is quiet on the wire relative to its footprint on disk — it logs obsessively, with restrictive permissions, under /sdcard/Download/wifi by default — so on your own infrastructure the sar.jsonl trail is an audit asset, while on someone else's network the same behaviors are exactly what wireless IDS rules for deauth floods and rogue association attempts are built to catch. The line between the two is authorization, and the tool's own scope gate exists to keep operators on the right side of it.

Educational analysis for authorized security professionals. Use only in controlled, authorized environments.

Related coverage

• kev-data for programmatic access to the CISA known exploited vulnerabilities catalog


• garble for stripping source-revealing metadata out of Go binaries


• Inside kernel-research: how Googles kernelXDK assembles a full Linux kernel exploitation workbench