OWASP CTF in a Box

A self-hosted control plane for security-learning events — one box, one free GitHub org.
Run it for a university, a high school, an OWASP chapter, a meetup.

Working on the kit (humans and agents)

Read AGENTS.md before you write code. It is the operating manual: the exact commands CI runs, the failure modes this repo has already hit, and the review invariants in docs/reviewing.md. CLAUDE.md is a pointer to the same file.

A change is ready when CI is green and every actionable CodeRabbit thread on the latest commit is resolved (or declined on the record). Commits follow Conventional Commits and carry no AI attribution.

Small, well-specified work is tagged good first issue. New modules start as an issue, not a PR — see CONTRIBUTING.md.

What this is

A control plane, not a single game. The box gives an event its shared spine — a GitHub org, team registration, a live leaderboard, an organizer admin panel, and the scoring pipeline that feeds it. Modules plug challenge content into that spine, and any subset can run alone or together: patch-to-score Secure Development, a Quiz bank, a Jeopardy board, and externally hosted AI challenges. The module contract is the boundary between spine and content, so the box is built to host further modules — forensics, API-security, cloud — as they land.

Why it exists. The Secure Development module teaches defence rather than attack, and it is a genuinely good way to teach secure coding. Until now, running one meant standing up Vercel, Upstash, Lambda and DynamoDB, holding the cloud bill, and having access to a private scoring image. That is a reasonable ask for a conference with a budget. It is an unreasonable ask for a university security course, a high-school club, an OWASP chapter night, or a weekend workshop.

This kit removes it. Everything runs from Docker Compose on one machine you already have — a laptop, a spare desktop, a small VPS — plus one free GitHub org for the forks. The rubrics for all six targets ship inside the box, so there is no private image to request and no scoring code to write. Nothing is billed, nothing phones home, and when the event ends you archive the repos and stop the stack.

Who it's for: anyone who wants to run this event and does not want to become a cloud operator to do it — course instructors, club organizers, OWASP chapter leads, workshop facilitators, security teams running an internal training day.

Status

Deployed and exercised end to end; not yet run for a real cohort. The full scoring path ships in-kit — the scorer's bearer-authed POST /score, the self-contained scoring workflow for the forks, the poll transport — and scripts/smoke.sh drives that whole pipeline against mocks. Beyond that, the kit runs continuously on a hosted box from the same Compose file this repo ships, GET /health reports the exact revision serving it, and an end-to-end pass over that live instance is where a batch of real defects were found and fixed — the sort a mocked suite cannot see.

What has not happened is a real event: a cohort of contestants opening real PRs against real forks, at once, for hours. That is the gap between "the pipeline works" and "the pipeline works at 40 people". Two caveats are open rather than buried: the Security Shepherd result matcher has a stated residual limit (an unusually-phrased refusal can still read as a solve — it can under-credit a correct patch, never award a free point), and the load profile of a full cohort is untested. Detail and current state: Status and upstream dependencies.

What it is not

• Not a general CTF platform. CTFd is mature, battle-tested, and has a large plugin ecosystem — if you want a conventional jeopardy or attack-defense event with maximum flexibility, use CTFd. This kit's Jeopardy module is deliberately smaller than CTFd.
• Not a hosted practice gym. picoCTF gives you curriculum and challenges with zero operations — if you don't need to run your own event with your own content and roster, it's the better answer.
• Not an attack trainer. The flagship module grades patches, not exploits. Contestants fix vulnerabilities and a pipeline proves the fix.

What it does that those don't: patch-to-score defence training graded through GitHub pull requests, a module contract for mixing game types on one leaderboard, and a control plane you own end to end — one box, one free org, no cloud bill, no telemetry.

This is an OWASP Foundation project — an incubator-level tool project; its home page is owasp.org/projects/ctf-in-a-box. Four of the six vulnerable targets are OWASP projects (Juice Shop, WebGoat, Security Shepherd, VulnerableApp); DVWA and VAmPI are community projects. OWASP does not endorse or recommend any product or service, including the targets this kit hosts — they are training material, chosen for what they teach.

Quickstart

See it running in two minutes — no GitHub org, no OAuth app, nothing to configure. You need Docker with Compose v2 and openssl:

git clone https://github.com/OWASP/owasp-ctf-in-a-box
cd owasp-ctf-in-a-box
./scripts/dev-stack up