175 lines
5.8 KiB
Markdown
175 lines
5.8 KiB
Markdown
# WiFiX-Enhanced
|
|
|
|
A professional-grade WiFi captive portal system for security research and testing, featuring realistic web interfaces, credential collection, and advanced deauthentication capabilities.
|
|
|
|
## 🎯 Features
|
|
|
|
### Core Capabilities
|
|
- **Dual-Module Architecture**: ESP32 + BW16 for maximum performance
|
|
- **Realistic Web Portals**: Professional municipal WiFi interface
|
|
- **Credential Collection**: Secure storage with encryption and SD backup
|
|
- **5GHz Deauthentication**: Targeted disconnection of modern devices
|
|
- **OLED Display**: Real-time status and credential monitoring
|
|
- **Auto-Backup**: Automatic credential backup to SD card
|
|
- **Multiple Authentication Types**: Generic, Hotel, Corporate, Public, Social
|
|
|
|
### Technical Specifications
|
|
- **ESP32 Framework**: Arduino Core with PlatformIO
|
|
- **BW16 Module**: Realtek RTL8720DN (5GHz capable)
|
|
- **Storage**: SPIFFS + SD card support
|
|
- **Display**: 128x64 I2C OLED (SSD1306)
|
|
- **Web Interface**: Responsive HTML5 with JavaScript
|
|
- **Security**: AES encryption for stored credentials
|
|
|
|
## 📚 Documentation
|
|
|
|
### Quick Start
|
|
- [Quick Start Guide](QUICK_START.md) - Get running in 5 minutes
|
|
- [Flashing Guide](FLASHING_GUIDE.md) - Comprehensive setup instructions
|
|
- [Configuration Template](src/config_template.h) - All settings explained
|
|
- [Pin Chart & Wiring](PIN_CHART.md) - Complete connection guide
|
|
- [Wiring Diagram](WIRING_DIAGRAM.md) - Visual assembly guide
|
|
- [Pin Reference Card](PIN_REFERENCE_CARD.md) - Quick reference
|
|
|
|
### Hardware Setup
|
|
- **Pin Connections**: See FLASHING_GUIDE.md for detailed wiring
|
|
- **Power Requirements**: 5V 2A minimum
|
|
- **Antennas**: External recommended for range
|
|
|
|
### Software Requirements
|
|
- **PlatformIO Core** (recommended) or Arduino IDE
|
|
- **USB Drivers**: CP2102/CH340 for ESP32, RTL8720DN for BW16
|
|
- **Python 3.8+** for PlatformIO
|
|
|
|
## ⚡ Quick Flash (Windows)
|
|
|
|
```powershell
|
|
# One-time setup
|
|
pip install platformio
|
|
|
|
# Flash everything
|
|
flash_windows.bat
|
|
# Select option 4: "Flash All (ESP32 + Web Files)"
|
|
```
|
|
|
|
Or manually:
|
|
```powershell
|
|
# Flash ESP32
|
|
pio run -e esp32_main --target upload
|
|
|
|
# Upload web files
|
|
pio run -e esp32_main --target uploadfs
|
|
|
|
# Flash BW16
|
|
pio run -e bw16_deauth --target upload
|
|
```
|
|
|
|
## 🔧 Configuration
|
|
|
|
1. Copy `src/config_template.h` to `src/config.h`
|
|
2. Modify settings as needed:
|
|
- Network SSID and passwords
|
|
- Hardware pin assignments
|
|
- Feature toggles
|
|
- Security settings
|
|
|
|
## 📱 Usage
|
|
|
|
### Connection Process
|
|
1. Power on device (both modules)
|
|
2. Connect to "CityNet_Public_WiFi" network
|
|
3. Browser auto-opens to captive portal
|
|
4. Enter credentials on realistic login page
|
|
5. View captured data on OLED display
|
|
|
|
### Serial Console Commands (115200 baud)
|
|
```
|
|
help # Show available commands
|
|
status # System status
|
|
creds # List captured credentials
|
|
clearcreds # Clear credential storage
|
|
backup # Manual backup to SD
|
|
deauth [MAC] # Target specific device
|
|
reset # Factory reset
|
|
```
|
|
|
|
## 🛡️ Safety & Legal
|
|
|
|
**IMPORTANT**: This tool is for authorized security testing only!
|
|
|
|
- Use only on networks you own or have explicit permission to test
|
|
- Follow all applicable laws and regulations
|
|
- Respect privacy and data protection requirements
|
|
- Delete captured credentials after analysis
|
|
- Document your testing procedures
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
WiFiX-Enhanced/
|
|
├── data/ # Web interface files
|
|
│ ├── index.html # Login portal
|
|
│ └── welcome.html # Success page
|
|
├── src/ # Source code
|
|
│ ├── esp32_enhanced.ino # Main ESP32 firmware
|
|
│ ├── bw16_5ghz_deauth.ino # BW16 deauth firmware
|
|
│ ├── credential_manager.cpp # Credential handling
|
|
│ ├── credential_manager.h
|
|
│ ├── oled_display.cpp # OLED interface
|
|
│ └── oled_display.h
|
|
├── platformio.ini # Build configuration
|
|
├── FLASHING_GUIDE.md # Detailed setup guide
|
|
├── QUICK_START.md # Rapid deployment guide
|
|
└── flash_windows.bat # Windows flashing script
|
|
```
|
|
|
|
## 🚀 Advanced Features
|
|
|
|
### Credential Management
|
|
- Encrypted storage with AES-256
|
|
- Automatic SD card backup
|
|
- Multiple credential types (Generic, Hotel, Corporate, Public, Social)
|
|
- Real-time statistics on OLED
|
|
- CSV export capability
|
|
|
|
### Web Interface
|
|
- Professional municipal WiFi branding
|
|
- Responsive design for all devices
|
|
- Real-time connection status
|
|
- Session management with countdown timer
|
|
- Social login simulation
|
|
|
|
### Deauthentication
|
|
- Targeted 5GHz deauth attacks
|
|
- Channel hopping for maximum coverage
|
|
- Whitelist support for protected devices
|
|
- Configurable attack intervals
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Common Issues
|
|
- **Port not found**: Install USB drivers, check Device Manager
|
|
- **Upload timeout**: Hold BOOT button during upload
|
|
- **No WiFi**: Check antenna connections, verify BW16 power
|
|
- **Portal won't load**: Clear browser cache, try different browser
|
|
|
|
See [FLASHING_GUIDE.md](FLASHING_GUIDE.md) for detailed troubleshooting.
|
|
|
|
## 🤝 Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create feature branch
|
|
3. Test thoroughly on hardware
|
|
4. Submit pull request with documentation
|
|
|
|
## 📄 License
|
|
|
|
This project is for educational and authorized security testing purposes only. Users are responsible for complying with all applicable laws and regulations.
|
|
|
|
## ⚠️ Disclaimer
|
|
|
|
This tool is provided as-is for legitimate security research and testing. The authors are not responsible for misuse or any damages resulting from use of this software. Always obtain proper authorization before testing any network.
|
|
|
|
---
|
|
|
|
**Remember**: With great power comes great responsibility. Use ethically and legally. |