ShadowShield

Real-time protection against phishing, fake login pages, and scam sites — right in your browser.

---

What it does

ShadowShield watches the pages you visit and warns you before you hand your password to a fake login page. It's a Chrome extension (Manifest V3) that scores every page in real time using a layered approach — no single check decides anything on its own:

• Heuristics — around 30 explainable signals across ~85 commonly-impersonated brands: lookalike domains, homoglyphs, punycode tricks, brand names hidden in subdomains, credential-bait URLs, suspicious TLDs, and more.
• Live threat feeds — pulls confirmed-phishing lists (OpenPhish, URLhaus, Phishing.Database) and blocks known-bad URLs at the network layer, before the page even loads.
• A credential guard — pauses password submissions to cross-domain, unencrypted, or brand-new domains and asks you first.
• An optional AI second opinion — bring your own API key (Claude, GPT, Gemini, or any OpenAI-compatible endpoint, including a local model) and suspicious pages get a deeper look. Off by default.

Every verdict is explainable. The popup tells you why a page was flagged, in plain language — not just a red light.

Why I built it this way

I didn't want to build another extension that claims "AI-powered protection" and calls it a day. I wanted to know if it actually worked — and to be honest about the answer.

So I benchmarked the detection engine against 500 real phishing URLs and 500 legitimate sites (from Google's CrUX dataset). The first run was humbling: 7% detection. Instead of hiding that, I dug into which phishing URLs slipped through, added signals to catch what I was missing, and re-measured. It's now at 31% on the URL layer alone, with false positives under 1%.

That number isn't the whole story — it only measures the URL heuristics in isolation, not the feeds, page-content analysis, or AI layer on top. But it's a real, reproducible floor, and I can prove the improvement. You can re-run the benchmark yourself:

node benchmark/run-benchmark.js

Install

1. Download the latest release (grab the .zip under Assets) — or clone this repo — and unzip it
2. Open chrome://extensions
3. Turn on Developer mode (top-right)
4. Click Load unpacked and pick the folder
5. Pin the shield to your toolbar

Security — I treated my own code as untrusted

Building a security tool that isn't itself secure would be a bad joke, so I put the codebase through the same scrutiny I'd expect from a review:

• Static analysis (Semgrep, 400+ rules) across the extension and a companion Node/Express API. It found real bugs in my own code — an open-redirect / javascript: URI issue, a reflected-origin CORS misconfiguration, and an unpinned GitHub Actions supply-chain risk. Each one is fixed, with a regression test and a written explanation of why it mattered. See backend/SECURITY_REVIEW.md.
• A STRIDE threat model of the extension's own attack surface (THREAT_MODEL.md) — including the question I kept coming back to: what happens if a threat feed I trust gets poisoned? (Answer: a per-feed cap, so no single compromised source can dominate the blocklist.)
• Defense-in-depth in the code itself — strict CSP, zero eval and zero innerHTML (enforced by a test), message-sender verification so no web page can talk to the extension's core, and API keys kept in device-local storage that never syncs.
• 67 automated tests (46 for the extension, 21 for the backend) gate every change in CI.

Privacy

Short version: there's no ShadowShield server, and I never receive any of your data.

• All scanning happens locally in your browser.
• No accounts, no analytics, no tracking.
• Passwords, form contents, and keystrokes are never read.
• Three features make network requests, all documented in PRIVACY.md: downloading the public threat feeds, an occasional domain-age lookup (only on pages that ask for a password or already look suspicious), and — only if you turn it on with your own key — the AI check.

How it's built

manifest.json          MV3 config
background.js          service worker — feeds, blocking, AI relay, state
content.js             per-page scan + warning UI
heuristics.js          the scoring engine (~30 signals, ~85 brands)
trackers.js            tracker detection (~47 services)
pages/                 popup, settings, and the block screen
backend/               reference "report a site" API + OWASP review
benchmark/             the reproducible detection benchmark
tests/                 test suite

Releases

Versioning is automated with semantic-release driven by Conventional Commits, so every merge to main that warrants it cuts a version bump, changelog entry, tag, and GitHub Release with a downloadable build — no manual steps. See the Releases page for history.

Honest limitations

I'd rather be upfront than oversell:

• The 31% benchmark is the URL layer only — the feeds, page-content checks, and AI aren't in that number, so real-world coverage is higher, but I haven't put a measured figure on the full stack yet.
• Heuristics will never catch everything; this is a safety net, not a guarantee. Use good judgment too.
• The AI layer needs your own API key, so it's opt-in by nature.

Contributing

Issues and PRs welcome — especially if you can get a phishing page past it. See CONTRIBUTING.md. If you find a security issue, SECURITY.md has the disclosure process.

License

MIT — see LICENSE.