PhishShield is a production-grade, AI-driven cybersecurity system that detects and blocks malicious URLs and zero-day phishing attacks in real-time. It intercepts network traffic via a Chrome Extension and routes it through a multi-layered, low-latency "Early-Exit" Machine Learning pipeline.
- "Bounce" Architecture Interception: A Manifest V3 Chrome Extension that synchronously halts navigation to unverified links, buffering them with a modern interstitial UI.
- Early-Exit Inference Pipeline: Employs multiple stages of circuit-breaking to clear benign links in milliseconds without needing to execute heavy sandbox analysis.
- Multi-Modal AI Engine:
- URL & Content DistilBERT: NLP parsing for phishing URL vernacular and HTML DOM structures.
- PHP XGBoost Classifier: Static heuristic engine identifying backend web-shells, backdoors, and logic exploits natively.
- Behavior & Zero-Day Isolation Forests: Unsupervised anomaly detection tracking sandbox redirects and extreme entropy.
- Headless Sandbox Triage: Asynchronous headless rendering using Playwright to extract DOM paths and catch direct
.exe/.batfile payloads before they hit the disk. - Anti-False Positive Mitigations: Custom calculus to prevent ad-heavy free-hosting subdomains from being categorized as phishing if they lack credential harvesting mechanisms.
PhishShield utilizes an orchestration engine across 3 phases:
- Stage 1 (Liveness & Fast-Path): URL TLD heuristics and URL-DistilBERT determine if the string alone is highly trustworthy.
- Stage 2 (DOM Extraction): If suspicious, the Sandbox pulls HTML structural proxies. Content-DistilBERT scores the DOM.
- Stage 3 (Full Anomaly Fusion): XGBoost handles exposed backend signatures while Isolation Forests map behavioral footprints. All scores run through a weighted Risk Fusion matrix.
phishshield/
├── extension/ # Chrome Manifest V3 Extension (UI & Interceptors)
├── server/
│ ├── api/ # FastAPI App & Endpoints
│ ├── inference/ # Core ML Pipeline & Risk Engine
│ ├── models/ # Neural Networks & XGBoost architectures
│ ├── php_analyzer/ # Static codebase analyzers
│ └── sandbox/ # Async Playwright Headless Browser
├── data/ # Crawled legitimate & phishing domains (CSV)
├── run_server.py # Production Server deployment script
├── run_training.py # ML Retraining pipeline
└── requirements.txt # Python dependencies
Ensure you have Python 3.10+ installed.
# Clone the repository
git clone https://github.com/yourusername/phishshield.git
cd phishshield
# Create a virtual environment
python -m venv venv
source venv/bin/activate # On Windows use: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Install Playwright sandbox browsers
playwright install chromium(Note: Trained weights should be placed in models/ or trained locally)
If you need to train models from scratch on the provided datasets, you can utilize the training script or Colab notebooks:
python run_training.pyLaunch the production API server:
python run_server.py --port 8000 --workers 4- Open Google Chrome and navigate to
chrome://extensions/. - Enable Developer mode in the top right corner.
- Click Load unpacked.
- Select the
extension/folder from this repository. - The extension is now active and monitoring navigations.
POST /scan: Submit a single URL{"url": "https://example.com", "deep_scan": false}.POST /scan/batch: Submit an array of URLs for bulk risk analysis.POST /report: User crowdsourced endpoint to classify sites as safe/malicious.GET /health: Model status and RAM payload capacity checks.
Pull requests are welcome! If you're contributing new ML architectures, ensure they do not exceed a total 50ms latency overhead over the Fast-Path circuit breakers. Please see run_tests.py for ensuring regression stability.
This project is licensed under the MIT License.