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](https://www.arduino.cc/en/software)
2. **Install Realtek RTL8720DN Board Support**
   ```bash
   # 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**
   ```ini
   # 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):

```bash
# 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**
   ```bash
   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...
   <20><> 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`:
```cpp
// 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`:
```cpp
// Attack coordination
#define ATTACK_SYNC_DELAY_MS 100
#define DEAUTH_FRAME_COUNT 5
#define BEACON_FLOOD_INTERVAL_MS 100
```

### **BLE Configuration**
```cpp
// 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!**