A comprehensive, production-ready Attack-Defense Tick Capture The Flag (CTF) platform.
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.
- 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
nftableshost 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.
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.
.
├── 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.)
-
Copy and configure your local environment settings:
cp .env.example .env
-
Spin up the local databases (PostgreSQL and Redis):
docker compose -f deploy/compose/dev.yml up -d
-
Run the backend services in memory mode:
make run-backend-stack-postgres
-
Install dependencies and boot the Next.js frontend:
cd apps/web bun install bun run dev
The production deployment runs behind a Caddy reverse proxy with automated database migrations and host network enforcement.
-
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 CAPTURE_MODE=guarded # 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
-
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 NOPASSWDfor host inspection commands.Guarded live packet capture requires BPF LSM, kernel BTF, cgroup v2, and local rootful Docker. Setup enables it by default for files without an explicit mode; preflight rejects unsupported hosts. See capture deployment and migration before upgrading existing challenges. Use
CAPTURE_MODE=disabledfor PCAP analysis only.
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-matchCustom challenges deployed to the platform must conform to the Challenge Runtime Contract:
- Provide a working
/bin/shshell environment. - Expose an SSH daemon (
sshdordropbear). - Include a password setting command (
chpasswdorpasswd). - Support exposing or protecting the generated
AD_PLATFORM_UNLOCK_PROOFenvironment variable.
See our included examples to get started:



