🛡️ SafeSurf AI

Real-time Webpage Risk Analysis using a Chrome Extension and FastAPI Backend

SafeSurf AI is a backend-driven Chrome extension that analyzes webpages in real time and provides explainable security risk scores to help users identify potentially unsafe or suspicious websites.

The system follows a privacy-first client–server architecture, where only minimal, non-sensitive webpage signals are collected in the browser and evaluated by a FastAPI backend.

---

🚀 Features

• 🔍 Real-time webpage risk analysis
• 🧠 Explainable risk scoring (rule-based, no black box)
• 🌐 Backend-driven architecture using FastAPI
• 🧩 Chrome Extension (Manifest V3)
• 🎯 Visual risk badge injected directly into webpages
• 🟢🟡🔴 Color-coded risk levels (LOW / MEDIUM / HIGH)
• 🔐 Privacy-first design (no cookies, no user tracking)
• ⚡ Asynchronous client–server communication

---

🧠 How It Works

User opens webpage ↓ Chrome Extension collects minimal signals ↓ FastAPI backend computes risk score ↓ Explainable result returned ↓ Visual risk badge displayed on webpage

Signals Collected (Privacy-Safe)

• HTTPS vs HTTP
• Number of iframes
• Presence of phishing-related keywords (login, bank, password, verify)
• Current page URL (not stored persistently)

---

🧩 Tech Stack

Frontend (Browser Extension)

• Chrome Extension (Manifest V3)
• JavaScript
• Content Scripts + Background Service Worker

Backend

• FastAPI
• Python 3.12
• REST APIs
• Rule-based risk engine
• In-memory caching (development-safe)

Planned / Optional

• PostgreSQL (persistent storage)
• Redis (distributed caching)
• Docker (containerized deployment)
• ML-based phishing detection

---

📁 Project Structure

SafeSurf-AI/ ├── backend/ │ ├── app/ │ │ ├── api/ │ │ ├── services/ │ │ ├── models/ │ │ └── main.py │ └── Dockerfile │ ├── extension/ │ ├── manifest.json │ ├── content.js │ ├── background.js │ ├── popup.html │ └── popup.js │ └── README.md

---

⚙️ Backend Setup

1. Create and activate a virtual environment

cd backend
python -m venv venv
venv\Scripts\activate

2. Install dependencies

python -m pip install fastapi uvicorn pydantic

3. Run the backend server

python -m uvicorn app.main:app --reload

Backend will be available at:

http://127.0.0.1:8000

Swagger API documentation:

http://127.0.0.1:8000/docs

🧪 API Example

Endpoint

POST /analyze

Request

{
  "url": "http://example.com",
  "hasHTTPS": false,
  "iframeCount": 3,
  "suspiciousKeywords": ["login", "bank"]
}

Response

{
  "risk_score": 55,
  "risk_level": "MEDIUM",
  "reasons": [
    "Website is not using HTTPS",
    "Phishing-related keywords found"
  ]
}

🧩 Chrome Extension Setup

1. Open Chrome and navigate to chrome://extensions
2. Enable Developer mode
3. Click Load unpacked
4. Select the extension/ directory
5. Open any website to see the SafeSurf AI risk badge

---

🎨 Visual Risk Badge

• 🟢 LOW – No significant risk signals detected
• 🟡 MEDIUM – Potential security concerns identified
• 🔴 HIGH – Multiple high-risk indicators detected

Badge Characteristics

• Non-intrusive
• Informational only
• Fully explainable

---

🔐 Privacy & Ethics

SafeSurf AI is designed with privacy by default:

• ❌ No cookies
• ❌ No credentials
• ❌ No page content storage
• ❌ No user tracking
• ✅ Only transient, minimal signals are analyzed

---

🧭 Future Improvements

• Machine-learning-based phishing detection
• Persistent risk history using PostgreSQL
• Redis-based caching and rate limiting
• Dockerized backend and database
• Cloud deployment
• Optional proactive warnings for high-risk pages

---

📌 Why This Project Matters

SafeSurf AI demonstrates:

• Real-world client–server architecture
• Browser security concepts
• API-driven backend design
• Explainable decision systems
• Practical engineering trade-offs

This project reflects how modern security tooling is architected in production systems.

---

📄 License

MIT License
Free to use, modify, and distribute.