bw16-research/ResearchSPEC.md

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:

#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:

#include <TensorFlowLite_ESP32.h> // AI target selection
#include <LoRa.h>           // LoRa communication
#include <vector>          // STL containers

PlatformIO Configuration:

[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:

{
  "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.