PhishScope is a web application phishing email analysis tool that allows you to scan emails, URLs, and typosquatting domains for phishing links and malicious content. It is written in Python 3 and based on Flask. It uses the VirusTotal API and the BERT model to detect phishing emails.
PhishScope UML Diagram
To use the Feedback functionality, go into the app.py file and search (ctrl + f) for:
app.config['MAIL_USERNAME'] = 'YOUREMAIL@OUTLOOK.COM'
app.config['MAIL_PASSWORD'] = 'YOUREMAILPASSWORD'
Replace, 'YOUREMAIL@OUTLOOK.COM' and 'YOUREMAILPASSWORD' with your preferred email and passowrd. The feedback page will send user's responses to that email.
PhishScope uses the VirusTotal API for uploading and scanning files. This allows PhishScope to check if a file is malicious or benign based on VirusTotal's database. Additionally, it allows PhishScope to submit and scan URLs to determine if they lead to harmful content.
The API retrieves finished scan reports for files and URLs.
PhishScope uses the OpenAI's API key for chatbot functionality. The chatbot can assist users: by (1) Guiding users through the process of scanning email, URLs, and files; (2) Explain Concepts of phishing, how phishing attacks work, and common tactics; and (3) Describing the characteristics of phishing emails and websites, helping users to identify threats.
To use the APIs, create a config.py file with the API keys.
config.py
VIRUSTOTAL_API_KEY = 'API KEY'
OPENAI_API_KEY = 'API KEY'
Replace 'API KEY' with the VirusTotal & OPENAI API Keys.
Place the config.py file inside the Phishing-Detection-App\Flask App directory. This is the file tree:
Flask App/
├─ __pycache__/
├─ instance/
├─ static/
├─ templates/
├─ venv/
├─ app.py
├─ **config.py**
├─ my_model.py
PhishScope can run on any operating system that can install Python (Windows, Mac OS, and most Linux distributions). We recommend setting up a virtual environment and activating it (Python 3 Virtual Environment Tutorial).
Flask supports Python 3.8 and newer.
The requirements.txt file inside the Phishing-Detection-App\Flask App directory should list all Python libraries and dependencies that PhishScope uses. Use pip to install:
pip install -r requirements.txt
If you need to install the project dependencies manually, check below for installation.
Project Dependencies:
Install transformers [Need for BERT model] (Required: Win32 Long Paths Enabled)
$ pip install transformers
Other Dependencies
$ pip install plotly
$ pip install openai
$ pip install python-magic
$ pip install pdfplumber
$ pip install python-docx
$ pip install chardet
$ pip install tzdata
Install Database Libraries
$ pip install Flask-SQLAlchemy
$ pip install Flask-Migrate
CHECK the requirements.txt file for any other dependencies missing in the manual install.
You can now run the development server:
Make sure you are in the Phishing-Detection-App\Flask App directory
python3 app.py
The default Flask WSGI server (Werkzeug) will be used. If you wish to use another WSGI server (e.g. Gunicorn) or use a reverse proxy (e.g. NGINX), read the Flask-SocketIO documentation.
User Interface
There is a top navbar that allows access to the Upload (current/homepage), Analytics, Chatbot, Blacklist, and Feedback pages. There is another navbar or mininav bar that the user can select between Email Upload, Attachment Scanner, and URL Check parts of the tool. The initial UI shows an input area to enter a file and an upload button to submit to the VirusTotal API.
Visit Website: PhishScope
Email Upload
The user will input a file and click 'Upload'. That file will get sent to the VirusTotal API and return results labeling the file malicious or benign. It will also give a malicious score from 0% to 100%.
Attachment Scanner
The user will input a file and click 'Upload'. That file will get sent to the VirusTotal API and return 'Scan Results'.
URL Check
THe user will input a URL and click 'Check URL'. It will return Results similar to the 'Scan Results' from the Attachment Scanner, additionally it will show WHOIS information (domain registered date).
Simulated Training
A mini quiz that trains and explains phishing techniques to the user.
Analytics
Analytics dashboard that shows visualized statistics about the emails that have been analyzed. For example, split between safe and unsafe emails. The user can also download a PDF of the Analytics page.
Chatbot
Integration of OpenAI API, that allows users to ask for more information about phishing emails.
Blacklist
Allows users to build a list of known phishing email addresses. If an email was detected to be suspicious in one of the scanners, it will automatically be blacklisted. Users can also manually add/remove emails.
Feedback
User Feedback system that allows users to rate the accuracy and usefulness of phishing email detection, and provide provide feedback or suggestions.
A collection of datasets for classification and phishing detection tasks, compiled from various sources, including 18,000 Enron Corporation emails, 5,971 text messages, over 800,000 URLs, and 80,000 website instances.
https://huggingface.co/datasets/ealvaradob/phishing-dataset
A schematic depiction of the BERT model and its training process
Bidirectional Encoder Representations from Transformers (BERT) model. A deep learning model which is trained on text data. Unlike traditional models that process text in one direction (either left-to-right or right-to-left), BERT considers both directions which helps it learn to understand the context of words.
https://huggingface.co/rpg1/tinyBERT_phishing_model
A free course that helps coders apply deep learning to practical problems. Covers building and training models for various applications using tools like PyTorch, fast.ai, and Hugging Face.
This project started in 2024 and was presented as a Senior Project for graduation at the University of South Florida. The team was composed by Thurmond Guy, Cameron Brauner, Ryan Gillespie, and Dylan Love.
