A self-hosted, 7-layer phishing detection pipeline that scans your inbox in real time — running entirely on-prem, with a locally-hosted LLM as the final verdict layer. No email content ever leaves the machine it runs on.
Built for environments where privacy and control matter as much as detection accuracy — designed with government/enterprise inbox protection in mind.
Most phishing filters are either a black box (SaaS tools that route your email through a third party) or a simple keyword blocklist. PhishGuard is neither: it's a transparent, layered detection engine you can read, audit, and run entirely on your own infrastructure — from IMAP fetch to final verdict, nothing is sent to an external API.
- 7-layer detection pipeline — authentication (SPF/DMARC), domain intelligence (homograph/lookalike detection), psychological manipulation analysis, link scanning, sender behavior profiling, threat intelligence, RAG-based pattern matching against known scam campaigns, and a locally-hosted LLM as the final AI judge
- Real-time dashboard — live threat feed, layer-by-layer score breakdown, full email content viewer, one-click quarantine
- Attachment malware scanning — real signature-based detection via ClamAV, run in its own isolated container (not just heuristic file-type checks)
- Push notifications — real device alerts on confirmed threats, not just a dashboard badge
- Human-in-the-loop verdict override — mark false positives safe, or reassign a missed scam, with confirmation before anything that permanently affects future detection
- Cascading analysis — cheap deterministic layers run first; the expensive LLM layer is only invoked when the verdict genuinely depends on it, keeping the system usable on modest hardware
- Fully local LLM — runs on Ollama, no API keys, no external calls, no content leaving your machine
IMAP Inbox
│
▼
Celery Beat (polls every 15s) ──► Celery Worker (single-concurrency queue)
│
▼
┌─────────────────────────┐
│ 7-Layer Risk Engine │
├─────────────────────────┤
│ 1. Authentication (SPF/ │
│ DMARC/spoofing) │
│ 2. Domain Intelligence │ ◄── run concurrently
│ 3. Psychological Analysis│ (Phase 1)
│ 4. Link Scanner │
│ 5. Sender Behaviour │
│ 6. Threat Intelligence │
│ 7. Attachment Scanner │──► ClamAV (isolated container)
├─────────────────────────┤
│ RAG Pattern Matching │ ◄── Phase 2
├─────────────────────────┤
│ Local LLM Verdict │ ◄── Phase 3 (cascade-skipped
│ (Ollama, on-prem) │ when earlier layers already
└─────────────────────────┘ settle the verdict)
│
▼
Postgres (threat log) + Redis (queue)
│
▼
Alert + Push Notification ◄──► React Dashboard
| Layer | Technology |
|---|---|
| Backend / API | FastAPI, Celery, Redis |
| Database | PostgreSQL, SQLAlchemy |
| AI / LLM | Ollama (local), custom RAG pattern matching |
| Malware scanning | ClamAV (isolated daemon container) |
| Frontend | React, Vite, Tailwind |
| Infra | Docker Compose |
- Docker & Docker Compose
- 6GB+ RAM available to Docker (see Resource notes below)
- A Gmail (or IMAP-compatible) account with an app password for the inbox to monitor
git clone https://github.com/<your-username>/phishguard.git
cd phishguard
cp .env.example .envFill in .env with your own values (see Environment variables below — never commit this file, it's already gitignored).
docker compose up -d --build
docker compose logs -f workerFirst boot will take a few minutes — it pulls the base LLM model, builds the custom phishguard-fast model, and downloads ClamAV's signature database. Once you see the worker polling successfully, open the dashboard:
http://localhost:8080
See .env.example for the full list with descriptions. At minimum you'll need:
| Variable | Purpose |
|---|---|
EMAIL_ADDRESS / EMAIL_PASSWORD |
IMAP account to monitor (use an app password, not your real password) |
POSTGRES_PASSWORD |
Database password |
APP_SECRET_KEY |
API auth key — required on every dashboard/API request |
VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY |
Push notification keys — generate with scripts/generate_vapid_keys.py |
ABUSEIPDB_KEY, VIRUSTOTAL_KEY, GOOGLE_SAFE_BROWSING_KEY |
Optional threat-intel enrichment (layers degrade gracefully without these) |
The local LLM is the heaviest component. phishguard-fast is built on llama3.2:3b-instruct-q4_K_M (~2GB resident) rather than a larger model — this is a deliberate choice for a narrow, well-scoped classification task, not an open-ended reasoning one, and keeps the whole stack runnable on modest hardware (tested comfortably within a 6GB Docker memory allocation). If you have more headroom, swap the FROM line in Modelfile for a larger model and rebuild via docker compose run --rm ollama-init.
├── api/ # FastAPI app — routes, schemas
├── pipeline/ # Core detection engine
│ ├── layers/ # The 7 individual detection layers
│ ├── risk_engine.py # Orchestrates all layers, calculates final verdict
│ ├── worker.py # Celery tasks — fetch, queue, analyze
│ ├── alerting.py # Alert + push notification triggering
│ └── clamav_scan.py # Attachment malware scanning client
├── models/ # SQLAlchemy models + DB utilities
├── dashboard/ # React frontend
├── docker/ # Entrypoint + init scripts
├── Modelfile # Custom Ollama model definition
└── docker-compose.yml
If you find a vulnerability in this project, please see SECURITY.md for responsible disclosure guidelines rather than opening a public issue.
MIT — feel free to fork, adapt, and build on this. Attribution appreciated.
Built by Sabin — final-year BCA student focused on cybersecurity. Feedback and contributions welcome.