Skip to content

Emfinity-Interactive/Python-Phishing-URL-Detector

BranchesTags

Repository files navigation

Phishing URL Detector

A comprehensive Python application that detects potentially dangerous phishing URLs through multiple security checks. Available in both terminal and GUI versions.

Features

  • Real-time Online Database Updates: Fetches latest phishing domains from PhishTank and OpenPhish
  • Built-in Phishing Database: Contains a curated list of known phishing domains (20+ domains)
  • URL Parsing: Accurately extracts and validates domain information
  • Multi-layer Security Checks:
    • Real-time online phishing database checking
    • Known phishing domain detection
    • Suspicious character analysis (@ symbols, consecutive dots/dashes)
    • HTTPS verification
    • Domain reputation checking
  • Risk Assessment: Categorizes threats as SAFE, LOW, MEDIUM, or HIGH risk
  • User-Friendly Interface: Available in both command-line and GUI versions
  • Offline Fallback: Works without internet connection using local database
  • Error Handling: Gracefully handles malformed URLs and network errors
  • Cross-Platform: Works on Windows, macOS, and Linux
  • Flake8 Compliant: Code follows PEP 8 standards and best practices

Installation

No additional packages required! This application uses only Python standard libraries.

User Guide

🎯 For Complete Beginners

  1. Download/Clone this project to your computer
  2. Find the folder on your computer
  3. Double-click the Start_GUI.bat file
  4. Type any URL in the text box (e.g., google.com)
  5. Click "Check URL" or press Enter
  6. Read the results - green = safe, red = dangerous!

🔧 For Advanced Users

# Terminal version with online database updates
python phishing_detector.py

# GUI version
python phishing_detector_gui.py

# Run all tests
python test_phishing_detector.py

# Check code quality
flake8 *.py

📝 Example Usage

Safe URL Test:

Input: https://www.google.com
Result: ✅ SAFE (Green)
Details: Using HTTPS, legitimate domain, no suspicious features

Dangerous URL Test:

Input: paypal-security.com
Result: ❌ DANGEROUS (Red)  
Details: Known phishing domain, avoid this site!

Code Structure

  • Python 3.6 or higher
  • Standard Python libraries: urllib.parse, re, tkinter

Clone the Repository

git clone https://github.com/yourusername/python-phishing-url-detector.git
cd python-phishing-url-detector

Quick Start

🖱️ Super Easy Launch (Windows)

Three ways to instantly start the application:

  1. Double-click Start_GUI.bat - Instantly opens the graphical interface ⚡
  2. Double-click phishing_detector_gui.py - Direct GUI launch (if Python is associated)
  3. Double-click phishing_detector.py - Terminal version with interactive mode

🚀 One-Click Setup

If Python files don't open automatically:

  • Right-click → Run as Administrator → setup_python_association.bat
  • This will associate .py files with Python for easy double-clicking

Windows Command Line

# Run terminal version
run.bat run-terminal

# Run GUI version  
run.bat run-gui

# Run tests
run.bat test

# Show help
run.bat help

Unix/Linux/macOS Users

# Run terminal version
make run-terminal
# or
python phishing_detector.py

# Run GUI version
make run-gui
# or 
python phishing_detector_gui.py

# Run tests
make test

# Show help
make help

Usage

Terminal Version

Run the command-line version:

python phishing_detector.py

Features:

  • Interactive URL input with online/offline mode selection
  • Real-time phishing database updates from PhishTank and OpenPhish
  • Detailed analysis reports with risk assessment
  • Special commands:
    • update - Force database update
    • stats - Show database statistics
    • q, quit, exit - Exit application
  • Continuous operation until user exits
  • Automatic database refresh (every hour when online)

GUI Version

🖱️ Easy Start: Double-click Start_GUI.bat file

Or run manually:

python phishing_detector_gui.py

Features:

  • One-click launch with Start_GUI.bat file
  • User-friendly graphical interface with modern design
  • Real-time URL analysis with instant results
  • Color-coded results:
    • 🟢 Green = Safe/Low risk
    • 🟡 Orange = Medium risk warnings
    • 🔴 Red = High risk/Dangerous
  • Detailed analysis reports with security recommendations
  • Enter key support - Type URL and press Enter
  • Clear and About functionality
  • Resizable window with professional layout
  • Copy-paste friendly URL input

Online Features

Real-time Database Updates

The application can fetch the latest phishing domains from trusted sources:

  • PhishTank API: Access to 26,000+ verified phishing URLs
  • OpenPhish Feed: Community-maintained phishing database
  • Automatic Updates: Database refreshes every hour when online mode is enabled
  • Fallback Mode: Works offline using local database if internet is unavailable

Usage Options

# Enable online features (recommended)
🌐 Enable online phishing database updates? (y/N): y

# Disable online features (offline mode)
🌐 Enable online phishing database updates? (y/N): n

Special Commands

  • update - Force immediate database update
  • stats - Show database statistics and last update time

How It Works

Detection Methods

  1. Real-time Online Database Check: Fetches latest phishing domains from:
    • PhishTank API (26,000+ domains)
    • OpenPhish feed (updated regularly)
  2. Known Phishing Domain Check: Compares against local database of known phishing sites
  3. Suspicious Character Detection: Identifies potentially malicious characters:
    • @ symbols (often used to hide real domains)
    • Consecutive dots .. (directory traversal attempts)
    • Multiple dashes -- or underscores __ (domain spoofing)
  4. HTTPS Verification: Ensures the connection uses secure encryption
  5. URL Validation: Checks for proper URL format and structure
  6. Domain Reputation Check: Verifies if domain resolves and is active

Risk Assessment

  • HIGH Risk: Known phishing domain in online databases + other suspicious features
  • MEDIUM Risk: Some suspicious characteristics detected
  • LOW Risk: Minor issues found (e.g., no HTTPS)
  • SAFE: No suspicious features detected, passes all checks

Examples

Safe URL (Online Mode)

🔍 Checking: https://www.google.com
Result: ✅ SAFE
Risk Level: SAFE
Domain: www.google.com
Scheme: HTTPS
Details: 
  1. ✅ Domain is active and resolves
  2. ✅ Using secure HTTPS connection
  3. ✅ No suspicious features detected

Suspicious URL (Real-time Detection)

🔍 Checking: http://[email protected]
Result: ❌ SUSPICIOUS/DANGEROUS
Risk Level: HIGH
Domain: malicious-site.com
Scheme: HTTP
Details: 
  1. ⚠️ 'malicious-site.com' found in updated phishing database
  2. ⚠️ Suspicious character '@' found
  3. ⚠️ Not using secure HTTPS connection
💡 Recommendation: DO NOT VISIT - This appears to be a phishing site

Database Statistics

📊 Phishing Detector Statistics
----------------------------------------
Total phishing domains: 27,060
Online checking: Enabled
Last update: 2025-07-29 14:30:15
Time since update: 0:15:23
Suspicious characters checked: ['@', '..', '--', '__']
----------------------------------------

Project Structure

📁 Python Phishing URL Detector/
├── 🖱️ Start_GUI.bat              # ← CLICK THIS! Opens GUI instantly
├── 🐍 phishing_detector.py       # Terminal version with online features
├── 🖼️ phishing_detector_gui.py   # GUI version (user-friendly)
├── 🧪 test_phishing_detector.py   # Comprehensive test suite
├── ⚙️ setup_python_association.bat # Python file association setup
├── 🎨 create_icon.ps1            # Icon generator script
├── 📋 README.md                  # This documentation
├── 📦 requirements.txt           # Python dependencies (none needed!)
├── 🔧 setup.py                   # Package setup
├── 📝 pyproject.toml             # Modern Python packaging
├── 🏗️ Makefile                   # Unix build commands
├── 🪟 run.bat                    # Windows batch commands
├── ✅ .flake8                    # Code quality configuration
└── 📊 FLAKE8_COMPLIANCE.md       # Code quality report

Key Files for Users:

  • Start_GUI.bat - The easiest way to launch the application
  • phishing_detector_gui.py - Graphical interface
  • phishing_detector.py - Terminal interface with advanced features

Terminal Version (phishing_detector.py)

  • PhishingDetector: Main detection class with online capabilities
  • update_phishing_database(): Real-time database updates
  • _fetch_from_source(): Online data fetching from APIs
  • handle_special_commands(): Command processing (update, stats)
  • setup_detector(): Initialize detector with user preferences
  • process_url_analysis(): URL analysis and result display
  • print_banner(): Application header
  • main(): Application entry point (modular design)

GUI Version (phishing_detector_gui.py)

  • PhishingDetector: Core detection logic (same as terminal)
  • PhishingDetectorGUI: Tkinter-based interface
  • Color-coded results and detailed reporting
  • About dialog and help functionality

Customization

Adding New Phishing Domains

Edit the known_phishing_domains set in the PhishingDetector class:

self.known_phishing_domains = {
    'paypal-security.com',
    'amazon-security.org',
    'your-new-domain.com',  # Add new domains here
    # ... more domains
}

Modifying Suspicious Characters

Update the suspicious_characters list:

self.suspicious_characters = ['@', '..', '--', '__', 'new-char']

Adjusting Risk Levels

Modify the risk calculation in the analyze_url() method:

if risk_factors >= 3:
    risk_level = 'HIGH'
elif risk_factors >= 1:
    risk_level = 'MEDIUM'
else:
    risk_level = 'LOW'

Troubleshooting

🐛 Common Issues & Solutions

Problem: "Python files won't open when I double-click"

  • Solution: Right-click setup_python_association.bat → Run as Administrator
  • This will associate Python files with the Python interpreter

Problem: "Start_GUI.bat doesn't work"

  • Solution: Make sure Python is installed and in your PATH
  • Test: Open Command Prompt → Type python --version
  • If not found, reinstall Python and check "Add Python to PATH"

Problem: "GUI window appears but crashes"

  • Solution: Your Python installation may be missing tkinter
  • Fix: Reinstall Python with "tcl/tk and IDLE" option checked

Problem: "Online features don't work"

  • Solution: Check your internet connection
  • The app works offline too, just with limited phishing database

Problem: "False positives in detection"

  • Solution: This tool is conservative for safety
  • Always verify suspicious results manually
  • Report issues on GitHub for database improvements

🔧 System Requirements

  • Windows 7/10/11 (primary support)
  • macOS/Linux (should work but untested with .bat files)
  • Python 3.6+ (with tkinter for GUI)
  • Internet connection (optional, for online database updates)

Security Considerations

This tool provides guidance but should not be the only line of defense:

  • Always verify suspicious URLs through official channels
  • Never enter credentials on suspicious websites
  • Keep browsers updated with latest security patches
  • Use additional security tools like antivirus and firewalls
  • Be cautious with shortened URLs and email links

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Contribution Ideas

  • Expand the phishing domain database
  • Add more sophisticated detection algorithms
  • Implement machine learning-based detection
  • Add support for checking multiple URLs at once
  • Create a web-based version

License

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

Disclaimer

This tool is for educational and security awareness purposes. While it implements several detection methods, it may not catch all phishing attempts. Users should always exercise caution when visiting unfamiliar websites and never enter sensitive information on suspicious sites.

Future Enhancements

  • ✅ Real-time online phishing database integration
  • ✅ Advanced modular code structure
  • ✅ Flake8 compliance and code quality
  • ✅ One-click GUI launcher (Start_GUI.bat)
  • ✅ User-friendly installation process
  • ✅ Comprehensive documentation with examples
  • ⏳ Machine learning-based URL analysis
  • ⏳ Browser extension version
  • ⏳ Batch URL processing (check multiple URLs)
  • ⏳ Integration with VirusTotal API
  • ⏳ Email scanning capabilities
  • ⏳ Custom blacklist/whitelist management
  • ⏳ REST API version for developers
  • ⏳ Docker containerization
  • ⏳ Mobile app version

Support

If you encounter any issues or have questions:

  1. Check the existing issues in the repository
  2. Create a new issue with detailed description
  3. Include error messages and system information
  4. Provide steps to reproduce the problem

Acknowledgments

  • Python Software Foundation for the excellent standard library
  • Security community for phishing research and awareness
  • Contributors and users who help improve this tool

🎬 Quick Demo

GUI Usage (Recommended for Beginners)

1. 📁 Open project folder
2. 🖱️ Double-click "Start_GUI.bat"
3. ⚡ GUI window opens automatically
4. 📝 Type: google.com
5. 🔍 Click "Check URL" or press Enter
6. ✅ Result: SAFE (green text)
7. 📝 Try: paypal-security.com  
8. ❌ Result: DANGEROUS (red text)

Terminal Usage (Advanced Users)

1. 🖱️ Double-click "phishing_detector.py"
2. 🌐 Choose: y (enable online) or n (offline)
3. 📝 Enter URL: google.com
4. ✅ See detailed analysis
5. 💡 Special commands: 'update', 'stats', 'q'

Remember: Stay vigilant online and always verify suspicious URLs through official channels!

About

Comprehensive Python application for detecting phishing URLs

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Sponsor this project

 
Learn more about GitHub Sponsors

Packages

No packages published

Languages