xc xc
This commit is contained in:
337
README.md
Normal file
337
README.md
Normal file
@@ -0,0 +1,337 @@
|
||||
# 🔥 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!**
|
||||
Reference in New Issue
Block a user