Table of Contents

Bug Bounty Platform

Backend
Frontend
Infrastructure

Features

Authentication & Authorization
Vulnerability Reports
Platform Management
Architecture Patterns

Architecture
Quick Start
Configuration
API Endpoints
Project Structure
Development
Source Code

Bug Bounty Platform

Full-stack vulnerability disclosure platform with CVSS scoring, report lifecycle management, and role-based access.

Overview

A complete bug bounty platform where security researchers submit vulnerability reports to organizations. Features JWT authentication with Argon2id hashing, CVSS severity scoring, full report lifecycle management (submitted → triaged → accepted → resolved), role-based access control (user/company/admin), and a React dashboard for managing programs and submissions.

Status: Complete | Difficulty: Advanced

Tech Stack

Backend

Technology	Version	Purpose
FastAPI	0.123+	Async web framework
PostgreSQL	18	Primary database
SQLAlchemy	2.0+	Async ORM (mapped columns)
Alembic	1.15+	Database migrations
PyJWT	-	JWT token handling
pwdlib + Argon2	-	Password hashing
Pydantic	v2	Request/response validation
uuid-utils	-	UUID v7 generation

Frontend

Technology	Version	Purpose
React	-	UI framework
TypeScript	-	Type safety
Vite	-	Build tool
TanStack Query	v5	Server state management
Zustand	-	Client state (persisted)
Axios	-	HTTP client with interceptors
Zod	-	Runtime validation
Sass	-	Styling

Infrastructure

Docker Compose
Nginx reverse proxy
Justfile task runner

Features

Authentication & Authorization

JWT access + refresh token flow with automatic renewal
Argon2id password hashing (PHC winner)
Token version tracking for instant invalidation
Role-based access control (User, Company, Admin)

Vulnerability Reports

CVSS severity scoring
Full lifecycle: submitted → triaged → accepted → resolved / rejected
Markdown-formatted descriptions
Attachment support

Platform Management

Company program creation and management
Researcher profiles and submission history
Admin dashboard for platform oversight

Architecture Patterns

Repository pattern for data access
Pydantic schemas for validation (input/output separation)
FastAPI dependency injection throughout
Database session management with automatic rollback
Mixin-based models (UUIDMixin, TimestampMixin)

Architecture

┌─────────────────────────────────────────────────────────┐
│                   Frontend (React + TS)                   │
│  Zustand (auth) | TanStack Query | Axios interceptors    │
│  Auto token refresh on 401                               │
└───────────────────────────┬─────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────┐
│                    Nginx Reverse Proxy                    │
└───────────────────────────┬─────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────┐
│                   Backend (FastAPI)                       │
│                                                          │
│  Routes → Dependencies → Repositories → Models           │
│                                                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────────┐  │
│  │   Auth   │  │  Users   │  │  Reports / Programs  │  │
│  │  JWT +   │  │  CRUD    │  │  CVSS scoring        │  │
│  │  Argon2  │  │  Roles   │  │  Lifecycle mgmt      │  │
│  └──────────┘  └──────────┘  └──────────────────────┘  │
│                                                          │
│  Core: database.py | security.py | dependencies.py      │
│  Base: UUIDMixin | TimestampMixin | DeclarativeBase      │
└───────────────────────────┬─────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────┐
│                     PostgreSQL 18                         │
│  Users | Reports | Programs | Credentials                │
│  UUID v7 PKs | Async via asyncpg                         │
└─────────────────────────────────────────────────────────┘

Quick Start

cd PROJECTS/advanced/bug-bounty-platform

# Copy environment file
cp .env.example .env

# Start development environment
just up
# Or: docker compose up --build

# Access at http://localhost:8420

Configuration

# Database
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/bugbounty

# JWT
SECRET_KEY=your-secret-key
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=15
REFRESH_TOKEN_EXPIRE_DAYS=7

# CORS
CORS_ORIGINS=["http://localhost:3000"]

API Endpoints

Method	Endpoint	Description
POST	`/api/auth/register`	User registration
POST	`/api/auth/login`	JWT authentication
POST	`/api/auth/refresh`	Token refresh
GET	`/api/users/me`	Current user profile
POST	`/api/reports`	Submit vulnerability report
GET	`/api/reports/{id}`	Get report details
PATCH	`/api/reports/{id}`	Update report status
GET	`/api/programs`	List bounty programs

Project Structure

bug-bounty-platform/
├── backend/
│   ├── src/app/
│   │   ├── core/
│   │   │   ├── database.py       # Async session manager
│   │   │   ├── security.py       # JWT + Argon2id
│   │   │   ├── dependencies.py   # Auth dependency injection
│   │   │   └── Base.py           # UUIDMixin, TimestampMixin
│   │   ├── user/                  # User module
│   │   │   ├── models.py         # User + UserRole enum
│   │   │   ├── repository.py     # Data access
│   │   │   ├── schemas.py        # Pydantic validation
│   │   │   └── routes.py         # API endpoints
│   │   ├── report/               # Report module (same pattern)
│   │   └── program/              # Program module (same pattern)
│   └── pyproject.toml
├── frontend/
│   ├── src/
│   │   ├── api/                  # Axios client + hooks
│   │   ├── stores/               # Zustand (auth persisted)
│   │   └── components/
│   └── package.json
├── infra/                         # Docker + Nginx
├── compose.yml
└── Justfile

Development

# Backend
uv run ruff check .
uv run mypy .
uv run pytest tests/

# Frontend
pnpm lint
pnpm build
pnpm test