PhishGuardian/README.md

# PhishGuardian

PhishGuardian is a browser extension designed to detect and manage phishing emails. It uses machine learning to identify potential phishing 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 phishing emails using machine learning
- Allows users to mark emails as safe
- Allows users to move phishing emails to the trash
- Provides notifications for detected phishing emails

## 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 backend.py
   ```

### Setting up Gmail API

### To integrate the Gmail API, follow these steps:

1. Visit the Google Cloud Console at https://console.cloud.google.com/apis/credentials.
2. Click on "Create Project" and fill in the required fields.
3. Navigate to the Library, find the Gmail API, and enable it.
4. Go to the OAuth consent screen and select the "External" option in the User Type field and click "Create". Enter the application name and your email address. Skip the "App logo" and "App domain" fields. Also, skip all the following windows until the last step "Summary", where click "Back to dashboard". Then, in the "Publishing status" field, click "Publish app".
5. Go to the Credentials tab and click on "Create Credentials". Then, select "OAuth client ID", choose "Web application", and fill in the following fields:

- javascript_origins: ["http://localhost:5000"]
- redirect_uris: ["http://localhost:5000/oauth2callback"]

6. A popup window will appear where you can obtain the "Client_id" which must be noted in 'manifest.json'. There will also be a button to download a JSON file. Place this file in the backend folder for convenience, name the file "client_secret.json", or you can rename it in backend.py as needed.
7. These setup instructions will assist you in integrating and using the Gmail API effectively in your project.

### 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 `PhishGuardian` directory.

## Usage

1. Click on the PhishGuardian extension icon in the Chrome toolbar.
2. Select the email system from the list - either Gmail or Outlook.
3. Login with your email credentials.
4. Use the "Check Mail" button to scan for phishing emails. 
5. If a phishing email is detected, a popup window will appear with list of mails with options to mark the email as "Safe" or "Move" it to the trash.
6. After use, you can close the additional popup window, and you will see the changes made in your email service. 
7. To use it again, follow steps 4-6 of this list.

## Code Overview

### Backend Architecture Description

#### Flask Application:

- Flask is used as the main web framework.

#### CORS:

- Enabled using Flask-CORS to handle cross-origin requests.

#### Configuration and Environment:

- Secret Key: Defined for managing sessions.

- Environment Variable: OAUTHLIB_INSECURE_TRANSPORT is set to '1' to allow insecure HTTP connections during development. This can be removed once a certificate is obtained from Google.

#### OAuth 2.0:

- Client Secrets: Loaded from the client_secret.json file.

- Scopes: Defined for permissions to read and modify Gmail data.

- Routes: /authorize to initiate the OAuth process and /oauth2callback to handle the OAuth callback.

#### Session Management:

- Saving and Loading Credentials: Functions for storing and loading OAuth credentials in the session.

#### Email Handling:

- Safe Emails: Stored in a JSON file safe_emails.json.

#### Data Collection for Custom Training Model:

- All emails that the user marks to be moved to the trash are recorded in a separate CSV file - safe_trash.csv, which is used as a database in the future for training the model to better recognize phishing.

### Frontend

- `popup.html`: The main interface of the extension.
- `popup.js`: Handles interactions in the popup, such as login, checking mail, and handling responses.
- `background.js`: Listens for messages from the popup and handles notifications.
- `notification.html` & `notification.js`: The interface and logic for the notification popup.

### Routes:

- /validate-outlook-login: For validating Outlook credentials.
- /fetch-emails: To fetch and classify emails from Outlook.
- /check_mail: To check emails from Gmail.
- /mark_safe/<email_id>: To mark emails as safe.
- /move_trash/<email_id>: To move emails to the trash in Gmail.
- /delete-email: To delete an email from Outlook.
- /logout: To clear the session.

### Backend Checks

The backend performs checks on the email content itself to detect any presence of links, buttons (for confirmation or verification purposes). The model has been trained on a dataset containing a high volume of invalid emails, which includes additions of HTML, incorrect and suspicious text. Emails that are too short will also be considered suspicious.