CommunityShield – Phase 1 Foundation

This repo contains the deliverables for Phase 1 of the CommunityShield roadmap: a Chrome extension MVP paired with a FastAPI backend that classifies URLs as safe, caution, or danger for UK users.

Repository Layout

README.md                # You're here – high-level instructions
backend/                 # FastAPI + scanner logic + pytest suite
extension/               # Chrome extension MVP (UI + badge + alerts)
docs/ROADMAP.md          # Six-phase product roadmap
docs/DOGFOOD.md          # Dogfooding guide
docs/MODERATION.md       # Community moderation instructions

Each surface is isolated so engineers can work independently without tripping over each other.

Running the Stack Locally

1. Backend API

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# Optional but recommended: enable Google Safe Browsing lookups
# export COMMUNITYSHIELD_SAFE_BROWSING_KEY=your-google-api-key
uvicorn app.main:app --reload --port 8000

2. Chrome Extension

1. Open Chrome → chrome://extensions.
2. Enable Developer Mode.
3. Click Load unpacked and choose the extension/ directory.
4. Pin the extension to the toolbar. The badge will update as you browse.

3. Tests

cd backend
pytest

Phase 1 + 2 Checklist Coverage

• ✅ Chrome UI with Home/Alerts/Dashboard tabs and dynamic badge.
• ✅ Real-time scanner calling FastAPI; badges show Safe / Caution / Dangerous.
• ✅ UK scam list seeds HMRC, Royal Mail, and major bank phishing domains.
• ✅ FastAPI backend with /scan endpoint and pytest suite for scanner logic.
• ✅ Report Scam flow inside the extension, backed by /reports APIs and moderation tooling.
• ✅ Community threat database powers the Trending list + manual/automatic notifications.
• ✅ Richer static signals (mixed-content, cross-origin forms, punycode, obfuscated scripts) gathered by the extension and scored server-side, plus high-risk allowlists for gov/banking flows.
• ✅ Google Safe Browsing integration (optional) flags known phishing/malware domains automatically.
• ✅ Lightweight AI classifier combines heuristics + page features to boost or downgrade verdicts, with training samples logged for future model iterations.
• ✅ Feed ingestion script (backend/scripts/fetch_phishing_feeds.py) pulls OpenPhish, PhishStats, URLHaus (and UCI when available) to bootstrap AI training.
• ✅ Scheduled GitHub Actions workflow (.github/workflows/train.yml) fetches feeds, trains the ML model (backend/scripts/train_model.py), and publishes the latest classifier artifact.

Use this as the baseline before layering community reporting (Phase 2) and beyond.