CyclePatrol

CyclePatrol é um único script Bash, cp.sh. É uma ferramenta de avaliação de segurança Wi-Fi para o terminal. Funciona em Linux e Android (Kali NetHunter). Requer root.

A ferramenta executa em loop. Em cada ronda:

1. faz scan das redes Wi-Fi próximas,
2. analisa cada beacon e lê os factos de segurança,
3. executa os módulos de avaliação ativados (WPS, PMKID, handshake, dicionário WPA2, WPA3/SAE, DPP, enterprise EAP),
4. guarda factos, evidências (ficheiros de prova) e um relatório HTML.

Apenas para uso autorizado. O CyclePatrol executa ataques wireless ativos. Utilize apenas em redes que possui ou para as quais tem autorização escrita para testar.

Esta documentação é escrita apenas a partir do código-fonte. Não explica como atacar redes. Explica como a ferramenta é construída, como os dados circulam e onde está a lógica de segurança.

---

Factos

Item	Valor	Fonte
Nome da ferramenta	CyclePatrol	TOOL_NAME
Versão	1.3	VERSION
Versão SAR / relatório	1 / 4	SAR_VERSION / REPORT_VERSION
Linguagem	Bash 5+	—
Privilégio	root necessário	run_precheck
Interface predefinida	wlan2	DEF_IFACE
Diretório de log predefinido	/sdcard/Download/wifi	DEF_LOG_DIR
Ficheiros no repositório	cp.sh, vendor/oui.json, vendor/vendors.json, README.md, LICENSE	raiz do repositório
Testes / CI	nenhum no repositório	raiz do repositório
Configuração	apenas variáveis de ambiente + flags CLI	main

---

Instalação / Arranque

# 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

Ajuda e a lista completa de opções:

./cp.sh --help

---

Pipeline

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

Consulte docs/architecture.md e docs/data-flow.md para mais detalhes.

---

Componentes principais

Componente	Funções (exemplos)	Tarefa
Arranque / configuração	main, validate_env, run_precheck, auto_install_deps	analisar flags, verificar root + interface + ferramentas, criar diretórios temporários
Controlo de interface	ensure_mode, iface_set_type, iface_set_channel, iface_do_scan	modo monitor/managed, canal, scan iw
Stealth	stealth_mac_rotate, stealth_gen_mac, stealth_wps_id_block	MAC aleatório, UUID WPS aleatório
Scan + análise	scan_band, parse_scan	recolher saída de iw scan, analisar beacons em campos
Enriquecimento	get_chip, get_cves, detect_dpp_vulns, consultas à KB de vendors	OUI → vendor → chipset, sugestões de CVE, verificações DPP
Portão de âmbito	active_attack_permitted, allowlist_init_active	decidir se um módulo ativo pode ser executado num BSSID
Módulos de avaliação	attack_pixie, attack_vendor, attack_pmkid, attack_deauth_handshake, attack_wpa_psk_brute, attack_wpa_enterprise_eviltwin	os testes wireless (encapsulam ferramentas externas)
Cracking offline	offline_crack, _hashcat_22000, _aircrack_cap	crack de PMKID / handshake capturados
Evidência + saída	sar_store_record, save_proof, make_report, recon_report	factos JSONL, ficheiros de prova, relatórios HTML
Localização	location_fix, location_nmea_feeder	etiquetagem GPS para war-driving (Android / gpsd)

Mapa completo de funções: docs/project-structure.md.

---

Ferramentas externas utilizadas

O CyclePatrol é um orquestrador. Chama ferramentas wireless padrão do Linux como subprocessos.

Ferramenta	Utilizada por	Propósito
iw, ip, nmcli, macchanger	interface + stealth	scan, modo, canal, MAC
reaver	attack_pixie, attack_vendor, attack_null, attack_empty, attack_user_pin	troca com registrador WPS
pixiewps	attack_pixie	recuperação offline de PIN WPS
wpa_supplicant, wpa_cli, wpa_passphrase	WPS, verify_psk_live, attack_wpa_psk_brute	associação, verificação de chave em tempo real
hcxdumptool, hcxpcapngtool	attack_pmkid, attack_pmkid_active	captura PMKID → hashcat 22000
tcpdump	eapol_passive_capture	captura EAPOL passiva
airodump-ng, aireplay-ng, mdk4	attack_deauth_handshake, run_recon	captura, deauth, recon
hashcat, aircrack-ng	offline_crack	crack offline de capturas
eaphammer, hostapd-wpe	attack_wpa_enterprise_eviltwin	captura de credenciais evil-twin 802.1X
dragondrain, dragontime	sae_dos_dragondrain, sae_timing_dragontime	verificações WPA3 / SAE — funções definidas mas nunca chamadas (código morto), ver docs/security.md O6
tshark, airgraph-ng	recon_report	análise de uptime, gráficos
gpsd, termux-location, gpspipe	localização	fix / etiquetagem GPS
jq	KB de vendors	consulta JSON (opcional)

Detalhe dos módulos e gating: docs/modules.md.

Saída

Tudo é escrito em LOG_DIR (predefinido /sdcard/Download/wifi). O diretório é criado com chmod 700; os ficheiros de saída usam chmod 600.

Caminho	O quê
sar.jsonl	factos por AP, um objeto JSON por linha
cp_audit.log	log de auditoria: AP, método, resultado
report_*.html	relatório de avaliação (descobertas, severidade, evidência)
report_recon_*.html	relatório de levantamento recon passivo
proof/proof_*.conf	prova de uma descoberta confirmada: PIN, PSK, SHA-256, verificação em tempo real
proof/handshake_*.cap	handshake de 4 vias capturado
proof/pmkid_*.22000	PMKID em formato hashcat 22000
proof/eapol_*.pcap	captura EAPOL
known_bssids.txt, processed_bssids.txt	estado (ignorar já feitos)
recon_reported.txt, vuln_reported.txt	estado de de-duplicação de relatórios

Severidades do relatório: Critical / High / Medium / Low. Estados das descobertas: confirmed / potential / beacon-based / config-based. Os segredos são mascarados no corpo do relatório a menos que REVEAL_CREDS=1. Esquema de campos e modelo de relatório: docs/outputs.md.

---

Mapa da documentação