#challenge.yml Reference

Every challenge in this platform is described by a single challenge.yaml (or challenge.yml) file at the root of its package directory. The same file is read in three situations: an admin uploads a one-shot tarball/zip, a public GitHub repo is imported, and a repo binding re-syncs a checkout. All three paths share one parser, so the schema below is identical everywhere.

This page documents the exact fields the importer understands, where each value lands, and what is deliberately ignored. Everything here is derived from ChallengeYamlModel and ChallengeImportService in the server — not from the upstream gzcli docs, which differ in places.

#Key conventions

• Keys are camelCase. The deserializer is built with CamelCaseNamingConvention. A key like container_image (snake_case) is silently dropped — use containerImage. This applies to nested blocks too (memoryLimit, cpuCount, checkerImage, allowEgress, …).
• Unknown keys are ignored, not errors. The parser runs with IgnoreUnmatchedProperties(), so a typo or an upstream gzcli field we don't map simply has no effect. There is no validation warning for an unrecognized key — double-check spelling against the tables below.
• Some template keys have no effect. value: and visible: are not fields the importer maps — like any unrecognized key they are silently dropped by IgnoreUnmatchedProperties(). They exist in templates only so the file round-trips with gzcli; scoring and visibility stay admin-controlled.
• A missing containerImage triggers an auto-build. For any container-type challenge, if container.containerImage is omitted (or is a gzcli template placeholder like {{.slug}}:latest), the platform looks for ./src/Dockerfile, then ./Dockerfile, and builds it. See Auto-build behavior.

#Top-level keys

These keys sit at the root of challenge.yml.

#The type enum

type is parsed case-insensitively into the ChallengeType enum. Accepted values:

AttackDefense and KingOfTheHill both report IsContainer() == true and run on the shared A&D engine (UsesAdEngine() == true). That is why both reuse the container: block for their service image and honor the ad: block.

#The container: block

Used by all container types, including AttackDefense and KingOfTheHill. Every key is optional; an omitted key leaves the existing value untouched (so a sparse block only overrides what it names). Container fields are applied only when type is a container type.

container:
  exposePort: 80
  memoryLimit: 256
  cpuCount: 1
  storageLimit: 256
  # containerImage: ghcr.io/your-org/web-chal:latest   # or omit to auto-build ./src/Dockerfile
  # flagTemplate: "flag{[GUID]}"
  # networkMode: Isolated   # one of: Open | Isolated | Custom
  # enableTrafficCapture: false

#Auto-build behavior

When the challenge is a container type, the importer resolves a build intent from containerImage:

1. Local path (./src, ./Dockerfile, /…, anything ending in /Dockerfile) → resolve the build context and build. If the referenced Dockerfile doesn't exist, the challenge is flagged MissingDockerfile.
2. Template placeholder (containerImage contains {{, e.g. {{.slug}}:latest) or omitted → look for ./src/Dockerfile, then ./Dockerfile. If found, build it; the platform fills in the image tag. If a placeholder was given but no Dockerfile exists, it's a MissingDockerfile error.
3. Registry ref (nginx:alpine, ghcr.io/foo:tag) → pulled as-is, no build.

# Auto-build: no containerImage, Dockerfile lives at ./src/Dockerfile
container:
  exposePort: 8080
  memoryLimit: 512

#The ad: block

The ad: block carries the per-challenge Attack & Defense / King of the Hill knobs. It is consulted only when type is AttackDefense or KingOfTheHill (UsesAdEngine()), and it is sparse-friendly: an omitted key keeps the current value. The service image and ports come from the shared container: block — ad: only carries the engine-specific switches.

ad:
  checkerImage: "ghcr.io/your-org/attack-defense-checker:latest"
  allowEgress: true
  allowSelfReset: true

#Complete example: Attack & Defense

# yaml-language-server: $schema=https://raw.githubusercontent.com/dimasma0305/gzcli/refs/heads/main/internal/template/templates/others/ctf-template/.gzctf/challenge.schema.yaml

name: "attack-defense"
author: "your-name"

description: |
  Example Attack & Defense service. The platform plants a fresh flag into
  /flag every tick; your service must expose it only to whoever holds the
  intended capability, and defenders patch the bug without breaking the
  checker.

type: "AttackDefense"
value: 1000              # ignored on import — points are admin-controlled

# A&D reuses the container block for the per-team SERVICE image + port.
# containerImage omitted -> platform auto-builds ./src/Dockerfile.
container:
  exposePort: 80
  memoryLimit: 256
  cpuCount: 1
  storageLimit: 256

ad:
  # checkerImage: "ghcr.io/your-org/attack-defense-checker:latest"  # registry ref; omit -> TCP probe
  allowEgress: true       # can the service reach the internet?
  allowSelfReset: true    # may a team reset its own container?

#Complete example: King of the Hill

# yaml-language-server: $schema=https://raw.githubusercontent.com/dimasma0305/gzcli/refs/heads/main/internal/template/templates/others/ctf-template/.gzctf/challenge.schema.yaml

name: "king-of-the-hill"
author: "your-name"

description: |
  Example King of the Hill challenge. A single SHARED service — the "hill" —
  that every team races to control. Each round the platform issues a fresh
  control token; exploit the hill to write that token into /koth/king. The
  platform reads /koth/king every tick: while it holds your token AND the hill
  is still functional (checker Ok), you earn hold points.

type: "KingOfTheHill"
value: 1000              # ignored on import — KotH is hold-scored, not flag-scored

# ONE shared hill container for the whole game (not one per team).
# containerImage omitted -> platform auto-builds ./src/Dockerfile.
container:
  exposePort: 80
  memoryLimit: 256
  cpuCount: 1
  storageLimit: 256

ad:
  # checkerImage: "ghcr.io/your-org/king-of-the-hill-checker:latest"  # health-only probe
  allowEgress: false      # the hill is a target; it almost never calls out
  allowSelfReset: false   # MUST stay false — the hill is shared across all teams

#See also

• Templates — the package layout, ./src/Dockerfile, ./checker, and solver/ conventions.
• Repo bindings — keeping challenges in sync from a GitHub repo.
• Scoring — how points, decay (minScoreRate / difficulty), and blood bonuses actually work, given that value: is ignored.