PhishGuardian/README.md

# PhishGuardian

PhishGuardian is a browser extension designed to detect and manage suspicious emails. It uses machine learning to identify suspicious emails and provides options to mark them as safe or move them to the trash. The extension is built using Flask for the backend and JavaScript for the frontend.

## Features

- Detects suspicious emails using machine learning
- Allows users to mark emails as safe
- Allows users to move suspicious emails to the trash

## Installation

### Prerequisites

- Python 3.6+
- Flask
- scikit-learn
- Chrome browser

### Backend setup

1. Clone the repository:
    ```sh
    git clone https://git.wmi.amu.edu.pl/s452649/PhishGuardian.git
    cd PhishGuardian/backend
    ```

2. Install the required Python packages:
    ```sh
    pip install -r requirements.txt
    ```

3. Run the Flask backend:
    ```sh
    python app.py
    ```

### Extension setup

1. Open Chrome and go to `chrome://extensions/`
2. Enable "Developer mode" by toggling the switch in the top right corner.
3. Click on "Load unpacked" and select the `extension` directory within the `PhishGuardian` directory.

## Usage

1. Click on the PhishGuardian extension icon in the Chrome toolbar.
2. Login with your email credentials. For now, only credentials for Outlook are supported (this will change in the future).
3. Use the "Fetch Emails" button to retrieve your emails.
4. Select an email from the list and click the "Classify Email" button to scan the email.
5. Classification result will be displayed.
6. Use the "Mark as Safe" button to mark the email as safe or the "Delete Email" button to delete a suspicious email.

## Code overview

### Backend (`app.py`)

- Uses Flask to handle HTTP requests.
- Uses IMAP to connect to the email server and fetch emails.
- Uses scikit-learn to classify emails as suspicious or not based on the content.
- Provides endpoints for fetching emails, classifying emails, marking emails as safe, and deleting emails.

### Frontend

- `popup.html`: The main interface of the extension.
- `popup.js`: Handles interactions in the popup, such as login, fetching emails, and handling responses.
- `background.js`: Manages the background tasks of the extension, such as opening the popup.
- `styles.css`: Contains the styles for the extension's UI.
- `manifest.json`: Configuration file for the Chrome extension.
- `images/icon16.png`, `images/icon48.png`, `images/icon128.png`: Icons used for the extension.

## API endpoints

- `POST /fetch-emails`: Fetch emails from the email server.
- `POST /classify-email`: Classify an email as phishing or not.
- `POST /mark-safe`: Mark an email as safe.
- `POST /delete-email`: Delete an email from the email server.

## Files and directories

### Backend directory

- `app.py`: Main Flask application file.
- `spam_classifier_model.pkl`: Pre-trained machine learning model for classifying emails.
- `vectorizer.pkl`: Pre-trained vectorizer for transforming email content into a format suitable for the classifier.
- `source.txt`: Contains a link from which the datasets were downloaded.
- `lingSpam.csv`, `enronSpamSubset.csv`, `completeSpamAssasin.csv`: These are the datasets used to train the model (Random Forest is the chosen model).
- `data_join.py`: Script which merges the three datasets into one CSV file called `joined_data.csv`.
- `joined_data.csv`: The combined dataset resulting from `data_join.py`.
- `ML.ipynb`: Jupyter notebook containing all the machine learning and vectorizer information.
- `requirements.txt`: File containing the list of required Python packages.

### Extension directory

- `popup.html`: The main HTML file for the extension's UI.
- `popup.js`: JavaScript for handling UI interactions and communicating with the backend.
- `background.js`: JavaScript for background tasks and managing the extension's lifecycle.
- `styles.css`: CSS styles for the extension's UI.
- `manifest.json`: Configuration file for the Chrome extension.
- `images/icon16.png`, `images/icon48.png`, `images/icon128.png`: Icons used for the extension.

## How it works

1. **Login**: Users log in with their email credentials using the extension.
2. **Fetch emails**: The extension fetches emails from the server and displays them in the popup.
3. **Classify emails**: Emails are classified as suspicious or not. The classification results are stored and associated with each email.
4. **Mark as safe/Delete**: Users can mark suspicious emails as safe or delete them. The actions are reflected in the backend and the UI is updated accordingly.