How domysh/ctfbox works
CTFBox is an open attack/defense CTF platform. Organizers configure a competition, start it, and manage teams, services, and network state; players access team VMs, attack services, and submit flags, while checkers and the game server produce scores shown on the scoreboard. Its runtime spans deployment, distributed nodes, routers, isolated team boxes, service workloads, and game operations. The README documents the broad workflow and capabilities; source excerpts show selected UI and service implementations, so some subsystem links are documented rather than source-verified.
Main entry points: main.go Game server · run.py Platform launcher · services Team VMs · MainLayout.tsx Game web UI
Components 24
Configuration
- Config editor
editor/app/page.tsx - Topology preview
editor/components/NodesSection.tsx - Config model
editor/lib/config.ts - Topology logic
editor/lib/topology.ts
Deployment and network
- Platform launcher
run.py - VM provisioning
incus/customize-vm.py - Router agent
router/agent.py - Route commands
router/confgen.py - Local simulation
simulation/simulate.py
Competition operations
- Game server
gameserver/src/main.go - Competition database
gameserver/src/db/models.go - Checker worker
gameserver/src/worker.go - Flag submissions
gameserver/src/submission_api.go - Score calculation
gameserver/src/scoreboard.go
Player services
- Service checkers
gameserver/checkers - Team VMs
vm/services - PCSS service
vm/services/PCSS/main.py - Pwnzer0tt1Shop
vm/services/Pwnzer0tt1Shop/backend/app.py - Shop frontend
vm/services/Pwnzer0tt1Shop/frontend/src/App.tsx
Web interfaces
- Game web UI
gameserver/frontend/src/components/MainLayout.tsx - Admin console
gameserver/frontend/src/pages/AdminPage.tsx - Scoreboard UI
gameserver/frontend/src/pages/ScoreboardPage.tsx
Other components
- Organizers
- Players
Connections 26
- Organizers → Config editor: configure
README.md - Config editor → Topology preview: preview topology
README.md - Topology preview → Topology logic: validates topology
editor/components/NodesSection.tsx - Topology logic → Config model: uses config types
editor/lib/topology.ts - Organizers → Platform launcher: start platform
README.md - Platform launcher → Team VMs: provisions boxes
- Platform launcher → Game server: starts game server
- Platform launcher → Router agent: deploys routers
- Router agent → Route commands: reconciles network
README.md - Router agent → Game server: reads network state
README.md - Team VMs → PCSS service: hosts service
- Team VMs → Pwnzer0tt1Shop: hosts service
vm/services/Pwnzer0tt1Shop/backend/app.py - Players → Team VMs: connect
README.md - Players → Flag submissions: submit flags
- Service checkers → Checker worker: checks services
- Checker worker → Score calculation: supplies check results
- Flag submissions → Competition database: records submissions
- Score calculation → Competition database: reads competition data
- Game web UI → Game server: requests game data
- Admin console → Game server: admin requests
- Scoreboard UI → Game server: loads scores
- Game web UI → Admin console: routes admin page
gameserver/frontend/src/components/MainLayout.tsx - Game web UI → Scoreboard UI: routes scoreboard
gameserver/frontend/src/components/MainLayout.tsx - Players → Shop frontend: use service app
- Shop frontend → Pwnzer0tt1Shop: calls service API
- Organizers → Local simulation: run local simulation
README.md