WiFi Pentesting Framework (WPF)

A comprehensive, modular framework for WiFi penetration testing with a passive-first approach.

🌟 Features

• Modular Architecture: Pluggable modules for different testing scenarios
• Passive-First Approach: Emphasizes passive reconnaissance before active attacks
• Safety Features: Built-in safe mode to prevent accidental network disruption
• Comprehensive Logging: Detailed logging and audit trails
• Multiple Attack Vectors: Handshake capture, PMKID attacks, wordlist management
• Cross-Platform: Works on Linux, macOS, and Windows (with WSL/Bash)

📁 Framework Structure

wifi-pentest-framework/
├─ wpf.sh                      # Main entrypoint (Bash)
├─ wpf.ps1                     # PowerShell wrapper for Windows
├─ lib/                        # Shared libraries
│  ├─ colors.sh               # Color definitions
│  ├─ log.sh                  # Logging utilities
│  ├─ menu.sh                 # Interactive menu system
│  ├─ checks.sh               # System checks and validation
│  └─ utils.sh                # Common utility functions
├─ modules/                    # Core modules
│  ├─ iface.sh                # Interface management (monitor mode, etc.)
│  ├─ scan_passive.sh         # Passive scanning and traffic capture
│  ├─ analyze_pcaps.sh        # PCAP analysis and statistics
│  ├─ handshake_stub.sh       # WPA handshake capture
│  ├─ pmkid_stub.sh           # PMKID capture and processing
│  ├─ wordlist_tools.sh       # Wordlist management and optimization
│  └─ plugin_template.sh      # Template for custom modules
├─ out/                        # Output directory for captures and reports
├─ logs/                       # Log files
└─ .env                        # Configuration file

🚀 Quick Start

Prerequisites

Linux/macOS:

• Bash 4.0+
• Root privileges (for monitor mode and packet capture)
• Network tools: iwconfig, ip, tcpdump

Windows:

• PowerShell 5.1+ or PowerShell Core
• Windows Subsystem for Linux (WSL) or Git for Windows (with Bash)

Recommended Tools:

• aircrack-ng suite
• tshark/wireshark
• hcxtools (for PMKID attacks)
• hashcat (for password cracking)

Installation

1. Clone or download the framework:

   git clone https://github.com/trefeon/wifi-pentest-framework.git wifi-pentest-framework
   cd wifi-pentest-framework

2. Make scripts executable (Linux/macOS):

   chmod +x wpf.sh
   chmod +x modules/*.sh

3. Configure the framework:

   # Edit .env file to customize settings
   nano .env

Usage

Linux/macOS:

# Interactive mode
sudo ./wpf.sh

# With specific interface
sudo ./wpf.sh -i wlan0

# Disable safe mode
sudo ./wpf.sh --no-safe-mode

# Show help
./wpf.sh --help

Windows:

# Interactive mode
.\wpf.ps1

# With arguments
.\wpf.ps1 -Arguments "-i", "wlan0"

📋 Modules Overview

Interface Management (iface.sh)

• Enable/disable monitor mode
• Channel configuration
• MAC address randomization
• Interface state restoration

Passive Scanning (scan_passive.sh)

• Quick scans (30s, 2.4GHz)
• Extended scans (5min, 2.4GHz + 5GHz)
• Targeted scanning
• Channel hopping
• Traffic capture and analysis

PCAP Analysis (analyze_pcaps.sh)

• Wireless network discovery
• Handshake extraction
• Traffic statistics
• Protocol analysis
• Format conversion (CSV, JSON, text)

Handshake Capture (handshake_stub.sh)

• Passive handshake monitoring
• Active deauthentication attacks
• Handshake validation
• Multiple target support

PMKID Capture (pmkid_stub.sh)

• Client-less PMKID attacks
• hcxtools integration
• Hashcat format preparation
• Target validation

Wordlist Tools (wordlist_tools.sh)

• Wordlist optimization
• Length and pattern filtering
• Duplicate removal
• Targeted wordlist generation
• Rule-based mutations

⚙️ Configuration

The framework uses a .env file for configuration. Key settings include:

# Safety and behavior
SAFE_MODE=true                    # Restrict destructive operations
LOG_LEVEL=INFO                    # Logging verbosity
VERBOSE=false                     # Detailed output

# Scanning
SCAN_DURATION=60                  # Default scan time (seconds)
CHANNEL_HOP_INTERVAL=2            # Channel hop interval (seconds)
MAX_CAPTURE_SIZE=100M             # Maximum capture file size

# Attacks
HANDSHAKE_TIMEOUT=300             # Handshake capture timeout
PMKID_TIMEOUT=120                 # PMKID capture timeout
DEAUTH_COUNT=10                   # Deauth packets to send

🔒 Safety Features

Safe Mode (Default: Enabled)

• Prevents accidental network disruption
• Limits deauthentication packet count
• Requires confirmation for destructive operations
• Provides warnings for potentially harmful actions

Logging and Audit

• All operations are logged with timestamps
• Session tracking for forensic analysis
• Error logging for troubleshooting
• Command execution history

Interface Restoration

• Automatic interface state restoration on exit
• MAC address restoration
• Monitor mode cleanup
• Signal handlers for graceful shutdown

🎯 Usage Examples

Basic Network Discovery

# Start framework and navigate to "Passive Scanning" → "Quick scan"
sudo ./wpf.sh

# This performs a 30-second 2.4GHz scan and analyzes results

Handshake Capture

# Navigate to "Handshake Capture" → "Passive handshake capture"
# Enter target BSSID: AA:BB:CC:DD:EE:FF
# Wait for natural handshake or use active attack (if safe mode disabled)

PMKID Attack

# Navigate to "PMKID Capture" → "Client-less PMKID attack"
# Enter target BSSID: AA:BB:CC:DD:EE:FF
# Framework will attempt to capture PMKID for offline cracking

Wordlist Management

# Navigate to "Wordlist Tools" → "Generate targeted wordlist"
# Enter target SSID: "CompanyWiFi"
# Framework generates SSID-based password variations

🛠️ Development

Creating Custom Modules

Use the provided template (modules/plugin_template.sh) to create custom modules:

1. Copy the template:

   cp modules/plugin_template.sh modules/my_module.sh

2. Customize the module metadata and functions

3. Implement your specific functionality in your_main_function()

4. Add the module to the main menu system

Contributing

1. Follow the existing code structure and style
2. Include proper error handling and logging
3. Add input validation for all user inputs
4. Test with both safe mode enabled and disabled
5. Update documentation for new features

📚 Tool Dependencies

Required (Core Functionality)

• bash 4.0+
• iwconfig / iw
• ifconfig / ip
• tcpdump
• ps, grep, awk, sed

Recommended (Enhanced Features)

• aircrack-ng suite: Advanced WiFi tools

  • airodump-ng: Network discovery
  • aireplay-ng: Active attacks
  • aircrack-ng: WEP/WPA cracking

• Wireshark/tshark: Packet analysis

• hcxtools: PMKID attacks and processing

• hashcat: Password cracking

• john: Password cracking with rules

Installation Examples

Ubuntu/Debian:

sudo apt update
sudo apt install aircrack-ng wireshark-common tshark hashcat

CentOS/RHEL:

sudo yum install aircrack-ng wireshark hashcat

macOS (with Homebrew):

brew install aircrack-ng wireshark hashcat

⚠️ Legal Notice

This framework is intended for:

• Authorized penetration testing
• Educational purposes
• Security research on your own networks

Users are responsible for ensuring they have proper authorization before testing any networks. Unauthorized access to computer networks is illegal in most jurisdictions.

🐛 Troubleshooting

Common Issues

1. "No wireless interfaces found"

   • Ensure wireless adapter is connected and recognized
   • Check if drivers support monitor mode
   • Try: iwconfig or ip link show

2. "Permission denied" errors

   • Run with sudo for network operations
   • Check if user is in necessary groups (e.g., netdev)

3. Monitor mode fails

   • Some adapters don't support monitor mode
   • Try different wireless adapter
   • Check for conflicting network managers

4. Tools not found

   • Install missing dependencies
   • Check PATH configuration
   • Some tools may have different names on different systems

Debug Mode

Enable debug mode in .env:

DEBUG_MODE=true
LOG_LEVEL=DEBUG

This provides detailed execution information for troubleshooting.

📄 License

MIT License - see LICENSE file for details

🤝 Support

• Issues: Report bugs and request features via GitHub Issues
• Documentation: Refer to module-specific help sections
• Community: GitHub Discussions and Issues

---

Remember: Always obtain proper authorization before conducting any penetration testing activities.