Fantasy Cyber League

A gamified cybersecurity awareness training platform that transforms traditional security education into an engaging, competitive experience. Built as part of the KV6014 Computing Group Project at Northumbria University.

Live Demo

The platform is deployed and available for testing. Credentials are provided in a separate document.

Service	URL	Description
Fantasy Cyber League	https://grp-prjct.vercel.app/	Main platform — register an account or use provided test credentials to explore the dashboard, complete security challenges, earn points, and climb the leaderboard
GoPhish Admin Panel	https://159.65.48.193:3333/	Phishing simulation backend — view campaigns, email templates, and target groups. Accept the browser's certificate warning to proceed (self-signed certificate) credentials provided in the credentials document
Mailhog Email Viewer	http://159.65.48.193:8025/	Email capture interface — all simulated phishing emails are sent here instead of real inboxes. View sent campaigns and test email interactions safely

Recommended testing flow:

Log into the main platform and explore the dashboard
Complete a few challenges (Password Game, Quiz, URL Sniper) to see points and badges in action
Visit the GoPhish admin panel to see how campaigns are configured
Check Mailhog to view the phishing emails that have been sent
Use the admin account to sync users and launch a test campaign from the platform's admin panel

⚠️ Known Limitations

Important: Vercel uses a read-only filesystem which prevents writing to local SQLite databases. The following features are affected in production:

CSV Quiz Upload — Cannot add new quizzes (quizzes are pre-populated before deployment)

Spot the Phish Game — Cannot add new phishing emails via admin panel (emails are pre-populated)

Badge Awards — Badge progress may not persist between sessions

Phishing Stats Tracking — Lifetime phishing detection stats may not persist

All data stored in the remote PHP API (users, points, leaderboards, submissions) works normally. All features work as expected when deployed locally.

Overview

Fantasy Cyber League addresses a critical problem in organisational security: over 90% of data breaches begin with phishing attacks, yet traditional security training fails to change employee behaviour. Our platform combines real phishing simulations powered by GoPhish with gamification elements including points, leaderboards, badges, and interactive challenges to create lasting behavioural change.

Features

Security Challenges

Password Game — Test and improve password creation skills with real-time strength analysis and feedback
Spot the Phish — Identify phishing emails from a pool of legitimate and malicious messages
URL Sniper — Fast-paced game to identify malicious URLs before time runs out
Quiz Challenges — Customisable quiz system with CSV upload support for administrators
And more!

Gamification

Points & Levels — Earn points for completing challenges and progress through levels
Monthly Leaderboards — Compete against colleagues with department and organisation-wide rankings
Achievement Badges — 14 unique badges including Draft Pick, Clean Sheet, Phish Hunter, and MVP
Streak Tracking — Daily challenge completion streaks with rewards

GoPhish Integration

Automated User Sync — Synchronise users from the platform to GoPhish organised by department
Campaign Management — Launch and monitor phishing campaigns directly from the admin panel
Email Templates — Create phishing email templates
Results Tracking — Points automatically updated based on user interactions with simulated phishing emails

AI Assistant

Claude-Powered Chatbot — Integrated AI assistant for cybersecurity education
Security Tips — Generates security awareness tips

Resources Hub

Live Search — Search for cybersecurity news, articles, and videos via SerpAPI
Curated Content — Access to current threat intelligence and training materials

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Frontend (Flask Templates)               │
│                     Bootstrap 5 + Cyberpunk Theme               │
└─────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Flask Application Server                    │
│                      
└─────────────────────────────────────────────────────────────────┘
          │                       │                       │
          ▼                       ▼                       ▼
┌─────────────────┐   ┌─────────────────┐   ┌─────────────────────┐
│  Local SQLite   │   │   PHP      API  │   │  External Services  │
│  - Badges       │   │   (Northumbria) │   │  - GoPhish Server   │
│  - Quiz Qs      │   │   - Users       │   │  - Claude API       │
│  - Phishing     │   │   - Challenges  │   │  - SerpAPI          │
│    Emails       │   │   - Submissions │   │  - Mailhog (Dev)    |
│                 |   |                 |   |  - Vercel           |
└─────────────────┘   │   - Leaderboard │   └─────────────────────┘
                      │   - Rewards     │
                      └─────────────────┘

Tech Stack

Component	Technology
Backend	Python 3.10+, Flask 3.1
Frontend	Bootstrap 5.3, Jinja2 Templates
Database	SQLite (local), PHP/SQLite API (remote)
Phishing Simulation	GoPhish
AI Chatbot	Claude API (Haiku)
Search	SerpAPI
Hosting The Platfrom	Vercel
Hosted Database	NUWebspace
Hosting GoPhish and Mailhog	Digital Ocean (GitHub Student Plan)
Email Testing	Mailhog

Installation

Prerequisites

Python 3.10 or higher
pip package manager
Access to GoPhish server (for phishing simulations)
API keys for Claude and SerpAPI (optional features)

Local Development Setup

Clone the repository

git clone https://github.com/nayem-m/grp_prjct.git
cd grp_prjct

Create and activate virtual environment

python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate     # Windows

Install dependencies
```
pip install -r requirements.txt
```

Configure environment variables

cp .env.example .env
# Edit .env with your configuration
# API keys are provided in the credentials document

Run the development server
```
python main.py
```
Access the application
```
http://localhost:5000
```

Configuration

Create a .env file in the '/app' directory with the following variables:

# GoPhish Integration
GOPHISH_API_URL=https://your-gophish-server:3333/api
GOPHISH_API_KEY=your-gophish-api-key

# Claude AI Assistant
CLAUDE_API_KEY=your-anthropic-api-key

# SerpAPI (Resource Search)
SERPAPI_KEY=your-serpapi-key

Environment Variable Reference

Variable	Required	Description
`GOPHISH_API_URL`	Yes	GoPhish server API endpoint
`GOPHISH_API_KEY`	Yes	GoPhish API authentication key
`CLAUDE_API_KEY`	No	Anthropic API key for AI chatbot
`SERPAPI_KEY`	No	SerpAPI key for resource search

Project Structure

fantasy-cyber-league/
├── app/
|   ├── .env.example         # Env file 
│   ├── __init__.py          # Flask app factory and routes
│   ├── ai_assistant.py      # Claude AI integration
│   ├── auth.py              # Authentication (login/register)
│   ├── badges.py            # Badge award logic
│   ├── badges_db.py         # Badge database operations
│   ├── challenge_tracker.py # Progress tracking for badges
│   ├── dashboard.py         # User dashboard
│   ├── password.py          # Password strength game
│   ├── phishing_db.py       # Phishing emails database
│   ├── phishing_game.py     # Spot the Phish game
│   ├── quiz_db.py           # Quiz questions database
│   ├── quiz_game.py         # Quiz challenge system
│   ├── sniper_game.py       # URL Sniper game
│   ├── update_points.py     # Points and leaderboard updates
│   ├── static/
│   │   └── css/
│   │       ├── site.css     # Main stylesheet
│   │       ├── badge/       # Badge images
│   │       └── img/         # Platform images
│   └── templates/           # Jinja2 HTML templates
├── CYBERAPP/                # PHP REST API (deployed separately)
│   ├── api.php              # API router
│   └── classes/             # Endpoint handlers
├── main.py                  # Application entry point
├── requirements.txt         # Python dependencies
├── DESIGN.md                # Figma wireframes link
├── archive-django/          # Original Django prototype (deprecated)
└── README.md

Additional Files

DESIGN.md contains a link to our Figma wireframes documenting the initial UI/UX design process. These wireframes guided the development of the cyberpunk-themed interface and helped the team align on the visual direction before implementation.

archive-django/ contains our original Django prototype from the early sprints. We pivoted to Flask as it offered a simpler, more lightweight architecture better suited to our needs. This folder is retained for reference and to demonstrate our iterative development process following agile methodology.

API Documentation

Custom API

The platform uses a PHP REST API hosted on NUWebspace for persistent data storage.

Base URL: https://w23012928.nuwebspace.co.uk/cyberapp/api

Users

Method	Endpoint	Description
GET	`/users`	List all users
GET	`/users?user_id={id}`	Get user by ID
GET	`/users?email={email}`	Get user by email
POST	`/users`	Create new user
PATCH	`/users?user_id={id}`	Update user
DELETE	`/users?user_id={id}`	Delete user

Challenges

Method	Endpoint	Description
GET	`/challenges`	List all challenges
POST	`/challenges`	Create challenge
PATCH	`/challenges?challenge_id={id}`	Update challenge
DELETE	`/challenges?challenge_id={id}`	Delete challenge

Submissions

Method	Endpoint	Description
GET	`/submissions`	List all submissions
GET	`/submissions?user_id={id}`	Get user submissions
POST	`/submissions`	Record submission

Leaderboard

Method	Endpoint	Description
GET	`/leaderboard`	Get current leaderboard
POST	`/leaderboard`	Update points (with `add_points: true`)

GoPhish Integration Endpoints (Flask)

Method	Endpoint	Description
POST	`/api/gophish/sync-users`	Sync users to GoPhish groups
GET	`/api/gophish/templates`	List email templates
POST	`/api/gophish/templates`	Create email template
GET	`/api/gophish/groups`	List target groups
GET	`/api/gophish/campaigns`	List campaigns
POST	`/api/gophish/campaigns`	Launch campaign

Database Schema

Remote API (SQLite via PHP)

users

Column	Type	Description
user_id	INTEGER (PK)	Unique user ID
username	TEXT	Display name
email	TEXT	Email address
password_hash	TEXT	Bcrypt hashed password
department	TEXT	Department name
user_access_level	TEXT	Role (user/admin)
total_points	INTEGER	Accumulated points
level	INTEGER	Current level
created_at	TIMESTAMP	Registration date

challenges

Column	Type	Description
challenge_id	INTEGER (PK)	Unique challenge ID
title	TEXT	Challenge name
description	TEXT	Challenge description
category	TEXT	Category (Quiz, Phishing, etc.)
difficulty	TEXT	Easy/Medium/Hard
points	INTEGER	Points available

submissions

Column	Type	Description
submission_id	INTEGER (PK)	Unique submission ID
user_id	INTEGER (FK)	User who submitted
challenge_id	INTEGER (FK)	Challenge completed
status	TEXT	pending/completed/failed
score_awarded	INTEGER	Points earned
submitted_at	TIMESTAMP	Submission time

Local SQLite Databases

badges.db — Badge definitions and user awards quiz_questions.db — Quiz questions by challenge phishing_emails.db — Phishing email content for games phishing_stats.db — User phishing detection statistics

Local GoPhish Setup (not needed as it is running on a VPS)

For local development and testing, you can run GoPhish on your own machine. This allows you to test phishing campaigns without a remote server.

Prerequisites

GoPhish binary (download from releases)
Mailhog for safe email capture (emails never leave your machine)
Python 3 for the webhook processor

Step 1: Install Mailhog

Mailhog captures all outgoing emails so you can test safely without sending real emails.

Option A: Binary (Recommended)

# Linux
wget https://github.com/mailhog/MailHog/releases/download/v1.0.1/MailHog_linux_amd64
chmod +x MailHog_linux_amd64
./MailHog_linux_amd64

# Mac
brew install mailhog
mailhog

# Windows - download MailHog_windows_amd64.exe from releases

Option B: Docker (Used in this project)

docker run -d -p 1025:1025 -p 8025:8025 mailhog/mailhog

Mailhog will be available at:

SMTP Server: localhost:1025 (for GoPhish to send emails)
Web UI: http://localhost:8025 (to view captured emails)

Step 2: Install GoPhish

Download the binary for your OS from GoPhish Releases

Extract and navigate to the folder

unzip gophish-v0.12.1-linux-64bit.zip
cd gophish-v0.12.1-linux-64bit

Create/update config.json

{
  "admin_server": {
    "listen_url": "127.0.0.1:3333",
    "use_tls": true,
    "cert_path": "gophish_admin.crt",
    "key_path": "gophish_admin.key"
  },
  "phish_server": {
    "listen_url": "127.0.0.1:8080",
    "use_tls": false
  },
  "db_name": "sqlite3",
  "db_path": "gophish.db",
  "webhook_url": "http://localhost:9000",
  "migrations_prefix": "db/db_",
  "contact_address": "",
  "logging": {
    "filename": "gophish.log",
    "level": "info"
  }
}

Run GoPhish

# Linux/Mac
chmod +x gophish
./gophish

# Windows
gophish.exe

Get your initial password from the console output:

time="2024-01-15T10:30:00Z" level=info msg="Please login with the username admin and the password abc123def456"

Access the admin panel at https://localhost:3333 (accept the self-signed certificate warning)

Step 3: Configure GoPhish Sending Profile

In the GoPhish admin panel, create a Sending Profile for Mailhog:

Field	Value
Name	`Mailhog Local`
SMTP From	`phishing@test.local`
Host	`localhost:1025`
Username	(leave blank)
Password	(leave blank)
Ignore Certificate Errors	✓ Checked

Click "Send Test Email" to verify — check http://localhost:8025 to see it.

Step 4: Set Up the Webhook Processor

The webhook processor automatically updates user points based on their interactions with phishing emails.

Copy webhook_processor.py to your GoPhish directory (included in /gophish/ folder)
Install dependencies
```
pip install requests urllib3
```

Run the processor

python webhook_processor.py

You should see:

============================================================
GoPhish Webhook Processor
============================================================
API Endpoint: https://w23012928.nuwebspace.co.uk/cyberapp/api
Listening on: http://localhost:9000
============================================================

Points System:
  Email Opened: -5 points
  Clicked Link: -25 points
  Submitted Data: -50 points
  Email Reported: +30 points
  Campaign Complete: +10 points

Waiting for GoPhish events...
============================================================

Step 5: Configure Flask Environment

Update your .env file to point to local GoPhish:

# Local GoPhish Configuration
GOPHISH_API_URL=https://localhost:3333/api
GOPHISH_API_KEY=your-api-key-from-gophish-settings

To get your API key:

Log into GoPhish admin panel
Go to Settings (gear icon)
Copy the API Key

Step 6: Create a Landing Page

In GoPhish, create a simple landing page for credential capture:

Field	Value
Name	`Test Landing Page`
HTML	`<html><body><h1>Login</h1><form method="post"><input name="username" placeholder="Username"><input name="password" type="password" placeholder="Password"><button>Login</button></form></body></html>`
Capture Submitted Data	✓ Checked
Capture Passwords	✓ Checked
Redirect to	`https://example.com`

Testing the Full Flow

Start all services (in separate terminals):

# Terminal 1: Mailhog
./MailHog_linux_amd64

# Terminal 2: GoPhish
./gophish

# Terminal 3: Webhook Processor
python webhook_processor.py

# Terminal 4: Flask App
python main.py

Sync users from your Flask admin panel (this creates GoPhish groups by department)
Create a campaign via the admin panel or GoPhish directly
Check Mailhog at http://localhost:8025 to see the phishing emails
Click a link in the test email and watch the webhook processor update points

Points System

User Action	Points
Email Sent	0
Email Opened	-5
Clicked Link	-25
Submitted Credentials	-50
Reported Phishing	+30
Didn't Fall For It	+10

GoPhish Template Variables

When creating email templates, use these variables:

Variable	Description
`{{.FirstName}}`	Target's first name
`{{.LastName}}`	Target's last name
`{{.Email}}`	Target's email address
`{{.Position}}`	Target's department
`{{.URL}}`	Unique phishing link
`{{.Tracker}}`	Hidden tracking pixel (required for open detection)
`{{.From}}`	Sender address

Important: Always include {{.Tracker}} in your HTML templates for email open tracking:

<html>
<body>
  <p>Dear {{.FirstName}},</p>
  <p>Click <a href="{{.URL}}">here</a> to verify.</p>
  {{.Tracker}}
</body>
</html>

Troubleshooting

Issue	Solution
Certificate error connecting to GoPhish	The Flask app uses `verify=False` for self-signed certs
Emails not appearing in Mailhog	Check Sending Profile uses `localhost:1025`
Webhook not receiving events	Ensure `webhook_url` in config.json matches processor port
Points not updating	Check webhook processor console for errors
API key rejected	Regenerate in GoPhish Settings → API Key

Deployment

Web Application (Vercel)

The Flask application is deployed on Vercel:

Connect your GitHub repository to Vercel
Select "Flask" as the framework preset
Add environment variables in the Vercel dashboard:
- GOPHISH_API_URL
- GOPHISH_API_KEY
- CLAUDE_API_KEY
- SERPAPI_KEY
Deploy — Vercel automatically builds and deploys on each push to main

GoPhish Server (Digital Ocean with GitHub Student Plan)

GoPhish runs on a separate Digital Ocean droplet with Mailhog for email capture:

Download and extract the GoPhish binary
Configure config.json (see Local GoPhish Setup section)
Run Mailhog via Docker: docker run -d --restart unless-stopped -p 1025:1025 -p 8025:8025 mailhog/mailhog
Run the webhook processor as a background service
Configure the Flask app environment variables with the GoPhish API endpoint and key

Contributing

This project was developed by a 6-member team following Agile methodology with 2-week sprints.

Team Members

Elliot Massey
Moosa Nayem
Katie Beer
Joe Mcdermott
Mark Clifford
Reuben Mcquire

Acknowledgements

Northumbria University — KV6014 Computing Group Project
GoPhish — Open-source phishing simulation platform
Anthropic — Claude AI API
SerpAPI — Search results API

License

This project is submitted as coursework for KV6014 at Northumbria University.

Fantasy Cyber League — Making cybersecurity training engaging, competitive, and effective.

Name		Name	Last commit message	Last commit date
CYBERAPP		CYBERAPP
app		app
archive-django		archive-django
gophish		gophish
.gitignore		.gitignore
DESIGN.md		DESIGN.md
README.md		README.md
main.py		main.py
requirements.txt		requirements.txt
run.py		run.py

Latest commit

History

Folders and files

Repository files navigation

Fantasy Cyber League

Live Demo

⚠️ Known Limitations

Overview

Features

Security Challenges

Gamification

GoPhish Integration

AI Assistant

Resources Hub

Architecture

Tech Stack

Installation

Prerequisites

Local Development Setup

Configuration

Environment Variable Reference

Project Structure

Additional Files

API Documentation

Custom API

Users

Challenges

Submissions

Leaderboard

GoPhish Integration Endpoints (Flask)

Database Schema

Remote API (SQLite via PHP)

Local SQLite Databases

Local GoPhish Setup (not needed as it is running on a VPS)

Prerequisites

Step 1: Install Mailhog

Step 2: Install GoPhish

Step 3: Configure GoPhish Sending Profile

Step 4: Set Up the Webhook Processor

Step 5: Configure Flask Environment

Step 6: Create a Landing Page

Testing the Full Flow

Points System

GoPhish Template Variables

Troubleshooting

Deployment

Web Application (Vercel)

GoPhish Server (Digital Ocean with GitHub Student Plan)

Contributing

Team Members

Acknowledgements

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages