Skip to content

README.md

Latest commit

 

History

History
127 lines (90 loc) · 5.48 KB

README.md

File metadata and controls

127 lines (90 loc) · 5.48 KB

ScamShield logo

ScamShield: Real-Time Scam Detection for the Browser

Chrome Extension Manifest V3 Hackathon MVP Client-side Scoring

ScamShield is a Chrome extension MVP that analyzes the page a user is currently visiting, looks for scam and phishing patterns, and explains the risk in plain language. It combines fast local heuristics with an optional AI explanation layer so users get both an immediate safety signal and a human-readable reason for the warning.

Overview

The system is designed for live browser protection and demo-friendly evaluation:

  • It scans the active page for suspicious domain, content, link, form, iframe, and script signals.
  • It assigns a local safety score from 0-100, where higher means safer.
  • It classifies pages as safe, suspicious, or dangerous.
  • It highlights risky outgoing links before the user navigates away.
  • It shows results inside a Chrome side panel and on-page warning UI.
  • It can generate an AI explanation through Gemini or OpenRouter for pages that need more context.

How The System Works

ScamShield follows a staged detection pipeline:

  1. Content script scan
    The extension reads the current page and extracts URL, title, metadata, visible text, links, forms, iframes, and script behavior.

  2. Heuristic scoring
    The background worker scores the page locally using weighted signals such as:

    • suspicious TLDs and lookalike domains
    • brand impersonation patterns
    • urgency language and sensitive-data prompts
    • off-site login links
    • suspicious forms and hidden iframes
    • obfuscated or hostile JavaScript behavior

  3. Threat enrichment
    The system checks additional intelligence such as local blocklist matches and domain-age risk when available.

  4. User-facing response
    ScamShield updates the side panel, stores the result per tab, and shows in-page warnings or overlays for suspicious and dangerous pages.

  5. Optional AI explanation
    For non-obviously-safe pages, the extension can ask Gemini or OpenRouter to turn the detected signals into a short explanation and recommended next steps.

Key Features

  • Real-time page scanning for every loaded or meaningfully updated page
  • Client-side detection pipeline for fast first-pass scoring
  • Risky link interception before users click through
  • Side panel dashboard for readable scan results
  • Session-aware tab state so results persist while browsing
  • Optional AI assistance with fallback explanations when no provider is configured
  • Demo testcase suite for safe and scam scenarios

Project Structure

.
|-- scam-shield/
|   |-- background.js          # Main scan orchestration pipeline
|   |-- content/               # Page scanning + on-page warnings
|   |-- scoring/               # Heuristics, blocklist, domain-age, AI explanation
|   |-- sidebar/               # Side panel UI
|   |-- popup/                 # Extension popup
|   |-- options/               # Provider/API key settings
|   `-- manifest.json          # Chrome extension manifest
|-- testcases/                 # Demo pages for safe vs scam
evaluation
`-- README.md

Run The Extension

  1. Open chrome://extensions
  2. Turn on Developer mode
  3. Click Load unpacked
  4. Select the scam-shield folder
  5. Open any website and click the extension icon to open the side panel

AI Provider Setup

ScamShield supports two optional providers for explanations:

  • Gemini
  • OpenRouter

You can configure them in either of these ways:

  • Add local values in scam-shield/config.local.json
  • Or open the extension options page and save provider settings there

If no provider is configured, ScamShield still works. It falls back to a locally generated explanation based on the detected signals.

Demo Testcases

The repository includes a testcases/ folder with judge-ready pages for demos:

  • safe/ contains benign examples
  • scam/ contains scam-like phishing pages meant to trigger detection logic

See testcases/README.md for hostname mapping and local demo instructions.

Production Note

This repository is intentionally built as a hackathon MVP. It is strong for demos, prototyping, and validating the user experience, but it is not yet production hardened.

Important limitations:

  • API keys can be configured locally inside the extension workflow
  • AI calls are made directly from the extension for development speed
  • the detection logic is heuristic-first and should be continuously tuned against real-world datasets
  • a production version should move sensitive provider access and threat intelligence behind a secure backend

Why This Project Matters

ScamShield is aimed at a practical browser-security problem: most users do not need raw technical indicators, they need a fast and understandable answer to a simple question:

"Does this page look safe, and why?"

This project focuses on answering that question quickly, visibly, and in a form that non-technical users can act on.