Email Phishing Detector

Local FastAPI service and Chrome extension that rate Gmail threads for phishing, spam, and malicious links in real time.

---

Table of Contents

• About
• Quick Start
• Usage
• Browser Extension Setup
• API Reference
• Troubleshooting
• Contributing
• Hacktoberfest
• Submitting a Pull Request
• Guidelines for Pull Request
• Authors
• Community & Conduct

---

About

We combine a FastAPI backend and a Manifest V3 Chrome extension to surface phishing risk directly inside Gmail. The server loads the Hugging Face model cybersectony/phishing-email-detection-distilbert_v2.4.1 (four labels: safe, suspicious, scam/fraud, malicious URL) and augments the response with sender impersonation heuristics. The extension calls /predict, then inserts a severity banner beneath the Gmail subject line so users immediately know whether to trust an email.

Key highlights:

• Real-time banner tones (green/amber/red) based on model confidence and sender analysis.
• Homoglyph, typosquatting, and freemail impersonation checks against common brands.
• Optional PHISH_DEV mode to replace the transformer with deterministic heuristics for offline or rapid local testing.
• Health probes (/health, /live, /ready) for deployment monitoring.

---

Quick Start

# 1) Clone and enter the project
git clone https://github.com/<your-username>/ai-phishing-mail-detector-extension.git
cd ai-phishing-mail-detector-extension

# 2) Create & activate a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate        # Windows PowerShell: .venv\Scripts\Activate.ps1

# 3) Install backend dependencies
pip install -r requirements.txt

# 4) (Optional) Enable lightweight heuristic stub
export PHISH_DEV=1               # Windows PowerShell: $Env:PHISH_DEV = "1"

# 5) Launch the FastAPI server
uvicorn main:app --reload

# API available at http://127.0.0.1:8000
# Interactive docs at http://127.0.0.1:8000/docs

Note: The first run without PHISH_DEV downloads transformer weights (~500 MB). Ensure network access and disk space.

---

Usage

1. Start the FastAPI backend as shown above.
2. Load the Chrome extension (see Browser Extension Setup).
3. Open Gmail in the same browser profile and view any thread; a banner renders under the subject once /predict responds.
4. Severity cues:
   • Likely safe (green) → ham prediction with low phishing risk.
   • Warning (amber) → spam indicators or suspicious sender heuristics.
   • Danger (red) → high phishing probability, denylisted sender, or malicious URL indicators.
5. Keep the Gmail tab open; background observers rescan new or updated messages automatically.

---

Browser Extension Setup

• Open Chrome and navigate to chrome://extensions.
• Enable Developer mode (top-right toggle).
• Click Load unpacked and choose the extension/ folder.
• Confirm extension/content.js points to your backend host (http://127.0.0.1:8000 by default).
• Refresh Gmail; the analysis banner should appear within a couple of seconds after opening a thread.

---

API Reference

POST /predict

Request body:

{
  "text": "<raw email body text>",
  "sender_email": "[email protected]",
  "sender_name": "Microsoft Account Team"
}

Response fields (summary):

• label, confidence – top model label and probability.
• phishing_probability, ham_probability – normalized scores.
• sender_analysis – reasons, risk score, and impersonation hints.
• is_phishing – final verdict using probability threshold (0.90) and sender flags.
• elapsed_ms – end-to-end inference time.

Supporting endpoints:

• GET / → Redirects to interactive docs.
• GET /health, GET /live, GET /ready → Return { "status": "ok" } for monitoring probes.

---

Troubleshooting

• Model download fails → Temporarily enable PHISH_DEV=1 or ensure Hugging Face access from your network.
• Extension CORS errors → Backend already enables CORS for all origins; verify host/port matches host_permissions in extension/manifest.json.
• No banner appearing → Check Chrome devtools for content-script errors and ensure the backend responds on http://127.0.0.1:8000/predict.
• Slow predictions → Warm up the model with a sample request or run on hardware with GPU/AVX acceleration.

---

Contributing

We welcome contributions of all kinds—bug fixes, model improvements, UI polishing, and documentation tweaks. Please open an issue to discuss major changes before implementing them.

---

Submitting a Pull Request

1. Fork the repository (top-right on GitHub).
2. Clone your fork locally:

   git clone <HTTPS-ADDRESS>
   cd <NAME-OF-REPO>

3. Create a new branch:

   git checkout -b <your-branch-name>

4. Make your changes and stage them:

   git add .

5. Commit your changes:

   git commit -m "feat: describe your change"

6. Push to your fork:

   git push origin <your-branch-name>

7. Open a Pull Request describing the modifications, expected behavior, and any screenshots/logs. Link related issues (e.g., “Fixes #123”).

---

Guidelines for Pull Request

• Avoid automated or low-effort spam PRs.
• Ensure code runs locally (uvicorn + extension) before submitting.
• Add or update documentation/tests when behavior changes.
• Maintainers reserve the right to label contributions as invalid if they do not meet project standards.

---

Community & Conduct

By contributing to this project you agree to uphold our Code of Conduct. Treat others with respect, report issues responsibly, and help foster a welcoming environment.

---

🤍 Crafted with love by ACM‑VIT