WiFi Brute Force Tool

A professional Wi-Fi password security testing tool for educational purposes and authorized penetration testing.

⚠️ LEGAL DISCLAIMER

READ THIS CAREFULLY BEFORE USING THIS TOOL

This software is provided for EDUCATIONAL and RESEARCH purposes ONLY. Unauthorized access to computer networks is ILLEGAL and may result in severe civil and criminal penalties.

By using this tool, you explicitly agree that:

✓ You will ONLY use this tool on networks you own or have explicit written permission to test
✓ You understand that unauthorized network access is illegal under federal and state laws
✓ You accept full responsibility for your actions and any consequences
✓ The authors and contributors are NOT liable for any misuse or damage caused by this software

Applicable Laws:

Computer Fraud and Abuse Act (CFAA) - 18 U.S.C. § 1030
Various state computer crime laws
International cybercrime laws

Violators may face:

Criminal prosecution
Heavy fines
Imprisonment
Civil lawsuits

🎯 Features

Network Scanning: Detect and list available WiFi networks with signal strength and security type
Brute Force Testing: Test network security using password lists or generated patterns
Password Generation: Built-in password generators (numeric, alphabetic, alphanumeric, common patterns)
Flexible Configuration: Customizable delays, timeouts, and attempt limits
Detailed Logging: Comprehensive logging to file and console with verbosity control
Progress Tracking: Real-time progress display with ETA calculation
Result Export: Save scan and attack results to files
Professional CLI: Clean, user-friendly command-line interface
Zero Dependencies: Uses only Python standard library

📋 Requirements

Operating System: Windows 10/11
Python: 3.7 or higher
Privileges: Administrator rights (required for WiFi operations)
Tools: Windows netsh command (included in Windows)

🚀 Installation

Method 1: Install from Source (Recommended for Development)

# Clone the repository
git clone https://github.com/mmoobbeeiidat-design/wifi-brute-tool.git
cd wifi-brute-tool

# Install in development mode
pip install -e .

Method 2: Install from PyPI (When Published)

pip install wifi-brute-tool

Method 3: Direct Installation

# Download and install directly
pip install git+https://github.com/mmoobbeeiidat-design/wifi-brute-tool.git

Verify Installation

wifi-brute --version

📖 Usage

Basic Commands

1. Scan for WiFi Networks

# Basic scan
wifi-brute --scan

# Save scan results to file
wifi-brute --scan --output scan_results.txt

# Verbose output
wifi-brute --scan --verbose

2. Brute Force Attack with Wordlist

# Attack using a password wordlist
wifi-brute --attack --target "MyNetwork" --wordlist passwords.txt

# With custom delay and timeout
wifi-brute --attack --target "MyNetwork" --wordlist passwords.txt --delay 2.0 --timeout 15

# Limit maximum attempts
wifi-brute --attack --target "MyNetwork" --wordlist passwords.txt --max-attempts 1000

# Save results
wifi-brute --attack --target "MyNetwork" --wordlist passwords.txt --output results.txt

3. Brute Force Attack with Generated Passwords

# Generate numeric passwords
wifi-brute --attack --target "MyNetwork" --generate numeric --min-length 8 --max-length 10

# Generate alphabetic passwords
wifi-brute --attack --target "MyNetwork" --generate alpha --min-length 6 --max-length 8

# Generate alphanumeric passwords
wifi-brute --attack --target "MyNetwork" --generate alphanumeric --max-passwords 5000

# Generate common password patterns
wifi-brute --attack --target "MyNetwork" --generate common

🔧 Command-Line Options

Main Actions

Option	Description
`-s, --scan`	Scan for available WiFi networks
`-a, --attack`	Perform brute force attack

Network Configuration

Option	Description
`-t, --target SSID`	Target network SSID (required for attack)

Password Source

Option	Description
`-w, --wordlist FILE`	Path to password wordlist file
`-g, --generate TYPE`	Generate passwords: numeric/alpha/alphanumeric/common

Password Generation Options

Option	Description	Default
`--min-length N`	Minimum password length	8
`--max-length N`	Maximum password length	12
`--max-passwords N`	Maximum passwords to generate	10000

Attack Options

Option	Description	Default
`-d, --delay SECONDS`	Delay between attempts	1.0
`--timeout SECONDS`	Connection timeout	10
`--max-attempts N`	Maximum attempts (0 = unlimited)	0

Output Options

Option	Description
`-o, --output FILE`	Save results to file
`-v, --verbose`	Enable verbose output
`--log-file FILE`	Log file path (default: wifi_brute.log)

Other Options

Option	Description
`--version`	Show version and exit
`-h, --help`	Show help message

💡 Examples

Example 1: Complete Security Audit

# Step 1: Scan networks
wifi-brute --scan --output networks.txt --verbose

# Step 2: Test your network with common passwords
wifi-brute --attack --target "MyHomeWiFi" --generate common --output test_results.txt

# Step 3: Review results
cat test_results.txt

Example 2: Custom Wordlist Attack

# Create custom wordlist
echo "password123" > my_wordlist.txt
echo "admin2024" >> my_wordlist.txt
echo "Welcome123" >> my_wordlist.txt

# Run attack
wifi-brute --attack --target "TestNetwork" --wordlist my_wordlist.txt --delay 0.5 --verbose

Example 3: Educational Testing

# Test with limited attempts for demonstration
wifi-brute --attack --target "DemoNetwork" --generate numeric --min-length 4 --max-length 6 --max-attempts 100 --verbose

🐍 Python API Usage

You can also use the tool programmatically in your Python scripts:

from wifi_brute_tool import WiFiScanner, WiFiBruteForcer, PasswordGenerator

# Scan networks
scanner = WiFiScanner()
networks = scanner.scan()
for network in networks:
    print(f"Found: {network['ssid']} - Signal: {network['signal']}")

# Generate passwords
generator = PasswordGenerator()
passwords = generator.generate_common_patterns(max_count=100)

# Perform brute force test
brute_forcer = WiFiBruteForcer(
    ssid="MyNetwork",
    delay=1.0,
    timeout=10,
    verbose=True
)
result = brute_forcer.start(passwords)

if result['success']:
    print(f"Password found: {result['password']}")
else:
    print("Password not found")

📁 Project Structure

wifi-brute-tool/
├── wifi_brute_tool/          # Main package directory
│   ├── __init__.py           # Package initialization
│   ├── __main__.py           # Module entry point
│   ├── cli.py                # Command-line interface
│   ├── scanner.py            # Network scanning module
│   ├── brute_forcer.py       # Brute force engine
│   ├── password_generator.py # Password generation
│   ├── logger.py             # Logging utilities
│   └── config.py             # Configuration management
├── tests/                    # Test suite (optional)
├── docs/                     # Documentation (optional)
├── examples/                 # Example scripts (optional)
├── setup.py                  # Package installation script
├── requirements.txt          # Dependencies (none for core)
├── requirements-dev.txt      # Development dependencies
├── README.md                 # This file
├── LICENSE                   # MIT License
├── .gitignore                # Git ignore rules
└── MANIFEST.in               # Package manifest

🔒 Security Considerations

For Network Owners:

Test Your Network: Use this tool to verify your WiFi password strength
Strong Passwords: Use passwords with 16+ characters, mixed case, numbers, and symbols
WPA3: Upgrade to WPA3 encryption if supported by your router
Regular Updates: Change your WiFi password periodically
Monitor Access: Regularly check connected devices

For Security Researchers:

Get Permission: Always obtain written authorization before testing
Scope Definition: Clearly define the scope of testing
Report Findings: Follow responsible disclosure practices
Document Everything: Keep detailed logs of all testing activities
Respect Privacy: Never access or transmit user data

🛡️ Ethical Guidelines

✓ Acceptable Use

Testing your own WiFi networks
Authorized penetration testing with written consent
Educational research in controlled environments
Security awareness training
Demonstrating vulnerabilities to improve security

✗ Prohibited Use

Accessing networks without authorization
Stealing internet access
Malicious attacks on public or private networks
Distributing obtained passwords
Any illegal activity

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

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

Development Setup

# Clone your fork
git clone https://github.com/mmoobbeeiidat-design/wifi-brute-tool.git
cd wifi-brute-tool

# Install development dependencies
pip install -r requirements-dev.txt

# Install package in editable mode
pip install -e .

# Run tests (when available)
pytest

# Format code
black wifi_brute_tool/
isort wifi_brute_tool/

# Check code quality
flake8 wifi_brute_tool/
pylint wifi_brute_tool/

📝 License

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

MIT License

Copyright (c) 2025 Mohammad Obeidat

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🐛 Troubleshooting

Common Issues

Issue: "netsh command not found"

Solution: Ensure you're running on Windows. The tool requires Windows netsh command.

Issue: "Access denied" errors

Solution: Run the command prompt or terminal as Administrator.

Issue: "No networks found"

Solution: Ensure WiFi adapter is enabled and working. Try netsh wlan show interfaces.

Issue: Connection attempts fail

Solution:
- Verify the target SSID is correct and in range
- Check WiFi adapter is functioning properly
- Ensure network uses WPA2-PSK (WPA3 and Enterprise not supported)

Issue: Slow performance

Solution:
- Increase --delay value to give more time between attempts
- Reduce --max-passwords for password generation
- Use a smaller wordlist

📚 Additional Resources

Learning Materials

Related Tools

Aircrack-ng: Popular WiFi security auditing tool
Hashcat: Advanced password recovery tool
John the Ripper: Password cracking tool
Wireshark: Network protocol analyzer

Legal Resources

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: github.poppy814@passinbox.com

🙏 Acknowledgments

Thanks to the Python community for excellent standard library modules
Inspired by various WiFi security research projects
Built for educational purposes and responsible security testing

⚖️ Final Warning

This tool is a double-edged sword. Use it responsibly, ethically, and legally. The knowledge and power it provides come with great responsibility. Always remember:

"With great power comes great responsibility"

Stay legal. Stay ethical. Stay secure. 🔒

Made with ❤️ for Security Education

Star ⭐ this repo if you find it helpful!

Name		Name	Last commit message	Last commit date
wifi_brute_tool		wifi_brute_tool
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
PACKAGE_SUMMARY.md		PACKAGE_SUMMARY.md
QUICK_START.md		QUICK_START.md
README.md		README.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
setup.py		setup.py

Latest commit

History

Folders and files

Repository files navigation