chore: import local project into Gitea
This commit is contained in:
175
ResearchSPEC.md
Normal file
175
ResearchSPEC.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# WiFiX-Enhanced Research Specification
|
||||
|
||||
## 1. Objective & Scope
|
||||
This project is a **dual-band WiFi deauthentication and evil portal system** designed for wireless penetration testing. It combines an ESP32 for 2.4GHz operations and evil portal hosting with a BW16 module for 5GHz deauthentication attacks, enabling coordinated dual-band security testing.
|
||||
|
||||
## 2. Hardware Requirements
|
||||
|
||||
### **Core Components:**
|
||||
- **ESP32 Development Board** (ESP32-WROOM-32 or equivalent)
|
||||
- **BW16 Module** (Realtek RTL8720DN-based 5GHz WiFi module)
|
||||
- **OLED Display** (SSD1306 128x64 I2C)
|
||||
- **Power Supply** (5V 2A recommended for both devices)
|
||||
|
||||
### **ESP32 Pin Configuration:**
|
||||
```
|
||||
SSD1306_SDA = GPIO 21
|
||||
SSD1306_SCL = GPIO 22
|
||||
BW16_UART_TX = GPIO 17
|
||||
BW16_UART_RX = GPIO 16
|
||||
```
|
||||
|
||||
### **BW16 Pin Configuration:**
|
||||
```
|
||||
ESP32_UART_TX = GPIO 7
|
||||
ESP32_UART_RX = GPIO 8
|
||||
```
|
||||
|
||||
### **Optional Components:**
|
||||
- **LoRa Module** (SX1276) - GPIO 5 (SS), 14 (RST), 2 (DIO0)
|
||||
- **Bluetooth** (Built-in ESP32)
|
||||
- **SPIFFS Storage** (For portal templates and credential storage)
|
||||
|
||||
## 3. Framework/SDK Requirements
|
||||
|
||||
### **ESP32 Framework:**
|
||||
- **Arduino Core for ESP32** (v3.3.1+)
|
||||
- **ESP-IDF Compatibility Layer** for raw 802.11 packet injection
|
||||
|
||||
### **BW16 Framework:**
|
||||
- **Realtek AmebaD SDK** (v3.1.9+)
|
||||
- **WiFi Compatibility Layer** for promiscuous mode operations
|
||||
|
||||
## 4. Libraries & Dependencies
|
||||
|
||||
### **Core Libraries:**
|
||||
```cpp
|
||||
#include <WiFi.h> // ESP32 WiFi
|
||||
#include <WebServer.h> // HTTP server
|
||||
#include <DNSServer.h> // DNS server for captive portal
|
||||
#include <SPIFFS.h> // File system for templates
|
||||
#include <ArduinoJson.h> // JSON communication
|
||||
#include <SSD1306Wire.h> // OLED display
|
||||
#include <BluetoothSerial.h> // Bluetooth attacks
|
||||
```
|
||||
|
||||
### **Advanced Features:**
|
||||
```cpp
|
||||
#include <TensorFlowLite_ESP32.h> // AI target selection
|
||||
#include <LoRa.h> // LoRa communication
|
||||
#include <vector> // STL containers
|
||||
```
|
||||
|
||||
### **PlatformIO Configuration:**
|
||||
```ini
|
||||
[env:esp32]
|
||||
platform = espressif32
|
||||
board = esp32dev
|
||||
framework = arduino
|
||||
monitor_speed = 115200
|
||||
|
||||
[env:bw16]
|
||||
platform = realtek-ameba
|
||||
board = bw16
|
||||
framework = arduino
|
||||
```
|
||||
|
||||
## 5. Communication Protocols
|
||||
|
||||
### **UART Serial Communication:**
|
||||
- **Baud Rate:** 115200
|
||||
- **Protocol:** JSON-based messages
|
||||
- **Message Types:**
|
||||
- `BW16_READY` - Module initialization complete
|
||||
- `DEAUTH_SUCCESS` - Successful 5GHz deauthentication
|
||||
- `start_scan_5ghz` - Initiate 5GHz scanning
|
||||
- `start_deauth` - Begin deauthentication attack
|
||||
|
||||
### **JSON Message Structure:**
|
||||
```json
|
||||
{
|
||||
"type": "DEAUTH_SUCCESS",
|
||||
"data": "{\"target\":\"AA:BB:CC:DD:EE:FF\",\"ssid\":\"TestNetwork\"}"
|
||||
}
|
||||
```
|
||||
|
||||
## 6. Attack Capabilities
|
||||
|
||||
### **5GHz Deauthentication (BW16):**
|
||||
- **Channels:** 36, 40, 44, 48, 149, 153, 157, 161, 165
|
||||
- **Packet Injection:** Raw 802.11 deauth frames
|
||||
- **Burst Mode:** 50 packets per burst, 100ms intervals
|
||||
- **Success Detection:** 10+ successful deauths triggers ESP32
|
||||
|
||||
### **2.4GHz Evil Portal (ESP32):**
|
||||
- **Captive Portal:** DNS hijacking and web server
|
||||
- **Templates:** Corporate, Hotel, Coffee Shop, Airport, Generic
|
||||
- **Credential Harvesting:** Form capture and storage
|
||||
- **AI Integration:** Target selection using machine learning
|
||||
|
||||
### **Additional Attack Vectors:**
|
||||
- **Bluetooth:** SerialBT for additional wireless attacks
|
||||
- **LoRa:** Long-range communication for distributed attacks
|
||||
- **Zigbee:** IoT device targeting (placeholder)
|
||||
|
||||
## 7. Documentation Requirements
|
||||
|
||||
### **Immediate Needs:**
|
||||
1. **Hardware Setup Guide** - Physical wiring and connections
|
||||
2. **Flashing Instructions** - Step-by-step firmware deployment
|
||||
3. **Library Installation** - Dependency management
|
||||
4. **Usage Manual** - Operational procedures and safety
|
||||
|
||||
### **Technical Documentation:**
|
||||
1. **API Documentation** - Communication protocol specs
|
||||
2. **Attack Methodology** - Technical details of deauthentication
|
||||
3. **Security Considerations** - Legal and ethical guidelines
|
||||
|
||||
### **Reference Materials Needed:**
|
||||
1. **ESP32 Datasheets** - Pinouts and capabilities
|
||||
2. **BW16 Technical Reference** - Realtek RTL8720DN documentation
|
||||
3. **802.11 Protocol Specs** - Deauthentication frame structure
|
||||
4. **WiFi Security Standards** - WPA2/WPA3 vulnerabilities
|
||||
|
||||
## 8. Risks & Constraints
|
||||
|
||||
### **Technical Limitations:**
|
||||
- **5GHz Range:** Limited by BW16 antenna design
|
||||
- **Concurrent Operations:** ESP32 handles multiple tasks
|
||||
- **Memory Constraints:** Limited SPIFFS storage for templates
|
||||
- **Power Requirements:** High current draw during attacks
|
||||
|
||||
### **Legal Considerations:**
|
||||
- **Authorization Required:** Only test on owned networks
|
||||
- **Regulatory Compliance:** FCC/CE regulations for radio transmission
|
||||
- **Ethical Guidelines:** Responsible disclosure principles
|
||||
|
||||
### **Security Risks:**
|
||||
- **Credential Storage:** Encrypted storage required
|
||||
- **Network Exposure:** Isolated testing environment recommended
|
||||
- **Firmware Integrity:** Signed updates to prevent tampering
|
||||
|
||||
## 9. Development Tools
|
||||
|
||||
### **Required Software:**
|
||||
- **Arduino IDE** or **PlatformIO**
|
||||
- **ESP32 Board Package** (v3.3.1+)
|
||||
- **Realtek AmebaD Board Package** (v3.1.9+)
|
||||
- **Python 3.8+** (for optional AI components)
|
||||
|
||||
### **Testing Equipment:**
|
||||
- **WiFi Analyzer** - For attack verification
|
||||
- **Spectrum Analyzer** - Optional for RF analysis
|
||||
- **Isolated Test Network** - Safety and compliance
|
||||
|
||||
## 10. Glossary
|
||||
|
||||
- **BSSID** - Basic Service Set Identifier (MAC address of AP)
|
||||
- **Deauthentication** - 802.11 management frame forcing disconnection
|
||||
- **Evil Twin** - Rogue access point mimicking legitimate network
|
||||
- **Promiscuous Mode** - WiFi interface capturing all traffic
|
||||
- **SPIFFS** - SPI Flash File System for ESP32
|
||||
|
||||
---
|
||||
|
||||
*This documentation serves as the foundation for understanding, deploying, and operating the WiFiX-Enhanced penetration testing system. All operations must comply with local laws and regulations.*
|
||||
Reference in New Issue
Block a user