WIFIjam v2.0 - Professional WiFi Security Testing Tool

A Professional WiFi Security Testing Tool with Modern GUI

🚀 What's New in v2.0

🎨 Modern Web-Based GUI - Beautiful, responsive dashboard with real-time updates
🔌 REST API & WebSocket - Full-featured API for programmatic access
📦 Pip Installable - Install with a single command: pip install wifijam
🖥️ Cross-Platform - Works on Linux, macOS, and Windows
⚡ Real-Time Monitoring - Live network discovery and attack progress
🛠️ Professional Architecture - Clean, modular, production-ready code
📊 Advanced Features - Packet capture, device tracking, advanced attacks
🔒 Security Focused - Proper error handling and permission management
🤖 Automated CI/CD - GitHub Actions workflows with OIDC PyPI publishing
📈 Auto Versioning - Automatic semantic versioning on every push

✨ Features

Core Capabilities

WiFi Network Scanning - Discover nearby networks with detailed information
Monitor Mode Management - Enable/disable monitor mode on compatible adapters
Deauthentication Attacks - Disconnect devices from target networks
2.4GHz & 5GHz Jamming - Disrupt WiFi communications on both bands
Multi-Adapter Support - Detect and manage multiple WiFi adapters
Real-Time Updates - WebSocket-based live data streaming

Advanced Features (NEW in v2.0)

Packet Capture & Analysis - Full packet capture with Scapy integration
WPA Handshake Capture - Capture and export WPA/WPA2 handshakes
Device Tracking - Track and fingerprint connected devices
MAC Vendor Lookup - Identify device manufacturers
Device Type Detection - Classify devices (smartphone, laptop, IoT, etc.)
Signal History - Track signal strength over time
Advanced Attack Types - Evil Twin, Auth Flood, Beacon Flood, Disassociation

User Interface

Web Dashboard - Modern, intuitive web interface
Network Visualization - Interactive network discovery table
Attack Control Panel - Easy-to-use attack configuration
System Monitoring - Real-time system and adapter status
Configuration Management - Persistent settings and preferences
Comprehensive Logging - Detailed logs with filtering and export

Technical Features

Cross-Platform - Linux (primary), macOS (limited), Windows (info only)
Multiple Attack Methods - aireplay-ng, Scapy, custom implementations
Async Architecture - Non-blocking operations with asyncio
RESTful API - Complete API for automation and integration
WebSocket Support - Real-time bidirectional communication
Modular Design - Clean separation of concerns

📋 Requirements

System Requirements

Python 3.8+
Root/Administrator privileges (for monitor mode and attacks)
WiFi adapter with monitor mode support (for attacks)

Linux (Recommended)

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install -y aircrack-ng iw wireless-tools net-tools

# Arch/Manjaro
sudo pacman -S aircrack-ng iw wireless_tools net-tools

# Fedora/RHEL
sudo dnf install aircrack-ng iw wireless-tools net-tools

macOS

# Limited support - scanning only
# Monitor mode and attacks not supported on most hardware
brew install python3

Windows

# Very limited support - network information only
# Requires WSL2 for full functionality
# Install WSL2 and follow Linux instructions

🔧 Installation

Method 1: Pip Install (Recommended)

# Install from PyPI (when published)
pip install wifijam

# Or install from source
git clone https://github.com/AryanVBW/WIFIjam.git
cd WIFIjam
pip install -e .

Method 2: Manual Installation

# Clone repository
git clone https://github.com/AryanVBW/WIFIjam.git
cd WIFIjam

# Install dependencies
pip install -r requirements.txt

# Run directly
python -m wifijam.cli gui

🎯 Usage

GUI Mode (Default)

# Start with GUI (opens browser automatically)
sudo wifijam gui

# Start without opening browser
sudo wifijam gui --no-browser

# Then navigate to: http://localhost:8080

Command Line Interface

# Display system information
wifijam info

# List WiFi adapters
wifijam adapters

# Show configuration
wifijam config --show

# Set configuration
wifijam config --set server.port=8888

# Reset configuration
wifijam config --reset

Python API

from wifijam.api.server import APIServer
from wifijam.core.config import Config

# Create and configure server
config = Config()
config.server.port = 8080

# Start server
server = APIServer(config)
server.run()

📖 Quick Start Guide

1. Check System Compatibility

sudo wifijam info

This will show your system information, capabilities, and dependencies.

2. List WiFi Adapters

sudo wifijam adapters

Verify your WiFi adapter is detected and supports monitor mode.

3. Start the GUI

sudo wifijam gui

The dashboard will open in your default browser.

4. Using the Dashboard

Select Adapter - Choose your WiFi adapter from the configuration
Enable Monitor Mode - Toggle monitor mode (Linux only)
Scan Networks - Start scanning to discover nearby networks
Select Target - Click "Target" on a discovered network
Configure Attack - Choose attack type and parameters
Execute - Start the attack and monitor progress

🏗️ Architecture

wifijam/
├── core/               # Core functionality
│   ├── config.py      # Configuration management
│   ├── logger.py      # Logging system
│   ├── system.py      # System detection
│   └── exceptions.py  # Custom exceptions
├── wifi/              # WiFi operations
│   ├── adapter.py     # Adapter management
│   ├── scanner.py     # Network scanning
│   ├── monitor.py     # Monitor mode
│   └── attack.py      # Attack operations
├── api/               # API server
│   ├── server.py      # Main server
│   ├── websocket.py   # WebSocket manager
│   └── routes.py      # API routes
└── cli.py             # Command-line interface

🔌 API Documentation

REST API Endpoints

System

GET /api/system/info - Get system information
GET /api/system/dependencies - Check dependencies

Adapters

GET /api/adapters - List all adapters
GET /api/adapters/{interface} - Get adapter details
POST /api/adapters/{interface}/select - Select adapter

Monitor Mode

POST /api/monitor/enable - Enable monitor mode
POST /api/monitor/disable - Disable monitor mode
GET /api/monitor/status - Get monitor status

Scanning

POST /api/scan/start - Start network scan
POST /api/scan/stop - Stop scan
GET /api/scan/networks - Get discovered networks
GET /api/scan/status - Get scan status

Attacks

POST /api/attack/start - Start attack
POST /api/attack/stop - Stop attack
GET /api/attack/status - Get attack status

Configuration

GET /api/config - Get configuration
POST /api/config - Update configuration
POST /api/config/reset - Reset configuration

WebSocket Events

Connect to ws://localhost:8080/ws

Server → Client Events:

connected - Connection established
network_discovered - New network found
attack_progress - Attack progress update
monitor_mode - Monitor mode status change
system_event - System event notification

Client → Server Events:

ping - Heartbeat
subscribe - Subscribe to events

🛡️ Security & Legal

⚠️ Important Disclaimer

This tool is for educational and authorized security testing ONLY.

Only use on networks you own or have explicit written permission to test
Unauthorized WiFi jamming/deauthentication is ILLEGAL in most countries
The authors provide NO WARRANTY and are NOT RESPONSIBLE for misuse
Users are solely responsible for compliance with local laws and regulations

Legal Considerations

United States: Violates FCC regulations (47 U.S.C. § 333)
European Union: Violates Radio Equipment Directive
United Kingdom: Violates Wireless Telegraphy Act 2006
Canada: Violates Radiocommunication Act
Australia: Violates Radiocommunications Act 1992

Penalties can include:

Heavy fines (up to $100,000+ USD)
Criminal prosecution
Imprisonment
Civil liability

Ethical Use

✅ Acceptable Use:

Testing your own networks
Authorized penetration testing
Educational research in controlled environments
Security audits with written permission

❌ Unacceptable Use:

Attacking public WiFi networks
Disrupting others' internet access
Unauthorized network testing
Malicious intent

🐛 Troubleshooting

Monitor Mode Issues

# Check if adapter supports monitor mode
iw list | grep -A 10 "Supported interface modes"

# Kill conflicting processes
sudo airmon-ng check kill

# Manually enable monitor mode
sudo ip link set wlan0 down
sudo iw wlan0 set monitor control
sudo ip link set wlan0 up

Permission Errors

# Always run with sudo on Linux
sudo wifijam gui

# Check if running as root
id -u  # Should return 0

No Networks Found

Verify adapter is in monitor mode
Check if adapter supports monitor mode
Ensure there are networks in range
Try increasing scan duration

Dependencies Missing

# Install all dependencies
sudo apt-get install -y aircrack-ng iw wireless-tools

# Verify installation
which airmon-ng airodump-ng aireplay-ng

📚 Documentation

Complete Guides

INSTALLATION.md - Detailed installation instructions
PYPI_PUBLISHING_COMPLETE_GUIDE.md - Complete PyPI setup guide
PYPI_TRUSTED_PUBLISHER_FIX.md - Fix authentication issues
AUTOMATIC_VERSIONING_GUIDE.md - Automatic versioning system
ENHANCEMENT_SUMMARY.md - v2.0 enhancement summary
PHASE1_FEATURES.md - Advanced features documentation
CONTRIBUTING.md - Contribution guidelines
DEPLOYMENT.md - Deployment instructions

Quick Setup

# Run automated setup script
./scripts/setup-pypi-publishing.sh

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'feat: add some amazing feature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👏 Credits & Acknowledgments

Inspired by WIFI Jamming in Python
David Bombal's red python scripts
Scapy - Packet manipulation library
Aircrack-ng - WiFi security tools
The open-source community

📧 Contact

Author: Vivek W (AryanVBW)
Email: admin@aryanvbw.live
GitHub: @AryanVBW
Website: aryanvbw.github.io
Instagram: @Aryan_Technolog1es

FilesExpand file tree

README_NEW.md

Latest commit

History