{"id":13546469,"url":"https://github.com/picoCTF/picoCTF","last_synced_at":"2025-04-02T18:30:48.877Z","repository":{"id":47091328,"uuid":"53499652","full_name":"picoCTF/picoCTF","owner":"picoCTF","description":"The platform used to run picoCTF 2019. (deprecated)","archived":true,"fork":false,"pushed_at":"2024-05-13T17:56:47.000Z","size":9511,"stargazers_count":288,"open_issues_count":55,"forks_count":91,"subscribers_count":19,"default_branch":"master","last_synced_at":"2024-11-03T14:35:50.317Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://picoctf.org","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/picoCTF.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-03-09T13:26:51.000Z","updated_at":"2024-10-23T18:28:24.000Z","dependencies_parsed_at":"2024-06-21T16:48:56.631Z","dependency_job_id":"da691d81-d12f-45aa-bcd3-5c7a3d663647","html_url":"https://github.com/picoCTF/picoCTF","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/picoCTF%2FpicoCTF","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/picoCTF%2FpicoCTF/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/picoCTF%2FpicoCTF/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/picoCTF%2FpicoCTF/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/picoCTF","download_url":"https://codeload.github.com/picoCTF/picoCTF/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246869666,"owners_count":20847172,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T12:00:38.414Z","updated_at":"2025-04-02T18:30:47.444Z","avatar_url":"https://github.com/picoCTF.png","language":"Python","funding_links":[],"categories":["Python (144)","Platforms"],"sub_categories":[],"readme":"# picoCTF\n\n## Deprecation Warning\n\nThis repository contains an older, deprecated version of the picoCTF platform which was used to run\nthe picoCTF 2019 competition. Our development efforts are currently focused on our\nnew web platform at [play.picoctf.org](http://play.picoctf.org), and this repo is\nno longer maintained or supported. We do not recommend its use for new competitions.\n\nIf you are looking to host your own CTF, we recommend a modern tool such as\n[CTFd](https://github.com/CTFd/CTFd) or [kCTF](https://github.com/google/kctf).\n\n## Introduction\n\nThe picoCTF platform is the infrastructure which is used to run\n[picoCTF](https://picoctf.com/).\n\nThe platform is designed to be easily adapted to other CTF or programming\ncompetitions.\n\nIf using the platform to host a custom competition, we recommend using the most\nrecent tagged [release](https://github.com/picoCTF/picoCTF/releases). The\n`master` branch represents active development and may not be stable.\nAdditionally, we cannot guarantee the stability or security of any outdated\nreleases.\n\nAdditional documentation can be found at [docs.picoctf.com][docs] or within the\n[`/docs` directory](./docs/README.md).\n\n[docs]:https://docs.picoctf.com\n\nPlease visit our Discord server for other platform deployment questions not\ncovered in our documentation: https://discord.gg/WQGdYaB\n\n## Quick Start\n\nThe following steps will use [Vagrant](https://www.vagrantup.com/) to get you\nquickly up and running with the picoCTF platform by deploying the code base to\ntwo local virtual machines. You can read more about using `vagrant` in our\n[documentation](./docs/vagrant.md)\n\n```\ngit clone https://github.com/picoCTF/picoCTF.git\ncd picoCTF\nvagrant up\n```\n\nThese commands perform the following:\n\n1. Get the source code at the most recent development state (`git`)\n2. Change into the source code directory (`cd`)\n3. Bring up a local copy of the picoCTF platform (`vagrant`)\n    - This will take approximately 30-45 minutes based on your network speed as\n    vagrant downloads a base virtual machine and all the components to install\n    the platform. This is a one-time, upfront cost. Obligatory [xkcd][].\n\n[xkcd]:https://xkcd.com/303/\n\nNow that your local copy of picoCTF has been deployed:\n\n4. Browse to http://192.168.2.2/\n5. Login with the automatically created administrator account\n    - user: `ctfadmin`\n    - password: `dev`\n\nMake your first change. For example to change \"CTF Placeholder\" in the\nnavigation bar:\n\n6. Edit `picoCTF-web/web/_includes/header.html`\n7. Update the running site.\n    - If you have `ansible` installed locally on your machine it is as\n    ```\n    cd infra_local\n    ansible-playbook site.yml --limit web --tags web-static\n    ```\n    - If you do not, then you can run the same command from within the virtual\n    machine:\n    ```\n    vagrant ssh web\n    cd /picoCTF/infra_local\n    ansible-playbook site.yml --limit web --tags web-static\n    ```\n\nThen check out the [infra_local](./infra_local) directory for more information\non using the local development environment in a more efficient manner.\n\n### Next Steps\n\nInterested in development? Check out the notes in [infra_local][il].\n\nInterested in running a public event? Check out the notes in [infra_remote][ir]\nand the [Running Your Own Competition][r] section of this document.\n\nThe documentation has more information on [Alternative Deployments][ad].\n\nContinue reading for more information on the picoCTF project.\n\n[il]:./infra_local\n[ir]:./infra_remote\n[r]:/README.md#running-your-own-competition\n[ad]:./docs/alt_deployment.md\n\n## Project Overview\n\nThis project is broken down into a few discrete components that compose to build\na robust and full featured CTF platform. Specifically the project consists of\nthe following:\n\n1. [picoCTF-web](./picoCTF-web). The website and all APIs.\n2. [picoCTF-shell](./picoCTF-shell). Where users go to solve challenges.\n3. [problems](./problems). CTF problem source code.\n4. [ansible](./ansible). Used for configuring machines.\n5. Infrastructure Examples. Different ways to deploy the picoCTF platform\n  - [infra_local][il]. Local infrastructure (Vagrant)\n  - [infra_remote][ir]. Remote infrastructure (Terraform)\n\n### Walkthrough\n\nOnce you bring everything up, the main flow between components is:\n\n![Architecture](docs/architecture.png)\n\nHere is a walkthrough:\n1. The user connects to the \"Web Server\". This is an nginx server.\n   - The nginx server serves up content in [picoCTF-web/web](picoCTF-web/web).\n   - The nginx server only serves up static HTML files.\n   - Most HTML files contain javascript, which is rendered browser-side for\n     speed.\n   - The browser rendering in turn makes requests to a REST-ful like API `/api/`\n     to nginx. Requests to `/api` are forwarded to an API server (running on the\n     same host for development).\n   - There is a special interface called `/admin`, which is used by the admin to\n     connect to new shell servers.\n2. The users `/api` request is forwarded to the API server.\n   - The API server is a python flask server with code under\n     [picoCTF-web/api](picoCTF-web/api)\n   - There is an API for adding users, checking passwords, etc.\n   - There is an API for serving up challenges, checking flags, etc.\n   - The API keeps track of user score and membership to teams.\n3. A user can `ssh` to the shell server.\n   - The shell server is loaded with problems, with examples in\n     [problems](problems/).\n   - The web server connects to the shell server and retrieves a JSON file\n     containing problem instance location, point value, etc.\n   - The web server authenticates users using password data stored and via the\n     API.\n\nSome important terminology:\n+ A _problem_ is a logical CTF problem. (Sometimes called a _challenge_)\n  + Solving a problem gives a user points.\n  + A problem can be _locked_ or _unlocked_ for a user.\n  + Super important: problems *do not* have flags. They are purely logical.\n+ A _problem instance_, or _instance_ for short, is a generated version of a\n  challenge to be solved by a user.\n  + A single problem can have instances `inst_1`, `inst_2`, ..., `inst_n`. Each\n    instance has its own flag `flag_1`, `flag_2`, ..., `flag_n`\n  + Users are assigned specific problem instances, and they are expected to\n    submit only their flag. For example, if user Foo has instance `inst_1`, only\n    `flag_1` is a valid flag (aa separate instance flag `flag_2` is not valid)\n  + Instances were invented to help combat flag sharing. If player Foo has been\n    assigned `inst_1` but submits `flag_2`, then whomever has `inst_2` shared\n    their flag. There may be legitimate reasons for flag sharing, but in many\n    competitions it is indicative of cheating.\n  + Instances are generated from a _template_. Think of it like templating in a\n    web framework. For example, a buffer overflow problem may template the\n    specific buffer size so a solution for `inst_i` will not work for `inst_j`.\n\n### picoCTF-web\n\nThe competitor facing web site, the API for running a CTF, and the management\nfunctionality for CTF organizers. The development [Vagrantfile](./Vagrantfile)\ndeploys picoCTF-web to a virtual machine (web) at http://192.168.2.2/. If you\nwant to modify the look and feel of the website, this is the place to start.\n\n### picoCTF-shell-manager\n\nThe tools to create, package, and deploy challenges for use with the picoCTF\nplatform. This supports the deployment of auto-generated challenge instances and\nprovides competitors shell access to aid in challenge solving. The development\n[Vagrantfile](./Vagrantfile) deploys the shell-server as a second virtual\nmachine (shell) at http://192.168.2.3/. If you want to modify challenge\ndeployment primitives, this is the place to start.\n\n### picoCTF Compatible Problems\n\nExample challenges that are compatible with the picoCTF platform. These\nchallenges can be easily shared, deployed, or adapted for use in a CTF. The\ndevelopment [Vagrantfile](./Vagrantfile) installs these examples to the shell\nserver and loads them into the web interface. If you want to see how to create\nchallenges or leverage the hacksport library, this is the place to start.\n\n### Ansible for Automated System Administration\n\nThe tool we use to install, configure, deploy, and administer the picoCTF\nplatform is [Ansible](https://www.ansible.com/). This allows us to create\nflexible, parameterized, automated playbooks and roles that apply across\ndevelopment, staging, and production environments. If you want to modify way the\nplatform is configured, this is the place to start.\n\n## Running Your Own Competition\n\nIf you are looking to run your own CTF competition, you should:\n1. Make sure you can bring up the local infrastructure (`Vagrantfile`\n   and [infra_local][il])\n1. Make sure you understand how to deploy the infrastructure via `terraform` and\n   `ansible` ([infra_remote][ir]).\n2. You can reskin the look and feel of the site by editing the\n   [picoCTF-web/web](picoCTF-web/web) javascript and HTML code.\n3. To enable password reset emails, log in using the site administrator\n   account and configure Email under Management \u003e Configuration.\n4. You should start writing your own problems, loading them into the shell\n   server, and syncing the web server problem set with the shell server via the\n   `/admin` URL endpoint.\n\nDo not underestimate the importance of spending significant time in problem\ndevelopment. Our internal system is:\n1. We form a working group for the contest.\n2. We often vet problem ideas with the group before implementation.\n3. Implement and deploy. Hardcode nothing (or as little as possible).\n4. *THE KEY STEP:* Play test! Often the initial problem will have an\n   intellectual leap built-in that's obvious to the creator but to no one\n   else. Play testing makes sure the problem is coherent, self-contained, and\n   fun.\n\nFor more on running events see:\n- [The Many Maxims of Maximally Effective CTFs][maxims]\n- [PPP's Suggestions For Running a CTF][ppp]\n\n[maxims]:https://captf.com/maxims.html\n[ppp]:https://github.com/pwning/docs/blob/master/suggestions-for-running-a-ctf.markdown\n\n## Giving Back and Development\n\nThe picoCTF platform is always under development.\n- See [CONTRIBUTING.md](CONTRIBUTING.md) for setting up a git workflow and some\n  standards.\n- We are especially interested any improvements on continuous integration and\n  automated testing.\n\nIf you are interested in research in CTFs (e.g., improving skill acquisition,\ndecreasing time to mastery, etc.), please feel free to email David Brumley.\n\n## Credits\n\npicoCTF was started by David Brumley with his CMU professor hat in 2013. The\nintention has always been to give back to the CTF community.\n\nThe original heavy lifting was done by his graduate students, and special thanks\nis due to Peter Chapman (picoCTF 2013 technical lead) and Jonathan Burket\n(picoCTF 2014 technical lead) for their immense efforts not only developing\ncode, but for organizing art work, problem development, and so on.\n\nIn 2015-2016 significant effort was done by\n[ForAllSecure](https://forallsecure.com) at the companies expense. This includes\nadding concepts like the shell server, and rewriting significant portions of the\nweb server.\n\nBoth CMU and ForAllSecure have agreed to release all code under the [MIT\nLICENSE](./LICENSE) . We do encourage attribution as that helps us secure\nfunding and interest to run picoCTF year after year, but it is not\nnecessary. Also, if you do end up running a contest, do feel free to drop David\nBrumley a line.\n\n- Bug Reports: [GitHub Issues](https://github.com/picoCTF/picoCTF/issues)\n- Contributors (in no particular order): David Brumley, Tim Becker, Chris Ganas,\n  Roy Ragsdale, Peter Chapman, Jonathan Burket, Collin Petty, Tyler Nighswander,\n  Garrett Barboza, Mong-Yah \"Max\" Hsieh\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FpicoCTF%2FpicoCTF","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FpicoCTF%2FpicoCTF","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FpicoCTF%2FpicoCTF/lists"}