PhishLens

Project site · Architecture · Privacy policy · Threat model · ML methodology · Demo script

PhishLens is a defensive Chrome extension and FastAPI backend for explainable phishing risk analysis in real time.

It combines local URL heuristics, privacy-preserving DOM signals, optional PhishTank threat intelligence, backend-side TLS certificate inspection, and an optional machine learning model. The project is built as a practical cybersecurity portfolio project with clear safety boundaries.

PhishLens catching a look-alike PayPal login (paypa1-secure-login.com) and explaining exactly why it is dangerous. End-to-end walkthrough:

Quick Start

# 1. Clone and set up the backend
git clone https://github.com/JuanCardesa/PhishLens.git && cd PhishLens
cp .env.example .env
python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r backend/requirements-dev.txt

# 2. Start the backend
uvicorn app.main:app --app-dir backend --reload

# 3. Build the extension
cd extension && npm install && npm run build

# 4. Load the extension in Chrome: chrome://extensions → Developer mode → Load unpacked → select extension/dist

# 5. (Optional) Build a real ML dataset and retrain the model
python ml/datasets/build_dataset.py && python ml/train_model.py

Current Status

• Detection. URL heuristics (typosquatting via Levenshtein, homograph/IDN attacks via a hand-written punycode decoder and confusable map, a brand’s full domain hidden in subdomains) and privacy-preserving DOM signals (credential fields, external form actions, brand impersonation), scored into an explainable risk breakdown by URL, DOM, threat intelligence, TLS, domain age, and ML.
• Backend enrichment (FastAPI). /analyze, /report, /health; PhishTank threat intel, backend TLS + Certificate Transparency inspection, RDAP domain-age lookups — each with URL normalization, TTL caching, timeouts, and clean degradation when unavailable.
• Extension (MV3). React popup with a risk breakdown and feedback controls, an options page (backend URL, timeout, overlay), and a dismissible warning overlay for dangerous results. Works fully offline; the backend only enriches.
• ML. Training and evaluation pipeline on a real PhishTank + Tranco dataset, with SHAP per-prediction explanations and documented limitations (see ML methodology).
• Quality & safety. Unit tests plus a shared ext/backend scoring contract and a real-Chromium E2E smoke test; rate limiting, structured diagnostics with no sensitive payloads, host-only SQLite feedback, Docker, and CI (backend, extension, security, PR Guardian).

Screenshots

Safe result	Suspicious result	Dangerous result

Local-only mode (backend unavailable)	Danger overlay

Architecture

Chrome page
  -> content script extracts non-sensitive DOM signals
  -> popup computes local heuristic score
  -> popup optionally calls FastAPI /analyze
  -> backend adds URL, threat intel, TLS, and ML signals
  -> popup shows score, label, confidence, risk breakdown, and feedback controls
  -> dangerous results can display a dismissible page overlay
  -> development diagnostics expose counters only

The extension never sends full HTML, form values, passwords, or typed emails. The backend receives only the current URL and technical DOM features.

Stack

• Extension: TypeScript, React, Vite, Chrome Extension API, Manifest V3.
• Backend: Python, FastAPI, Pydantic, httpx, scikit-learn, pandas, joblib.
• Quality: pytest, ruff, TypeScript checks, GitHub Actions.
• Runtime: Docker and Docker Compose.

Development Setup

Backend

Linux / macOS

python -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements-dev.txt
uvicorn app.main:app --app-dir backend --reload

Windows

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r backend/requirements-dev.txt
.\.venv\Scripts\python.exe -m uvicorn app.main:app --app-dir backend --reload

Health check:

curl http://localhost:8000/health

Interactive API documentation is available at http://localhost:8000/docs while the backend is running.

Extension

cd extension
npm install
npm run build

Load extension/dist in Chrome:

1. Open chrome://extensions.
2. Enable Developer mode.
3. Select “Load unpacked”.
4. Choose the extension/dist folder.

The extension works locally without the backend. When the backend is available at http://localhost:8000, the popup enriches the local result with backend analysis.

Extension settings are available from the popup settings button or Chrome extension details page. The default backend is http://localhost:8000.

Tests

Backend:

.\.venv\Scripts\python.exe -m pip install -r backend/requirements-dev.txt
pytest backend/tests

Extension:

cd extension
npm run lint
npm run test
npm run build
npm audit --audit-level=high

ML demo:

python ml/train_model.py
python ml/evaluate_model.py

Docker:

docker compose build
docker compose up backend

Review automation:

python scripts/ci/pr_guardian.py --all

Demo readiness:

python scripts/dev/check_demo.py

Configuration

Copy .env.example to .env for local overrides. No real keys are committed.

Variable	Default	Description
PHISHTANK_API_KEY	(empty)	Optional PhishTank application key. Omit to skip threat intel.
PHISHTANK_USER_AGENT	phishtank/phishlens-demo	User-Agent sent with PhishTank requests (required by their API).
PHISHLENS_ALLOWED_ORIGINS	http://localhost:5173	Comma-separated CORS origins. Add chrome-extension://* only for local dev.
PHISHLENS_CHROME_EXTENSION_IDS	(empty)	Comma-separated Chrome extension IDs for production CORS.
PHISHLENS_ENABLE_THREAT_INTEL	true	Enable/disable PhishTank lookups.
PHISHLENS_ENABLE_TLS_ANALYSIS	true	Enable/disable backend TLS certificate inspection.
PHISHLENS_ENABLE_CT_LOG_LOOKUP	true	Enable/disable Certificate Transparency log lookups (crt.sh) as an additional TLS risk signal.
PHISHLENS_ENABLE_DOMAIN_AGE_LOOKUP	true	Enable/disable RDAP domain-registration-age lookups.
PHISHLENS_EXTERNAL_TIMEOUT_SECONDS	4.0	Timeout for external backend enrichment calls such as PhishTank, RDAP, and crt.sh.
PHISHLENS_MODEL_PATH	app/models/phishlens_model.joblib	Path to a trained joblib model artifact.
PHISHLENS_BRAND_DOMAINS_PATH	app/data/brand_domains.json	Path to the curated brand-domain list used for typosquat/brand-impersonation detection.
PHISHLENS_ENABLE_DIAGNOSTICS	true	Expose aggregate counters at GET /diagnostics.
PHISHLENS_DIAGNOSTICS_TOKEN	(empty)	When set, GET /diagnostics requires X-Diagnostics-Token: <value>.
PHISHLENS_ENABLE_RATE_LIMITING	true	Enable in-memory sliding-window rate limits.
PHISHLENS_ANALYZE_RATE_LIMIT	60	Max /analyze requests per window per IP.
PHISHLENS_REPORT_RATE_LIMIT	20	Max /report requests per window per IP.
PHISHLENS_RATE_LIMIT_WINDOW_SECONDS	60	Rate-limit window in seconds.
PHISHLENS_BEHIND_PROXY	false	Trust X-Forwarded-For when behind nginx / Caddy / ALB.
PHISHLENS_FEEDBACK_DB_PATH	feedback.db	SQLite path for feedback metadata. Set to "" to disable.
PHISHLENS_ENABLE_DEMO_THREAT_SOURCE	false	Enable localhost-only dangerous demo signal.

Extension settings:

• Backend URL: defaults to http://localhost:8000.
• Timeout: clamped between 1000 ms and 10000 ms.
• Danger overlay: enabled by default and only shown for dangerous results.

Ethical And Privacy Notice

PhishLens is defensive only. It must not collect credentials, typed emails, private form content, or full page HTML. It is a risk-assistance tool, not a phishing verdict authority. False positives and false negatives are expected, especially outside the limited dataset and signal coverage documented below.

Local Demo

Run the backend, demo pages, and extension locally:

$env:PHISHLENS_ENABLE_DEMO_THREAT_SOURCE="true"
.\.venv\Scripts\python.exe -m uvicorn app.main:app --app-dir backend --reload
python demo/serve_demo.py
cd extension
npm run build

Load extension/dist in Chrome and visit:

• http://localhost:8080/pages/safe.html
• http://localhost:8080/pages/suspicious.html
• http://localhost:8080/pages/phishlens-demo-dangerous-login-secure-update.html

The dangerous demo requires PHISHLENS_ENABLE_DEMO_THREAT_SOURCE=true and only matches localhost URLs containing phishlens-demo-dangerous. Use localhost rather than 127.0.0.1: the backend rejects private IP literals as an SSRF safeguard.

Package the extension:

cd extension
npm run package

The zip is written to extension/release/.

Limitations

• The ML model is trained on a real PhishTank + Tranco dataset (1200 rows; 5-fold CV accuracy 0.907 ± 0.008, hold-out accuracy 0.92 on 396 rows — precision 0.87/recall 0.99/F1 0.93 for legitimate URLs, precision 0.99/recall 0.85/F1 0.92 for phishing, confusion matrix [[197, 1], [29, 169]]; see docs/ml-methodology.md for a known URL-length dataset bias that was found and fixed and the full classification report). These numbers do not describe the model’s production behavior: DOM features (has_password_field, num_forms, etc.) are hardcoded to 0 for every training row because the dataset is built from URLs only, without a live browser session — but backend/app/services/ml_service.py feeds real DOM features from the extension’s content script at inference time. The reported accuracy/precision/recall reflect a URL-only model; the 6 DOM columns it sees in production were never exercised with real variation during training, so any influence they have on live predictions is unvalidated extrapolation, not something these metrics back up.
• TLS analysis runs from the backend and may differ from what the browser sees behind proxies or TLS inspection.
• PhishTank checks require a user-provided API key and are rate limited.
• Feedback storage is intentionally minimal: hostname, labels, note presence, request ID, and timestamp only. It is not a replacement for a reviewed training dataset.
• Diagnostics are development counters only and should not be treated as production telemetry.
• In-memory rate limiting is process-local and resets when the backend restarts.
• The current build prioritizes explainability and safe defaults over coverage.

Lessons Learned

A few things found during a deliberate self-audit of this project, kept here instead of quietly fixed and forgotten, because how a bug was found and corrected is often more informative than the fact that the code is now clean:

• The content script and danger overlay were silently broken in real Chrome, while every automated check stayed green. Adding Firefox support introduced an ES import statement into two files that execute as classic, non-module scripts (MV3 content scripts and chrome.scripting.executeScript-injected files can’t be modules). tsc, vitest, and vite build all passed, because none of them load the bundle in an actual browser — Vitest mocks the module graph, and Vite’s build doesn’t check runtime module-format compatibility. Found by recording this README’s demo GIF with a real Playwright + Chromium session instead of a screen recording tool, which surfaced “Could not establish connection” the moment the popup tried to collect DOM features. Fixed by splitting the build into two Rollup passes — ES modules for popup/options/the service worker, IIFE for the content script and overlay. The lesson: a green test suite proves the code you tested, not the environment you didn’t.
• A 95% ML accuracy number was hiding a trivial shortcut. The training dataset built legitimate URLs as bare domain roots (https://example.com/) while phishing URLs from PhishTank carry real paths, so url_length alone separated the two classes almost perfectly — the model was learning “has a path” instead of phishing patterns. Fixed by adding realistic paths to legitimate URLs; honest accuracy dropped to ~91% CV. Detailed in docs/ml-methodology.md.
• The offline fallback’s “dangerous” label was effectively unreachable. It needed ~92% of its own maximum possible score because the threshold (60) was hand-picked against a smaller scale than the backend’s (70) without reconciling the two. Fixed by scaling the local score onto the backend’s 0-100 range before applying the same threshold.
• Backtesting the URL heuristic weights surfaced their own blind spot. Without typosquat/homograph signals (which need the raw domain — not stored in the dataset for privacy), the remaining numeric-only heuristics never reach the scoring cap on this dataset. That’s not a miscalibration; it confirms typosquat/homograph detection carries most of the URL category’s weight in practice. See docs/ml-methodology.md.
• A new external call (RDAP) silently exceeded the extension’s request timeout. Adding domain-age lookups didn’t itself cause this — profiling showed the real cost was a one-time, multi-second sklearn import triggered by lazily unpickling the ML model on the first request, which also blocked the event loop for concurrent requests. Fixed by warming up the model from a FastAPI lifespan handler at startup; first-request latency dropped from ~5.5s to ~1.4s.
• The heuristic-only “confidence” number is overconfident, not just unproven. A reliability diagram against the committed dataset showed every confidence bin sitting below the perfectly-calibrated line, and the bin holding 96% of rows (confidence ≈ 0.90) was only ~52% accurate — barely better than guessing. Not “fixed” with a quick correction factor in this round, because calibrating against a dataset that can’t exercise typosquat/homograph/DOM/TLS/domain-age/threat-intel signals would just calibrate to this benchmark’s blind spots. Documented as a known limitation instead: treat the heuristic-only confidence as a tie-breaker, not a probability. See docs/ml-methodology.md.

Roadmap

See docs/roadmap.md.

Review And Release Process

PhishLens uses deterministic review gates instead of relying on a single reviewer. See docs/review-methodology.md and docs/release-process.md.

Publication preparation lives in docs/chrome-web-store.md, with permission rationale in docs/permissions.md.

This site is open source. Improve this page.