ADTickPlatform

A comprehensive, production-ready Attack-Defense Tick Capture The Flag (CTF) platform.

---

What is ADTickPlatform?

ADTickPlatform is an all-in-one Attack-Defense CTF framework designed to manage and automate periodic game ticks, isolated service environments, automated flag validation, and secure participant connectivity.

It comes equipped with highly concurrent Go-based microservices, a real-time responsive Next.js participant and operator interface, automatic WireGuard gateway management, and host-level firewall enforcement.

---

Visual Showcases

Real-Time 3D Attack Globe & Leaderboard

Tick Scheduler & Live Attack Feed

---

Key Features

• Real-time Dynamic Scoreboard & Visuals: An interactive 3D WebGL attack globe, real-time live-updating team scoreboard, and comprehensive attack feed powered by Server-Sent Events (SSE).
• Secure Tenant Isolation: Automatic deployment of per-team challenge service instances isolated inside dedicated Docker runtimes.
• First-Class Match lifecycle Control: Support for starting, stopping, freezing, and first-class match pause/resume. Pausing automatically blocks submissions, stops the scheduler, freezes tick advances, and restricts WireGuard access to organizer-only peers.
• WireGuard VPN Gateway & Firewall: Automatic client certificate management for participant VPN profiles and integrated nftables host firewall rulesets to enforce tenant network isolation.
• FaustCTF-Style Scoring: Built-in score calculations where flag points decay dynamically as more teams compromise a service, combined with SLA uptime scoring.
• Exploit-Gated SSH Credential Management: Automated generation and deployment of stable SSH root credentials to let players patch and secure their challenge containers.

---

Documentation

Comprehensive documentation guides are available in the docs/ directory:

• System Architecture — Under-the-hood design and service relationships.
• Deployment: Host (Debian/Ubuntu/Arch) — Production setup guide.
• Game Rules & Runtime Flows — Scoring formulas and tick structure.
• Participant Platform Manual — A guide for CTF competitors.
• Organizer Admin API Guide — Controlling the match programmatically.
• Operator CLI Cheatsheet — Rapid control commands.
• Ops Runbook & Trusted Reconcile — Operational guidelines.
• Final Rehearsal Checklist — Pre-flight sanity checks.
• Participant OpenAPI Spec — Platform API specs.
• Challenge Runtime Contract — Specifications for challenge builders.

Live documentation is also exposed on the running platform under /docs/participant, /docs/platform-api, and /docs/platform-api-v2.openapi.yaml.

---

Repository Layout

.
├── apps/web                 # Next.js frontend application (Dashboard, Admin, Visuals)
├── deploy/                  # Deployment files (Compose scripts, Dockerfiles, proxies)
│   ├── caddy/               # Caddy reverse proxy & Virtual Host configurations
│   ├── compose/             # Local & production compose configurations
│   └── docker/              # Service build Dockerfiles
├── docs/                    # Architectural and operational manuals
├── examples/                # Example challenge service implementations
├── internal/                # Shared Go utilities (network, databases, auth)
├── scripts/                 # Setup scripts, data seeders, and validation smoke tests
└── services/                # Go backend microservices (api-gateway, game-core, wireguard, etc.)

---

Quick Start (Local Development)

Prerequisites

• Docker & Docker Compose
• Go 1.21+
• Bun
• make

Setup

1. Copy and configure your local environment settings:

   cp .env.example .env

2. Spin up the local databases (PostgreSQL and Redis):

   docker compose -f deploy/compose/dev.yml up -d

3. Run the backend services in memory mode:

   make run-backend-stack-postgres

4. Install dependencies and boot the Next.js frontend:

   cd apps/web
   bun install
   bun run dev

---

Production Deployment

The production deployment runs behind a Caddy reverse proxy with automated database migrations and host network enforcement.

1. Configure production secrets and public addresses:

   make generate-prod-env CHALLENGE_SOURCE_HOST_PATH=/srv/adplatform/challenge-sources
   make setup-prod-env DOMAIN=localhost SCHEME=https   # or your public domain
   # Creates deploy/compose/prod.env with random secrets + ADMIN_PASSWORD
   # Public DNS uses Caddy ACME; localhost/IP uses a generated self-signed cert.
   make create-admin   # after the stack is up; uses ADMIN_* from prod.env

2. Validate and spin up the production container stack:

   make preflight-prod-host
   make up-prod-host
   make create-admin

   Note: Operator operations require root execution or sudo NOPASSWD for host inspection commands.

---

Testing & Validation

The platform includes a robust test and validation pipeline to ensure correctness:

• Complete CI validation run: make ci
• Go Unit Tests: make test
• Next.js Typechecks: bun run web:typecheck
• Visual Regression Tests: bunx playwright install chromium && make e2e
• Challenge Simulation Smoke Test: make smoke-sample-challenge-docker
• High-throughput load testing: make simulate-attack-map-load
• Database rollback drill: make smoke-prod-db-restore

To reset the database and runtime files to a clean starting state:

make bootstrap-clean-match

---

Challenge Development Contract

Custom challenges deployed to the platform must conform to the Challenge Runtime Contract:

• Provide a working /bin/sh shell environment.
• Expose an SSH daemon (sshd or dropbear).
• Include a password setting command (chpasswd or passwd).
• Support exposing or protecting the generated AD_PLATFORM_UNLOCK_PROOF environment variable.

See our included examples to get started:

• Sample HTTP Challenge
• Sample LFI Challenge
• Sample RCE Challenge