Skip to content

BigRAE CMS

Content and asset management.

Responsibility

  • Scenario catalog (declarative templates)
  • Asset management (agents, credentials)
  • Range content tracking (scenario associations)
  • Config hydration for Engine

CMS owns what gets deployed. Engine owns how it gets provisioned.

Architecture

graph LR
    MC[Mission Control] --> CMS
    CMS --> Engine

    subgraph CMS
        Templates[Scenario Templates]
        Loader[Template Loader]
        Hydrator[Config Hydrator]
    end

    Templates --> Loader
    Loader --> Hydrator
    Hydrator -->|range_config| Engine

Scenario Templates

Declarative YAML definitions in cms/scenarios/templates/.

Template Schema

id: string                    # Unique identifier
name: string                  # Display name
description: string           # User-facing description
enabled: boolean              # Available to users
ngfw: boolean                 # Requires NGFW

instances:
  - name: string              # Instance display name
    role: string              # attacker, victim, dc
    os_type: string           # kali, windows, ubuntu, from_agent
    xdr_agent: boolean        # Deploy XDR agent
    join_domain: boolean      # Join AD domain (optional)
    domain_controller: boolean # Is DC (optional)
    ai_agent: boolean         # AI-assisted (optional)
    dc_config:                # DC configuration (optional)
      domain_name: string
      netbios_name: string

subnets:
  - name: string              # Subnet name
    instances: [string]       # Instance names in subnet
    connected_to: [string]    # Subnets this subnet needs to reach (unidirectional)

Available Scenarios

ID Name Instances NGFW
basic Basic Range attacker, victim No
basic_ngfw Basic Range with NGFW attacker, victim Yes
ad_attack_lab AD Attack Lab attacker, dc, victim No
ad_attack_lab_ngfw AD Attack Lab with NGFW attacker, dc, victim Yes

Hydrated Range Config

CMS hydrates templates with user-specific data before calling Engine.

range_config = {
    "scenario_id": "basic",
    "subnet_index": 5,
    "instances": [
        {"role": "attacker", "os_type": "kali"},
        {
            "role": "victim",
            "os_type": "ubuntu",
            "agent": {
                "s3_key": "agents/123/abc.deb",
                "filename": "agent.deb",
            }
        }
    ],
}

Models

Catalog Models (System-Defined Types)

Model Purpose
OperatingSystem Available OS types (Windows, Ubuntu, Kali)
CredentialType Types of credentials (SCM, Deployment Profile)
InstanceType VM instance type definitions
AppType Application type definitions (NGFW)

Asset Models (User-Owned)

Model Purpose
AgentConfig XDR/XSIAM agent installer uploaded by user
Credential User credentials with type-specific data

Entity Models (Materialized in Ranges)

Model Purpose
Instance VM instance definition in a range
App Application (NGFW) definition in a range
Subnet Network subnet definition in a range

Request Tracking

Model Purpose
Request Provisioning request container (correlation UUID)
RangeInstance Tracks hydrated scenario config sent to Engine
MissionControlTenantLeasePolicy Optional complete runtime replacement for the deployment lease fallback
MissionControlGroupLeasePolicy One complete, revisioned lease policy for an eligible Django RBAC group
MissionControl*LeasePolicyRevision Durable tenant/group compare-and-set fences retained across policy reset

Mission Control lease-policy boundary

CMS owns runtime Mission Control lease-policy persistence and resolution. The canonical value type remains shared.mission_control_lease.MissionControlLeasePolicy; ORM columns and API serializers only adapt that contract at their boundaries.

cms.services.resolve_mission_control_lease_policy() reads the effective tenant policy and committed eligible-group memberships. Multiple configured groups are folded with minimum durations and logical-AND extension admission, then bounded by the tenant maximum. The resolver never reads provider claim copies, workspace/organization roles, CTF teams, or caller-supplied group selectors.

Cold creation and warm claim resolve and snapshot the initial, increment, maximum, source, tenant revision, and group revisions inside their existing assignment transaction. Engine and provider adapters receive only the persisted deadline effects and do not query policy. Extension admission re-resolves the live boolean switch, while the generation's duration fields remain immutable.

The /api/v1/administer/mission-control/lease-policy/ surface uses browser session authentication with CSRF, an active-superuser service recheck, complete replacement/reset commands, revision compare-and-set semantics, and strict audit in the same transaction as each mutation. API tokens and staff-only sessions are not sufficient. Reset advances a durable scope revision before removing the override, preventing a stale command from matching a later policy incarnation.

Internal Modules

Module Purpose
cms/scenarios/loader.py Template loading and validation
cms/scenarios/schema.py Pydantic models for templates
cms/scenarios/hydrator.py Config hydration logic
cms/assets/services.py Agent CRUD, storage quota

Service Interface

Agents

Function Purpose
create_agent(user, ...) Create agent record
delete_agent(user, agent_id) Soft delete agent
list_agents(user) Get user's agents
get_agent(user, agent_id) Get single agent

Credentials

Function Purpose
create_credential(user, type, ...) Create credential (scm, authcode)
delete_credential(user, credential_id) Delete credential
list_credentials(user) Get user's credentials (includes type)
get_credential(user, credential_id) Get single credential

Ranges

Function Purpose
create_range(user, scenario_id, agent_id, ...) Hydrate template, call Engine
destroy_range(user, range_id) Tear down range
list_ranges(user) Get user's ranges
get_range(user, range_id) Get single range
cancel_range(user, range_id) Cancel provisioning range
pause_range(user, range_id) Pause range
resume_range(user, range_id) Resume range

Uploads

Function Purpose
initiate_upload(user, name, filename, file_size) Validate, generate presigned URL
complete_upload(user, upload_token) Verify and finalize upload
cancel_upload(user, upload_token) Clean up failed upload

Agent upload cancel is a state-mutating authenticated POST. Browser-session callers must satisfy Django/DRF CSRF validation: explicit cancel uses JSON with X-CSRFToken, and page-unload cleanup uses a form-encoded sendBeacon() body containing upload_token and csrfmiddlewaretoken. The signed upload token is validated by cms.services.cancel_upload() and matched to the current session upload lock before the lock is cleared. Empty, malformed, missing-token, stale, wrong-user, or expired-token cancel requests leave the lock in place; stale locks recover through the upload lock timeout.

Per-file size limit. A single agent installer may be at most AGENT_MAX_FILE_SIZE_MB (default 2048, that is 2 GiB using binary MiB). This per-file ceiling is distinct from the per-user storage quota below. It is enforced at three trust boundaries against one policy helper (cms.assets.validation.agent_max_file_size_bytes), so the layers cannot drift: the SPA guards the picked file before initiation; initiate_upload rejects a declared file_size above the ceiling before any quota lookup or presigned URL is issued; and complete_upload re-checks the authoritative provider-reported object length against the current ceiling (independently of the token's declared size), deleting the object and rejecting even a stale or crafted token that was signed under a different cap. The presigned PUT also binds the declared length into the provider's signed request as defense in depth, but the finalization check is the authoritative boundary. The SPA reads the ceiling from the max_file_size_bytes field on the agent-list response so its client-side guard always matches the server value.

User Quota

Function Purpose
get_storage_used(user) Check storage quota

The per-user storage quota (AGENT_USER_STORAGE_QUOTA_MB, default 5120, that is 5 GiB) caps the total size of a user's active agents and is a separate policy from the per-file size limit above. A request may satisfy the per-file limit yet still be rejected because it would exceed the aggregate quota; a request over both receives the per-file decision first.

Scenarios

Function Purpose
list_scenarios(user) Get available scenarios with metadata
get_scenario(scenario_id) Get single scenario template
validate_scenario_requirements(scenario_id, agent) Check agent meets requirements