Build a lab for HackerPod

Turn a vulnerability you understand into a machine other people can break. Every lab is reviewed by a person before it reaches players, and goes live credited to you.

Step by step

1. Claim your idea. Open an issue in gowthaman-k-s/hackerpod-labs using the Claim a lab form: the vulnerability, the technology and the difficulty. A maintainer replies so two people don't build the same lab. You can have one lab under review at a time.
2. Fork the repository and copy the template. Copy labs/_template/ to labs/<your-lab-id>/. The id is lowercase letters, numbers and hyphens, e.g. sqli-bakery.
3. Add your application. Put the vulnerable app's source code in the folder. Already have a project? Bring its source, not a ready-made image — reviewers have to be able to read everything that runs.
4. Write the Containerfile. Start from the template's. Use an official base image pinned by its digest, install packages with the system's package manager, copy your files in, and finish with a non-root USER. The build has no internet access except official package mirrors, so commit anything else your lab needs.
5. Read the flag from the environment. At start-up your app reads its flag from LAB_FLAG (or LAB_FLAG_<ID> when the lab has several objectives). Never write a flag into your code: every player gets a fresh random one at each launch.
6. Describe it in lab.yml. Name, summary, category, difficulty, estimated minutes, the one port your app listens on, and the objectives with their points.
7. Prove it can be solved. Write solution.sh: a short script that exploits your lab and prints the flag it captures. It runs in a minimal container with sh and curl, and the address of your lab in LAB_URL.
8. Explain it for reviewers. In README.md: where the flaw is, how the flag is exposed, and anything unusual.
9. Test it in the HackerPod sandbox. The template's compose.test.yaml runs your lab the way players will: no internet, no extra privileges, reachable only from your own computer. Then run the checking tools from the repository:

   $ pip install pyyaml jsonschema
   $ python tools/validate_lab.py labs/<your-lab-id>
   $ python tools/scan_lab.py labs/<your-lab-id>

   The scan must say PASS. If it finds something, it tells you the file, the line and how to fix it.
10. Open a pull request. Change only your lab's folder. Automatic checks build it, scan it and solve it with a random flag. Fix anything they report and push again.
11. Review. A maintainer reads your lab and approves it, asks for changes, or declines it with a reason. You see their notes on the pull request. If you push changes after approval, it is reviewed again.
12. Live. After merge your lab is published and appears in the HackerPod app and on this site with your name on it. New versions go through the same steps.

What a lab must not contain

HackerPod decides how labs run — networking, ports, storage and privileges — so they can never harm a player's computer. Submissions that try to decide these themselves are rejected by the checks.

Some things — like a shell, outside links, encoded data or setuid programs — are allowed when they are the point of the lab, but a maintainer has to agree. Explain them in your README.

Content rules

• Labs are practice targets. No real malware, no working exploits for unpatched real-world products, no real people's data.
• You must have the right to publish everything you submit, under the licence you choose in lab.yml.
• Be kind in issues and reviews.