SOC-SIM

2022-01-25

SOC Simulator (soc-sim) -- Technical Documentation

1. Overview

The SOC Simulator is TryHackMe's interactive Security Operations Center training platform. It places users in realistic SOC analyst scenarios where they triage security alerts using industry-standard SIEM tools (Splunk, Elastic, or Azure Sentinel), investigate incidents on an analyst workstation VM, classify alerts, and write case reports -- all in a time-bound, scored environment.

The system orchestrates the full lifecycle: scenario selection, VM provisioning, log ingestion, timed alert release, real-time investigation, report submission, AI-powered evaluation, and scoring.

2. High-Level Architecture

3. Directory Structure

Backend (API)

apps/api/app/api/v2/src/
├── routes/companies/soc-sim.ts          # Company-scoped API routes
├── controllers/soc-sim/                 # Request handlers
├── services/soc-sim/
│   ├── manage-runs.ts                   # Run lifecycle (init, pause, resume, terminate)
│   ├── vms.ts                           # VM deployment & management
│   ├── runs.ts                          # Run CRUD operations
│   ├── alerts.ts                        # Alert import from Sanity CMS
│   ├── run-alerts.ts                    # Run alert lifecycle & scoring
│   ├── run-logs.ts                      # Log ingestion via EventBridge
│   ├── reports.ts                       # Case report management
│   ├── run-alert-assign.ts             # Alert assignment logic
│   ├── run-evaluate.ts                  # AI-powered evaluation
│   ├── multiplayer-runs.ts             # Multiplayer coordination
│   ├── sentinel.ts                      # Azure Sentinel integration
│   └── socket.ts                        # WebSocket event emitters
├── models/soc-sim/
│   ├── run.ts                           # SOCSimRun Mongoose model
│   └── run-alert.ts                     # SOCSimRunAlert Mongoose model
├── common/
│   ├── interfaces/soc-sim/              # TypeScript interfaces
│   ├── enums/soc-sim/                   # Enums (status, severity, types)
│   ├── constants/vms/index.ts           # VM IDs, health check config
│   └── constants/soc-sim/              # SOC Sim constants
└── infra/sockets/handlers/soc-sim.ts    # WebSocket event handlers

Frontend

apps/frontend/src/features/soc-sim/
├── soc-sim.tsx                          # Root component
├── soc-sim.slice.ts                     # Core RTK Query API slice
├── soc-sim.types.ts                     # TypeScript types
├── landing-sections/                    # Home, scenarios, stats, leaderboard
├── scenario-onboarding/                 # Onboarding flow
├── soc-sim-dashboard/                   # Active run dashboard
├── alert-queue/                         # Alert triage interface
├── case-reports/                        # Report listing
├── case-reports-details/                # Individual report editor
├── playbooks/                           # Playbook listing
├── summary/                             # Run summary page
├── public-summary/                      # Shareable summary
├── components/                          # Shared components (nav, VM frame)
├── contexts/                            # Polling, modal contexts
└── tour/                                # Coach-marking system

4. Data Models

SOCSimRun (soc_sim_runs)

SOCSimRunAlert (soc_sim_run_alerts)

5. Run Lifecycle

Lifecycle Steps

1. STARTING -- Run document created, VM deployment triggered asynchronously
2. READY -- VMs are healthy, logs scheduled, alerts inserted; user can begin investigation
3. PAUSED -- VMs terminated, alert shownAt timestamps frozen
4. COMPLETED -- All true-positive alerts resolved; scoring + AI evaluation triggered
5. TERMINATED -- User manually ended the run before completing
6. ABANDONED -- System auto-terminated (VM expiry, inactivity)

6. VM Creation & Deployment

VM Types & IDs

These defaults can be overridden per-scenario via Sanity CMS fields (analyst_vm_upload_id, siem_vm_upload_id, siem_elastic_vm_upload_id).

Deployment Details

• EC2 Deployment: Uses VMsService.deployVm() which creates an EC2 instance from a pre-configured AMI with the appropriate security groups and subnets
• Retry Logic: Up to 2 retries on failure; on each retry, previously deployed instances are terminated
• Guacamole Connection: Each VM gets a remote desktop connection via Apache Guacamole, providing browser-based access through an iframe
• Instance Tracking: Each deployed VM gets an Instance document in MongoDB with a 3-hour expiry time
• Cost Tagging: All VMs tagged with CostCenter.SOC_SIM

7. Alert Generation & Release

Alert Timing Formula

scenarioSpeed = 0  →  shownAt = run.startedAt + index (all at once)
scenarioSpeed = 1  →  shownAt = run.startedAt + releaseTime + 150s buffer
scenarioSpeed > 1  →  shownAt = run.startedAt + (releaseTime / scenarioSpeed)

The 150-second buffer at scenarioSpeed === 1 ensures alerts appear after the corresponding SIEM logs have been ingested, giving users evidence to investigate before the alert fires.

Alert Properties from CMS

Each scenario alert in Sanity contains:

• severity (critical/high/medium/low)
• type (phishing/process/execution/network/web attack/rce)
• incidentId, alertRule, description
• details (JSON-encoded alert payload)
• releaseTime (seconds offset from run start)
• meta.isTruePositive -- ground truth for scoring
• meta.isEscalationRequired -- ground truth for escalation scoring
• meta.classificationPoints, meta.escalationPoints, meta.evaluationPoints
• meta.evaluationCriteria -- criteria for AI evaluation
• meta.playbook -- linked playbook reference

8. Log Ingestion Pipeline

Log Scheduling Details

• Splunk/Elastic: Each log becomes an AWS EventBridge one-time schedule that triggers a Lambda function at the log's release_time. The Lambda sends the log via HTTP to the SIEM VM's collector API. Logs are processed in batches of 400.
• Sentinel: Logs are converted to CSV, uploaded to Azure Blob Storage in batches of 5,000, then a lab action triggers ingestion into the Sentinel workspace.
• Timestamp Alignment: Log timestamps are recalculated relative to run.startedAt so that log events and alert times are consistent.
• Scenario Speed: When scenarioSpeed > 1, the EventBridge schedule time is compressed (release_time / scenarioSpeed), but the embedded log timestamp remains at real-time offset to match alert details.

9. Scoring & Evaluation

Scoring Breakdown

Completion Trigger

A run completes automatically when all true-positive alerts have been resolved (areTruePositivesResolved()). False-positive alerts do not need to be resolved for completion. Upon completion:

1. VMs are terminated asynchronously
2. Classification & escalation points are calculated
3. AI evaluation runs on all report writeups
4. Run stats computed (MTTR, FP rate, mean dwell time)
5. Certification section updated (if applicable)
6. Segment analytics event fired
7. Mission progress tracked

10. Real-Time Communication

The WebSocket layer is primarily used for multiplayer runs where multiple analysts share the same alert queue. Events notify all participants of alert assignments and run status changes in real-time.

11. Feature Flags (GrowthBook)

12. Frontend User Flow

13. API Endpoints Summary

Public Routes (User-facing)

Company Routes (Management Dashboard)

14. Infrastructure Summary

Key infrastructure characteristics:

• No dedicated IaC -- SOC Sim reuses the platform's shared VM infrastructure
• VM Lifetime: 3 hours default, extendable by 1 hour (max once, must be within last hour, max 6 hours total)
• Health Check Polling: Every 3 seconds via Agenda.js until VMs respond or 30-minute timeout
• EventBridge Schedules: One-time schedules per log entry, cleaned up on run termination
• Cost Center Tagging: All resources tagged CostCenter.SOC_SIM for billing attribution