🛡️ AI Phishing Detection Engine

ML-powered URL phishing classifier using feature engineering and ensemble learning.

---

🎯 Example Output

URL: http://192.168.1.1/secure-login/update-billing.php?id=82736
Verdict: 🔴 PHISHING (98.3% confidence)
Key signals: has_ip_address (1), num_hyphens (3), path_entropy (3.82)

URL: https://www.google.com
Verdict: 🟢 LEGITIMATE (99.1% confidence)
Key signals: uses_https (1), domain_entropy (2.14), url_length (22)

---

✨ Features

• 20 engineered URL features — entropy, IP detection, TLD analysis, shortener detection, and more
• 3 ML models compared — Random Forest, Gradient Boosting (XGBoost), Logistic Regression
• Interactive CLI demo — analyse URLs in real time from the terminal
• Batch prediction — classify thousands of URLs from a CSV file
• Color-coded output — instant visual feedback (red = phishing, green = safe)
• Portfolio-ready — clean code with docstrings, type hints, and unit tests

---

🚀 Quick Start

1. Install dependencies

pip install -r requirements.txt

2. Download the dataset

python data/download_dataset.py

3. Train the model

python src/train.py

4. Predict

# Single URL
python src/predict.py "https://www.google.com"

# From a file (one URL per line)
python src/predict.py --file urls.txt

# Batch CSV
python src/predict.py --batch urls.csv --output results.csv

5. Interactive demo

python demo.py

---

🔍 How It Works

Feature Engineering

The engine extracts 20 numeric features from each URL (no network requests needed):

#	Feature	Description
1	url_length	Total character count
2	domain_length	Length of the domain
3	path_length	Length of the URL path
4	num_dots	Count of . characters
5	num_hyphens	Count of - characters
6	num_underscores	Count of _ characters
7	num_slashes	Count of / characters
8	num_query_params	Number of query parameters
9	num_fragments	Count of # characters
10	num_digits_in_domain	Numeric chars in domain
11	has_ip_address	IP instead of domain name
12	has_at_symbol	@ present (phishing trick)
13	has_double_slash_redirect	// after protocol
14	uses_https	HTTPS scheme
15	uses_shortening_service	Known URL shortener
16	domain_entropy	Shannon entropy of domain
17	path_entropy	Shannon entropy of path
18	has_suspicious_tld	Suspicious TLD (.tk, .xyz, etc.)
19	subdomain_count	Number of subdomains
20	longest_word_in_url	Longest alphabetic word

Model Training

Features are fed into three classifiers for comparison. The Random Forest (200 trees, max depth 20) serves as the primary model and is saved for prediction.

---

📊 Model Performance

Model	Accuracy	Precision	Recall	F1
Random Forest	0.96	0.95	0.97	0.96
Gradient Boosting	0.95	0.94	0.96	0.95
Logistic Regression	0.89	0.88	0.90	0.89

Results will vary depending on the dataset used. The table above shows typical performance.

Feature Importance

---

📁 Project Structure

phishing-detection-engine/
├── README.md                  # This file
├── requirements.txt           # Python dependencies
├── data/
│   └── download_dataset.py    # Auto-download the dataset
├── src/
│   ├── __init__.py
│   ├── feature_extractor.py   # 20-feature engineering class
│   ├── train.py               # Train, evaluate, and save models
│   ├── predict.py             # CLI prediction tool
│   └── utils.py               # Shared helpers
├── models/
│   ├── phishing_detector.pkl  # Trained model (after training)
│   └── feature_importance.png # Feature chart (after training)
├── tests/
│   └── test_features.py       # pytest unit tests
└── demo.py                    # Interactive CLI demo

---

🧪 Running Tests

python -m pytest tests/ -v

---

🔮 Future Improvements

• Email header analysis — parse DKIM, SPF, and return-path for email-based phishing detection
• Real-time browser extension — Chrome/Firefox extension that warns users before visiting phishing sites
• Deep learning approach — character-level CNN/LSTM for URL classification without manual feature engineering
• WHOIS integration — check domain age, registrar, and registration country as additional features
• Ensemble stacking — combine all three models' predictions for higher accuracy

---

📄 License

MIT License — see LICENSE for details.