BigRAE CTF¶
Capture-the-flag is a Django app (ctf) layered on the platform's range system. It
owns event/challenge/scoring data and orchestrates a dedicated range per participant
by calling the existing CMS range services; it does not introduce a second
provisioning path.
ADR-066 authorization¶
The source contract for CTF authorization lives in
ctf.api.operation_policy: it names the registered action and SQL-owned scope
locator for all 118 current /api/v1/ctf/ operations, and classifies the
named browser routes, Django admin models and inlines, CTF management
commands, scheduled task types, and external service effects. The issue's
baseline was 114
operations; the current published API contains four additional operations.
The browser routes serve an SPA shell; privileged data and effects belong to
the API and service boundaries. Public registration and scoreboard projection
retain their explicit publication checks. Scenario discovery retains the CMS
model-access boundary.
ctf.services.unified_authorization composes an active human or service
principal, the credential's exact action ceiling, CTF-owned event scope, and
the shared OpenFGA provider. Event creation checks the selected existing
account, organization, or workspace parent. Individual accounts have no
invented organization or workspace; team and enterprise accounts use an
organization or workspace parent. OpenFGA must show exactly one matching
event parent. The same exact-parent rule covers event-derived ranges. The
SQL authorization inventory includes account- and organization-placed events
in scoped delegation proofs and checks exact event ancestry on direct policy
mutations. Service participant admission and current-event reads already use the shared check;
the participant row and lifecycle predicates remain separate requirements.
Provider failures deny with a bounded unavailable response.
S8 binds those decisions to the production service and API paths. Legacy user flags, ownership and staff rows no longer substitute for policy decisions. The policy-aware Django admin disables direct domain writes. This describes source behavior, not a live deployment.
Staff assignment, removal and ownership transfer retain a versioned effect
plan in CTFEventAuthorityTransition. The plan fixes the event, subjects,
scope, provider binding and semantic effect keys before publication. Workspaces
owns the existing mutation journal and readback. An evaluator outage remains
retryable; an explicit denial remains denied. A current authorized administrator
can settle an exact retained plan after a recipient becomes inactive. New
inactive grants and inactive callers remain denied.
GET /api/v1/ctf/events/{event_id}/staff-members/ exposes an authorized nullable
pending_transition receipt with its UUID, kind, recipient, requested role,
creation time and completed/total effect counts. The browser resumes that
command through the existing staff endpoints. It does not expose raw policy
tuples or credentials. See identity and lifecycle contracts
for the DFDs, recovery state and lock order.
Responsibility¶
- Model CTF events, challenges, flags, teams, brackets, submissions, hints, and notifications.
- Validate flag submissions and compute scores and leaderboards.
- Provision and clean up one range per participant from the event's scenario.
- Serve participant, organizer/admin, and JSON API surfaces.
URL Surface¶
ctf.urls (app_name = "ctf") mounts three groups under /ctf/:
| Group | Prefix | Audience |
|---|---|---|
| Public registration | /ctf/public/events/<event-uuid>/ |
Unauthenticated, explicitly published event projection and CSRF-protected request intake |
| Participant | /ctf/ |
Competitors: dedicated login, password change, dashboard, challenges, range, scoreboard, team |
| Organizer/Admin | /ctf/admin/ |
Organizers: events, challenges, participants, teams, brackets, ranges, notifications, analytics |
| API | /ctf/api/ |
JSON endpoints for events, challenges, scenarios |
Participant access uses isolated temporary username/password accounts; organizer views are gated to CTF organizer roles. The portal sidebar distinguishes participant-only users so the two surfaces stay structurally separate (see ADR-013).
Models¶
Models live in the ctf.models package (split from a single module in PR #856);
__init__ re-exports every public symbol so from ctf.models import X is stable. All
inherit CTFBaseModel with a SoftDeleteManager (soft delete by default).
| Model | Purpose |
|---|---|
CTFEvent |
Competition: window, scenario, capacity, team mode, throttles, scoreboard policy, cleanup policy |
CTFPublicRegistrationRequest |
Minimal event-scoped name/email intake with pending, approved, or rejected disposition; never participant authority |
CTFChallenge |
Scored task: category, points, difficulty, release time, prerequisite, target instance/port, tags/topics |
CTFFlag |
The sole source of flag truth: one or more flags per challenge, each stored as a hash (static), pattern (regex), or sentinel (programmable/http) with type, case sensitivity, and validator config |
CTFTopic, CTFChallengeTag, CTFChallengeFile, CTFChallengePrerequisite |
Challenge taxonomy, attachments, and unlock graph |
CTFBracket, CTFTeam, CTFParticipant |
Cohorts, teams, and per-user participation |
CTFSubmission, CTFReceiptConsumption, CTFAward |
Flag attempts, durable issuer-scoped signed-receipt replay evidence, and manual point awards |
CTFChallengeRating |
Participant difficulty ratings |
CTFHint, CTFHintUsage |
Optional, point-reducing hints and usage tracking |
CTFNotification, CTFScheduledTask |
Announcements and scheduled work (legacy aggregate evidence; see Scoped communications) |
CTFContentHydrationReceipt |
Digest, object-identity fingerprints, bounded counts, and pristine/drifted state for scenario-managed event content |
CommunicationCampaign, CommunicationTargetEvent, MessageRevision, CommunicationIntent, RecipientSnapshot, DeliveryAttempt, RecipientReceipt |
Scoped communications domain (ADR-051): workspace-confined campaigns, immutable content, normalized release occurrences, server-resolved recipients, per-transport delivery commands, and read/acknowledgement state |
CTFEvent carries an immutable scalar workspace_id tenancy boundary (ADR-051):
it is resolved once at creation from an authorized workspace or the creator's
personal workspace, existing events are backfilled, and it is never a cross-layer
foreign key. This is the scope a communication campaign is confined to.
Flag material is persisted only as CTFFlag rows (static flags as hashes, regex as
patterns, programmable/HTTP as validator config), never on the challenge itself.
Plaintext is never stored after flag creation, and submission checking compares
against the CTFFlag records. A single plaintext flag on challenge create/update
is normalized into one static CTFFlag; a challenge with no flag rows is
unverifiable (every submission is rejected).
Receipt-capable validators use an immutable server-derived CTF → CMS → Engine binding and an installation-owned authenticated verifier profile. Verification runs outside locks; the exact registration and objective mapping are rechecked inside the scoring transaction, where a durable issuer-scoped consumption row enforces one-shot use. The generic platform never interprets scenario proof claims or receives symmetric signing bytes. Receipt attempts persist only a fixed redaction marker in submission history; legacy flag types preserve their existing history behavior. See the operator and extension contract.
Services¶
Flag submission requires a live team in the participant's event when team_mode is enabled.
The service checks membership before flag verification and again against the locked participant before recording the submission.
Rejection creates no submission or score change.
The optional require_team check preserves team creation, joining, and other actions.
Business logic lives under ctf.services (views stay thin):
event,challenge,flag,bracket,hint,award,attachment,notification: entity operations.participant/:lifecycle,bulk_import,queries.scoring/: materialized-leaderboard hot path with an authoritative recompute fallback (get_scoreboard,calculate_score, ranks, stats, timeline, and therecompute_*maintenance helpers).authorization,audit: access checks and audit trail.public_registration: closed public projection, event-locked pending intake, participant-capability review/disposition, and bounded PII retention.communication/: the scoped-communications domain (see below):audience,campaigns,release,lifecycle,retention.
Scenario content hydration¶
ctf.services.content_resolution resolves a deployment-owned scenario
reference through the provider-neutral shared.cloud.ObjectStorage protocol.
It performs a bounded head/download with an ETag, generation, or version
precondition, verifies the declared SHA-256 digest before parsing, and removes
temporary bytes in finally. Provider errors, object coordinates, validator
configuration, and bundle bodies do not cross the public error boundary.
ctf.content_bundle is a closed, data-only
shifter-ctf-content/v1 contract. It validates resource bounds, challenge
identities and orders, native flag policy, prerequisite references, and the
complete DAG before a database transaction begins. It supports native static,
regex, and HTTPS HTTP validators; it does not execute package code or enable
programmable validators.
Event creation composes the resolver with
ctf.services.hydrate_event_ctf_content. The service locks the event, checks
ownership and state, writes the graph through native challenge/hint/prerequisite
services, creates one receipt, and records a strict audit event in one atomic
transaction. An exact pristine replay is a no-op. Foreign rows, changed source
evidence, shape mismatch, or a drifted receipt fail closed.
All native organizer mutation paths mark an existing receipt drifted inside their transaction. Both manual and scheduled activation require a pristine receipt whose scenario and digest match current deployment configuration. Scenarios without a configured content reference retain existing behavior.
The deployment reference catalog is the separate closed contract
shifter-ctf-content-references/v1, parsed at startup from private deployment
configuration. This feature does not reuse the RAES package catalog or persist
bundle bodies in scenario/event JSON. See the
operator runbook for publication, provider
IAM, runtime settings, rotation, and failure recovery.
Range Provisioning¶
ctf.services.range provisions a range per participant from event.scenario_id via
CMS range services, the same path Mission Control uses to launch a range.
provision.py:provision_participant_range(participant_id, *, actor)checks the current credential, then locks the event and participant to reserve one immutable launch. Provider work follows that commit. Retry resumes the same request rather than creating another generation.batch.py: throttled event-wide provisioning, pacing participant spin-ups.lifecycle.py,status.py,tasks.py: teardown, status reads, and task wiring.vpn.py: resolves the current participant's generation-bound OpenVPN profile through the CTF → CMS → Engine service boundary. The participant API exposes it only throughPOST /api/v1/ctf/range/vpn-profile/with current event participation and the exact assigned range, CSRF enforcement for sessions, a credential delivery rate limit, no-store response headers, and a delivery audit event.recovery.py:recover_participant_range(participant_id, *, strategy, operator, spare_range_instance_id=None)recovers a destroyed participant range (organizer-only).rebuildprovisions a fresh range via the CMS bridge;reassign_spareconsumes an availableCTFSpareRangefrom the participant's own event pool and reassigns its ownership to the participant principal through the CMS and Engine service boundaries. The intent is persisted as aCTFRangeRecoveryrow keyed on participant + old range + strategy; resumption after a partial failure is data-driven (recorded replacement id and the live old-range status), so retries never duplicate the replacement or the audit row. The old range is always destroyed; there is no disposition/forensics-retention choice. Recovery writes one shared audit row.spares.py:provision_event_spares(event_id, target_count, *, operator=None)tops up an event's prewarmed spare-range pool (CTFEvent.spare_range_count), each spare owned by the event owner's principal in the event's account scope until consumed.get_event_spare_summary(event_id)reports pool counts for the admin surface;cleanup_event_spares(event_id)tears down unconsumed spares and their managed users at event teardown. A spare's status reachesready/failedvia the existingcms.services.range_status_changedprojection (ctf.signals.sync_ctf_spare_range_status).
Long waits are broken into heartbeat-touching chunks so the scheduler's liveness file does not go stale and provisioning stays responsive to shutdown.
Participant OpenVPN access¶
The CTF bridge mints a closed OpenVPN capability from the event cleanup deadline and the single participant-access Kali member, falling back to the unique hydrated Kali member for legacy templates without access declarations. Engine persists it beside the range; Mission Control ranges and topology without that capability do not create a VPN edge. Provisioning admits the deployment's shared OpenVPN pool (#2480) to that member only when the capability is present, and stores the participant profile in the provider secret store. The pool asks the portal before it admits a client and then allows only the member's address and declared ports. Django persists only a closed, non-secret binding containing the generation, owner, target, endpoint, profile version, and secret reference. Profile bytes are resolved and validated in memory only after CTF provenance, participant ownership, range status, request generation, and target membership checks pass.
The participant range-status projection exposes only
vpn_profile_available; it does not expose provider, endpoint, target, or secret
metadata. Paused and non-ready ranges cannot deliver a profile. Destroy removes the
provider material. Ownership transfer is rejected while a participant VPN binding
exists because clearing a database reference cannot revoke a downloaded credential;
recovery must destroy that generation and provision a new one for the replacement
owner before it becomes ready.
Certificates remain valid through the trusted teardown deadline, subject to a
397-day maximum capability window that fails before cloud mutation. Each
participant holds one live session per range; a newer connection replaces the
older one, and destroy, pause, or the deadline disconnects it within one pool
heartbeat. On GCE only the provisioner reads the CA, the pool identity reads only
its server identity, and the shared range-host identity cannot read VPN secrets.
See the provider-neutral range substrate
for the ADR-039 contract and the issue 1695 architecture preflight
for the threat model and containment decisions.
Scoped communications (ADR-051)¶
ctf.services.communication owns the durable domain for scoped communications,
detailed in the communications preflight.
This is the domain-model slice (issue #2048) of the umbrella capability; the
transport workers, HTTP endpoints, range-trigger ingress, and browser renderer
are later slices.
- A
CommunicationCampaignis bound to exactly one immutable workspace and may target one or more events, but only events that share that workspace and admit the author's notification capability.create_campaignis the confinement gate: it authorizes active workspace membership throughworkspaces.services(USE_CTF_COMMUNICATIONS, the one sanctioned CTF toworkspaces.servicesedge) and re-authorizes every target event. Workspace membership never grants event or recipient authority, and a missing or unauthorized target returns one opaque denial. - Message content is validated at authoring time against the versioned
ctf-communication-markdown/v1profile inctf.communication_contracts(bounded subject and body, no raw HTML, no executable URL schemes, and anhttpslink-host allowlist). Editing content creates a new immutableMessageRevision; a persisted revision is frozen. resolve_recipientsis the single closed audience resolver over theAudienceKindselector (one participant, a set, teams, one event, or an explicit multi-event union). It reaches event-scopedCTFParticipantrows through the sharedviewing_participant_qpredicate and stores public UUIDs only, never an email address or ORM predicate.release_campaignresolves the audience and, in one transaction, writes the immutableCommunicationIntent, deterministic per-recipientRecipientSnapshotrows andRecipientReceiptstate, the initial per-transportDeliveryAttemptcommands, and a strictshared.auditCOMMUNICATIONevent. Release is idempotent on the intent identity, and per-recipient uniqueness means a retry can never grow the audience. A recipient's delivery coordinate is stored withshared.field_encryption, never as authority.- Lifecycle transitions (
cancel_campaign,on_participant_removed,on_event_cancelled,on_range_replaced) stop only not-yet-claimed delivery commands and fence scheduled work; an accepted send is never recalled and the immutable snapshot identity survives as bounded evidence with its coordinate erased.purge_expired_communications(management commandprune_ctf_communications) physically deletes content and coordinates afterCTF_COMMUNICATION_RETENTION_DAYS, rather than leaving a restorable soft-deleted row.
ADR-065 retires legacy notification writes. Historical CTFNotification reads
remain available; retired write routes return bounded 410 responses. The scoped
communication ledger owns new participant notices. The shared
WebSocketNotification transport and topic projection are separate from the
retired email writer. Organizer-only legacy email remains unavailable until a
supported recipient and transport contract exists.
Notification and restricted scoreboard authority¶
Notification recipient lists contain candidate human users derived from current owner and staff principals. Membership and role facts do not authorize delivery. The notification socket binds the current credential and retains its ceiling through topic subscription, replay and each delivery. The owning CTF topic checks current event-read policy or eligible participation; temporary credentials remain confined to their exact event and lifecycle. Service principals do not map to a responsible user's browser notifications.
The participants-only scoreboard uses current native event-read authority or eligible participant read access. Registered viewing participants may retain read access after disqualification where the existing viewing rules permit it; banned, deleted and unregistered rows do not qualify. Ordinary participant credentials also require current participation policy. Public publication and hidden scoreboards keep their separate publication rules.
Scoreboard refresh¶
The SPA participant and organizer scoreboard hooks poll their API read every
15 seconds (SCOREBOARD_POLL_MS in frontend/src/api/ctf.ts). They also
refetch on window focus and on network reconnect. Thus a scoring event shows
within 30 seconds (CTF-401). A frozen participant board withholds later solves
by design. The ADR-072 position_changed hint is optional and only accelerates
the refresh. See the
design note.
Scheduled Work¶
Two management commands operate the event runtime:
run_ctf_scheduler: long-running scheduler that drives batch range provisioning, cleanup, reminders, scheduled tasks, participant-account anonymization, and bounded public-registration-request deletion, writing a liveness heartbeat.ctf_recompute_leaderboard: recomputes materialized leaderboard columns authoritatively when reconciliation is needed.
Boundaries¶
- Public registration is a server-rendered, exact route ahead of the authenticated
SPA catch-all. Visibility requires an explicit per-event flag, a live workspace
scope, and
registrationstatus. The service allowlists event metadata and useseffective_registration_deadline; the page does not project arbitrary event pages or organizer/participant state. - Anonymous POSTs use Django form validation and CSRF, body/field bounds, shared source/event/fleet rate budgets, generic duplicate success, fixed public errors, no-store/no-referrer/noindex response controls, and an event-row lock. Intake has no account, invitation, seat, range, webhook, or mail side effect.
- Organizer listing and disposition use the existing
participantsevent capability and exact event API scopes. Approval delegates toctf.services.participant.lifecycle.add_participant; it does not duplicate capacity, account, or provisioning policy. Publication and disposition audits contain identifiers and closed state only, never submitted PII. - CTF reaches the range system through CMS/engine service calls, consistent with
ADR-001 (cross-layer access goes through service boundaries).
ctfis one of the recognized layers in the import policy. - Per-function complexity stays under the Ruff C901 gate (ADR-012); existing high-complexity CTF functions carry tracked exemptions.
See Also¶
- CTF: participant guide.
- CTF Organizer Guide: running an event.
- Native CTF scenario content: private publication and deployment binding.