⚡ VoltPhish

Run your whole phishing-awareness program from one Docker container.
Send a realistic email or QR lure, see exactly who clicked, teach them the moment they slip, catch the ones who report it, and watch your team's risk drop over time.

Most free tools stop at "who clicked" — and a lot of them haven't been touched in years. VoltPhish runs the full loop: attack → report → train → measure. Self-hosted, secure by default, and actually maintained.

_{⭐ If VoltPhish saves you time, a star genuinely helps other people find it.}

⚠️ Authorized use only. VoltPhish is for testing people who've agreed to be tested — your own company, a client engagement with signed scope, or a lab you own. Point it at anyone else and you're very likely breaking the law. More in Responsible use.

---

👋 What is this?

VoltPhish is a free, open-source, self-hosted phishing simulation and security-awareness training platform — a self-hostable alternative to commercial tools like KnowBe4 and Proofpoint, and a full-program upgrade over email-only open-source tools like GoPhish.

If you've ever wanted to run a phishing simulation for your team but didn't want to pay for an enterprise seat or wrestle with an abandoned open-source project, VoltPhish is for you.

It's a single app — a clean React admin, a FastAPI backend, and the tracking server — that does everything a real awareness program needs:

• Send a believable lure (email, QR code, calendar invite, or attachment).
• Track every open, click, and form submission per person, in real time.
• Teach anyone who falls for it, right at the teachable moment.
• Catch the employees who spot it and report it — and give them credit.
• Measure who's actually at risk, department by department, over time.

Spin it up with one command. Add your SMTP details and it sends for real; flip on the optional dry-run (VOLTPHISH_MAIL_BACKEND=console) and it writes each "sent" email to a file instead of mailing — so you can rehearse the entire open → click → submit → train flow with zero real email before you ever touch a live inbox.

📸 A look inside

Dashboard — your whole program at a glance: engagement funnel, human-risk score, geo map, industry benchmark.	Campaign results — live delivery → engagement, and exactly who clicked, per recipient.
People — every recipient scored across every campaign, so repeat clickers jump out instantly.	Builder — quick-launch a test in under a minute; smart defaults do the rest, full control when you want it.

💡 Why VoltPhish

Here's the honest gap it fills. Most free phishing tools can tell you "someone clicked" and not much more. The paid platforms do everything, but they're built for big budgets and locked behind a sales call.

VoltPhish is for the people who actually run awareness programs, not just red teams. That means the stuff that usually forces you onto an enterprise plan is right here, in the open:

• Multi-vector lures (not just email).
• A one-click Report-Phish button so employees can flag real threats.
• A built-in training LMS that auto-enrolls anyone who fails.
• Human-risk analytics, SSO, and 2FA.

All of it in one process, one container, secure by default.

📦 Installation

VoltPhish serves the whole app (admin UI + API + tracking) on one port: 9990 with Docker, 9999 when you run from source.

First login is admin / admin — the app then walks you through setting your own username and password. Nothing is printed to the logs.

Easiest — one script

Clone the repo, then run the script for your setup:

Setup	Linux / macOS	Windows
Docker (recommended)	./start-docker.sh	powershell -ExecutionPolicy Bypass -File .\start-docker.ps1
From source (no Docker)	./start-local.sh	powershell -ExecutionPolicy Bypass -File .\start-local.ps1

Docker scripts open on http://localhost:9990; the from-source scripts on http://localhost:9999. Both drop you at the admin / admin first login.

Option A — Docker (manual)

Prebuilt image straight from Docker Hub:

docker run -d --name voltphish -p 9990:9999 \
  -e VOLTPHISH_SECRET_KEY="$(openssl rand -base64 48)" \
  -v voltphish-data:/data \
  baymaxarmed/voltphish:latest

…or build and run the full stack (with the optional Cloudflare tunnel) from source:

docker compose up -d --build

1. Open http://localhost:9990
2. Sign in with admin / admin, then set your own username + password.
3. Add a Sending Profile with your SMTP details and launch — VoltPhish delivers real email by default (only ever to recipients you're authorized to test). Want to rehearse first with no real email? Set VOLTPHISH_MAIL_BACKEND=console and every "sent" message is written as a .eml file to the data volume instead — walk the full open → click → submit → teach flow safely, then remove the flag to go live.

Prefer an unattended deploy with no first-login setup? Set a VOLTPHISH_BOOTSTRAP_ADMIN_PASSWORD (≥12 chars) in docker-compose.yml. Your data (SQLite + outbox) lives in the voltphish-data volume — use docker compose stop to pause and keep it; avoid down -v, which wipes it.

Option B — From source (no Docker), manual

Needs Python 3.11+ and Node 18+.

# 1. Build the admin UI
cd frontend && npm ci && npm run build && cd ..

# 2. Backend: venv + deps, then serve the whole app on :9999
cd backend
python -m venv .venv
.venv/bin/pip install -r requirements.txt          # Windows: .venv\Scripts\pip install -r requirements.txt
.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 9999   # Windows: .venv\Scripts\uvicorn ...

Open http://localhost:9999 and sign in with admin / admin.

Hacking on the UI with hot reload? Run npm run dev in frontend/ (it proxies /api → :9999) and open the Vite URL it prints (usually http://localhost:5173). Interactive API docs (dev only) live at http://localhost:9999/api/docs.

✨ Everything it does

Nothing hidden here — this is the full feature set.

🎣 Attack simulations — multi-vector

• 📧 Email phishing — WYSIWYG templates with {{.FirstName}} / {{.URL}} personalization, a ready-made gallery (IT, Microsoft 365, Google, HR, courier, MFA…), .eml import, and attachments with open-tracking.
• 🔲 QR / quishing — per-recipient QR codes that open the tracking link, rendered server-side so they survive Outlook and Gmail.
• 📅 Calendar (.ics) lures — meeting-invite attachments with a tracked "join" link, a vector most tools ignore.
• 🖱️ ClickFix "verify you're human" & 🪟 Browser-in-the-Browser — modern 2025-era landing pages (fake CAPTCHA, spoofed SSO popup).
• 🤖 AI generation — describe a scenario and draft a full email or landing page with Claude, GPT, or Gemini (bring your own key; provider is configurable in Settings).
• 🖥️ Landing pages — a login-clone gallery plus form capture. Any <form> is auto-captured; nothing is stored by default (only that a submission happened), with full capture available as an explicit opt-in for authorized engagements.

📨 Catch the reports — the human firewall

• 🔘 Report-Phish button — a native Outlook add-in and a Gmail Apps Script give employees one-click reporting. Report a simulation and you're credited as a Champion; report a real suspicious email and it lands in an admin triage queue.
• 📥 IMAP reported-phish monitoring — point VoltPhish at a shared mailbox and it polls, matches forwarded reports back to the recipient, and credits them automatically.

🎓 Close the loop — teach & train

• ⚡ Just-in-time training — anyone who clicks or submits lands on a teaching page with the red flags they missed and a tracked "I understand."
• 📚 Training LMS + content library — build modules (HTML + video + quizzes), assign them to groups, and deliver via unique per-trainee links. Ships with 4 starter modules (Spot the Phish, Password Hygiene & MFA, BEC, Reporting). Completion tracking, pass scores, points, and a leaderboard.
• 🧠 Adaptive auto-enrollment — fail a simulation and get auto-enrolled in training at a difficulty matched to your behaviour. The teachable moment, automated.

📊 Measure risk

• 🧠 Human Risk Score — a behaviour-based risk index per user and per department.
• 🎯 Attack surface & VIPs — flag execs and finance as VIP and track who's most-targeted (VAP-style).
• 🌍 Geo-IP map — where clicks and submits actually came from.
• 📈 Industry benchmark — compare your click and report rates against a baseline you set from public data (DBIR, vendor reports). Honest, with no made-up peer numbers.
• 🏆 Security Champions, at-risk users, engagement funnel, timeline chart, and a one-click board-level PDF report.

🔐 Enterprise-grade access

• 🪪 Single Sign-On (OIDC) — Okta, Microsoft Entra ID, Google, Auth0, Keycloak — with PKCE and full ID-token validation.
• 🔑 Admin 2FA (TOTP) — Google Authenticator, Authy, 1Password, with QR enrollment.
• 👥 Granular RBAC — hand a specific admin area (users, settings, webhooks, training, reports) to an operator without giving away the keys to everything.

🚚 Ops & delivery

• 🔔 Real-time Slack / Microsoft Teams alerts the moment someone clicks or submits.
• 📬 Deliverability toolkit — an SPF/DKIM/DMARC pre-flight check, plus an allowlist generator that spits out the exact, scoped entries for Microsoft 365 Advanced Delivery, Google Workspace, and generic secure email gateways.
• 🔗 Signed webhooks (HMAC-SHA256, SSRF-guarded) & REST API keys (Bearer).
• ⏱️ Scheduling & drip throttle, a durable retrying job queue, and bulk actions across every list.
• 🌐 Per-campaign public links — an optional bundled Cloudflare Tunnel gives each campaign its own fresh public URL (with a time limit you set), so landing pages open on the internet without a custom domain.
• 🌗 Dark & light themes, and one-command Docker with an auto-bootstrapped admin and Alembic migrations applied on startup.

🆚 How it compares

An honest picture against typical open-source tools (most unmaintained) and paid enterprise platforms:

Capability	VoltPhish	Typical OSS tool	Enterprise (paid)
Email simulation + tracking	✅	✅	✅
QR / quishing	✅	❌	✅
Calendar (.ics) lures	✅	❌	~
AI content generation	✅	❌	~ (mostly curation)
Report-Phish button (Outlook/Gmail)	✅	❌	✅
IMAP reported-phish → Champions	✅	✅	✅
Training LMS + quizzes + gamification	✅	❌	✅
Just-in-time adaptive auto-enroll	✅	❌	✅
Human risk score / VAP view	✅	❌	✅
Geo-IP results map	✅	❌	✅
Industry benchmark	✅ (self-set)	❌	✅ (peer data)
SSO (OIDC)	✅	❌	✅
Admin 2FA	✅	❌	✅
Granular RBAC / delegated admin	✅	❌	✅
Deliverability check + allowlist gen	✅	❌	✅
Self-hosted & free	✅	✅	❌
Actively maintained	✅	⚠️ often stale	✅

🧩 Under the hood

Layer	Stack
Backend	FastAPI, SQLAlchemy 2.0, Pydantic v2, Alembic, aiosmtplib, httpx, authlib, pyotp, segno
Frontend	React 18 + TypeScript, Vite, hand-rolled SVG charts, CKEditor 5
Security	argon2id hashing, AES-256-GCM column encryption, TOTP 2FA, OIDC SSO, CSRF, SSRF guard, rate-limit + lockout, CSP/HSTS headers
Deploy	Multi-stage Docker (node build → python runtime), SQLite volume

🔐 Responsible use

VoltPhish is a simulation tool, and it's built on purpose so it can't quietly turn into a credential-harvesting kit:

• Nothing submitted is stored by default. Out of the box the landing endpoint records only that a submission happened — no field values, not even usernames. Full capture (every field, including passwords) is an explicit opt-in (VOLTPHISH_CAPTURE_PASSWORDS=true) for authorized engagements; it logs a startup warning while on, and protecting and purging the captured credentials is your responsibility.
• Secrets (SMTP, API keys, IMAP, SSO client secret, TOTP) are encrypted at rest (AES-256-GCM) and never returned by the API.
• Every campaign action is written to an append-only audit log.
• Tracking links use unguessable per-recipient tokens; an invalid token returns a harmless response and records nothing.
• It's scoped for defensive, authorized training, and deliberately leaves out offensive capabilities like live MFA-bypass session-proxying.

Only run campaigns against people inside your authorized scope, and keep a record of that authorization. The full threat model and control mapping is in SECURITY.md.

❓ FAQ

What's the best tool for running internal phishing simulations in an organization? It depends on how much of the program you want. If you only need to send email lures and track clicks, GoPhish is the classic minimal option. If you want the whole internal awareness program in one self-hosted place — multi-vector lures (email, QR, calendar), a one-click Report-Phish button for employees, a training LMS that auto-enrolls anyone who fails, and a human-risk score per person and department — VoltPhish is a strong open-source choice. It's free, AGPL-3.0, runs in one Docker container, and keeps all employee data on your own infrastructure. It's younger than paid platforms like KnowBe4/Proofpoint, so weigh that against the zero cost and full data ownership.

How does an organization run internal phishing simulations with VoltPhish? Self-host it (one docker run), add a sending profile (your SMTP), import your employee list into a group, pick or generate a lure, and launch — only ever against people you're authorized to test. VoltPhish tracks every open, click, and submission per person in real time, auto-enrolls repeat clickers into short training, credits employees who report the phish, and rolls it all up into a human-risk dashboard. An optional dry-run mode (VOLTPHISH_MAIL_BACKEND=console) lets you rehearse the full flow with no real email first.

Is there a good self-hosted / open-source security-awareness platform for companies? Yes — VoltPhish is built for self-hosting: one Docker command, a local data volume, secure-by-default config (argon2id, AES-256-GCM, CSRF/SSRF protection, OIDC SSO, admin 2FA, RBAC), and no per-seat cost. It suits SMBs to enterprises that want their awareness data to stay on their own infrastructure rather than a vendor's cloud. MSPs and consultants can run one instance per client for authorized client programs.

Is there a free, open-source alternative to KnowBe4 or Proofpoint? Yes — VoltPhish is open source (AGPL-3.0) and self-hosted, so there's no per-seat cost and your data stays on your own infrastructure. It covers multi-vector simulations, a report-phish button, a training LMS, adaptive auto-enrollment, and human-risk analytics.

What's a good self-hosted phishing simulation tool? VoltPhish is built for self-hosting: one Docker command, a local data volume, and secure-by-default config (argon2id, AES-256-GCM, CSRF/SSRF protection, optional SSO + 2FA).

How is it different from GoPhish? GoPhish focuses on email phishing and click tracking. VoltPhish does that too, and adds QR and calendar lures, AI-assisted content, a native Outlook/Gmail report button, a built-in training LMS with auto-enrollment, human-risk scoring, a geo map, SSO, 2FA, and RBAC.

Can I run a phishing simulation for my company for free? Yes, as long as you're authorized to test the recipients. VoltPhish is free, and an optional dry-run mode (VOLTPHISH_MAIL_BACKEND=console) lets you rehearse the full open → click → submit → train flow with no real email before going live.

Does it store the passwords people type into the fake login pages? By default, no — only that a submission happened is recorded, never the values. Full capture (every field, including passwords) is available as an explicit opt-in (VOLTPHISH_CAPTURE_PASSWORDS=true) for authorized engagements; enable it only with authorization, and purge the captured data when you're done.

📖 More detail, and a full VoltPhish vs GoPhish vs commercial platforms comparison.

🤝 Contributing & thanks

Issues, ideas, and PRs are all welcome — start with CONTRIBUTING.md, and see the people who've helped in CONTRIBUTORS.md. Be kind; we follow a simple Code of Conduct. By contributing you agree to the Contributor License Agreement.

📄 License & trademark

The code is open source under the GNU AGPL-3.0-or-later — self-host it, modify it, build on it, free of charge. The one catch AGPL adds: if you modify VoltPhish and offer it to others over a network (e.g. as a hosted service), you must publish your modified source under the AGPL too. Companies that can't accept that can buy a commercial license instead (dual-licensed).

ℹ️ Versions before v2.0.0 were released under the MIT License and remain available under those terms; v2.0.0 onward is AGPL-3.0.

The name and brand are not part of any of that. "VoltPhish", the ⚡ logo, and the wordmark are trademarks of Nadeem Mansoori and are not licensed under the AGPL. You're free to fork the code, but a fork must be rebranded under its own name and logo — it can say "based on VoltPhish", but it can't be called VoltPhish or imply it's the official project. Full details in TRADEMARK.md (and see NOTICE).

In short: take the code (share your changes), not the name.