This repository contains an older, standalone version of the platform used to run the picoCTF 2019 competition. Our development efforts are currently focused on our new web platform at play.picoctf.org, and this repo is not actively maintained.
The picoCTF platform is the infrastructure which is used to run picoCTF.
The platform is designed to be easily adapted to other CTF or programming competitions.
If using the platform to host a custom competition, we recommend using the most
recent tagged release. The
master branch represents active development and may not be stable.
Additionally, we cannot guarantee the stability or security of any outdated
Please visit our Discord server for other platform deployment questions not covered in our documentation: https://discord.gg/WQGdYaB
The following steps will use Vagrant to get you
quickly up and running with the picoCTF platform by deploying the code base to
two local virtual machines. You can read more about using
vagrant in our
git clone https://github.com/picoCTF/picoCTF.git cd picoCTF vagrant up
These commands perform the following:
- Get the source code at the most recent development state (
- Change into the source code directory (
- Bring up a local copy of the picoCTF platform (
- This will take approximately 30-45 minutes based on your network speed as vagrant downloads a base virtual machine and all the components to install the platform. This is a one-time, upfront cost. Obligatory xkcd.
Now that your local copy of picoCTF has been deployed:
- Browse to http://192.168.2.2/
- Login with the automatically created administrator account
Make your first change. For example to change "CTF Placeholder" in the navigation bar:
- Update the running site.
- If you have
ansibleinstalled locally on your machine it is as
cd infra_local ansible-playbook site.yml --limit web --tags web-static
- If you do not, then you can run the same command from within the virtual machine:
vagrant ssh web cd /picoCTF/infra_local ansible-playbook site.yml --limit web --tags web-static
- If you have
Then check out the infra_local directory for more information on using the local development environment in a more efficient manner.
Interested in development? Check out the notes in infra_local.
The documentation has more information on Alternative Deployments.
Continue reading for more information on the picoCTF project.
This project is broken down into a few discrete components that compose to build a robust and full featured CTF platform. Specifically the project consists of the following:
- picoCTF-web. The website and all APIs.
- picoCTF-shell. Where users go to solve challenges.
- problems. CTF problem source code.
- ansible. Used for configuring machines.
- Infrastructure Examples. Different ways to deploy the picoCTF platform
Once you bring everything up, the main flow between components is:
Here is a walkthrough:
- The user connects to the "Web Server". This is an nginx server.
- The nginx server serves up content in picoCTF-web/web.
- The nginx server only serves up static HTML files.
- The browser rendering in turn makes requests to a REST-ful like API
/api/to nginx. Requests to
/apiare forwarded to an API server (running on the same host for development).
- There is a special interface called
/admin, which is used by the admin to connect to new shell servers.
- The users
/apirequest is forwarded to the API server.
- The API server is a python flask server with code under picoCTF-web/api
- There is an API for adding users, checking passwords, etc.
- There is an API for serving up challenges, checking flags, etc.
- The API keeps track of user score and membership to teams.
- A user can
sshto the shell server.
- The shell server is loaded with problems, with examples in problems.
- The web server connects to the shell server and retrieves a JSON file containing problem instance location, point value, etc.
- The web server authenticates users using password data stored and via the API.
Some important terminology:
- A problem is a logical CTF problem. (Sometimes called a challenge)
- Solving a problem gives a user points.
- A problem can be locked or unlocked for a user.
- Super important: problems do not have flags. They are purely logical.
- A problem instance, or instance for short, is a generated version of a
challenge to be solved by a user.
- A single problem can have instances
inst_n. Each instance has its own flag
- Users are assigned specific problem instances, and they are expected to
submit only their flag. For example, if user Foo has instance
flag_1is a valid flag (aa separate instance flag
flag_2is not valid)
- Instances were invented to help combat flag sharing. If player Foo has been
flag_2, then whomever has
inst_2shared their flag. There may be legitimate reasons for flag sharing, but in many competitions it is indicative of cheating.
- Instances are generated from a template. Think of it like templating in a
web framework. For example, a buffer overflow problem may template the
specific buffer size so a solution for
inst_iwill not work for
- A single problem can have instances
The competitor facing web site, the API for running a CTF, and the management functionality for CTF organizers. The development Vagrantfile deploys picoCTF-web to a virtual machine (web) at http://192.168.2.2/. If you want to modify the look and feel of the website, this is the place to start.
The tools to create, package, and deploy challenges for use with the picoCTF platform. This supports the deployment of auto-generated challenge instances and provides competitors shell access to aid in challenge solving. The development Vagrantfile deploys the shell-server as a second virtual machine (shell) at http://192.168.2.3/. If you want to modify challenge deployment primitives, this is the place to start.
picoCTF Compatible Problems
Example challenges that are compatible with the picoCTF platform. These challenges can be easily shared, deployed, or adapted for use in a CTF. The development Vagrantfile installs these examples to the shell server and loads them into the web interface. If you want to see how to create challenges or leverage the hacksport library, this is the place to start.
Ansible for Automated System Administration
The tool we use to install, configure, deploy, and administer the picoCTF platform is Ansible. This allows us to create flexible, parameterized, automated playbooks and roles that apply across development, staging, and production environments. If you want to modify way the platform is configured, this is the place to start.
Running Your Own Competition
If you are looking to run your own CTF competition, you should:
- Make sure you can bring up the local infrastructure (
- Make sure you understand how to deploy the infrastructure via
- To enable password reset emails, log in using the site administrator account and configure Email under Management > Configuration.
- You should start writing your own problems, loading them into the shell
server, and syncing the web server problem set with the shell server via the
Do not underestimate the importance of spending significant time in problem development. Our internal system is:
- We form a working group for the contest.
- We often vet problem ideas with the group before implementation.
- Implement and deploy. Hardcode nothing (or as little as possible).
- THE KEY STEP: Play test! Often the initial problem will have an intellectual leap built-in that's obvious to the creator but to no one else. Play testing makes sure the problem is coherent, self-contained, and fun.
For more on running events see:
Giving Back and Development
The picoCTF platform is always under development.
- See CONTRIBUTING.md for setting up a git workflow and some standards.
- We are especially interested any improvements on continuous integration and automated testing.
If you are interested in research in CTFs (e.g., improving skill acquisition, decreasing time to mastery, etc.), please feel free to email David Brumley.
picoCTF was started by David Brumley with his CMU professor hat in 2013. The intention has always been to give back to the CTF community.
The original heavy lifting was done by his graduate students, and special thanks is due to Peter Chapman (picoCTF 2013 technical lead) and Jonathan Burket (picoCTF 2014 technical lead) for their immense efforts not only developing code, but for organizing art work, problem development, and so on.
In 2015-2016 significant effort was done by ForAllSecure at the companies expense. This includes adding concepts like the shell server, and rewriting significant portions of the web server.
Both CMU and ForAllSecure have agreed to release all code under the MIT LICENSE . We do encourage attribution as that helps us secure funding and interest to run picoCTF year after year, but it is not necessary. Also, if you do end up running a contest, do feel free to drop David Brumley a line.
- Bug Reports: GitHub Issues
- Contributors (in no particular order): David Brumley, Tim Becker, Chris Ganas, Roy Ragsdale, Peter Chapman, Jonathan Burket, Collin Petty, Tyler Nighswander, Garrett Barboza, Mong-Yah "Max" Hsieh