challenge_status_tracker/README.md

ctf_status.py

Reads the README.md of every repo in the GitLab challenges group (REST API, no clone) and shows which categories have challenges in which state, at which difficulty — in the terminal and as a HedgeDoc note. A status of Testing Ready or beyond is only believed if the repo backs it up (see Checking the repo).

Needs requests and PyYAML (python-requests python-yaml on Arch, python3-requests python3-yaml on Debian).

Setup

cp ctf_status.env.example ctf_status.env && chmod 600 ctf_status.env
$EDITOR ctf_status.env      # GitLab group URL + token, HedgeDoc note

Use

./ctf_status.py                          # terminal summary
./ctf_status.py -o overview.md           # + HedgeDoc markdown to a file
./ctf_status.py --stdout | wl-copy       # straight to clipboard, paste into HedgeDoc
./ctf_status.py --update                 # overwrite the note in HEDGEDOC_NOTE
./ctf_status.py --update <note-url>      # ... or an explicit one

The token is a fine-grained personal access token on the challenges group with Project: Read (to list the repos) and Repository: Read (to download the READMEs and description.yml, and to list the repo's files). A plain .env with GL_PAT= / GITLAB_URL= is read as well.

Keeping a HedgeDoc note up to date

--update overwrites an existing note in place, so the URL you share stays the same. Every run rewrites the whole body, starting with

---
tags: Logistics, h4tum CTF 2026
---

and a **Last updated:** <date> <time> <tz> line under the heading, so a stale note is obvious at a glance. Tags come from HEDGEDOC_TAGS (or --tags).

The note's permission has to be freely (Menu → Permission), because the run is anonymous. HedgeDoc 1.x has no REST API for editing a note, so the script talks the editor's own engine.io/socket.io + OT protocol over long-polling — it reads the current text, sends one "delete everything, insert this" operation, waits for the server's ack, and reads the note back to confirm. Anyone with the note open sees the change live. Plain requests, no websocket library.

--hedgedoc <instance> (POST a new note) is unrelated and only works where anonymous note creation is enabled — on hedgedoc.cit.tum.de it is not.

challs.txt for the deployment repo

--challs commits the clone URL of every challenge at Testing Ready or beyond that is not blocked (see Checking the repo) to CHALLS_PATH (default 2026/challs.txt) in the deployment repo CHALLS_REPO_URL, one per line, the same format as last year's:

git@gitlab.lrz.de:h4tum-ctf/h4tum-ctf-2026/challenges/baby_rsa.git
...

It only commits when the list actually changed, with a message naming what was added and removed (Update 2026/challs.txt from challenge status: +jwt -safe). A challenge that falls back below Testing Ready drops out again. Preview without committing:

./ctf_status.py -q --challs-out -

The token additionally needs Repository: Read and Repository: Write on the deployment project. If the branch is protected, the token's user must be allowed to push to it. Without CHALLS_BRANCH, the default branch is looked up, which also needs Project: Read there.

On a schedule, on a server

Two timers, independent of each other:

timer	when	runs
ctf-status.timer	every 30 minutes	--update (HedgeDoc note)
ctf-challs.timer	daily at 04:00 (server local time)	--challs (challs.txt commit)

Copy the repo to the server, create ctf_status.env or .env there (both are gitignored, so they do not travel with the code), then:

./install-timer.sh

It writes systemd user units into ~/.config/systemd/user/, substituting whatever directory the repo actually sits in, enables both timers, turns on lingering so they keep firing when you are not logged in, and does one run of each to prove they work. Re-run it any time; it just overwrites the units.

systemctl --user list-timers 'ctf-*'            # when they next fire
journalctl --user -u ctf-status.service -n 50   # what the HedgeDoc run did
journalctl --user -u ctf-challs.service -n 50   # what the challs.txt run did
systemctl --user start ctf-challs.service       # commit challs.txt now
systemctl --user disable --now ctf-challs.timer # stop the daily commit

The HedgeDoc timer fires at :00 and :30 with up to a minute of jitter; both timers have Persistent=true, so a run missed while the machine was down is caught up. Plain cron works too, if you would rather:

*/30 * * * * /path/to/planner/ctf_status.py --update --quiet
0 4 * * *    /path/to/planner/ctf_status.py --challs --quiet

--quiet keeps a successful run silent, so you only hear about it when something changed or broke. Overlapping runs of the same target are prevented by a lock file per target (the 04:00 challs run and the HedgeDoc run can overlap), and the HedgeDoc write is retried (--retries, default 3) before the run gives up with a one-line error and a non-zero exit.

What the note shows

1. ✅ Ready for infra testing — first thing in the note: every challenge at Testing Ready, Tested or Ready, linked to its repo, so infra knows what it can deploy and test against right now. Blocked ones are not in it.
2. ⛔ Claims Testing Ready+, but the repo disagrees — only shown when there are any: what the README claims, and why the repo says otherwise.
3. Status by category — how many challenges each category has per stage (⚪ Planning → 🟠 PoC Draft → 🟡 Testing Ready → 🔵 Tested → 🟢 Ready).
4. Category × difficulty — one dot per challenge, coloured by its status (⛔ when blocked), so gaps and stragglers show up at a glance.
5. Challenges — one table per category, linked to the repo, with event, author, tester and the repo's last activity.
6. Needs attention — see below.

Reading the README

Only the template's header block is parsed:

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

People fill it in loosely, so values are normalised:

• Status is matched against the five stages ("Tested with …" → Tested, "PoC" → PoC Draft). If it names several ("Planning to PoC Draft", a half-deleted option list) the least advanced one counts and it is flagged as unclear.
• Difficulty ranges written as medium-hard, medium/hard or easy to medium become their own column; otherwise the first level named wins.
• Category: the first one named counts ("rev, misc" → rev); the full value is shown next to the challenge. Categories outside the usual list (e.g. ai) get their own row.

Checking the repo

Anyone can write Status: Testing Ready, so for every challenge whose README claims Testing Ready, Tested or Ready the repo itself is looked at too. Each of these makes it blocked (⛔): it keeps its claimed status in the counts, but it is left out of Ready for infra testing and challs.txt, and the reason is shown in the note.

• no description.yml at the top level, or one that does not parse
• description.yml still has anything from the template it was copied from (netcat-check-multi-container): its id, name, author jh, its flag, or the cont1/cont2 / container-1/container-2 containers
• its category is not one of the README's categories
• the flag is not h4tum{...}
• dynamic: true, but no container has a flag: block to receive it
• a container's deploy_dir does not exist or has no Dockerfile
• no solve.py anywhere in the repo

These are cheap signs that a challenge was never finished, not proof that it works: a repo can pass every check and still not build or solve. That is what actually testing it is for.

What it flags

• challenge at Testing Ready or beyond with no tester ([Tester Name], ??, None, not found yet all count as none)
• status / difficulty / category missing or unclear
• no challenge name in the README
• repos whose README is missing or still the untouched template — these are left out of the counts

Repos GitLab has scheduled for deletion, and archived repos, are skipped.