Appearance
Components
A detailed map of the software components and what each module is responsible for.
Detailed component architecture
Backend modules (cyberrange/src/provisioning/)
| Module | Responsibility |
|---|---|
provision_api_fastapi.py | App entry point: mounts routers, startup checks (auth config, capacity config, migrations), starts the TTL reaper and score poller, serves /health and /capacity |
config.py, profiles.py, secrets_loader.py | Environment settings, deployment profiles (onprem, oci_12gib), secret resolution (environment, then SECRETS_FILE; Vault mode fails closed) |
auth.py, introspect_cache.py | Keycloak token introspection, 60-second claims cache, role extraction, guards (require_app_role, require_role, require_owner, require_owner_or_admin) |
pods_router.py | Lab endpoints, Manual Check, progress, flag submission, rubrics, instructor views, knowledge-gain export, reviews, evidence images, internal browser-score callback |
provision.py | Background lab build and teardown, failure rollback |
pod_net.py | Per-lab OVN networks, egress ACLs and peering; the Wazuh manager's return route to each lab; reconciler for orphans and for live labs' ACLs and routes |
lab_proxy.py | LXD proxy devices that expose each lab's DVWA on port 18300 + pod_id |
guest_nic.py, dvwa_compose.py, dvwa_ready.py | Wait for container networking; make DVWA and its database ready |
capacity.py, ttl.py | RAM and storage gates, capacity payload; lab expiry calculations |
reaper.py | TTL expiry, stuck-lab recovery, storage drift purge, network reconciliation |
score_poller.py, scoring.py, ssh_verifier.py, scoring_checks.sh | Automatic and manual milestone verification inside containers |
score_verifier.py, wazuh_rule_map.py | SIEM detection evidence (rule fired for an agent) |
scoring_diagnostics.py | Instructor-only, allow-listed failure reason codes per milestone, switched on per scenario, purged after a retention period |
hybrid_scoring.py, rubrics.py, flag_planting.py | Flag submission path, rubric catalog, per-student HMAC flags |
alerts_endpoint.py, alerts_reader.py, lab_history.py | Student and instructor SIEM views, archived alerts for ended labs, alert snapshots frozen with reports |
evidence_images.py | Validated, re-encoded evidence screenshots stored outside the release tree |
users_router.py, keycloak_admin.py | Admin-only account and role management through Keycloak's admin REST API; marking accounts as excluded from research data |
onboarding_router.py | Per-user first-login orientation state |
infra_health.py | Admin health view of API, LXD, Keycloak and Wazuh |
audit_router.py | Admin read-only audit log |
knowledge_gain.py, export_knowledge_gain.py, research_exclusions.py | Research metrics export (completion, time to milestone, detection, rubric scores), leaving out Admin-marked test accounts and staff |
wazuh_client.py | Wazuh API: tokens, agent lookup and status, agent cleanup, stale-name and connected-agent checks that can stop a lab from becoming ACTIVE |
models.py | Pydantic request and response models |
db.py, migrate.py, schema/v1.sql to v16.sql | SQLite connection settings and migrations (v11 orientation state, v12 Scenario 1 rubric text, v13 an unused booking table kept for history, v14 scoring diagnostics, v15 verification source, v16 research exclusions) |
logging_config.py | Text or JSON logs to stdout |
Portal modules (cyberrange/portal/src/)
| Path | Responsibility |
|---|---|
middleware.ts | Edge protection: redirect to /login, /no-role, or /dashboard |
lib/auth.ts | NextAuth options: Keycloak provider, session strategy, token refresh, role decoding |
lib/routeRoles.ts, lib/loginRouting.ts, components/auth/AuthGate.tsx | Role requirements per path, landing page per role, safe post-login redirects, client-side mirror of the edge checks |
lib/apiProxy.ts, app/api/**/route.ts | BFF: forward to FastAPI with the user's bearer token |
lib/api.ts | Typed client used by pages and hooks to call the BFF routes |
app/lab/dvwa/[[...path]]/route.ts, lib/dvwaProxy.ts, lib/dvwaScoreSignals.ts, lib/dvwaAutoLogin.ts | DVWA reverse proxy with HTML and cookie rewriting, path allow-list, CSP, Scenario 2 attack detection and near-miss reason codes, and automatic DVWA sign-in |
next.config.mjs | Response headers (framing, nosniff, referrer policy, no X-Powered-By), Image Optimization disabled, / redirect, dev rewrites |
hooks/* | Data hooks per feature (lab status polling, provisioning, progress, instructor and admin data) |
components/scenario/* | Scenario info, provisioning checklist, lab page (terminal, tasks, guide), Big Picture, SIEM viewer |
components/terminal/* | xterm.js integration and session manager |
components/instructor/*, components/admin/* | Instructor SIEM panels, lab history, review evidence; admin user modals |
hooks/useScenarios.ts | Static scenario catalog: names, descriptions, milestones, points |
public/scenarios/*.md | Student guides |
Supporting components
| Component | Responsibility | Source |
|---|---|---|
bridge-src/bridge.py | Terminal WebSocket server | cyberrange/bridge-src/ |
| Golden images | kali-base, meta-base, dvwa-base LXD images | cyberrange/deploy/oci_build_goldens_arm64.sh, deploy/golden/ |
| Host scripts | Keycloak realm and accounts, iptables fix for OCI, LXD peer wrapper, release pull and sync, Wazuh internal CA, API hardening and provisioner user, verification scripts | cyberrange/deploy/host/ |
| CI workflows | Release build and promotion; portal type check on every pull request | .github/workflows/ampere-release.yml, portal-typecheck.yml |
| Booking backend | Google Apps Script for test-session bookings and notices; creates no accounts | cyberrange/booking/Code.gs |
| systemd units | Service definitions and validators | cyberrange/deploy/systemd/ |
Sources
cyberrange/src/provisioning/*.py, schema/README.md, cyberrange/portal/src/**, cyberrange/portal/next.config.mjs, cyberrange/bridge-src/bridge.py, cyberrange/deploy/**, cyberrange/booking/Code.gs, .github/workflows/*.yml.