Bug Bounty Platform

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

Source Code

View on GitHub