# 🛡️ SecureMail — Email Threat Intelligence Gateway & Forensics Dashboard
SecureMail
An Advanced Gateway Email Security Platform, Phishing Analyzer, & Forensic Intelligence Dashboard.
## 📌 Project Overview
**SecureMail** is an end-to-end email threat detection and forensics gateway. It parses raw email headers and body text (`.eml` or `.msg`), conducts automated DNS security alignment checks, resolves originating server IPs, evaluates links/attachments through global reputation threat intelligence engines, and computes a comprehensive weighted risk score to classify malicious activity.
The system comprises three core components:
1. **🚀 FastAPI Backend**: Performs multi-stage parsing, DNS auditing, IP lookup, Tor exit node detection, and queries VirusTotal & AbuseIPDB APIs.
2. **📊 Glassmorphic Frontend**: A dashboard providing real-time email scan analysis, forensic threat feeds, network routing hop visualizations, and PDF/HTML report generators.
3. **🔌 Browser Extension**: A Chrome/Edge browser addon integrating seamlessly with Gmail and Outlook, allowing analysts to right-click email text for instant reputation lookups.
## ⚙️ How It Works (7-Stage Threat Pipeline)
When a raw email is loaded into the SecureMail gateway, it runs through a comprehensive processing sequence:
[ Raw Email (.eml) ] ➔ [ 1. Email Parser ] ➔ [ 2. DNS Auth Auditing ]
│ (SPF, DKIM, DMARC, ARC)
[ Weighted Risk Score ] 🠔 [ 7. Threat Classification ] 🠔 [ 3. Sender Verification ]
│ (Lookalike Domains, Spoofs)
[ 5. IP Reputation Audits ] 🠔 [ 4. URL Extraction & VT Rep ] 🠔 [ 6. Attachment Sandbox ]
(AbuseIPDB, Tor Exits) (Hash Lookup)
1. **Email Parser**: Extracts headers, plain text, HTML structures, and attachment metadata.
2. **DNS Auth Auditing**: Decodes authentication blocks to inspect **SPF**, **DKIM**, **DMARC**, and **ARC** status.
3. **Sender Verification**: Detects display-name spoofing, reply-to mismatches, and domain-impersonation lookalikes.
4. **URL Extraction**: Scrapes all embedded links and submits them to the **VirusTotal API** for reputation ratings.
5. **IP Auditing**: Traces the originating hops, checks IPs on **AbuseIPDB**, and maps sender ISP/geographic coordinates.
6. **Attachment Sandbox**: Extracts file hashes to look up known malware signatures on public threat registries.
7. **Risk Score Calc**: Computes a score from 0 to 100 based on weighted security alerts and applies threat classifications (e.g. `phishing`, `spoofing`, `malware`).
## ✨ Features
- **🚨 Live Threat Intelligence Feed**: Instantly logs and alerts security analysts of incoming critical threats.
- **🗺️ Forensic Routing Hop Audit**: Visually maps out intermediate email transfer servers to trace origins.
- **📝 Phishing Density Analysis**: Audits HTML and body copy to identify high-density urgency triggers and fraud-related keywords.
- **📑 Exporter Suite**: Instantly download professional print-ready **PDF Incident Reports** or offline **HTML logs** for audits.
- **🌓 Adaptive Theme Modes**: Fully responsive, gorgeous interface in both dark mode and light mode.
## 🛠️ Installation & Setup
### 1. Backend Setup (FastAPI Server)
Ensure you have **Python 3.8+** installed.
# Navigate to the Backend folder
cd Backend
# Create a virtual environment
python -m venv venv
# Activate the virtual environment
# On Windows:
venv\Scripts\activate
# On Linux/macOS:
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
#### Set up Environment Secrets
Create a `.env` file in the `Backend` directory (copy from `.env.example`):
VIRUSTOTAL_API_KEY=your_virustotal_api_key_here
ABUSEIPDB_API_KEY=your_abuseipdb_api_key_here
*(Note: `.env` is already configured in `.gitignore` to prevent exposing your keys on GitHub).*
#### Start the Server
python -m uvicorn app.main:app --port 8000 --reload
The API documentation will be available at `http://localhost:8000/docs`.
### 2. Frontend Setup (Dashboard)
Since the frontend uses vanilla HTML, CSS, and JS, no complex node compilation is required:
1. Open the `Frontend` directory.
2. Launch `index.html` in any browser.
3. Make sure the FastAPI backend is running on port `8000` to allow the dashboard to populate live data.
### 3. Browser Extension Installation
1. Open Google Chrome or Microsoft Edge and navigate to `chrome://extensions`.
2. Toggle on **Developer mode** (top-right corner).
3. Click **Load unpacked** (top-left button).
4. Select the `extension` folder inside this project directory.
5. The SecureMail shield icon will appear in your browser bar, ready for one-click scans!
## 📊 API Reference
| Endpoint | Method | Description |
| :--- | :--- | :--- |
| `/api/health` | `GET` | Health check route to verify backend status. |
| `/api/scan/email` | `POST` | Scans a raw email text block, computing a comprehensive report. |
| `/api/scan/url` | `POST` | Triggers a reputation query for a custom destination link. |
| `/api/attachments/scan` | `POST` | Uploads a file or queries an attachment hash. |
| `/api/forensics/` | `GET` | Retrieves historical scan logs. |
| `/api/forensics/{id}` | `DELETE` | Removes a threat log entry. |
## 🔒 Security Practices
API credentials are never pushed to the repository. The application relies entirely on `.env` files for configuration. If sharing this project, make sure to exclude the local `Backend/.env` file and instead distribute `.env.example` for manual key populating.
## 🎓 Final Year Project Submission
Developed as a final year academic project.
**Created by**: Samir Khurshid
**Project Name**: SecureMail Email Threat Intelligence Dashboard