BluePhish

1) Project Purpose

BluePhish is a local Security Awareness lab designed to simulate phishing campaigns in a controlled environment and analyze user behavior in an ethical and auditable way.

This project is intended for:

• authorized internal training
• human risk measurement
• structured security debriefing with practical metrics

Ethical boundaries:

• use only in authorized environments
• do not target real users without explicit approval and policy coverage
• do not impersonate external brands (for example Google or Microsoft)

2) Quick Start (Windows PowerShell)

1. Activate the virtual environment.

.\myenv\Scripts\Activate.ps1

2. Set at least the admin token.

$env:PHISHING_ADMIN_TOKEN = "set-a-strong-admin-token"

3. Start the application.

python BluePhish.py

4. Start the server from the CLI menu (option 1), then open:

• /training-login?id=alice&scenario=cloud
• /admin-login
• /admin

3) Core Features

• simulated phishing campaign delivery (with optional real SMTP mode)
• ethical training flow with scenarios and user actions
• admin dashboard with risk and behavior metrics
• JSON and CSV report exports
• runtime observability endpoints: /health and /metrics
• privacy-by-design data handling
• hardened admin authentication and session control

4) Security and Reliability Status

4.1 Credential Protection

• passwords are never stored in clear text
• only password length is stored (password_len)
• usernames are pseudonymized before storage

4.2 Admin Access Security

• admin token loaded from environment variable
• constant-time token comparison
• dedicated admin login endpoint with CSRF protection
• HttpOnly admin session cookie
• dedicated logout endpoint
• persistent admin rate limiting
• admin access audit trail (success/failure + details)

4.3 HTTP Hardening

• Cache-Control: no-store
• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• Referrer-Policy: no-referrer
• baseline Content-Security-Policy
• POST payload size enforcement with HTTP 413

4.4 Data Integrity and Privacy

• user_id normalization with trusted flag
• masked IP in stored telemetry
• automatic retention purge
• explicit rollback on database transaction failure

4.5 Dashboard Scalability

• dashboard time filtering executed in SQL
• DB-side limits for click/login retrieval to reduce memory footprint

4.6 SMTP Delivery Resilience

• configurable SMTP timeout
• configurable retries with incremental backoff
• temporary vs permanent error classification in structured logs

4.7 Runtime Stability

• graceful server shutdown with KeyboardInterrupt handling
• explicit stop-requested and stop-completed logging events

5) Architecture Overview

• BluePhish.py: CLI entrypoint, orchestration, and component factory
• server_http.py: HTTP handler/routing, admin flows, dashboard rendering
• app_config.py: environment parsing, dotenv loading, runtime validation
• analytics_engine.py: behavior analytics and anomaly metrics
• reporter_engine.py: report generation and export orchestration
• export_utils.py: JSON and CSV writing helpers
• structured_logging.py: structured JSONL logging
• db_backfill.py: batched username_hash backfill/migration
• server_support.py: ThreadingTCPServer and AdminGuard

6) Requirements

• Windows, Linux, or macOS
• Python 3.11+
• virtual environment recommended

Notes:

• the core app relies on Python standard library components
• quality tools used by CI/local checks: ruff and mypy

7) Environment Configuration

Supported environment variables:

• PHISHING_ADMIN_TOKEN: admin login token
• PHISHING_DB_PATH: SQLite path (default: awareness.db)
• PHISHING_RETENTION_DAYS: retention in days (default: 90)
• PHISHING_MAX_POST_BODY_BYTES: max POST body size (default: 16384, range 1024..1048576)
• PHISHING_SESSION_TTL_MINUTES: admin session TTL (default: 20, range 1..1440)
• PHISHING_COOKIE_SECURE: true/false, enables Secure on cookies
• PHISHING_ETHICAL_MODE: true/false, default true; disables legacy /login and /auth when true
• PHISHING_LOG_FILE: structured log file path (default: awareness.log)
• PHISHING_LOG_LEVEL: logging level (default: INFO)
• PHISHING_MIGRATION_BATCH_SIZE: migration batch size (default: 1000, range 100..50000)
• PHISHING_SMTP_TIMEOUT_SECONDS: SMTP timeout (default: 10, range 3..120)
• PHISHING_SMTP_MAX_RETRIES: max SMTP retries (default: 3, range 1..5)
• PHISHING_SMTP_RETRY_BACKOFF_SECONDS: SMTP retry backoff base (default: 2, range 0..10)

Current PowerShell session example:

$env:PHISHING_ADMIN_TOKEN = "set-a-strong-admin-token"
$env:PHISHING_DB_PATH = "awareness.db"
$env:PHISHING_RETENTION_DAYS = "90"
$env:PHISHING_MAX_POST_BODY_BYTES = "16384"
$env:PHISHING_SESSION_TTL_MINUTES = "20"
$env:PHISHING_COOKIE_SECURE = "false"
$env:PHISHING_ETHICAL_MODE = "true"
$env:PHISHING_SMTP_TIMEOUT_SECONDS = "10"
$env:PHISHING_SMTP_MAX_RETRIES = "3"
$env:PHISHING_SMTP_RETRY_BACKOFF_SECONDS = "2"

Persistent user-level PowerShell example:

setx PHISHING_ADMIN_TOKEN "set-a-strong-admin-token"
setx PHISHING_DB_PATH "awareness.db"
setx PHISHING_RETENTION_DAYS "90"
setx PHISHING_MAX_POST_BODY_BYTES "16384"
setx PHISHING_SESSION_TTL_MINUTES "20"
setx PHISHING_COOKIE_SECURE "false"
setx PHISHING_ETHICAL_MODE "true"
setx PHISHING_SMTP_TIMEOUT_SECONDS "10"
setx PHISHING_SMTP_MAX_RETRIES "3"
setx PHISHING_SMTP_RETRY_BACKOFF_SECONDS "2"

Default behavior:

• .env is loaded automatically if present
• if PHISHING_ADMIN_TOKEN is not set, admin login is unavailable

8) CLI Menu

Main menu options:

1. Start local server
2. Send email campaign (simulated)
3. Generate report
4. Security analysis
5. Exit

9) HTTP Endpoints

With server running on 127.0.0.1:8080:

• / (home)
• /health
• /metrics
• /admin-login
• /admin
• /admin-logout
• /training-login?id=alice&scenario=cloud
• /training-auth?id=alice&scenario=cloud (POST)

Legacy endpoints available only if PHISHING_ETHICAL_MODE=false:

• /login?id=alice
• /auth?id=alice (POST)

Supported training scenarios:

• cloud
• mail
• documents

10) Suggested Demo Flow

1. Set PHISHING_ADMIN_TOKEN.
2. Start the app and start the server.
3. Trigger a training event at /training-login.
4. Complete training action at /training-auth.
5. Authenticate at /admin-login and open /admin.
6. Run Security analysis and Generate report from the CLI menu.

11) Database and Data Model

Primary database:

• awareness.db (or PHISHING_DB_PATH value)

Main tables:

• clicks
• logins
• admin_access_audit
• admin_rate_limit

Login privacy model:

• username_hash is used as the analytics identifier
• username is kept for backward compatibility but stored pseudonymized
• password is always redacted ([REDACTED] or empty in training-specific flows)

Retention and privacy:

• automatic purge at startup based on retention policy
• masked IP for reporting surfaces
• trusted flag to separate reliable from potentially manipulated input

12) Reports and Analytics

Primary metrics include:

• total click events
• total login events
• unique clicked users
• unique compromised users
• click rate percentage
• compromise rate percentage
• top IP list
• behavior anomalies
• total training actions
• training risk by user
• training risk by department
• training continue rate percentage

Available exports:

• report.json
• training_report.csv
• clicks_report.csv
• logins_report.csv

Admin dashboard supports:

• timeframe filters: all, 7d, 30d, custom
• active filter display
• filtered metrics and tables

13) Testing and Quality Gates

Current test status:

• 22 automated tests (unit + integration)

Run tests locally:

python -m unittest -v

GitHub Actions CI:

• workflow: .github/workflows/ci.yml
• triggers: push and pull_request
• Python matrix: 3.11, 3.12, 3.13

CI quality gates:

• ruff check .
• mypy app_config.py server_support.py structured_logging.py db_backfill.py export_utils.py
• python -m unittest -v

Local quality gate replication:

python -m ruff check .
python -m mypy app_config.py server_support.py structured_logging.py db_backfill.py export_utils.py
python -m unittest -v

14) Troubleshooting

1. Admin login fails

• verify PHISHING_ADMIN_TOKEN
• use /admin-login
• if rate-limited, wait for retry window

2. Port 8080 already in use

• change Config.port
• stop the process using the port

3. Windows test failures with SQLite lock files

• avoid deleting SQLite files while connections are open
• rerun from a clean shell

4. Dashboard has no data

• with PHISHING_ETHICAL_MODE=true, use /training-login and /training-auth
• /login and /auth are blocked in ethical mode

5. Slow migration on large DB

• increase PHISHING_MIGRATION_BATCH_SIZE (for example 5000)

6. Unstable real SMTP delivery

• tune PHISHING_SMTP_TIMEOUT_SECONDS and PHISHING_SMTP_MAX_RETRIES
• tune PHISHING_SMTP_RETRY_BACKOFF_SECONDS to avoid aggressive retries
• inspect awareness.log for temporary vs permanent errors

15) Known Limitations

• admin authentication is shared-token based
• no built-in HTTPS (local HTTP server)
• admin sessions are process-memory based
• local SQLite storage/reporting model

16) Roadmap

High priority:

1. RBAC with separated admin/auditor roles
2. extended audit for dashboard and sensitive export access
3. session persistence beyond process lifetime
4. deployment hardening with HTTPS reverse proxy

Medium priority:

1. combined dashboard filters (user/scenario/trusted)
2. additional negative HTTP test cases (invalid cookies, CSRF replay, boundary payload)
3. /metrics expansion (latency and status-code aggregations)
4. per-event retention policy granularity

Low priority:

1. installable packaging with CLI entrypoint
2. alternative backend storage for higher concurrency

17) Responsible Use

BluePhish is intended exclusively for authorized training, awareness, and internal research. Users are responsible for legal, policy, and ethical compliance.