jean-nestor/evil-twin-apAutomated evil twin access point toolkit with traffic capture and real-time monitoring for wireless penetration testing and security research.
A complete, modular, and reproducible evil twin access point setup for defensive security testing, penetration testing, and wireless security research.
FOR EDUCATIONAL AND AUTHORIZED SECURITY TESTING ONLY
This tool is provided for:
ILLEGAL USE IS STRICTLY PROHIBITED. Unauthorized access to computer networks is a crime in most jurisdictions. Users are solely responsible for:
By using this tool, you agree to use it only on networks you own or have explicit written permission to test.
This toolkit creates a rogue wireless access point (evil twin) that mimics a legitimate network. It captures network traffic by creating an identical SSID that clients may automatically connect to, believing it's the legitimate network.
An evil twin is a fraudulent Wi-Fi access point that appears to be legitimate but is set up to eavesdrop on wireless communications. The attack works by positioning a rogue access point near the target network, broadcasting the same SSID, and tricking devices into connecting.
Your wireless adapter MUST support AP (Access Point) mode. Not all wireless cards support this functionality.
These adapters are known to work well and support AP mode:
| Chipset | Model Examples | Features | Price Range |
|---|---|---|---|
| RTL8812AU | Alfa AWUS036ACH, TP-Link Archer T4U | Dual-band (2.4/5GHz), High power, Excellent range | $40-60 |
| RTL8814AU | Alfa AWUS1900, TP-Link Archer T9UH | Quad antenna, AC1900, Long range | $60-80 |
| Atheros AR9271 | TP-Link TL-WN722N v1, Alfa AWUS036NHA | Stable, Well-supported, Budget-friendly | $20-35 |
| MT7612U | Panda PAU0D, Alfa AWUS036ACM | Dual-band, Good compatibility | $35-50 |
| RTL8188EU | Various budget adapters | Basic, 2.4GHz only, Entry-level | $10-20 |
Alfa AWUS036ACH (RTL8812AU)
TP-Link TL-WN722N v1 (Atheros AR9271)
Alfa AWUS036ACM (MT7612U)
Before purchasing, verify the adapter supports AP mode:
# Check if your current adapter supports AP mode
iw list | grep -A 10 "Supported interface modes"
# Look for this in the output:
# * AP
# * monitor
These will be automatically installed by install_dependencies.sh:
hostapd - Creates the access pointdnsmasq - Provides DHCP and DNS servicesiptables - Configures NAT and firewall rulesiproute2 - Network interface configurationwireless-tools - Wireless management utilitiesnet-tools - Network diagnostic toolsiw - Wireless configuration utilitytcpdump - Packet capture utility# Clone the repository
git clone https://github.com/yourusername/evil-twin-ap.git
cd evil-twin-ap
# Install dependencies
sudo ./install_dependencies.sh
# Detect your wireless interfaces
sudo ./detect_interface.sh
# Configure your settings (update interface if needed)
nano hostapd.conf # Change SSID, channel, interface
nano dnsmasq.conf # Adjust DHCP settings, interface
# Start the evil twin
sudo ./start_evil_twin.sh
git clone https://github.com/yourusername/evil-twin-ap.git
cd evil-twin-ap
The installation script automatically detects your Linux distribution and installs required packages:
sudo ./install_dependencies.sh
What it does:
CRITICAL STEP: Before configuring, detect which wireless interface supports AP mode:
sudo ./detect_interface.sh
This script will analyze all wireless interfaces and recommend the best one to use.
Example output:
==========================================
Wireless Interface Detection
==========================================
[INFO] Scanning for wireless interfaces...
[✓] Found 2 wireless interface(s)
═══════════════════════════════════════════
Interface: wlan1
═══════════════════════════════════════════
State: DORMANT
MAC Address: 1a:60:c6:85:87:53
Driver: rtl88XXau
[INFO] Checking capabilities for wlan1...
[✓] Supports AP mode (Access Point) ✓
[✓] Supports Monitor mode ✓
Current Mode: managed
═══════════════════════════════════════════
Interface: wlan0
═══════════════════════════════════════════
State: DOWN
MAC Address: b2:72:bf:bc:31:bd
Driver: iwlwifi
[INFO] Checking capabilities for wlan0...
[✓] Supports AP mode (Access Point) ✓
[✓] Supports Monitor mode ✓
Current Mode: managed
[!] Power management is ON (may cause issues)
==========================================
Summary & Recommendations
==========================================
[✓] Found 2 AP-capable interfaces:
- wlan1
- wlan0
[INFO] Recommendation: Use wlan1 (likely external USB adapter)
[!] wlan0 is usually built-in WiFi - use external adapter if available
[INFO] To update configuration files, run:
sed -i 's/^interface=.*/interface=wlan1/' hostapd.conf
sed -i 's/^interface=.*/interface=wlan1/' dnsmasq.conf
Current Configuration:
hostapd.conf: interface=wlan1
dnsmasq.conf: interface=wlan1
[INFO] After updating, verify with: iw list | grep -A 10 'Supported interface modes'
Key Insights:
If you have multiple interfaces:
After installation and interface detection, verify everything is working:
# Check hostapd
hostapd -v
# Check dnsmasq
dnsmasq -v
# List wireless interfaces
iw dev
# Verify AP mode support (detailed)
iw list | grep -A 10 "Supported interface modes"
# Check current interface configuration
grep "^interface=" hostapd.conf dnsmasq.conf
Edit hostapd.conf to customize your evil twin:
nano hostapd.conf
Key settings to modify:
# Wireless interface (CHANGE to wlan1 if using external USB adapter)
interface=wlan1
# Network name (CHANGE THIS to match target network)
ssid=TestNetwork
# Channel (1-11 for 2.4GHz, 36-165 for 5GHz)
channel=6
# WiFi password
wpa_passphrase=letitrain2
# Country code (affects available channels)
country_code=US
Edit dnsmasq.conf to customize network settings:
nano dnsmasq.conf
Key settings:
# Interface to serve DHCP/DNS (MUST match hostapd.conf)
interface=wlan1
# DHCP range (adjust as needed)
dhcp-range=192.168.99.10,192.168.99.250,12h
# Gateway (this machine)
dhcp-option=3,192.168.99.1
# DNS servers (upstream)
server=8.8.8.8
server=8.8.4.4
Default settings:
sudo ./start_evil_twin.sh
What happens:
Output example:
==========================================
Evil Twin AP - Start Script
==========================================
[INFO] Checking privileges...
[SUCCESS] Running with root privileges
[INFO] Checking dependencies...
[SUCCESS] All dependencies found
[INFO] Discovering internet interface...
[SUCCESS] Internet interface detected: eth0
[INFO] Checking interface wlan1...
[SUCCESS] Interface wlan1 found
...
==========================================
Evil Twin AP Started Successfully!
==========================================
Configuration:
SSID: TestNetwork
Channel: 6
Password: letitrain2
AP IP: 192.168.99.1
Subnet: 192.168.99.0/24
WLAN Interface: wlan1
Internet Interface: eth0
To stop the Evil Twin AP, run:
sudo ./stop_evil_twin.sh
To capture traffic for analysis:
sudo ./capture_traffic.sh
sudo ./capture_traffic.sh -v # verbose mode
sudo ./stop_evil_twin.sh
What happens:
Output example:
==========================================
Evil Twin AP - Stop Script
==========================================
[INFO] Stopping hostapd...
[SUCCESS] hostapd stopped (PID: 12345)
[INFO] Stopping dnsmasq...
[SUCCESS] dnsmasq stopped (PID: 12346)
...
==========================================
Session Statistics
==========================================
Unique clients connected: 3
Last 10 DHCP assignments:
192.168.99.10 - AA:BB:CC:DD:EE:01
192.168.99.11 - AA:BB:CC:DD:EE:02
192.168.99.12 - AA:BB:CC:DD:EE:03
The toolkit includes a comprehensive traffic capture script that saves packet data as PCAP files for analysis:
# Basic capture (continuous until Ctrl+C)
sudo ./capture_traffic.sh
# Capture for specific duration (60 seconds)
sudo ./capture_traffic.sh -d 60
# Capture with verbose output and live statistics
sudo ./capture_traffic.sh -v
# Capture only HTTP/HTTPS traffic
sudo ./capture_traffic.sh -f "tcp port 80 or tcp port 443"
# Capture with custom filename
sudo ./capture_traffic.sh -n my_test_capture
# Capture on specific interface
sudo ./capture_traffic.sh -i wlan1
# Capture with file rotation (50MB files, max 20 files)
sudo ./capture_traffic.sh -s 50 -m 20
-i, --interface <name> Wireless interface to capture (default: wlan0)
-d, --duration <seconds> Capture duration in seconds (default: continuous)
-n, --name <name> Custom capture filename prefix
-f, --filter <filter> BPF capture filter (e.g., "tcp port 80")
-s, --size <MB> Rotate files when size reaches MB (default: 100)
-m, --max-files <num> Maximum number of rotated files (default: 10)
-v, --verbose Show verbose packet statistics
-h, --help Show help message
output/ directoryAll captures are saved in output/ with timestamp-based filenames:
capture_YYYYMMDD_HHMMSS.pcapyourname_YYYYMMDD_HHMMSS.pcap# Open in Wireshark (GUI)
wireshark output/capture_20251018_143215.pcap
# Analyze with tcpdump
tcpdump -r output/capture_20251018_143215.pcap -n
# Filter for specific protocols
tcpdump -r output/capture_20251018_143215.pcap 'tcp port 80'
# Extract HTTP requests
tcpdump -r output/capture_20251018_143215.pcap -A 'tcp port 80'
# Get capture statistics
capinfos output/capture_20251018_143215.pcap
# Use tshark for advanced analysis
tshark -r output/capture_20251018_143215.pcap -Y "http.request"
# HTTP traffic only
sudo ./capture_traffic.sh -f "tcp port 80"
# HTTPS traffic only
sudo ./capture_traffic.sh -f "tcp port 443"
# HTTP and HTTPS
sudo ./capture_traffic.sh -f "tcp port 80 or tcp port 443"
# DNS queries
sudo ./capture_traffic.sh -f "udp port 53"
# Specific IP address
sudo ./capture_traffic.sh -f "host 192.168.99.10"
# Exclude broadcast traffic
sudo ./capture_traffic.sh -f "not broadcast and not multicast"
# Capture only TCP traffic
sudo ./capture_traffic.sh -f "tcp"
The toolkit provides several ways to monitor connected clients:
Automatically updated every 5 seconds:
tail -f logs/connections.log
Example output:
=== Sat Oct 18 14:32:15 EDT 2025 ===
Connected clients:
192.168.99.10 dev wlan1 lladdr aa:bb:cc:dd:ee:01 REACHABLE
192.168.99.11 dev wlan1 lladdr aa:bb:cc:dd:ee:02 STALE
View DHCP leases in real-time:
tail -f logs/dnsmasq.log
Example output:
dnsmasq-dhcp[12346]: DHCPDISCOVER(wlan1) aa:bb:cc:dd:ee:01
dnsmasq-dhcp[12346]: DHCPOFFER(wlan1) 192.168.99.10 aa:bb:cc:dd:ee:01
dnsmasq-dhcp[12346]: DHCPREQUEST(wlan1) 192.168.99.10 aa:bb:cc:dd:ee:01
dnsmasq-dhcp[12346]: DHCPACK(wlan1) 192.168.99.10 aa:bb:cc:dd:ee:01 android-device
Monitor hostapd logs:
tail -f logs/hostapd.log
# List connected clients
sudo iw dev wlan1 station dump
# Show DHCP leases
cat /var/lib/misc/dnsmasq.leases
# Check interface status
ip addr show wlan1
# View active connections
sudo arp -a -i wlan1
Problem: Your wireless adapter isn't detected.
Solutions:
# Check if adapter is connected
lsusb | grep -i wireless
# Check interface name
ip link show
# Try replugging USB adapter
# Check kernel messages
dmesg | tail -20
# Run the detection script
sudo ./detect_interface.sh
Problem: Your adapter doesn't support creating access points.
Solution: You need a different wireless adapter. See Hardware Requirements for recommendations.
Verify support:
iw list | grep -A 10 "Supported interface modes"
# Should show: * AP
Problem: hostapd can't start the access point.
Solutions:
# Check if interface is busy
sudo airmon-ng check kill
# Verify interface is up
sudo ip link set wlan1 up
# Check hostapd config syntax
sudo hostapd -d hostapd.conf
# View detailed logs
cat logs/hostapd.log
# Make sure you're using the right interface
grep "^interface=" hostapd.conf
Problem: NetworkManager is managing the wireless interface.
Solution:
# The start script handles this, but if issues persist:
sudo systemctl stop NetworkManager
sudo systemctl disable NetworkManager # Temporarily
# After testing, re-enable:
sudo systemctl enable NetworkManager
sudo systemctl start NetworkManager
Problem: NAT/routing isn't configured correctly.
Solutions:
# Verify IP forwarding
cat /proc/sys/net/ipv4/ip_forward
# Should output: 1
# Check NAT rules
sudo iptables -t nat -L -v
# Verify internet interface
ip route show default
# Test internet on host
ping -c 3 8.8.8.8
# Check if eth0 has internet
ping -I eth0 -c 3 8.8.8.8
Problem: Not running with sufficient privileges.
Solution:
# Always use sudo
sudo ./start_evil_twin.sh
Problem: Wireless regulations restrict certain channels.
Solutions:
# Check available channels for your country
iw list | grep -A 20 "Frequencies:"
# Edit hostapd.conf and change to available channel
nano hostapd.conf
# Common safe channels: 1, 6, 11 (2.4GHz)
Problem: Port 53 (DNS) is already in use.
Solutions:
# Check what's using port 53
sudo lsof -i :53
# Stop systemd-resolved if running
sudo systemctl stop systemd-resolved
# Or configure dnsmasq to use different port
Problem: Scripts are using wlan0 instead of wlan1 (or vice versa).
Solutions:
# Run interface detection
sudo ./detect_interface.sh
# Update config files to use correct interface
sed -i 's/^interface=.*/interface=wlan1/' hostapd.conf
sed -i 's/^interface=.*/interface=wlan1/' dnsmasq.conf
# Verify changes
grep "^interface=" hostapd.conf dnsmasq.conf
If you encounter issues:
logs/hostapd.log, logs/dnsmasq.logsudo ./detect_interface.shbash -xdmesg and journalctlevil-twin-ap/
│
├── README.md # This file (documentation)
├── LICENSE # License information
│
├── hostapd.conf # Access point configuration
├── dnsmasq.conf # DHCP/DNS server configuration
│
├── install_dependencies.sh # Dependency installer (all distros)
├── detect_interface.sh # Wireless interface detection & verification
├── start_evil_twin.sh # Main start script
├── stop_evil_twin.sh # Cleanup and stop script
├── capture_traffic.sh # Traffic capture script (PCAP)
│
├── .evil_twin.pid # Runtime PID file (created automatically)
├── .capture.pid # Capture PID file (created automatically)
│
├── logs/ # Log directory (created at runtime)
│ ├── hostapd.log # Access point logs
│ ├── dnsmasq.log # DHCP/DNS logs
│ └── connections.log # Client connection tracking
│
└── output/ # Packet capture directory
└── *.pcap # PCAP files from traffic capture
| File | Purpose | Modify? |
|---|---|---|
hostapd.conf | AP settings (SSID, channel, password, interface) | ✅ Yes - customize for your test |
dnsmasq.conf | DHCP/DNS configuration (interface, IP range) | ✅ Yes - adjust network settings |
install_dependencies.sh | Installs required packages | ❌ No - run as-is |
detect_interface.sh | Detects wireless interfaces & AP mode support | ❌ No - run as-is |
start_evil_twin.sh | Starts the evil twin AP | ⚠️ Rarely - only for advanced customization |
stop_evil_twin.sh | Stops and cleans up | ❌ No - run as-is |
capture_traffic.sh | Captures traffic to PCAP files | ⚠️ Use CLI options instead |
logs/*.log | Runtime logs | 📖 Read-only - for monitoring |
output/*.pcap | Captured packet data | 📖 Read-only - for analysis |
This toolkit by design:
To enhance security of your testing:
Organizations can protect against evil twin attacks by:
Contributions are welcome! Please follow these guidelines:
git checkout -b feature/your-feature# Use descriptive function names
configure_network_interface() {
# Clear comments
# Error handling
# Verbose output
}
# Consistent formatting
print_info "Starting process..."
command || print_error "Failed to execute command"
This project is provided for educational and authorized security testing purposes only.
MIT License (see LICENSE file for full text)
Copyright (c) 2025 [Your Name]
Permission is hereby granted for educational and authorized security
testing purposes only...
┌─────────────────────────────────────────────────────────────┐
│ │
│ This tool is provided for EDUCATIONAL PURPOSES ONLY │
│ │
│ Unauthorized access to computer networks is ILLEGAL │
│ │
│ Always obtain written permission before testing │
│ │
│ You are responsible for your actions │
│ │
└─────────────────────────────────────────────────────────────┘
Remember: With great power comes great responsibility. Use this tool ethically, legally, and responsibly.
Happy (Authorized) Testing! 🔐