Skip to content
Athena User Guide
Esc
↑↓navigate↵open⌘Jpreview
On this page

Import an existing checker

Run a checker written for ctf-gameserver, Hackerdom checksystem, ForcAD or enochecker3 behind an Athena base image.

If you already have a checker for another attack/defence platform, you can keep its source. Athena provides two base images that speak its checker contract and run your checker inside the same container:

Base image Imports
ghcr.io/astraqcd/ctf-platform/ad-checker-base-argv:1.0.0 ctf-gameserver, Hackerdom checksystem and ForcAD checkers
ghcr.io/astraqcd/ctf-platform/ad-checker-base-enochecker:1.0.0 enochecker3 checkers

Both are public, need no registry login, and are Python 3.13 images. Pin the version tag as shown: a new base image version gets a new tag and never replaces this one. Your checker image starts from one of them, installs whatever your checker needs at build time (for example RUN pip install --no-cache-dir requests, since a check has no internet access), and names your checker as its command. You then register the result as the service’s Checker image, as in Register services.

Each import is a compatibility profile with stated limits, listed below. A checker that relies on something outside its profile doesn’t run unchanged.

What every import shares

  • Verdicts keep their meaning. The table below maps each platform’s results to Athena’s. A checker crash, an unexpected exit code, a missing result or anything outside the profile is reported as Cancelled with a reason. That carries no penalty for the team, and it doesn’t earn the team SLA either.
  • Placement must be safe to repeat. Athena may retry a flag placement, and the retry is the same logical operation. A put that creates something new on every call must be made idempotent.
  • State stays within its tick. Whatever your checker stores between placing a flag and reading it back is kept per team, service, store and tick, never team-wide.
  • Output is partly scrubbed. Before you see a checker’s logs, Athena removes the flag the check handled, the values it keeps in its stored state, and the private flag ID a checksystem or ForcAD put prints. A value your checker makes up and never stores, such as a generated password, isn’t removed, nor is anything shorter than four characters, and the output of a checksystem or ForcAD check is passed through as written.
Legacy result Athena verdict
checksystem 101 OK, enochecker OK Up
checksystem 102 CORRUPT Flag missing
checksystem 103 MUMBLE, enochecker MUMBLE Faulty
checksystem 104 DOWN, enochecker OFFLINE Down
ctf-gameserver OK, DOWN, FAULTY, FLAG_NOT_FOUND the same
exit 110 or any other code, enochecker INTERNAL_ERROR, no result Cancelled, with the reason

ctf-gameserver

Build on ad-checker-base-argv and select the dialect:

FROM ghcr.io/astraqcd/ctf-platform/ad-checker-base-argv:1.0.0
ENV ATHENA_CHECKER_DIALECT=ctf-gameserver
WORKDIR /checker
COPY checker.py ./
CMD ["python3", "/checker/checker.py"]

The base image bundles a compatible checkerlib with the same public API, state encoding and file-descriptor protocol as upstream. Each call runs exactly one of your methods (place_flag, check_service or check_flag) for one tick.

Limits of this profile:

  • Python checkers on the bundled checkerlib only. A statically linked Go checker, a vendored copy of the library, or a script that depends on upstream’s combined multi-tick run is outside it.
  • One flag store, numbered 0. Register the service with Flag stores set to 1.
  • Noise and havoc aren’t supported and answer Cancelled.

Hackerdom checksystem and ForcAD

Build on ad-checker-base-argv, select the dialect and name your executable:

FROM ghcr.io/astraqcd/ctf-platform/ad-checker-base-argv:1.0.0
ENV ATHENA_CHECKER_DIALECT=checksystem
WORKDIR /checker
COPY checker.py ./
CMD ["python3", "/checker/checker.py"]

Use ATHENA_CHECKER_DIALECT=forcad for a ForcAD checker. ForcAD’s checker_type tags go in ATHENA_FORCAD_CHECKER_TYPE (for example pfr or nfr; the default is hackerdom). The dialect has no default: an image without one answers Cancelled to every check with the configuration error.

Each Athena operation is one call of your executable:

Operation Call
Place a flag put <host> <id> <flag> <vuln>
Read a flag back get <host> <private id> <flag> <vuln>
Check the service check <host>

vuln is the flag store number plus one, so store 0 is vuln 1. The private flag ID your put prints stays private. Only checksystem’s JSON public_flag_id, or ForcAD’s output under pfr, is published to teams as the flag ID. Noise and havoc aren’t supported and answer Cancelled.

enochecker3

Build on ad-checker-base-enochecker and name your checker as module:attribute, pointing at an Enochecker instance, its FastAPI app or a function that returns one:

FROM ghcr.io/astraqcd/ctf-platform/ad-checker-base-enochecker:1.0.0
WORKDIR /checker
COPY checker.py ./
CMD ["checker:app"]

The base image carries enochecker3 0.14.0. Each operation becomes the matching enochecker method. putflag and getflag, putnoise and getnoise use the flag store as the variant. havoc runs one variant per tick, cycling through the havoc variants your checker declares (the tick number modulo their count). Checking the service runs every havoc variant your checker declares, one after another within the checker timeout, and reports the worst result: an earlier Faulty never hides a later Down. If the timeout runs out before every variant has run, the check is Cancelled rather than Up, unless a variant that did run already failed.

Limits of this profile:

  • ChainDB is supported for the task chain being run. MongoDB clients, raw collections and team-wide state aren’t, and a checker that imports pymongo fails at startup.
  • enochecker’s MUMBLE covers a missing flag and a wrong answer alike, so an imported enochecker3 checker reports Faulty where a native checker would report Flag missing. Its own timeouts and dropped connections also arrive as MUMBLE, and so read Faulty, not Down.
  • Your app starts once per check, which takes a few seconds of the checker timeout. Leave room for it when you set the timeout.

Test before the network opens

After the host is ready, run a diagnostic from Checks against one team’s service; see Diagnose failing checks. A diagnostic runs your real checker image against a real box and changes no score.

Was this page helpful?