PhishUs

PhishUs is a self-hosted, multi-tenant phishing-simulation and security-awareness platform built on Django. It lets a security team create simulated phishing campaigns, send them to a list of recipients, track who opened, clicked, entered data, or reported the email, and follow up with awareness training content and reporting.

Development has stopped and this repository is no longer maintained. It is published as-is so others can use it, learn from it, or build on it.

⚠️ Disclaimer / Intended use

This software sends emails that impersonate legitimate communications and hosts pages designed to capture credentials or other input, for the purpose of measuring and training human susceptibility to phishing. That is exactly the same technical capability used in real phishing attacks.

• This project is intended only for authorized use by information security professionals running security-awareness campaigns against their own organization, or an organization that has given explicit, informed consent to be tested.
• Do not use this software to target anyone without clear authorization. Unauthorized use may be illegal in your jurisdiction (computer fraud, wire fraud, unauthorized access, and similar statutes) regardless of intent.
• The authors and contributors take no responsibility for how this software is used. You are solely responsible for obtaining proper authorization and complying with the law before running any campaign.
• This is a statement of intent, not an enforceable license term — see LICENSE.

Status and history

• No longer actively developed. No new features, and no guarantee that reported bugs will be fixed. Pull requests are welcome but may not be reviewed promptly.
• The project has a number of incomplete or half-built features (see Known limitations below). It was a working product, not a finished one.

Features

• Multi-tenant organizations — a super-admin manages multiple client organizations; each organization's staff only see their own data.
• Campaigns → scenarios → templates — a campaign is built from one or more scenarios (click-only, credential/data-entry, or malicious-attachment simulations), each pairing an email template with a landing page.
• Recipient management — import recipients with department, position, and location metadata; target campaigns at a location/department/position group or a custom list.
• Tracking — per-recipient tracking of sent, opened (tracking pixel or provider webhook), link-clicked, data-entered, and self-reported events, with timestamps for each.
• Post-click training — recipients who fail a scenario can be routed to awareness/training content.
• Reporting — per-campaign charts and results (reports app, built on django-chartjs).
• Landing pages & email templates — a template gallery keyed off files on disk (or a Cloud Storage bucket), so adding a new landing page is just adding an HTML file.
• Pluggable mail sending — send through the Mail services API or plain SMTP, configurable per organization (settings app → Mail Servers).
• Bilingual UI
• Basic subscriptions/billing scaffolding — subscriptions app models plans, invoices, and payments for a multi-tenant SaaS billing flow (not wired to a real payment gateway — see limitations).

Known limitations / missing features

This was a real, evolving product, not a polished reference app. Before you rely on it, be aware of:

• No automated test coverage. Every app has a tests.py, but they're all empty Django boilerplate.
• No production static-file pipeline configured for a plain server. STATIC_SERVED_FROM=local works fine with DEBUG=True; in PYTHON_ENV=prod (DEBUG=False) you'll need to run collectstatic and serve the result yourself (nginx, whitenoise, etc.) — see Deployment.
• Subscriptions/billing is scaffolding, not a working payment flow. The models and admin views exist; there's no payment gateway integration.
• reCAPTCHA is required to boot the app (RECAPTCHA_PUBLIC_KEY / RECAPTCHA_PRIVATE_KEY are read unconditionally in settings.py) — get a free key pair from Google even if you don't care about bot protection.
• Some in-app strings and comments still mix English and Arabic informally; translations may be incomplete in places.

Architecture

Django project (phishus/) split into one app per concern:

account (auth/orgs), admin (super-admin backend), campaign, scenarios, emails, landingpages, recipients, reports, training, subscriptions, settings (mail servers, email addresses, thumbnails), manage (org-staff dashboard), core (mail-sending + webhook handling shared by other apps).

Deployment

Three ways to run it; pick one.

Option A — Docker (recommended for a quick try)

cp .env.example .env
# edit .env: set SECRET_KEY, RECAPTCHA keys, and DATABASE_URL to match docker-compose.yml's db service
docker compose up --build

This starts a Postgres container and the app, running migrations automatically on start. Then, in another terminal:

docker compose exec web python manage.py createsuperuser
docker compose exec web python manage.py loaddata prebuilt_templates.json

The app is then available at http://localhost:8000.

Option B — Straight (no Docker, no cloud)

python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# edit .env: set SECRET_KEY, RECAPTCHA keys, and a DATABASE_URL pointing at a
# Postgres instance you run yourself (PYTHON_ENV=dev also works with sqlite —
# just point DATABASE_URL at sqlite:///db.sqlite3)
python manage.py migrate
python manage.py createsuperuser
python manage.py loaddata prebuilt_templates.json
python manage.py runserver

Building your own campaign content

Email templates are database records (see prebuilt_templates.json for the generic examples, loaded via loaddata); landing pages are plain HTML files under templates/inapp_landing_pages/<click|data_entry|attachment>/ (or a

Tech stack

Django 3.1, Django REST Framework, PostgreSQL (or SQLite for local dev)

License

MIT — see LICENSE. Also read the disclaimer above; it's not a license term, but it is the author's intent for this project.