🛡️ PhishGuard AI

AI-Powered Phishing URL Detection System

97% Accuracy | Real-Time Detection | Production Ready

Features • Quick Start • API Docs • Contributing

---

📖 About

PhishGuard AI is a robust, production-ready phishing detection system that combines machine learning with modern web technologies to identify malicious URLs in real-time. Built with enterprise-grade architecture, it delivers high-accuracy threat detection while maintaining exceptional performance.

🎯 Key Highlights

• 🎓 Machine Learning Excellence: Random Forest classifier achieving 97% accuracy with optimized hyperparameters
• ⚡ Lightning Fast: Sub-second response times via FastAPI's asynchronous architecture
• 🌐 Modern Stack: Full-stack solution with Next.js frontend and Python ML backend
• 🔒 Security Focused: Designed for integration into email filters, browser extensions, and security platforms
• 📊 Comprehensive Analysis: Multiple model comparisons (Random Forest, Decision Tree, Logistic Regression, KNN)

---

✨ Features

Core Capabilities

• Real-Time URL Analysis - Instant classification with RESTful API endpoint
• High-Precision Detection - 97% accuracy, 96% precision, 98% recall
• Scalable Architecture - Microservices design for horizontal scaling
• Interactive Dashboard - User-friendly Next.js interface for URL submission and result visualization
• Model Persistence - Trained models saved with joblib for fast loading
• Comprehensive Logging - Full request/response logging for monitoring and debugging

Use Cases

• 🔐 Email security gateways
• 🌐 Browser extension development
• 🏢 Enterprise security platforms
• 📱 Mobile app integration
• 🎓 Educational cybersecurity projects

---

🏗️ Architecture

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────┐
│   Next.js UI    │ ──────> │   FastAPI Server │ ──────> │  ML Pipeline    │
│   (Frontend)    │ <────── │   (REST API)     │ <────── │  (scikit-learn) │
└─────────────────┘         └──────────────────┘         └─────────────────┘
     Port 3000                   Port 8000                  Random Forest

Tech Stack

Layer	Technology	Purpose
Frontend	Next.js 14, React, TailwindCSS	Responsive UI with modern design patterns
Backend	FastAPI, Pydantic, Uvicorn	High-performance async API server
ML Engine	scikit-learn, pandas, numpy	Model training and inference

---

📊 Model Performance

Primary Model: Random Forest

Evaluated on 20% held-out test set from 11,000+ phishing URLs dataset:

Metric	Score
Accuracy	97.0%
Precision	96.0%
Recall	98.0%
F1-Score	97.0%

Model Comparison

Algorithm	Accuracy	Training Time
Random Forest	97.0%	~2.5s
Decision Tree	94.5%	~0.8s
Logistic Regression	92.3%	~1.2s
K-Nearest Neighbors	93.8%	~1.5s

---

🚀 Quick Start

Prerequisites

Ensure you have the following installed:

• Node.js 18+ (Download)
• Python 3.10+ (Download)
• Git (Download)

Installation

1️⃣ Clone the Repository

git clone https://github.com/HassanNetSec/phishguard-ai.git
cd phishguard-ai

2️⃣ Backend Setup

cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
.\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start FastAPI server
uvicorn server:app --reload --host 0.0.0.0 --port 8000

✅ Backend API running at http://localhost:8000

3️⃣ Frontend Setup

Open a new terminal:

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

✅ Web application running at http://localhost:3000

---

📡 API Documentation

Endpoints

POST /predict

Analyze a URL for phishing indicators.

Request Body:

{
  "url": "https://example.com"
}

Response (Safe URL):

{
  "status": "safe",
  "message": "✅ SAFE: URL appears legitimate",
  "details": [
    "All security checks passed",
    "Valid domain with proper DNS records",
    "Model confidence: 94.2%",
    "No suspicious patterns detected"
  ],
  "prediction_score": 0.942
}

Response (Dangerous URL):

{
  "status": "dangerous",
  "message": "🚨 DANGER: URL Likely Phishing Attempt",
  "details": [
    "Multiple strong indicators of a phishing attempt detected",
    "Highly suspicious URL pattern",
    "Model confidence: 96.8%",
    "DO NOT enter credentials, payment info, or personal data",
    "Close this page immediately",
    "Report this URL to your IT department or relevant authorities"
  ],
  "prediction_score": 0.968
}

Interactive API Docs

Once the backend is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

---

📁 Project Structure

phishguard-ai/
├── backend/
│   ├── server.py                    # FastAPI application
│   ├── requirements.txt             # Python dependencies
│   └── randomforestmodel.joblib     # Trained Random Forest model
├── frontend/
│   ├── app/                         # Next.js app directory
│   ├── components/                  # React components
│   ├── styles/                      # CSS/Tailwind styles
│   ├── public/                      # Static assets
│   └── package.json                 # Node dependencies
├── PhishGuard_ML_Training_Analysis.ipynb  # ML training notebook
├── phishing_websites.xlsx           # Training dataset
├── .gitignore
└── README.md

---

🛣️ Roadmap

• Add support for bulk URL analysis
• Implement user authentication and API keys
• Deploy to AWS/GCP with CI/CD pipeline
• Add real-time monitoring dashboard
• Integrate additional ML models (deep learning)
• Create browser extension
• Add multilingual support

---

🤝 Contributing

Contributions are welcome! Whether you're fixing bugs, improving documentation, or proposing new features, your help is appreciated.

How to Contribute

1. Fork the repository
2. Clone your fork: git clone https://github.com/HassanNetSec/phishguard-ai.git
3. Create a feature branch: git checkout -b feature/YourFeature
4. Make your changes and test thoroughly
5. Commit with clear messages: git commit -m 'Add: New feature description'
6. Push to your fork: git push origin feature/YourFeature
7. Open a Pull Request with a detailed description

Contribution Guidelines

• Write clean, readable code with comments
• Follow existing code style and conventions
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting PR

Areas for Contribution

• 🐛 Bug fixes and error handling improvements
• 📚 Documentation enhancements
• ✨ New ML models or feature engineering
• 🎨 UI/UX improvements
• 🧪 Additional test coverage
• 🌐 Internationalization support

---

📄 License

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

---

👥 Authors

• Hassan Khan - Initial work - HassanNetSec

See also the list of contributors who participated in this project.

---

🙏 Acknowledgments

• Dataset sourced from UCI Machine Learning Repository
• Inspired by modern phishing detection research
• Built with amazing open-source tools

---

📞 Contact

Have questions or suggestions? Reach out:

• Email: hassankhancyber647@gmail.com
• LinkedIn: Hassan Khan

---

⭐ Star this repo if you find it helpful!

Made with ❤️ and ☕