The checker contract
What a checker image must do in an attack/defence event, the verdicts it returns, and the limits it runs under.
A checker is a program you write for one service. It speaks that service’s own protocol as an ordinary client: register an account, store a note, list notes, read one back. It never exploits anything. Nothing generic can infer what “working” means for your service, which is why every service needs its own.
Your checker is a container image. Athena starts it once per check, calls one operation on it, and removes it. It listens for Athena on port 50051 of its own container, over gRPC, and is the server: it dials nothing of the platform’s.
To reuse a checker you already have, see Import an existing checker.
Operations
| Operation | What it does | Runs |
|---|---|---|
| Put flag | Stores this tick’s flag in one flag store, and returns a flag ID and optional state. | Once per team, store and tick. |
| Get flag | Reads back a flag placed in this tick or an earlier one still valid. | For each flag in the validity window. |
| Check service | Exercises everything the flag path doesn’t touch: search, listing, pagination, error handling. | Once per team and tick. |
| Put noise / Get noise | Stores and reads back data shaped exactly like flag data, so a team watching its traffic can’t pick out the valuable request. | Once per team, store and tick. |
| Havoc | Sends plausible background traffic. | Once per team and tick. |
Check service is what keeps the game honest. Without it, a team could remove every feature except the one the flag lives in, keep a perfect SLA and leave nothing to attack.
Every call carries the target box’s address, the team number, the service, the flag store, the current tick and the tick the call is about, the deadline, and the state your checker returned earlier. Flag calls also carry the flag, its expected pattern and hash; Check service also carries the current attack info.
Verdicts
| Verdict | Return it when |
|---|---|
| OK | The operation succeeded. |
| Down | The service timed out, refused the connection or dropped it. |
| Faulty | The service is reachable but answered wrongly. |
| Flag not found | The service works, but the flag is gone. |
Two more outcomes come from the platform, not from your checker. Cancelled means the check was withdrawn or its checker image was missing on the host; it counts neither for nor against the team. Recovering is derived by the platform when current checks pass but a check for an earlier tick failed.
A check that runs past its deadline is stopped and recorded as Down. So is a check whose checker container fails to start, never answers on port 50051, or drops the call: the platform can’t tell a broken checker from a broken service, and scores it against the team. A result that arrives after its deadline changes nothing.
Flag IDs
The flag ID is the public handle a flag sits behind: a username, a record ID, a path. Athena publishes it to every team in the attack info, so it must not reveal the flag itself. At most 128 bytes once UTF-8 encoded, not 128 characters: a longer ID is refused and the check is recorded as Faulty, or as Cancelled for a checker built on an Athena base image. The same limit applies to noise IDs. A message longer than 4,096 bytes is cut.
State
A flag placed in one tick is read back in later ones, so your checker usually needs to remember something, such as the credentials of the account it created. Return that as state from Put flag, and Athena hands it back with every later call about that flag. Your checker keeps nothing between calls.
- State is kept per team, service, flag store and tick, and separately for flags and noise.
- At most 64 KiB. A larger state is refused and the check is recorded as Faulty, or as Cancelled for a checker built on an Athena base image.
- State is deleted when the event ends and isn’t part of the data export.
Retries
Athena may call Put flag again for the same flag, for example after a lost connection. A retry is the same logical operation: it must not create a second account or a second record, and it scores at most once. Derive anything you create from the call’s inputs so a retry lands on the same place.
Runtime limits
Each check runs in its own container:
- a read-only root filesystem, with a small writable
/tmp; - no added capabilities and no privilege escalation;
- bounded CPU, memory and processes, sized from the host’s checker capacity;
- network access to the target box’s declared service ports and nothing else, with no internet access;
- output bounded in size, with flags, tokens and credentials scrubbed before you read it.
Checks reach boxes from addresses that rotate from check to check, drawn from the same range players use, so a team can’t allowlist the checker.