Skip to content

README.md

Latest commit

 

History

History
85 lines (59 loc) · 2.9 KB

README.md

File metadata and controls

85 lines (59 loc) · 2.9 KB
Raw

Phishing Detection Toolkit

A phishing URL & email analyser combining a machine learning ensemble with rule-based heuristics, plus an educational "awareness" mode that explains each flagged indicator.

Built by Devin Sarfo.

Features

  • URL Scanner — extracts 30 URL-based features (domain structure, IP usage, brand impersonation, shorteners, etc.) and scores them.
  • Email Analyser — extracts 8 text/structure features (word counts, link counts, urgency keywords, spelling errors, etc.).
  • ML Ensemble — Random Forest + Gradient Boosting + Logistic Regression (soft-voting ensemble) trained on labelled phishing datasets.
  • Heuristic Scoring — rule-based checks add explainability on top of the ML probability, flagging indicators the model alone might miss.
  • Educational popups — each flagged indicator can be clicked to learn about the underlying phishing technique.
  • Awareness page — a standalone /awareness page with general phishing education content.

Project Structure

backend/
  app.py               Flask app — serves the frontend and exposes the analysis API
  ml_model.py           Loads trained models and runs prediction + heuristic scoring
  feature_extractor.py  URL and email feature extraction used by both training and inference
  train_model.py        Trains the RandomForest/GradientBoosting/LogisticRegression ensemble
  test_model.py          Basic tests for the model pipeline
  email_model.pkl        Trained email classifier (generated by train_model.py)
  url_model.pkl           Trained URL classifier (generated by train_model.py)
  model_meta.json         Dataset/feature metadata for the trained models

frontend/
  index.html      URL/email scanner UI
  awareness.html  Phishing awareness/education page
  script.js       Scanner logic (calls the /api/analyze endpoint)
  popup.js        Educational indicator popup logic
  style.css       Styling

Dataset/
  phishing_site_urls.csv    URL training data
  email_phishing_data.csv   Email training data

Setup

Requires Python 3.10+.

pip install flask flask-cors scikit-learn pandas numpy joblib

Train the models (optional — pre-trained .pkl files are included)

python -m backend.train_model

Run the app

python -m backend.app

Then open http://localhost:5000 in your browser.

API

POST /api/analyze

{ "type": "url", "content": "http://example.com/login" }

or

{ "type": "email", "content": "From: ...\nSubject: ...\n\nBody text..." }

Returns a risk score, verdict, ML probability, and a list of flagged indicators with severities and explanations.

GET /api/status

Returns the loaded-model status and metadata.

Disclaimer

This tool is for educational purposes and is not 100% accurate. Always verify suspicious links by navigating to the official website directly rather than clicking email links.