challenge_status_tracker/README.md

CTF challenge status tracker

Tracks the progress of the h4tum CTF challenges. It reads every repo in the GitLab challenges group, works out each challenge's status, category and difficulty from its README.md, and checks that challenges marked as ready really are. The result goes to:

• a HedgeDoc note: an overview of all challenges, refreshed every 30 minutes
• challs.txt in the deployment repo: the clone URLs of every challenge ready for infra testing, updated daily
• the terminal: the same overview, for a quick look

Requirements

• Python 3.9+
• requests and PyYAML (python-requests python-yaml on Arch, python3-requests python3-yaml on Debian)

Configuration

cp .env.example .env && chmod 600 .env

Key	Required	Meaning
GITLAB_GROUP_URL	yes	GitLab group that holds one repo per challenge
GITLAB_TOKEN	yes	Personal access token, see below
HEDGEDOC_NOTE	for --update	URL of an existing note; its permission must be freely
HEDGEDOC_TAGS	no	Tags written into the note's front matter
CHALLS_REPO_URL	for --challs	Deployment repo that holds challs.txt
CHALLS_PATH	no	Path of the file in that repo (default 2026/challs.txt)
CHALLS_BRANCH	no	Branch to commit to (default: the repo's default branch)

The token needs Project: Read and Repository: Read on the challenges group. For --challs it also needs Repository: Read + Write on the deployment repo, and permission to push to the branch if it is protected.

Environment variables override the values in .env.

Usage

./ctf_status.py                     # print the overview
./ctf_status.py -o overview.md      # also write the note's markdown to a file
./ctf_status.py --update            # overwrite the HedgeDoc note
./ctf_status.py --challs            # commit challs.txt, if it changed
./ctf_status.py -q --challs-out -   # preview challs.txt without committing

./ctf_status.py --help lists all options. With --quiet, a run prints nothing unless something changed or failed.

Deployment

On the server, with .env in place:

./install-timer.sh

This installs and starts two systemd user timers:

Timer	Runs	Does
ctf-status.timer	every 30 minutes	--update: refresh the HedgeDoc note
ctf-challs.timer	daily at 04:00	--challs: commit challs.txt

Re-running the script is safe. To check on the timers:

systemctl --user list-timers 'ctf-*'
journalctl --user -u ctf-status.service -n 50
journalctl --user -u ctf-challs.service -n 50

How challenges are evaluated

Each challenge repo starts from a template whose README begins with:

### Challenge Name
- Category: crypto
- Difficulty: medium
- Event: ...
- Author: ...
- Tester: ...
- Status: Testing Ready

The status is one of Planning → PoC Draft → Testing Ready → Tested → Ready. Loosely written values are normalised. If a status names several stages, the least advanced one counts.

Two kinds of finding are reported:

• Problems are missing or unclear README fields, such as no category, an unreadable status, or a Testing Ready challenge with no tester. They are listed under Needs attention and change nothing else.
• Blockers are signs that a challenge claiming Testing Ready or beyond is not actually finished: description.yml is missing or still the template, its category or flag is wrong, a deploy_dir or its Dockerfile is missing, or there is no solve.py. A blocked challenge (⛔) is kept out of challs.txt.

Passing every check does not prove that a challenge builds or solves. That is what testing is for.

All rules are in tracker/checks.py, one function each.

Project layout

ctf_status.py          command line entry point
tracker/
  checks.py            the rules: README problems and repo blockers
  challenge.py         reads a README header into a Challenge
  gitlab.py            GitLab API access
  overview.py          runs parsing and checks over all repos
  terminal.py          terminal output
  markdown.py          HedgeDoc note
  challs.py            challs.txt
  hedgedoc.py          writes the note to HedgeDoc
  config.py            reads the configuration
install-timer.sh       installs the systemd units below
ctf-*.service/.timer   systemd unit templates