evil-bw16-orchestrator/README.md

🔥 Evil-BW16 Advanced Orchestrator v2.1

⚠️ LEGAL DISCLAIMER

This project is for EDUCATIONAL PURPOSES and AUTHORIZED SECURITY TESTING ONLY. Using this software against networks without explicit permission is ILLEGAL and may violate local laws. Users are solely responsible for compliance with applicable laws and regulations.

📖 Project Overview

Evil-BW16 is an advanced wireless security testing framework designed for the RTL8720DN (BW16) dual-band WiFi platform. It enables sophisticated penetration testing through distributed attacks, evil portal deployment, and comprehensive network reconnaissance.

🏗️ Architecture

• Master Device: Hosts web interface on 2.4GHz and evil portal on 5GHz
• Slave Devices: Execute distributed attacks coordinated by the master
• Communication: BLE (Bluetooth Low Energy) mesh network
• Attacks: Beacon flooding, deauthentication, karma attacks, probe flooding
• Portal: Captive portal for credential harvesting

🛠️ Hardware Requirements

Required Components

• 1x RTL8720DN (BW16) Development Board - Master device
• 2-8x RTL8720DN (BW16) Development Boards - Slave devices
• USB-C cables for programming and power
• Computer with Arduino IDE or PlatformIO

Recommended Components

• Breadboards for prototyping
• Jumper wires for connections
• LED indicators for status monitoring
• Power supply for extended operation

🚀 Installation & Setup Guide

Step 1: Development Environment Setup

Option A: Arduino IDE (Recommended)

1. Download Arduino IDE 2.x from arduino.cc
2. Install Realtek RTL8720DN Board Support

   # In Arduino IDE: File > Preferences > Additional Board Manager URLs
   # Add: https://github.com/ambiot/ambd_arduino/raw/master/Arduino_package/package_realtek.com_amebad_index.json
   

3. Install Board Package
   • Tools > Board > Boards Manager
   • Search "Realtek RTL8720DN"
   • Install "Realtek RTL8720DN by Realtek"

Option B: PlatformIO (Advanced)

1. Install PlatformIO in VS Code
2. Add Realtek Platform

   # platformio.ini
   [env:rtl8720dn]
   platform = https://github.com/ambiot/ambd_arduino.git
   board = rtl8720dn
   framework = arduino
   

Step 2: Required Libraries

Install these libraries in Arduino IDE (Tools > Manage Libraries):

# Core Libraries
- "ArduinoJson" by Benoit Blanchon (v6.x)
- "WiFi" (included with board)
- "BLEDevice" (included with board)
- "WebServer" (included with board)

# Optional Libraries (for filesystem support)
- "SPIFFS" by me-no-dev (for filesystem serving)
- "LittleFS" by lorol (alternative filesystem)

Step 3: Project Structure Setup

1. Clone/Download Project

   git clone <repository-url>
   cd evil-bw16
   

2. Verify Project Structure

   evil-bw16/
   ├── master/
   │   ├── master.ino              # Master firmware
   │   ├── Evil-BW16/
   │   │   └── BW16_defs.h         # Shared definitions
   │   └── filesystem_setup.md     # Filesystem guide
   ├── slave/
   │   └── slave.ino               # Slave firmware
   ├── data/
   │   ├── web_ui/
   │   │   └── index.html          # Web interface
   │   └── evil_portal.html        # Portal page
   └── README.md                   # This file
   

🔧 Firmware Flashing Instructions

Master Device Setup

1. Connect Master Device

   • Connect RTL8720DN board via USB-C
   • Ensure proper drivers are installed

2. Configure Arduino IDE

   Board: "RTL8720DN"
   Upload Speed: "921600"
   Port: [Select your device port]
   

3. Open Master Firmware

   • Open master/master.ino in Arduino IDE
   • Verify all includes are resolved

4. Compile & Upload

   • Click "Verify" to compile
   • Click "Upload" to flash firmware
   • Wait for upload completion

5. Verify Upload

   • Open Serial Monitor (115200 baud)
   • You should see initialization messages:

   🔥 Evil-BW16 Master Starting...
   <0A><> WiFi AP: Evil-BW16-Master
   🔗 BLE Scanner Active
   🌐 Web Server: http://192.168.1.1
   

Slave Device Setup

1. Prepare Slave Devices

   • Connect each RTL8720DN slave board
   • Use different USB ports or flash one at a time

2. Configure for Slave Role

   • Open slave/slave.ino in Arduino IDE
   • Ensure ROLE_MASTER is NOT defined (it's commented out)

3. Flash Each Slave

   • Upload slave/slave.ino to each slave device
   • Verify upload with Serial Monitor
   • Expected output:

   🔥 Evil-BW16 Slave Starting...
   📡 BLE Service: EVIL1234-5678-9ABC-DEF0-123456789ABC
   🔗 Waiting for master connection...
   

4. Label Your Devices

   • Mark one device as "MASTER"
   • Mark others as "SLAVE 1", "SLAVE 2", etc.

🌐 Network Configuration

Default Network Settings

Master AP (2.4GHz):
- SSID: "Evil-BW16-Master"
- Password: "master123"
- IP: 192.168.1.1

Portal AP (5GHz):
- SSID: "Free WiFi" (configurable)
- Password: (open)
- IP: 192.168.5.1

Customizing Network Settings

Edit master/Evil-BW16/BW16_defs.h:

// Web server credentials (master only)
#define AP_SSID   "YourCustomSSID"
#define AP_PASS   "YourCustomPassword"

// 5GHz Portal credentials
#define PORTAL_DEFAULT_SSID "YourPortalSSID"
#define PORTAL_IP "192.168.5.1"

🎯 First-Time Setup & Testing

Step 1: Power Up Devices

1. Power Master Device

   • Connect via USB or external power
   • Wait for initialization (30-60 seconds)

2. Power Slave Devices

   • Power up each slave device
   • Wait for BLE service to start

Step 2: Connect to Master

1. Connect to WiFi

   • Find "Evil-BW16-Master" network
   • Connect with password "master123"

2. Access Web Interface

   • Open browser to http://192.168.1.1
   • You should see the advanced dashboard

Step 3: Verify Slave Connections

1. Check Slave Status

   • Go to "Slaves" tab in web interface
   • Verify all slaves are connected
   • Check signal strength and status

2. Test Communication

   • Send a test command to slaves
   • Verify responses in logs

📁 Web Interface Deployment

Current Implementation (Ready to Use)

• The web interface is already embedded in the firmware
• No filesystem setup required - works immediately
• Access the advanced web interface at http://192.168.1.1

Filesystem Deployment (Optional)

• For production use, you can serve files from the device's filesystem
• See master/filesystem_setup.md for detailed instructions
• Options: SPIFFS, LittleFS, or SD card storage
• Copy data/web_ui/ contents to the device's filesystem

🚀 Usage Guide

Basic Operation

1. Power all devices
2. Connect to master WiFi
3. Access web interface
4. Configure attack parameters
5. Launch coordinated attacks

Advanced Features

• Real-time monitoring with live charts
• Distributed attacks across multiple slaves
• Credential harvesting via evil portal
• Network reconnaissance and AP cloning
• Comprehensive logging and analytics

🔧 Troubleshooting

Common Issues

Master Won't Connect to Slaves

• Verify BLE is enabled on all devices
• Check slave firmware is uploaded correctly
• Ensure ROLE_MASTER is defined in master only
• Check Serial Monitor for BLE errors

Web Interface Not Loading

• Verify WiFi connection to master
• Check IP address: http://192.168.1.1
• Clear browser cache
• Try different browser

Upload Failures

• Check USB cable and port
• Verify board selection in Arduino IDE
• Try different upload speed
• Reset device before upload

Memory Issues

• Reduce number of slaves (max 8)
• Clear logs periodically
• Restart devices if needed

Debug Information

• Serial Monitor: 115200 baud for debugging
• Web Logs: Check "Logs" tab in web interface
• BLE Status: Monitor connection status in "Slaves" tab

📊 Performance Optimization

Memory Management

• Monitor heap usage in web interface
• Restart devices if memory gets low
• Use fewer slaves for extended operation

Network Optimization

• Position slaves strategically for coverage
• Monitor signal strength in web interface
• Adjust attack intensity based on targets

🔒 Security Considerations

Network Security

• Change default passwords
• Use strong encryption for sensitive operations
• Monitor for unauthorized access

Legal Compliance

• Only test on networks you own or have permission
• Document all testing activities
• Follow local regulations and laws

📚 Advanced Configuration

Custom Attack Parameters

Edit attack settings in BW16_defs.h:

// Attack coordination
#define ATTACK_SYNC_DELAY_MS 100
#define DEAUTH_FRAME_COUNT 5
#define BEACON_FLOOD_INTERVAL_MS 100

BLE Configuration

// BLE connection parameters
#define BLE_SCAN_TIMEOUT_MS 10000
#define BLE_RECONNECT_INTERVAL_MS 30000
#define BLE_CONNECTION_TIMEOUT_MS 5000

🤝 Support & Community

Getting Help

• Check troubleshooting section above
• Review Serial Monitor output
• Verify all connections and configurations

Contributing

• Report bugs with detailed information
• Suggest improvements and features
• Share your testing experiences

📄 License

This project is provided as-is for educational purposes. Use responsibly and in compliance with local laws.

---

🎉 Your Evil-BW16 Advanced Orchestrator is now ready for authorized security testing!