Native CTF scenario content¶
BigRAE can populate a native CTF event from a private, digest-pinned content bundle when the event's scenario is selected. The platform creates the challenges, flags, hints, and prerequisite graph in the same database transaction as the event. No content import or plugin is required.
This is an operator publication flow. BigRAE deliberately does not expose an upload API for challenge bodies or flag material.
Contracts¶
The deployment reference catalog uses
shifter-ctf-content-references/v1:
{
"contract": "shifter-ctf-content-references/v1",
"references": [
{
"scenario_id": "example-lab",
"object_key": "ctf/content-bundles/example-lab/sha256-digest.json",
"digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
}
]
}
The referenced object uses shifter-ctf-content/v1:
{
"contract": "shifter-ctf-content/v1",
"scenario_id": "example-lab",
"challenges": [
{
"id": "challenge-001",
"name": "Example challenge",
"description": "Participant-facing task.",
"category": "Discovery",
"points": 100,
"difficulty": "easy",
"order": 1,
"flags": [
{
"type": "http",
"url": "https://validator.internal.example/verify",
"method": "POST",
"timeout": 5,
"headers": {},
"case_sensitive": true,
"order": 0
}
],
"hints": [],
"prerequisites": []
}
]
}
The parser rejects unknown fields, duplicate JSON keys and identities, unsafe regular expressions or HTTP validators, malformed prerequisite graphs, and content over the configured bounds. Bundle challenge IDs are stable, bundle-local identifiers; prerequisite entries refer to those IDs.
Receipt-capable deployments may instead select an operator-registered verifier profile without placing its endpoint or credential in the bundle:
{
"type": "http",
"protocol": "receipt-v1",
"profile_id": "example-penr1",
"objective_id": "flag-agent-control",
"case_sensitive": true,
"order": 0
}
The profile and objective must already be installed and approved, and a profile/objective pair may belong to only one active challenge in the event. See Signed-receipt CTF validators for the deployment profile, callback, key lifecycle, replay, and failure contracts.
Publish an immutable object¶
- Produce UTF-8 JSON using the bundle contract. Keep the source and generated object outside the BigRAE repository when it contains private content.
- Compute the SHA-256 digest over the exact bytes that will be uploaded.
- Put the digest in the object name and in the deployment reference.
- Upload with the provider's create-only generation/version precondition. Never overwrite a referenced key.
- Retain the provider object identity and digest in the deployment change record.
The portal workload needs read access only:
- GCP: set
ctf_content_bucket_nameon thegcp-devTerraform root. The portal workload identity receivesroles/storage.objectVieweron that bucket. - AWS EC2: set
ctf_content_bucket_arn,ctf_content_prefix, and optionallyctf_content_max_bytesin the portal environment overlay. - AWS EKS: set
ctf_content_bucket_arnandctf_content_prefixin the EKS environment overlay and set the bucket, prefix, and maximum bytes in the portal workload'sruntime_env.
The IAM grant is provider identity based. Do not create static storage keys.
Bind a scenario¶
Store the complete reference catalog as the
ctf_content_references object in the existing application secret. The
entrypoint serializes that field into
SHIFTER_CTF_CONTENT_REFERENCES_JSON at process startup. A deployment may
instead inject that environment variable from a private secret, but it must
not put the catalog in a ConfigMap, Terraform output, command argument, or
checked-in file.
The non-secret runtime settings are:
| Setting | Purpose | Default |
|---|---|---|
SHIFTER_CTF_CONTENT_BUCKET |
Private object bucket | unset |
SHIFTER_CTF_CONTENT_PREFIX |
Contained object-key prefix | ctf/content-bundles |
SHIFTER_CTF_CONTENT_MAX_BYTES |
Maximum accepted object bytes | 8388608 |
Restart or redeploy the portal and its workers after changing runtime configuration or the application secret. Startup fails if a reference catalog is malformed or references are configured without a bucket.
Create and verify an event¶
Create an event normally and select the bound scenario. Before the database transaction starts, BigRAE reads the object with a provider identity precondition, checks its size and declared SHA-256 digest, and validates the complete bundle. The event, native challenge graph, and hydration receipt then commit atomically.
Verify:
- The organizer challenge list has the expected challenge and hint counts.
- Prerequisite-locked challenges have the expected graph.
- The audit stream contains a
ctf_content_hydrationcreate record with the digest and bounded counts. - Opening registration and activating the event succeeds.
Creating an event for a scenario with no reference is unchanged. A referenced scenario fails event creation rather than creating partial content when storage, integrity, validation, native writes, or strict audit recording fails.
Drift, retry, and rotation¶
An exact retry against a pristine receipt is a no-op. Any organizer mutation of managed challenges, flags, hints, or prerequisites marks the receipt drifted. Activation then fails closed. BigRAE never silently merges, overwrites, or restores drifted content.
To publish a revision:
- Publish a new immutable object under a new digest key.
- Update the deployment reference and restart the portal.
- Either create a new event, or refresh an existing managed event to the new revision (see below).
Refresh an event to the configured revision¶
An organizer may reconcile a managed event to the currently configured, digest-pinned revision of its own scenario in place, without tearing the event down. This corrects a stale challenge title or flag while preserving challenge identity and every historical scoring row (submissions, hint usage, ratings). It is an explicit, owner-only content operation, never an automatic sync.
- Endpoint:
POST /api/v1/ctf/events/<event_id>/content/refresh/with body{"expected_current_digest": "sha256:<64 hex>"}. The organizer supplies only the digest they currently see as an optimistic concurrency fence; the server-configured bundle is the target. No object key, URL, bundle body, flag, validator configuration, or target digest is caller-controlled. The event detail projection exposes the current digest and drift state undermanaged_contentfor the organizer UI. - Matching is by
(event_id, source_id). Matched challenges keep their UUID, so submissions, ratings, attachments, and score history stay attached. DRAFTandREGISTRATIONevents (no scoring ledger yet) may reconcile the complete managed graph, including challenge additions/removals and hint/prerequisite changes. A refresh is refused if participant history already exists.ACTIVEandPAUSEDevents may refresh only presentation and verification fields, including challenge title/content and the complete flag/validator set. A revision that adds/removes/renames asource_id, changes hints or prerequisites, or changespoints,minimum_points,decay_function,decay_solve_count, ormax_attemptsis rejected atomically. Pausing does not make those changes safe; create a new event instead.ENDED,CANCELLED, andARCHIVEDcontent is historical evidence and is not refreshable.- Existing submissions and hint usage are never revalidated, rewritten, or rescored. A refresh changes only which proof future attempts accept.
- On success the receipt is updated to the target evidence and returns to
PRISTINE; an explicit refresh can therefore also restore drifted managed content from its configured bundle. The audit stream records actf_content_refreshevent with the previous and target digests, bounded counts, and changed-field categories, never content values.
Every path back to ACTIVE, including resuming a paused event, re-enforces
managed-content hydration readiness under the event lock, so a paused event
whose configured content has been revised cannot silently resume against stale
flags: restore or refresh it first.
Failure codes¶
The organizer/API error remains intentionally generic. Server-side reason codes distinguish the main operator actions:
| Code | Operator action |
|---|---|
CTF_CONTENT_NOT_CONFIGURED |
Set the bucket/runtime configuration. |
CTF_CONTENT_RESOLUTION_FAILED |
Check object existence and portal read IAM. |
CTF_CONTENT_CHANGED |
Publish and reference one stable object generation. |
CTF_CONTENT_DIGEST_MISMATCH |
Recompute the digest over the uploaded bytes. |
CTF_CONTENT_INVALID |
Validate the bundle contract and native flag policy. |
CTF_CONTENT_SCENARIO_MISMATCH |
Align the reference, bundle, and scenario IDs. |
CTF_CONTENT_DRIFT |
Refresh or create a fresh event; do not overwrite managed state. |
CTF_CONTENT_NOT_READY |
Restore the configured reference, refresh, or create a fresh event. |
CTF_CONTENT_REFRESH_CONFLICT |
Reload the event; the revision changed under you. |
CTF_CONTENT_REFRESH_UNSAFE |
Live refresh cannot change scoring/structure; create a new event. |
CTF_CONTENT_REFRESH_STATE |
Event state or history does not permit a refresh. |
Object keys, validator configuration, flag material, and provider exception text are not included in public errors or audit records.