🛡️ PhishGuard AI

Next-Gen AI Phishing Detection System

🚀 Launch Live Demo 🚀

Features • Architecture • Installation • API • Contributing

💡 The Problem

Phishing attacks account for 90% of all data breaches, with AI-generated scams becoming increasingly difficult to detect. Traditional rule-based filters struggle to keep up with these sophisticated threats.

🛡️ The Solution

PhishGuard AI is an intelligent defense layer that leverages Machine Learning (Logistic Regression) and Natural Language Processing (NLP) to analyze email intent, context, and linguistic patterns in real-time.

"Don't just block. Understand."

✨ Key Features

🧠 Intelligent Detection

98.3% Accuracy: Trained on the SMS Spam Collection dataset.
High Recall (91.3%): Prioritizes catching threats to minimize missed attacks.
Real-Time Analysis: Sub-100ms inference time.

🎨 Next-Gen UI/UX

Cyberpunk Aesthetic: Glassmorphism, neon accents, and Digital Rain effects.
Live Threat Feed: Real-time visualization of scanned emails.
Forensic Breakdown: Detailed confidence scores and probability analysis.

🎬 Demo

Dashboard Interface

Key Capabilities

Email Analysis: Paste suspicious email content for instant classification
Threat Visualization: Color-coded results (Red = Phishing, Green = Safe)
Forensic Details: Expandable technical analysis with raw model output
Scan History: Chronological feed of all analyzed emails
System Status: Real-time engine health monitoring

🎥 Live Demo

Watch PhishGuard AI in action:

Try it yourself:

Clone the repository
Run ./run_system.sh
Open http://localhost:5173
Paste a suspicious email and click "SCAN FOR THREATS"

🛠️ Tech Stack

Frontend

Framework: React 18 with Vite
Styling: Vanilla CSS with custom animations
Fonts: Google Fonts (Outfit, Orbitron)
Effects: Glassmorphism, Digital Rain, Custom Cursors

Backend

Framework: FastAPI
Server: Uvicorn (ASGI)
CORS: Enabled for cross-origin requests

Machine Learning

Algorithm: Logistic Regression
Feature Engineering: TF-IDF Vectorization
Text Processing: NLTK (stopwords, stemming)
Model Persistence: Joblib
Evaluation: scikit-learn metrics

Data

Dataset: SMS Spam Collection (UCI ML Repository)
Size: 5,574 messages
Split: 80% training, 20% testing

📦 Installation

Prerequisites

Python 3.8+
Node.js 16+
npm or yarn
Git

Clone Repository

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

Backend Setup

# Install Python dependencies
pip install -r requirements.txt

# Download NLTK data (automatic on first run)
python -c "import nltk; nltk.download('stopwords')"

# Train models (if not already trained)
python src/model_trainer.py

Frontend Setup

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Return to root
cd ..

🚀 Usage

Quick Start (Recommended)

# Launch both frontend and backend with one command
./run_system.sh

This will start:

Backend API: http://localhost:8000
Frontend Dashboard: http://localhost:5173

Manual Start

Backend Only

uvicorn src.api:app --reload --port 8000

Frontend Only

cd frontend
npm run dev

🏗️ Architecture

graph TD
    User[👤 User] -->|Access Dashboard| Frontend["⚛️ React Frontend<br>(GitHub Pages)"]
    Frontend -->|POST /predict| Backend["🚀 FastAPI Backend<br>(Railway)"]
    
    subgraph "Backend Services"
        Backend -->|Text Processing| NLP[📝 NLTK Preprocessing]
        NLP -->|Vectorization| TFIDF[🧮 TF-IDF Vectorizer]
        TFIDF -->|Inference| Model[🤖 Logistic Regression Model]
    end
    
    Model -->|Prediction & Score| Backend
    Backend -->|JSON Response| Frontend
    Frontend -->|Visual Feedback| User
    
    style Frontend fill:#61DAFB,stroke:#333,stroke-width:2px,color:black
    style Backend fill:#009688,stroke:#333,stroke-width:2px,color:white
    style Model fill:#FF9800,stroke:#333,stroke-width:2px,color:black

Data Flow

Input: User pastes email content into the React dashboard.
Request: Frontend sends a secure API request to the FastAPI backend.
Processing: Backend cleans text (stopwords, stemming) and vectorizes it.
Inference: ML model predicts probability of phishing.
Response: Result is returned and visualized with confidence scores.

Testing the System

Open http://localhost:5173 in your browser
Paste a suspicious email in the text area
Click "🛡️ SCAN FOR THREATS"
View results and confidence score
Check the Live Threat Feed for history

Example Phishing Email

URGENT! You have won a £100,000 Prize Jackpot! 
Click here to claim: http://suspicious-link.com
Reply with your bank details to: scammer@fake.com

📚 API Documentation

Base URL

http://localhost:8000

Endpoints

Health Check

GET /

Response

{
  "status": "online",
  "model": "Logistic Regression"
}

Predict Email

POST /predict
Content-Type: application/json

Request Body

{
  "text": "Your email content here"
}

Response

{
  "label": "Phishing/Spam",
  "probability": "0.9234",
  "raw_text": "Your email content here"
}

Interactive API Docs

Visit http://localhost:8000/docs for Swagger UI documentation.

📊 Model Performance

Metrics (Logistic Regression)

Metric	Score
Accuracy	98.3%
Precision	98.5%
Recall	91.3%
F1-Score	94.8%

Why Logistic Regression?

We chose Logistic Regression over Naive Bayes and Random Forest because:

High Recall: 91.3% recall minimizes false negatives (missed phishing emails)
Fast Inference: Real-time predictions with minimal latency
Interpretability: Clear feature importance for transparency
Efficiency: Low memory footprint and quick training

📁 Project Structure

phishguard-ai/
├── .github/                    # GitHub assets
│   ├── logo.png               # Repository logo
│   └── dashboard-demo.png     # Demo screenshot
├── frontend/                   # React application
│   ├── public/
│   │   └── cyber_background.png
│   ├── src/
│   │   ├── components/
│   │   │   ├── DigitalRain.jsx
│   │   │   └── Testimonials.jsx
│   │   ├── App.jsx
│   │   ├── App.css
│   │   └── main.jsx
│   ├── index.html
│   ├── package.json
│   └── vite.config.js
├── src/                        # Backend & ML
│   ├── api.py                 # FastAPI server
│   ├── data_loader.py         # Dataset handling
│   ├── features.py            # Feature engineering
│   ├── model_trainer.py       # Model training
│   ├── evaluation.py          # Performance metrics
│   └── inference.py           # Prediction engine
├── models/                     # Trained models
│   ├── Logistic_Regression.pkl
│   ├── tfidf_vectorizer.pkl
│   └── ...
├── .gitignore
├── requirements.txt
├── run_system.sh              # Launch script
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
└── README.md

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick Start

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

📄 License

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

👨‍💻 Contact

Developer: Subhajit Roy

📧 Email: subhajitroy857@gmail.com
💼 LinkedIn: linkedin.com/in/sr857
🐙 GitHub: github.com/sr-857

🙏 Acknowledgments

Dataset: SMS Spam Collection from UCI ML Repository
Inspiration: Modern cybersecurity dashboards and threat intelligence platforms
Libraries: React, FastAPI, scikit-learn, NLTK, and the amazing open-source community

⭐ Star this repository if you found it helpful!

Made with ❤️ and ☕ by Subhajit Roy

Name		Name	Last commit message	Last commit date
.github		.github
data		data
frontend		frontend
models		models
notebooks		notebooks
results		results
src		src
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
DEPLOYMENT.md		DEPLOYMENT.md
LICENSE		LICENSE
Procfile		Procfile
README.md		README.md
SECURITY.md		SECURITY.md
app.py		app.py
document.pdf		document.pdf
index.html		index.html
pdf_reader.py		pdf_reader.py
render.yaml		render.yaml
requirements.txt		requirements.txt
run_app.sh		run_app.sh
run_system.sh		run_system.sh

Latest commit

History

Folders and files

Repository files navigation