Attack & Defence

Attack & Defence worlds use distributed checkers. Biterra stores the round state, checker tokens, service configuration, SLA events, flag captures, and scores. It does not run a central ticker for every service.

Each challenge or service box should run its own checker process. The checker knows how to validate the local service, then checks in to the Biterra A/D API with the result for its team and service.

Operating model

1. Set the world type to Attack & Defence in the customer portal world settings.
2. Open the world admin portal and use the A/D workspaces to set the tick interval.
3. Create one A/D service per challenge service.
4. Open Checker API in the world admin and create a world-scoped checker token.
5. Deploy biterra CLI, or your own checker, beside each challenge service.
6. Run one checker process per service/team instance, or any equivalent distributed layout.

There is intentionally no central ticker requirement. If a single event operator wants to run one process that checks everything, they can, but the platform design assumes checkers live beside the services they understand.

For implementation details, see Writing and running A/D checkers.

Overview and game control

The Home workspace shows the current game state, active round, checker-health totals, and the latest result for every team/service pair. Use it to start, pause, or resume the game and to identify missing, stale, or faulty checkers.

Before starting scoring, confirm that every expected instance has a reachable URL and a recently reporting checker. Starting the game creates the first round; pausing stops new rounds while preserving the current configuration and history.

Services

A/D services represent the challenge services that can be attacked and checked. Each service has its own scoring values, flag rotation mode, colour, and icon.

Create and publish a service before expecting team instances to appear. Use the service placement mode to decide whether new instances share the service's base country or are distributed across available countries.

Bringing team instances online

The checker publishes its player-facing, routable instance URL when it starts and checks in. Biterra displays that reported value in Instances and uses it for the admin Open action, player target link, and checker assignment.target.

World managers can edit and save the URL as a manual override. A checker may probe a different Docker-local address internally, but it must advertise the address that players can reach.

Team instances are the concrete attack targets shown on the player map. A team can expose several services from one country, but a country cannot belong to two teams in the same world.

To bring an instance online:

1. Open Checker API → Checker access and create a short-lived enrollment token.
2. Deploy the biterra CLI or a custom checker beside the service, using the world URL and enrollment token.
3. Set BITERRA_INSTANCE_URL to the player-facing address and enroll the checker for the matching team and service.
4. Let checker startup publish the URL automatically, then use Instances to choose its country and save any manual URL correction.
5. Start or resume the game so the checker receives an assignment.
6. Confirm that Instances and Home show a current result instead of missing or stale.

The instance URL is the assignment target supplied to its checker. It must be reachable from wherever that checker runs; it does not have to be publicly accessible when the checker runs inside the same private network.

For CLI configuration, custom API examples, token handling, and retry guidance, see Writing and running A/D checkers.

Rounds

Rounds are the scoring intervals for an A/D game. Configure the round length while the game is stopped, then start or resume the game from Home. The Rounds workspace shows when each interval began and ended and identifies the active round.

Keep checker probe timeouts shorter than the round duration. A checker that cannot fetch and submit work within the interval can become stale or miss scoring opportunities.

Activity and troubleshooting

The Activity workspace records checker state changes and captured flags. Open a row to inspect its diagnostic message. Diagnostics should explain operational failures without containing flags, tokens, credentials, headers, or sensitive response bodies.

World managers can delete an activity entry from the table. Deleting an SLA or captured-flag entry also removes its associated score entry and deducts any points awarded by that entry. This cannot be undone, so the action requires confirmation.

Use activity together with the Home health table:

• Missing means no current checker report or no active round.
• Stale means the checker has not reported for the expected interval.
• Faulty means the checker itself or its functional validation failed.
• Flag missing means the checker could not retrieve or place the expected flag.

Map Builder

Use Map Builder to place team/service instances on countries in the player map. Select a country, find the instance, and move it there. Country placement controls where the target appears to players; it does not change the instance URL or checker enrollment.

Flag lifecycle

Services have a flag mode:

• Static flags: admins set flags on team service instances.
• Checker-managed flags: the checker can rotate the flag during its team-instance check-in by sending flag.

Checker reads never expose flags. Admin reads can show flags because admins own service configuration.

Player flag captures are idempotent per attacker team, victim team, service, round, and flag value.

Monitoring checkers

Use the world admin A/D workspaces to see:

• last check-in per service/team
• current up/down/stale/missing state
• current expected tick
• last flag rotation time
• recent SLA and flag capture events

If a row is missing or stale, the service checker is not checking in for the current round/tick.