Repository files navigation

This repository contains an older, deprecated version of the picoCTF platform which was used to runthe picoCTF 2019 competition. Our development efforts are currently focused on ournew web platform atplay.picoctf.org, and this repo isno longer maintained or supported. We do not recommend its use for new competitions.

If you are looking to host your own CTF, we recommend a modern tool such asCTFd orkCTF.

The picoCTF platform is the infrastructure which is used to runpicoCTF.

The platform is designed to be easily adapted to other CTF or programmingcompetitions.

If using the platform to host a custom competition, we recommend using the mostrecent taggedrelease. Themaster branch represents active development and may not be stable.Additionally, we cannot guarantee the stability or security of any outdatedreleases.

Additional documentation can be found atdocs.picoctf.com or within the/docs directory.

Please visit our Discord server for other platform deployment questions notcovered in our documentation:https://discord.gg/WQGdYaB

The following steps will useVagrant to get youquickly up and running with the picoCTF platform by deploying the code base totwo local virtual machines. You can read more about usingvagrant in ourdocumentation

git clone https://github.com/picoCTF/picoCTF.gitcd picoCTFvagrant up

These commands perform the following:

1. Get the source code at the most recent development state (git)
2. Change into the source code directory (cd)
3. Bring up a local copy of the picoCTF platform (vagrant)
   • This will take approximately 30-45 minutes based on your network speed asvagrant downloads a base virtual machine and all the components to installthe platform. This is a one-time, upfront cost. Obligatoryxkcd.

Now that your local copy of picoCTF has been deployed:

4. Browse tohttp://192.168.2.2/
5. Login with the automatically created administrator account
   • user:ctfadmin
   • password:dev

Make your first change. For example to change "CTF Placeholder" in thenavigation bar:

6. EditpicoCTF-web/web/_includes/header.html
7. Update the running site.
   • If you haveansible installed locally on your machine it is as

   cd infra_localansible-playbook site.yml --limit web --tags web-static

   • If you do not, then you can run the same command from within the virtualmachine:

   vagrant ssh webcd /picoCTF/infra_localansible-playbook site.yml --limit web --tags web-static

Then check out theinfra_local directory for more informationon using the local development environment in a more efficient manner.

Interested in development? Check out the notes ininfra_local.

Interested in running a public event? Check out the notes ininfra_remoteand theRunning Your Own Competition section of this document.

The documentation has more information onAlternative Deployments.

Continue reading for more information on the picoCTF project.

This project is broken down into a few discrete components that compose to builda robust and full featured CTF platform. Specifically the project consists ofthe following:

1. picoCTF-web. The website and all APIs.
2. picoCTF-shell. Where users go to solve challenges.
3. problems. CTF problem source code.
4. ansible. Used for configuring machines.
5. Infrastructure Examples. Different ways to deploy the picoCTF platform

• infra_local. Local infrastructure (Vagrant)
• infra_remote. Remote infrastructure (Terraform)

Once you bring everything up, the main flow between components is:

Here is a walkthrough:

1. The user connects to the "Web Server". This is an nginx server.
   • The nginx server serves up content inpicoCTF-web/web.
   • The nginx server only serves up static HTML files.
   • Most HTML files contain javascript, which is rendered browser-side forspeed.
   • The browser rendering in turn makes requests to a REST-ful like API/api/to nginx. Requests to/api are forwarded to an API server (running on thesame host for development).
   • There is a special interface called/admin, which is used by the admin toconnect to new shell servers.
2. The users/api request is forwarded to the API server.
   • The API server is a python flask server with code underpicoCTF-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.
3. A user canssh to the shell server.
   • The shell server is loaded with problems, with examples inproblems.
   • The web server connects to the shell server and retrieves a JSON filecontaining problem instance location, point value, etc.
   • The web server authenticates users using password data stored and via theAPI.

Some important terminology:

• Aproblem is a logical CTF problem. (Sometimes called achallenge)
  • Solving a problem gives a user points.
  • A problem can belocked orunlocked for a user.
  • Super important: problemsdo not have flags. They are purely logical.
• Aproblem instance, orinstance for short, is a generated version of achallenge to be solved by a user.
  • A single problem can have instancesinst_1,inst_2, ...,inst_n. Eachinstance has its own flagflag_1,flag_2, ...,flag_n
  • Users are assigned specific problem instances, and they are expected tosubmit only their flag. For example, if user Foo has instanceinst_1, onlyflag_1 is a valid flag (aa separate instance flagflag_2 is not valid)
  • Instances were invented to help combat flag sharing. If player Foo has beenassignedinst_1 but submitsflag_2, then whomever hasinst_2 sharedtheir flag. There may be legitimate reasons for flag sharing, but in manycompetitions it is indicative of cheating.
  • Instances are generated from atemplate. Think of it like templating in aweb framework. For example, a buffer overflow problem may template thespecific buffer size so a solution forinst_i will not work forinst_j.

The competitor facing web site, the API for running a CTF, and the managementfunctionality for CTF organizers. The developmentVagrantfiledeploys picoCTF-web to a virtual machine (web) athttp://192.168.2.2/. If youwant 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 picoCTFplatform. This supports the deployment of auto-generated challenge instances andprovides competitors shell access to aid in challenge solving. The developmentVagrantfile deploys the shell-server as a second virtualmachine (shell) athttp://192.168.2.3/. If you want to modify challengedeployment primitives, this is the place to start.

Example challenges that are compatible with the picoCTF platform. Thesechallenges can be easily shared, deployed, or adapted for use in a CTF. ThedevelopmentVagrantfile installs these examples to the shellserver and loads them into the web interface. If you want to see how to createchallenges or leverage the hacksport library, this is the place to start.

The tool we use to install, configure, deploy, and administer the picoCTFplatform isAnsible. This allows us to createflexible, parameterized, automated playbooks and roles that apply acrossdevelopment, staging, and production environments. If you want to modify way theplatform is configured, this is the place to start.

If you are looking to run your own CTF competition, you should:

1. Make sure you can bring up the local infrastructure (Vagrantfileandinfra_local)
2. Make sure you understand how to deploy the infrastructure viaterraform andansible (infra_remote).
3. You can reskin the look and feel of the site by editing thepicoCTF-web/web javascript and HTML code.
4. To enable password reset emails, log in using the site administratoraccount and configure Email under Management > Configuration.
5. You should start writing your own problems, loading them into the shellserver, and syncing the web server problem set with the shell server via the/admin URL endpoint.

Do not underestimate the importance of spending significant time in problemdevelopment. Our internal system is:

1. We form a working group for the contest.
2. We often vet problem ideas with the group before implementation.
3. Implement and deploy. Hardcode nothing (or as little as possible).
4. THE KEY STEP: Play test! Often the initial problem will have anintellectual leap built-in that's obvious to the creator but to no oneelse. Play testing makes sure the problem is coherent, self-contained, andfun.

For more on running events see:

• The Many Maxims of Maximally Effective CTFs
• PPP's Suggestions For Running a CTF

The picoCTF platform is always under development.

• SeeCONTRIBUTING.md for setting up a git workflow and somestandards.
• We are especially interested any improvements on continuous integration andautomated 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. Theintention has always been to give back to the CTF community.

The original heavy lifting was done by his graduate students, and special thanksis due to Peter Chapman (picoCTF 2013 technical lead) and Jonathan Burket(picoCTF 2014 technical lead) for their immense efforts not only developingcode, but for organizing art work, problem development, and so on.

In 2015-2016 significant effort was done byForAllSecure at the companies expense. This includesadding concepts like the shell server, and rewriting significant portions of theweb server.

Both CMU and ForAllSecure have agreed to release all code under theMITLICENSE . We do encourage attribution as that helps us securefunding and interest to run picoCTF year after year, but it is notnecessary. Also, if you do end up running a contest, do feel free to drop DavidBrumley 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