Phishing Simulation Application

A test project demonstrating a phishing simulation platform for security awareness training. The application allows administrators to send simulated phishing emails, track user interactions, and display educational awareness pages when recipients click on links.

Architecture

The application follows a microservices architecture with the following components:

Components

• Management Server (Port 3000): NestJS-based API server handling authentication, user management, phishing attempt creation, and template management. Protected by JWT authentication with role-based access control.

• Simulation Server (Port 3001): NestJS-based service responsible for sending phishing emails via SMTP and tracking link clicks. Secured with API key authentication.

• Frontend (Port 5173): React application built with Vite, providing a user interface for managing phishing campaigns. Features include authentication, dashboard for viewing attempts, and form for sending test emails.

• MongoDB: Document database storing users, phishing attempts, templates, and related metadata.

Flow

1. Administrator logs into the frontend and authenticates with the management server.
2. Administrator creates a phishing attempt by selecting a template and recipient email.
3. Management server creates the attempt record and sends a request to the simulation server.
4. Simulation server sends the phishing email using configured SMTP settings.
5. When a recipient clicks the link, the simulation server tracks the click and displays an awareness page.
6. The frontend dashboard displays all attempts with their current status.

Technology Stack

• Backend: NestJS, TypeScript, MongoDB (Mongoose)
• Frontend: React, TypeScript, Vite, Tailwind CSS, React Query, React Router
• Email: Nodemailer with SMTP
• Templates: Handlebars for email and awareness page rendering
• Authentication: JWT, bcrypt for password hashing
• API Documentation: Swagger/OpenAPI
• Containerization: Docker and Docker Compose

Demo

Dashboard

Send phishing tests and track attempts with real-time status updates.

Email Preview

View sent phishing emails in Mailtrap

Awareness Page

Educational page displayed when users click phishing links, providing immediate security training.

Prerequisites

• Node.js 20+ and pnpm (for local development)
• Docker and Docker Compose (for containerized setup)
• MongoDB (or use Docker)
• SMTP server access for sending emails

Setup and Running

Option 1: Using Docker Compose

1. Create environment files for each service:

management-server/.env:

MONGODB_URI=mongodb://mongodb:27017/phishing-app
PORT=3000
JWT_SECRET=test-jwt-secret
SIMULATION_SERVER_URL=http://simulation-server:3001
API_KEY=test-api-key
SEED_ADMIN_EMAIL=admin@example.com
SEED_ADMIN_PASSWORD=admin123

simulation-server/.env:

MONGODB_URI=mongodb://mongodb:27017/phishing-app
PORT=3001
API_KEY=test-api-key
SMTP_URL=smtp://username:password@smtp.example.com:587
MAIL_FROM=noreply@phishing-sim.com
SERVER_URL=http://localhost:3001

frontend/.env:

VITE_API_URL=http://localhost:3000

2. Start all services:

docker compose up -d

3. The seed script runs automatically on management server startup, creating:

   • Default admin user: admin@example.com / admin123
   • Three default phishing templates

4. Access the application:

   • Frontend: http://localhost:5173
   • Management API (Swagger Docs): http://localhost:3000/
   • Simulation API (Swagger Docs): http://localhost:3001/

Option 2: Local Development

1. Start MongoDB locally (or use Atlas/Docker) and update the MONGODB_URI in the .env files.

2. Set up and run the management server:

cd management-server
pnpm install
cp .env.example .env
# Edit .env and update the values
pnpm seed  # Run seed script to create admin user and templates
pnpm start:dev

3. Set up and run the simulation server:

cd simulation-server
pnpm install
cp .env.example .env
# Edit .env and update the values
pnpm start:dev

4. Set up and run the frontend:

cd frontend
pnpm install
cp .env.example .env
# Edit .env and populate VITE_API_URL=http://localhost:3000
pnpm dev

API Documentation

Both backend servers include interactive Swagger documentation for browsing endpoints, viewing schemas, testing APIs, and authenticating with JWT tokens or API keys.

• Management Server API Docs: http://localhost:3000/

  • JWT Bearer token authentication
  • Endpoints for authentication, phishing attempts, and templates

• Simulation Server API Docs: http://localhost:3001/

  • API key authentication (header: x-api-key)
  • Endpoints for sending phishing emails and tracking clicks

Project Structure

cymulate-test/
├── docker-compose.yml          # Docker Compose configuration
├── management-server/           # Management API server
│   ├── src/
│   │   ├── auth/               # Authentication module
│   │   ├── phishing-attempts/  # Phishing attempts management
│   │   └── scripts/            # Database seeding script
│   ├── Dockerfile
│   └── docker-entrypoint.sh    # Entrypoint with seed script
├── simulation-server/          # Email sending and tracking server
│   ├── src/
│   │   ├── phishing/           # Phishing email handling
│   │   ├── shared/             # Shared utilities (mail, guards)
│   │   └── templates/          # Handlebars email templates
│   └── Dockerfile
└── frontend/                   # React web application
    ├── src/
    │   ├── components/         # React components
    │   ├── pages/              # Page components
    │   ├── context/            # React context providers
    │   └── lib/                # Utility functions
    └── Dockerfile