WiFiAngel is an interactive terminal (TUI) application for authorized wireless security work on Linux. It uses Rich for menus and live tables, and orchestrates common Wi‑Fi and lab tools: aircrack-ng, hcxdumptool / hcxtools, hashcat, hostapd, dnsmasq, bettercap, reaver, and others.

Use only on networks and equipment you own or have explicit written permission to test. Unauthorized interception of networks or traffic is illegal in most jurisdictions.

• Features
• Requirements
• Installation
• Quick start
• Using the application
• Screenshots
• Runtime files and reports
• Repository layout
• Development
• License and disclaimer

All attack flows assume a selected target where applicable. The app asks for legal-use confirmation once at startup instead of repeating per-module confirmations.

Automated lab-style pipeline. Legal-use confirmation is requested once at startup; runtime modules do not repeat legal disclaimers or authorization prompts.

1. Monitor mode via the same adapter path as the main menu (WiFiAdapterManager).
2. Discovery — 60 seconds of airodump-ng with the same live network table used by the main menu scan.
3. Prioritization — scores networks (clients, signal, cipher family, WPS, etc.) and shows a prioritized table.
4. Target selection — comma-separated indices or explicit all; empty or invalid input cancels instead of broadening scope.
5. Parallel assessments — only networks with observed clients; per-network worker runs airodump + hcxdumptool, deauth bursts, 3–5 minute capture window (configurable in code), then aircrack-ng / hashcat as appropriate. Live status panel shows per-target heartbeat.
6. Results table and summary statistics; artifacts under auto_hack_sessions/<timestamp>/ and log append to the session report. Recovered Wi-Fi passphrases are shown in results and can be included in reports, so store outputs securely.

• Logger writes timestamped logs under logs/<timestamp>/ (main, attacks, networks, clients, evil twin, DNS, traffic helpers).
• generate_report() can produce security-oriented HTML output via the reports package.
• MITM runs create logs/mitm/<timestamp>/ (caplets, stdout/stderr, traffic/sensitive logs).

• OS: Linux with a real wireless adapter (not WSL without USB passthrough; VMs need the device passed through).
• Privileges: root (sudo).
• Python: 3.8+ recommended (3.10+ well tested).

pip install -r requirements.txt

Checked at session start (must be on PATH): airmon-ng, airodump-ng, aireplay-ng, hashcat, hcxdumptool.

Commonly required for full feature set:

Example:

sudo apt update
sudo apt install -y aircrack-ng hashcat hcxdumptool hcxtools hostapd dnsmasq macchanger reaver curl iproute2 iptables
# Optional
sudo apt install -y bettercap network-manager

On startup, app.main also runs warn_optional_missing_tools so you see which optional binaries are missing before using specific menus.

git clone <repository-url>
cd wifiangel
pip install -r requirements.txt

From the repository root:

sudo python3 wifiangel.py

The launcher:

1. Verifies root, OS, and Python imports
2. Creates runtime directories (logs, tmp, handshake, auto_hack_sessions)
3. Warns about optional missing tools
4. Shows the welcome banner and main menu

Ctrl+C from the main menu stops an active scan or exits / returns depending on context.

1. Choose adapter at startup (if prompted).
2. 1 — monitor mode (or rely on 2 to auto-enable when scanning).
3. 2 — run scan; press Enter when done reviewing the live table.
4. 3 — pick target AP.
5. 4 — run a specific attack or lab module.

Default paths are defined in config/defaults.py (e.g. wordlists/10-million-password-list-top-1000000.txt, fallback hints to /usr/share/wordlists/rockyou.txt). Dictionary and automated assessment flows prompt or fall back if files are missing.

Controller entrypoint for stateful workflow orchestration: interface bootstrap, monitor-mode transition, airodump-ng scan loop control, target context binding, module dispatch, and graceful lifecycle cleanup.

Offensive workflow dispatcher for handshake/PMKID acquisition pipelines, targeted/broadcast deauth primitives, WPS routines, Evil Twin lab provisioning (hostapd/dnsmasq/NAT), and bettercap-driven MITM telemetry sessions.

Diagnostic and post-capture analysis surface: RF channel interference modeling, multi-source handshake/PMKID validation, SSID/OUI-derived wordlist synthesis, capture integrity checks, WPS exposure scoring, and adaptive channel-hop interval optimization.

python -m pytest

This project is licensed under the GNU General Public License v3.0. See the LICENSE file.

The authors and contributors are not responsible for misuse. You alone are responsible for complying with applicable laws and for obtaining proper authorization before testing any network.