Initial commit of CyberSOC upgraded RLVR environment

Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.10-slim
+
+# Create user with home directory
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+# Copy requirements and install
+COPY --chown=user ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+# Copy all environment files
+COPY --chown=user . /app
+
+# The hackathon expects the OpenEnv Server to run on 7860 for Spaces Gradio endpoints
+# We will use uvicorn to host the app which complies with the spec
+CMD ["uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,531 @@
+# CyberSOC: Complete Project Review
+
+## 1. Project Overview — RLVR Positioning
+
+CyberSOC (CyberSOCEnv) is an **RLVR-stage reinforcement learning environment** that sits at the final rung of the model-maturation arc: **Random Init → Pretraining → SFT/IFT → Preference FT → RLVR**. It does not pretrain, supervise, or preference-align — it consumes a base model that has already been through those stages and turns its agentic actions into a dense, verifiable, 10-dimensional reward signal that GRPO can train on.
+
+It assumes a base model that has already been SFT-aligned. The environment itself does not perform SFT; it is an **RL-only artifact**. This satisfies **Daniel's "Law of RL"**: *The base model must get non-zero reward on Easy before it can meaningfully learn Hard.*
+
+**Built for**: The OpenEnv Hackathon (Meta Platforms)
+**Framework**: OpenEnv (Meta's RL environment framework)
+**License**: BSD-style (Meta Platforms, Inc.)
+
+### Guide Alignment Summary
+
+| Guide Section | Requirement | Our Implementation |
+|---|---|---|
+| §1 | Step-by-step, programmatic verification, hard-but-possible | 10 typed actions, 10-dim deterministic grader, Easy→Hard curriculum |
+| §4 | Design env before trainer | Env designed first; reset/step/state as first-class artifacts |
+| §6 | Keep task simple at first | 1000+ scenarios across 3 difficulty tiers enable curriculum learning |
+| §7 | Multiple independent reward functions | 10 dimensions consumed as `reward_funcs=[...]` by GRPOTrainer |
+| §8 | Protect against reward hacking | 8 distinct defenses mapped to guide's attack vectors |
+| §10 | Right training stack | Unsloth (QLoRA) + TRL (GRPO) + OpenEnv (transport) |
+| §11 | Prefer GRPO/RLVR | RLVR throughout; every reward is deterministic code (zero LLM-as-judge) |
+| §12 | Keep inference fast | Graph-delta injection + sparse nodes = rollout-latency optimizations |
+| §14 | Scale only after stable | All 9 components passed integration before any GRPO rollout |
+
+---
+
+## 2. Core Idea & Innovation
+
+### The Problem
+Traditional cybersecurity training environments use static puzzles with fixed answers. Real SOC work requires dynamic reasoning under time pressure with incomplete information.
+
+### The Solution
+CyberSOC creates a **fully dynamic, deterministic SOC simulation** with:
+
+1. **Procedural Scenario Generation** — 1,003 unique attack scenarios (3 curated + 1,000 generated) from seed-based deterministic generation. Same seed = same scenario, enabling reproducible RL training.
+2. **13 Threat Categories** — Ransomware, Phishing, Credential Theft, Lateral Movement, C2 Communication, Privilege Escalation, Data Exfiltration, Cryptomining, Supply Chain, Insider Threat, Webshell, Botnet, Malware.
+3. **Adaptive Red Team** — An adversary that reacts to agent actions: if you isolate a host, the attacker may pivot laterally. If you kill a process without blocking IOCs, it may reinfect with a `_v2` variant.
+4. **10-Dimensional Grading** — Not a binary pass/fail. Agents are scored across 10 weighted dimensions for nuanced RL credit assignment. **Zero LLM-as-a-judge.**
+5. **Business Continuity Constraints** — Rash actions (isolating clean subnets, killing legitimate processes) cause business downtime penalties.
+6. **TRL GRPO Integration** — 10 reward functions that plug directly into Hugging Face's TRL `GRPOTrainer` for RL fine-tuning.
+
+---
+
+## 3. Architecture
+
+```
+MetaRound2/
+├── models.py              # Pydantic data models (Observation, Action, State)
+├── client.py              # WebSocket client for agent interaction
+├── __init__.py            # Package exports
+├── inference.py           # LLM baseline inference script
+├── dashboard_server.py    # Dashboard + API server launcher
+├── pyproject.toml         # Python package config
+├── Dockerfile             # HuggingFace Spaces deployment
+├── openenv.yaml           # 1003 task manifest
+├── validate_submission.sh # Hackathon submission validator
+│
+├── server/                # Backend environment engine
+│   ├── app.py             # FastAPI application entry point
+│   ├── play_environment.py # Core environment (1284 lines)
+│   ├── tasks.py           # Hand-crafted task definitions (easy/medium/hard)
+│   ├── task_generator.py  # Procedural generation engine (1000+ tasks)
+│   ├── graders.py         # 10-dimensional grading system
+│   ├── threat_graph.py    # Typed knowledge graph
+│   ├── soar_playbooks.py  # 5 SOAR playbook definitions
+│   ├── action_validation.py # 3-gate action validation middleware
+│   ├── tool_router.py     # Phase state machine + triage solver
+│   ├── episode_sandbox.py # Wall-clock + step-limit guard
+│   ├── visualize_graph.py # PNG graph renderer (matplotlib/networkx)
+│   └── Dockerfile         # Multi-stage Docker build
+│
+├── training/              # RL training integration
+│   └── reward_funcs.py    # 10 TRL GRPO reward functions
+│
+├── dashboard/             # Real-time web dashboard
+│   ├── index.html         # Main HTML (6 panels)
+│   ├── css/styles.css     # Dark theme CSS (25KB)
+│   └── js/
+│       ├── app.js         # Main dashboard logic (45KB)
+│       ├── graphs.js      # D3.js threat graph + Chart.js (31KB)
+│       ├── api.js         # REST API client
+│       └── animations.js  # Micro-animations & effects
+│
+└── tests/                 # 10 test files + integration suite
+    ├── test_integration.py
+    └── test_task1.py ... test_task9.py
+```
+
+---
+
+## 4. Backend (Server)
+
+### 4.1 Core Environment — `play_environment.py`
+
+The heart of the project. `CyberSOCEnvironment` extends OpenEnv's `Environment` interface.
+
+**Key features:**
+- **`reset(task_id)`** — Builds the network, injects attack chains, initializes alert queue, seeds the ThreatGraph
+- **`step(action)`** — Processes one agent action, computes rewards, updates state, triggers adaptive adversary
+- **Concurrent sessions** — Each WebSocket connection gets its own environment instance
+- **ActionMiddleware** — Pre-flight validation (phase violations, graph-groundedness) before consuming a step
+
+**10 Agent Actions:**
+
+| # | Action | Purpose | Reward Range |
+|---|--------|---------|-------------|
+| 1 | `query_host` | Map architecture, get endpoint info | -0.05 to +0.05 |
+| 2 | `run_forensics` | Deep system artifact extraction | -0.02 to +0.10 |
+| 3 | `kill_process` | Terminate malicious execution | -0.08 to +0.25 |
+| 4 | `block_ioc` | Blacklist IOCs network-wide | -0.03 to +0.15 |
+| 5 | `isolate_segment` | Quarantine subnet or host | -0.10 to +0.15 |
+| 6 | `correlate_alerts` | Find shared entities across alerts | ±0.05 |
+| 7 | `enrich_ioc` | Threat-intel enrichment (actor, TTPs) | ±0.05 |
+| 8 | `scan_host_vulnerabilities` | Discover CVEs on a host | ±0.05 |
+| 9 | `trigger_playbook` | Execute SOAR automated response | ±0.10 |
+| 10 | `submit_containment_plan` | Final report — ends episode | 0.0 to 1.0 |
+
+### 4.2 Data Models — `models.py`
+
+All data flows through strict **Pydantic models** (429 lines):
+
+- **Enums**: `Severity`, `ThreatType` (13 types), `HostStatus`, `SubnetRole` (6 roles)
+- **Sub-models**: `Alert`, `HostInfo`, `NetworkTopology`, `ForensicsResult`, `TimelineEntry`
+- **`SOCObservation`** (extends OpenEnv `Observation`): 20+ fields including `alert_queue`, `network_topology`, `host_forensics`, `threat_graph_summary`, `reward_dimensions`, `available_playbooks`
+- **Actions**: Discriminated union of 10 action types via `SOCActionWrapper`
+- **`SOCState`** (internal): Tracks all episode state — killed processes, blocked IOCs, isolated subnets, etc.
+
+### 4.3 Task Definitions — `tasks.py`
+
+Three hand-crafted benchmark scenarios:
+
+| Task | Threats | Hosts | Max Steps | Description |
+|------|---------|-------|-----------|-------------|
+| **Easy** | 1 | 1 | 15 | Single ransomware on WS-042 |
+| **Medium** | 3 | 4 | 25 | Phishing → credential theft → lateral movement across 3 subnets |
+| **Hard** | 5 | 7 | 30 | Full APT: phishing → C2 → privesc → exfil → ransomware |
+
+**Network**: ~75 active hosts across 6 subnets (corporate, engineering, finance, DMZ, datacenter, executive) with realistic processes, ports, and criticality scores.
+
+### 4.4 Procedural Task Generator — `task_generator.py`
+
+Generates **1,000+ unique deterministic scenarios** from a seed:
+
+- `hash(task_id)` → deterministic `random.Random` seed → drives ALL choices
+- **Template pools**: 90+ malware process names, 40 C2 domains, 36 C2 IPs, 12 ransomware extensions, 12 data types
+- **3 difficulty tiers**: Easy (1 threat), Medium (2-3 threats, multi-stage chains), Hard (3-6 threats, APT campaigns)
+- **Alert generation**: Templated descriptions with randomized details (timestamps, file counts, data sizes)
+
+### 4.5 Grading System — `graders.py`
+
+**10-dimensional weighted grading:**
+
+| Dimension | Weight | What It Measures |
+|-----------|--------|-----------------|
+| `threat_containment` | 0.20 | Fraction of required process kills completed |
+| `ioc_blocking` | 0.12 | Fraction of known IOCs blocked (penalizes blind blocking) |
+| `forensic_investigation` | 0.10 | Compromised hosts examined |
+| `siem_correlation` | 0.08 | Whether alerts were correlated (bonus for early correlation) |
+| `threat_intel_usage` | 0.08 | IOCs enriched with threat intel |
+| `vuln_root_cause` | 0.08 | CVE root causes discovered (bonus if cited in plan) |
+| `business_impact` | 0.10 | Penalizes unnecessary isolation and over-isolation (>20% = -0.30) |
+| `step_efficiency` | 0.07 | Rewards SOAR playbook usage, penalizes step overrun |
+| `plan_coverage` | 0.10 | Threats addressed in final plan |
+| `plan_evidence_quality` | 0.07 | Evidence confidence from ThreatGraph |
+
+**Anti-gaming**: Per-occurrence penalty cap (±0.15), blind-blocking penalties, normalized evidence confidence.
+
+### 4.6 Threat Graph — `threat_graph.py`
+
+A **typed knowledge graph** tracking all SOC entities:
+
+- **5 Node Types**: `HostNode`, `ProcessNode`, `IOCNode`, `VulnerabilityNode`, `AlertNode`
+- **6 Edge Types**: `runs_on`, `involves`, `communicates_with`, `pivoted_from`, `part_of_chain`, `exploits`
+- **200-node cap** with LRU IOC pruning
+- **Version tracking** with changelog for delta queries
+- **Evidence confidence** computation for plan quality scoring
+- **Context summary** generation for LLM injection
+
+### 4.7 SOAR Playbooks — `soar_playbooks.py`
+
+5 automated response playbooks with prerequisite validation:
+
+| Playbook | Prerequisites | Sub-Actions |
+|----------|--------------|-------------|
+| `ransomware_containment` | Forensics run, process identified | kill_process, block_ioc |
+| `c2_disruption` | IOC enriched, C2 IP identified | block_ioc, isolate_segment |
+| `lateral_movement_lockdown` | Forensics run, lateral movement detected | kill_process, isolate_segment |
+| `phishing_response` | Phishing vector confirmed | enrich_ioc, block_ioc |
+| `data_exfil_stop` | Forensics run, exfil destination identified | block_ioc, kill_process |
+
+### 4.8 Action Validation — `action_validation.py`
+
+**3-gate middleware:**
+1. **Phase whitelist** — Actions restricted by phase (triage/investigation/remediation/report)
+2. **Schema validation** — Required arguments checked
+3. **Graph groundedness** — Actions must reference discovered entities (can't block an IOC you haven't seen)
+
+### 4.9 Tool Router — `tool_router.py`
+
+**Deterministic phase state machine:**
+- Phases: `triage` → `investigation` → `remediation` → `report` → `done`
+- Loop limits: max 4 investigation loops, 3 remediation loops
+- Supports **pushback** — agent can justify staying in a phase with graph references
+
+**Triage Solver**: Priority = `severity_weight × criticality_weight × (1 + blast_radius/10)`
+
+### 4.10 Episode Sandbox — `episode_sandbox.py`
+
+**Safety guardrails:**
+- **120-second wall-clock timeout** per episode
+- **20-step hard limit** per episode
+- **State integrity protection** — Protected fields (`_task_def`, `_live_requirements`, `_threat_graph`) are snapshot-hashed; mutations are detected and rolled back
+- **Hacking detection** — Reports any external state tampering
+
+### 4.11 Adaptive Red Team
+
+Two mechanisms in `play_environment.py`:
+
+1. **Reinfection** (`_maybe_reinfect`): 30% chance when killing a process if IOCs in the chain are unblocked → spawns `process_v2` variant + CRITICAL alert
+2. **Lateral Pivot** (`_execute_lateral_pivot`): Triggered by isolate/kill actions on hard tasks → copies malware to adjacent healthy host, adds `pivoted_from` edge, emits PIVOT alert, updates live requirements
+
+**Escalation**: Probability increases when agent is slow (step > 10 with 0 containments).
+
+### 4.12 Server Application — `app.py`
+
+FastAPI app created via OpenEnv's `create_app()`:
+- **POST /reset** — Reset environment with task_id
+- **POST /step** — Execute an action
+- **GET /state** — Get current state
+- **WS /ws** — WebSocket for persistent sessions
+- CORS enabled for dashboard communication
+- Supports 4 concurrent environment instances
+
+---
+
+## 5. Frontend (Dashboard)
+
+### 5.1 Overview
+
+A real-time **"CyberSOC Command Center"** web dashboard with 6 panels, built with vanilla HTML/CSS/JS + D3.js + Chart.js.
+
+### 5.2 Six Dashboard Panels
+
+1. **Alert Queue** — Live SIEM/EDR alerts with severity badges and IOC indicators
+2. **Live Threat Graph** — D3.js force-directed graph with 5 node types, drag/zoom, glow effects, pivot animation
+3. **Agent Actions** — Chronological action log with reward tracking
+4. **Network Topology** — Visual subnet map with compromised/isolated counts
+5. **Performance Metrics** — Chart.js radar chart (10 dimensions) + cumulative reward timeline
+6. **Mission Status** — Containment progress bars, business impact gauge, active threat list, episode controls
+
+### 5.3 Visual Design
+
+- **Dark theme** with glassmorphism panels
+- **Typography**: Inter (UI) + JetBrains Mono (data)
+- **Color system**: Accent colors for cyan, green, amber, red, purple
+- **Animations**: Count-up numbers, scale bounces, pulse glows, screen flashes
+- **Red Team pivot**: Screen border flash, toast notification, traveling dot animation on pivot edges
+
+### 5.4 Key Frontend Components
+
+**`graphs.js` (881 lines)**:
+- `ClientThreatGraph` — Client-side graph state manager synced from observations
+- `ThreatGraphViz` — D3.js v7 force simulation with SVG glow filters, curved edges, node symbols (circle/diamond/triangle/square/wye), click-to-highlight, drag behavior
+- `RadarChart` — Chart.js 10-axis radar for live grading dimensions
+- `RewardTimeline` — Gradient-filled cumulative reward line chart
+
+**`app.js` (45KB)** — Main orchestrator handling episode lifecycle, API calls, UI updates, phase indicator tracking
+
+**`api.js`** — REST client with auto-detection of server origin, session management, response parsing
+
+**`animations.js`** — Utility library for count-up, screen flash, toast notifications, scale bounce, pulse glow, dramatic final score reveal
+
+### 5.5 Dashboard Server — `dashboard_server.py`
+
+Wraps the FastAPI app to also serve the dashboard as static files at `/dashboard/`. Prints a styled ASCII banner on startup.
+
+---
+
+## 6. Inference & Training
+
+### 6.1 Inference Script — `inference.py`
+
+LLM baseline agent using **OpenAI-compatible API**:
+- System prompt defines SOC analyst role with all 6 core actions
+- Formats observations into structured text for the LLM
+- Parses JSON actions from LLM responses (with fallback extraction)
+- Runs episodes across easy/medium/hard tasks
+- Emits structured stdout logs: `[START]`, `[STEP]`, `[END]` (hackathon requirement)
+- Default model: `Qwen/Qwen2.5-72B-Instruct` via HuggingFace Router
+
+### 6.2 GRPO Reward Functions — `training/reward_funcs.py`
+
+10 TRL-compatible reward functions for **Group Relative Policy Optimization**:
+
+```python
+from training.reward_funcs import make_soc_reward_funcs
+reward_fns = make_soc_reward_funcs("http://localhost:8000")
+trainer = GRPOTrainer(model=model, reward_funcs=reward_fns, args=GRPOConfig(...))
+```
+
+Each function:
+1. Parses completion as JSON action list
+2. Replays actions against live environment server
+3. Returns the specific dimension's score from `grade_breakdown`
+4. Non-parseable completions return 0.0
+
+### 6.3 Per-Step Reward Dimensions
+
+The environment computes **live partial scores** every step (`_compute_reward_dimensions`) for GRPO credit assignment without waiting for the terminal grade. These are exposed in `SOCObservation.reward_dimensions`.
+
+---
+
+## 7. Testing
+
+**11 test files** covering all major components:
+
+| File | Focus |
+|------|-------|
+| `test_integration.py` | Full episode flows, phase violations, adaptive pivots, 10-dim grading, sandbox limits |
+| `test_task1.py` - `test_task9.py` | Individual task-specific validations |
+
+Key integration tests:
+- Easy/medium episodes complete without crashes
+- All 10 action types can be exercised in a single episode
+- Phase violations return negative reward (not crash)
+- Adaptive pivot fires on hard tasks
+- Step rewards accumulate correctly and are idempotent
+- Grader returns exactly 10 dimensions
+- Sandbox step limit raises `EpisodeTimeout`
+
+---
+
+## 8. Deployment & DevOps
+
+### Docker
+- **Root Dockerfile** — Slim Python 3.10, serves on port 7860 (HuggingFace Spaces)
+- **Server Dockerfile** — Multi-stage build from `ghcr.io/meta-pytorch/openenv-base`, uses `uv` for dependency management, health check on `/health`
+
+### Validation
+`validate_submission.sh` — 3-step validator:
+1. Ping HF Space `/reset` endpoint
+2. Docker build succeeds
+3. `openenv validate` passes
+
+### OpenEnv Manifest
+`openenv.yaml` — 1,003 task definitions with descriptions, max steps, and difficulty tags. Used by the OpenEnv framework for task discovery and benchmarking.
+
+---
+
+## 9. Environment Variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `API_BASE_URL` | LLM API endpoint | `https://router.huggingface.co/v1` |
+| `MODEL_NAME` | Model identifier | `Qwen/Qwen2.5-72B-Instruct` |
+| `HF_TOKEN` | HuggingFace API key | — |
+
+---
+
+## 10. Data Flow
+
+```mermaid
+sequenceDiagram
+    participant Agent as LLM Agent
+    participant Inf as inference.py
+    participant Env as CyberSOCEnvironment
+    participant TG as ThreatGraph
+    participant Gr as Grader
+
+    Inf->>Env: reset(task_id="hard")
+    Env->>TG: populate from task_def
+    Env-->>Inf: SOCObservation (alerts, topology)
+    
+    loop Each Step
+        Inf->>Agent: format_observation → LLM prompt
+        Agent-->>Inf: JSON action
+        Inf->>Env: step(SOCActionWrapper)
+        Env->>Env: ActionMiddleware.validate()
+        Env->>Env: Handle action (query/forensics/kill/etc)
+        Env->>TG: Update graph nodes/edges
+        Env->>Env: _adversary_react() (adaptive pivot)
+        Env->>Env: _compute_reward_dimensions()
+        Env-->>Inf: SOCObservation (updated state)
+    end
+    
+    Inf->>Env: step(submit_containment_plan)
+    Env->>Gr: grade_episode(actions, plan, graph, task_def, state)
+    Gr-->>Env: {final_score, breakdown[10], penalties, bonuses}
+    Env-->>Inf: SOCObservation (done=true, final_score)
+```
+
+---
+
+## 11. Red Team Design Philosophy
+
+The Red Team is NOT a separate LLM agent. It is a **deterministic adversarial dynamics engine** that defines the environment's state transition function.
+
+### 6 Behavioral Mechanisms
+1. **Reactive Pivoting**: Triggers on `isolate_segment` and `kill_process` (copy-not-move spread)
+2. **Persistence**: Reinfection triggers when a process is killed but its root IOC remains unblocked (teaches causal reasoning)
+3. **Time Pressure**: Pivot probability escalates +0.2 after step 10 if zero containments are achieved
+4. **Controlled Randomness**: Uses an episode-scoped `self._rng` (seeded by `task_id`) to ensure deterministic rollouts
+5. **Noisy Observations**: Benign processes mixed in host data
+6. **Escalation**: Pivot probabilities scale with difficulty (`Easy: 0.0`, `Medium: 0.3`, `Hard: 0.8`)
+
+### Attack Lifecycle Model (MITRE-aligned)
+`Phase 1: Compromise` → `Phase 2: Lateral Movement` → `Phase 3: Persistence` → `Phase 4: Escalation` → `Phase 5: Impact`
+
+---
+
+## 12. Reward-Hacking Defense Map
+
+Per guide §8, we implemented specific defenses against the known RL exploit vectors:
+
+| Guide Attack Vector | Our Defense |
+|---|---|
+| Editing timers | `EpisodeSandbox` wall-clock enforcement |
+| Caching results | Idempotent step rewards via `_fired_step_rewards` |
+| Abusing globals | Instance-scoped RNG + episode-scoped `self._rng` |
+| Mutating protected state | Sandbox hash-snapshot + rollback |
+| Exploiting env bugs | 3-gate validation middleware |
+| Reward-function gaming | Evidence confidence normalization |
+| Cheating via blind remediation | Graph-groundedness gate |
+| Blind IOC blocking | Enrichment-before-block penalty |
+
+---
+
+## 13. Curriculum Learning Strategy
+
+The 1000+ deterministic scenarios generated by `task_generator.py` are explicitly divided into three difficulty tiers to support Curriculum Learning (Guide §6).
+
+This exists precisely to satisfy **Daniel's Law of RL**: *The base model must get non-zero reward on Easy before it can meaningfully learn Hard.*
+
+- **Phase 1 (Warm-Start)**: `gen_0001`–`gen_0333` (Easy). Single threat, 15 max steps, 0.0 pivot probability.
+- **Phase 2 (Scaling)**: `gen_0334`–`gen_0666` (Medium). Multi-stage, 25 max steps, 0.3 pivot probability.
+- **Phase 3 (Stress-Test)**: `gen_0667`–`gen_1000` (Hard). APT, 30 max steps, 0.8 pivot probability.
+
+The adaptive pivot probability is itself a curriculum signal; the environment gets harder as the agent gets better.
+
+---
+
+## 14. Intended Training Stack
+
+CyberSOCEnv is designed for the canonical stack specified in Guide §10:
+
+1. **Unsloth**: 4-bit QLoRA loading and efficient inference
+2. **TRL**: `GRPOTrainer` consuming our 10 independent callable functions via `reward_funcs=[...]`
+3. **OpenEnv**: WebSocket transport and session isolation
+4. **vLLM**: Serving the rollout workers for maximum throughput
+
+A reference adapter module exists at `training/reward_funcs.py` that mirrors the Unsloth 2048 notebook structure 1:1, allowing plug-and-play GRPO training.
+
+---
+
+## 15. Anti-Patterns Avoided
+
+How we avoided the 7 common mistakes listed in Guide §21:
+
+1. **Building before designing env**: Env, types, and sandbox were built and tested completely offline before any trainer was attached.
+2. **LLM-as-a-judge**: CyberSOCEnv uses zero LLM-as-judge signals. Everything is deterministic code against the ThreatGraph.
+3. **Single monolithic reward**: We use a 10-dimensional verifiable rubric, fed independently into TRL.
+4. **Ignoring inference latency**: We implemented Graph Delta Injection (~10x fewer tokens) and a sparse-node generation strategy (~75 active nodes) specifically to optimize GRPO rollout latency.
+5. **No abuse prevention**: 3-gate middleware + EpisodeSandbox explicitly prevent out-of-band cheating.
+6. **Delayed deployment**: Environment was packaged with Docker and deployed to HF Spaces early.
+7. **Scaling prematurely**: All 9 components passed integration testing (`test_integration.py` through `test_task9.py`) before scaling to 1000 tasks.
+
+---
+
+## 16. Known Deviations & Alignment Items
+
+While we strive to match the OpenEnv canonical scaffolding (Guide §5), there are a few intentional architectural differences:
+
+1. **Action Dispatch**: We use a discriminated union wrapper (`SOCActionWrapper` with a `type` field) rather than a single flat action class. This matches the MCP ToolCall pattern and real SOC work better than a flat action space.
+2. **Decoupled Engine**: The core logic lives in `server/play_environment.py`, completely separate from the FastAPI transport layer in `server/app.py`. This ensures we can run headless parallel environments during GRPO without HTTP overhead if needed.
+
+---
+
+## 17. Team Structure & Role Split
+
+Per guide §17, responsibilities are split across three functional roles to execute the RL pipeline effectively.
+
+### Role 1: Environment Engineer
+**Mission**: Build a deterministic, unhackable, fast environment.
+**Owns**: `play_environment.py`, `tasks.py`, `threat_graph.py`, `episode_sandbox.py`, `action_validation.py`, `tests/`
+- **Scope**: Implements the state machine, Red Team behavior, and validates actions. Owns the core `step()` and `reset()` loops. Ensures the environment parses valid inputs and securely handles invalid ones.
+- **Hackathon Focus**: Bug fixes, latency optimization (graph deltas), sandbox integrity, and procedural scenario generation.
+
+### Role 2: Reward Engineer
+**Mission**: Design the mathematical signals that shape model behavior.
+**Owns**: `graders.py`, `training/reward_funcs.py`, `models.py`
+- **Scope**: Creates the 10-dimensional verifiable grading logic. Plumbs the environment outputs into TRL-compatible `reward_funcs`. Tunes the penalties to prevent reward hacking (e.g., punishing blind IOC blocking).
+- **Hackathon Focus**: Ensuring the model gets positive step-rewards early on to prevent it from collapsing, while preventing it from finding "lazy" exploits.
+
+### Role 3: Training Engineer
+**Mission**: Execute the GRPO curriculum and produce the final model.
+**Owns**: `training/` directory, Colab notebooks, `inference.py`
+- **Scope**: Sets up the actual training loops using Unsloth and TRL. Manages the hyperparameter tuning, LoRA checkpointing, and vLLM inference configuration. Runs the curriculum from Easy to Hard.
+- **Hackathon Focus**: Capturing the before/after learning curves on held-out tasks to prove to the judges that the environment actually works to train a model.
+
+---
+
+## 18. Key Innovations Summary
+
+| Innovation | Description |
+|-----------|-------------|
+| **Procedural Generation** | SHA-256 seeded RNG generates 1000+ unique deterministic scenarios |
+| **ThreatGraph** | Typed knowledge graph with version tracking, evidence confidence, and LRU pruning |
+| **10-Dim Grading** | Weighted multi-dimensional scoring replacing binary pass/fail |
+| **Adaptive Red Team** | Attacker reacts to defender actions — lateral pivots and reinfection |
+| **SOAR Playbooks** | Prerequisite-gated automated response workflows |
+| **3-Gate Validation** | Phase whitelist + schema + graph-groundedness prevents invalid actions |
+| **Episode Sandbox** | State integrity protection with hash-based tampering detection |
+| **Live GRPO Signals** | Per-step reward dimensions for RL credit assignment |
+| **Anti-Gaming** | Blind-blocking penalties, over-isolation cap, idempotent step rewards (0.40 cap) |
+| **Real-time Dashboard** | D3.js threat graph with pivot animations and 10-dim radar chart |
+
+---
+
+## 19. Technology Stack
+
+| Layer | Technologies |
+|-------|-------------|
+| **Backend** | Python 3.10+, FastAPI, Uvicorn, Pydantic v2, OpenEnv Core |
+| **Frontend** | Vanilla HTML/CSS/JS, D3.js v7, Chart.js v4, Inter/JetBrains Mono fonts |
+| **Inference** | OpenAI Python SDK, asyncio |
+| **Training** | TRL (Hugging Face), GRPO |
+| **DevOps** | Docker (multi-stage), uv package manager, pytest |
+| **Deployment** | HuggingFace Spaces (Docker SDK) |
+| **Visualization** | NetworkX + Matplotlib (server-side PNG), D3.js (client-side interactive) |

__init__.py

@@ -0,0 +1,33 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""CyberSOCEnv — Enterprise Cybersecurity Operations Center Environment."""
+
+from .client import CyberSOCClient
+from .models import (
+    SOCObservation,
+    SOCActionWrapper,
+    SOCState,
+    QueryHost,
+    IsolateSegment,
+    BlockIOC,
+    RunForensics,
+    KillProcess,
+    SubmitContainmentPlan,
+)
+
+__all__ = [
+    "CyberSOCClient",
+    "SOCObservation",
+    "SOCActionWrapper",
+    "SOCState",
+    "QueryHost",
+    "IsolateSegment",
+    "BlockIOC",
+    "RunForensics",
+    "KillProcess",
+    "SubmitContainmentPlan",
+]

client.py

@@ -0,0 +1,103 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""CyberSOCEnv Client — connects to the SOC environment server."""
+
+from typing import Dict
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+
+from .models import (
+    SOCObservation,
+    SOCActionWrapper,
+    SOCState,
+    Alert,
+    Severity,
+    ThreatType,
+    NetworkTopology,
+    ForensicsResult,
+    TimelineEntry,
+)
+
+
+class CyberSOCClient(
+    EnvClient[SOCActionWrapper, SOCObservation, SOCState]
+):
+    """
+    Client for the CyberSOCEnv environment.
+
+    Connects via WebSocket to the SOC environment server for
+    low-latency, persistent-session interaction.
+
+    Example:
+        >>> with CyberSOCClient(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(result.observation.alert_queue)
+        ...
+        ...     from play.models import QueryHost
+        ...     result = client.step(SOCActionWrapper(type="query_host", hostname="WS-001"))
+        ...     print(result.observation.host_forensics)
+    """
+
+    def _step_payload(self, action: SOCActionWrapper) -> Dict:
+        """Convert SOCActionWrapper to JSON payload for step message."""
+        return action.model_dump(exclude_none=True)
+
+    def _parse_result(self, payload: Dict) -> StepResult[SOCObservation]:
+        """Parse server response into StepResult[SOCObservation]."""
+        obs_data = payload.get("observation", {})
+
+        # Parse alerts
+        alerts = [Alert(**a) for a in obs_data.get("alert_queue", [])]
+
+        # Parse network topology
+        topo_data = obs_data.get("network_topology", {})
+        topology = NetworkTopology(**topo_data) if topo_data else NetworkTopology()
+
+        # Parse forensics (may be None)
+        forensics_data = obs_data.get("host_forensics")
+        forensics = ForensicsResult(**forensics_data) if forensics_data else None
+
+        # Parse timeline
+        timeline = [TimelineEntry(**t) for t in obs_data.get("timeline", [])]
+
+        observation = SOCObservation(
+            episode_id=obs_data.get("episode_id", ""),
+            alert_queue=alerts,
+            network_topology=topology,
+            host_forensics=forensics,
+            timeline=timeline,
+            business_impact_score=obs_data.get("business_impact_score", 0.0),
+            step_count=obs_data.get("step_count", 0),
+            active_threats=obs_data.get("active_threats", []),
+            max_steps=obs_data.get("max_steps", 30),
+            task_id=obs_data.get("task_id", "easy"),
+            total_reward=obs_data.get("total_reward", 0.0),
+            final_score=obs_data.get("final_score"),
+            grade_breakdown=obs_data.get("grade_breakdown"),
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+        )
+
+        result = StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+        # Attach episode_id directly on the result for easy RL loop access
+        result.episode_id = observation.episode_id  # type: ignore[attr-defined]
+        return result
+
+    def _parse_state(self, payload: Dict) -> SOCState:
+        """Parse server response into SOCState."""
+        return SOCState(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+            task_id=payload.get("task_id", "easy"),
+            total_reward=payload.get("total_reward", 0.0),
+            business_impact=payload.get("business_impact", 0.0),
+        )

dashboard/css/styles.css

@@ -0,0 +1,527 @@
+/* ============================================================
+   CyberSOC Command Center — Dark SOC Theme
+   ============================================================ */
+
+:root {
+  --bg-primary:    #0a0e17;
+  --bg-secondary:  #111827;
+  --bg-card:       #1a1f2e;
+  --border:        #2a3040;
+  --border-hover:  #3d4a60;
+
+  --accent-blue:   #3b82f6;
+  --accent-cyan:   #06b6d4;
+  --accent-green:  #10b981;
+  --accent-red:    #ef4444;
+  --accent-amber:  #f59e0b;
+  --accent-orange: #f97316;
+  --accent-purple: #8b5cf6;
+
+  --text-primary:   #f1f5f9;
+  --text-secondary: #94a3b8;
+  --text-muted:     #4b5563;
+
+  --glow-red:    0 0 20px rgba(239,68,68,0.45);
+  --glow-blue:   0 0 20px rgba(59,130,246,0.45);
+  --glow-green:  0 0 15px rgba(16,185,129,0.35);
+  --glow-amber:  0 0 15px rgba(245,158,11,0.35);
+  --glow-purple: 0 0 15px rgba(139,92,246,0.35);
+  --glow-cyan:   0 0 15px rgba(6,182,212,0.35);
+
+  --header-h: 60px;
+  --gap:       7px;
+  --r:         10px;
+  --r-sm:       5px;
+}
+
+/* ============================================================ Reset */
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+html, body { height: 100%; overflow: hidden; font-family: 'Inter', sans-serif;
+  background: var(--bg-primary); color: var(--text-primary); font-size: 13px; line-height: 1.5; }
+
+.mono { font-family: 'JetBrains Mono', monospace; }
+
+/* ============================================================ Header */
+.header {
+  position: fixed; top: 0; left: 0; right: 0;
+  height: var(--header-h); z-index: 100;
+  background: var(--bg-primary);
+  border-bottom: 1px solid var(--border);
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 0 16px; gap: 12px;
+  backdrop-filter: blur(4px);
+}
+
+.header-left { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }
+
+.shield-icon { font-size: 22px; filter: drop-shadow(0 0 8px rgba(59,130,246,0.7)); }
+
+.header-title { font-size: 15px; font-weight: 700; letter-spacing: 0.04em; white-space: nowrap; }
+
+/* Phase Indicator */
+.header-center { flex: 1; display: flex; flex-direction: column; align-items: center; gap: 3px; }
+
+.phase-indicator { display: flex; align-items: center; }
+
+.phase-dot { display: flex; flex-direction: column; align-items: center; gap: 3px; }
+
+.phase-dot-circle {
+  width: 11px; height: 11px; border-radius: 50%;
+  background: var(--text-muted); border: 2px solid var(--border);
+  transition: all 0.4s ease;
+}
+
+.phase-dot.active .phase-dot-circle  { background: var(--accent-blue); border-color: var(--accent-blue); box-shadow: var(--glow-blue); animation: phasePulse 1.6s ease infinite; }
+.phase-dot.completed .phase-dot-circle { background: var(--accent-green); border-color: var(--accent-green); box-shadow: var(--glow-green); }
+
+.phase-dot[data-phase="triage"].active     .phase-dot-circle { background: var(--accent-amber); border-color: var(--accent-amber); box-shadow: var(--glow-amber); }
+.phase-dot[data-phase="remediation"].active .phase-dot-circle { background: var(--accent-orange); border-color: var(--accent-orange); }
+.phase-dot[data-phase="report"].active     .phase-dot-circle { background: var(--accent-green);  border-color: var(--accent-green);  box-shadow: var(--glow-green); }
+
+@keyframes phasePulse { 0%,100%{box-shadow:0 0 6px rgba(59,130,246,.4)} 50%{box-shadow:0 0 18px rgba(59,130,246,.9)} }
+
+.phase-label { font-size: 8px; font-weight: 600; letter-spacing: .08em; color: var(--text-muted); transition: color .3s; white-space: nowrap; }
+.phase-dot.active    .phase-label { color: var(--accent-blue); }
+.phase-dot.completed .phase-label { color: var(--accent-green); }
+.phase-dot[data-phase="triage"].active    .phase-label { color: var(--accent-amber); }
+.phase-dot[data-phase="remediation"].active .phase-label { color: var(--accent-orange); }
+
+.phase-connector { width: 36px; height: 1px; background: var(--border); margin: 0 4px 12px; transition: background .4s; }
+.phase-connector.completed { background: var(--accent-green); }
+
+.red-team-alert {
+  font-size: 10px; font-weight: 700; letter-spacing: .1em;
+  color: var(--accent-red); padding: 2px 8px;
+  border: 1px solid var(--accent-red); border-radius: 4px;
+  animation: blink 0.7s ease infinite;
+}
+@keyframes blink { 0%,100%{opacity:1} 50%{opacity:.25} }
+
+/* Header right */
+.header-right { display: flex; align-items: center; gap: 14px; flex-shrink: 0; }
+
+.header-stat { display: flex; flex-direction: column; align-items: center; }
+.header-stat-label { font-size: 8px; font-weight: 600; letter-spacing: .1em; color: var(--text-muted); }
+.header-stat-value { font-size: 12px; font-weight: 700; }
+.header-stat-value.mono { font-family: 'JetBrains Mono', monospace; font-size: 10px; }
+
+.difficulty-badge {
+  padding: 3px 9px; border-radius: 4px; font-size: 9px; font-weight: 700; letter-spacing: .1em;
+  background: rgba(59,130,246,.15); color: var(--accent-blue); border: 1px solid rgba(59,130,246,.4);
+}
+.difficulty-badge.easy   { background:rgba(16,185,129,.15); color:var(--accent-green); border-color:rgba(16,185,129,.4); }
+.difficulty-badge.medium { background:rgba(245,158,11,.15); color:var(--accent-amber); border-color:rgba(245,158,11,.4); }
+.difficulty-badge.hard   { background:rgba(239,68,68,.15);  color:var(--accent-red);   border-color:rgba(239,68,68,.4); }
+
+/* ============================================================ Grid */
+.main-grid {
+  position: fixed; top: var(--header-h); left: 0; right: 0; bottom: 0;
+  display: grid;
+  grid-template-columns: 272px 1fr 256px;
+  grid-template-rows: 56% 44%;
+  gap: var(--gap); padding: var(--gap);
+}
+
+/* ============================================================ Panel */
+.panel {
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: var(--r);
+  box-shadow: 0 4px 24px rgba(0,0,0,.35);
+  display: flex; flex-direction: column; overflow: hidden;
+  transition: border-color .25s;
+}
+.panel:hover { border-color: var(--border-hover); }
+
+.panel-header {
+  padding: 8px 12px; border-bottom: 1px solid var(--border);
+  display: flex; align-items: center; justify-content: space-between; flex-shrink: 0;
+  min-height: 36px;
+}
+.panel-title { font-size: 11px; font-weight: 600; letter-spacing: .05em; }
+.panel-body   { flex: 1; overflow: hidden; position: relative; }
+
+.panel-1 { grid-column:1; grid-row:1; }
+.panel-2 { grid-column:2; grid-row:1; }
+.panel-3 { grid-column:3; grid-row:1; }
+.panel-4 { grid-column:1; grid-row:2; }
+.panel-5 { grid-column:2; grid-row:2; }
+.panel-6 { grid-column:3; grid-row:2; display:flex; flex-direction:column; }
+
+/* ============================================================ Badges */
+.badge {
+  display:inline-flex; align-items:center; justify-content:center;
+  min-width:18px; height:18px; padding:0 5px; border-radius:9px;
+  font-size:10px; font-weight:700; font-family:'JetBrains Mono',monospace;
+  background:rgba(239,68,68,.2); color:var(--accent-red); border:1px solid rgba(239,68,68,.4);
+}
+
+.reward-badge { font-family:'JetBrains Mono',monospace; font-size:12px; font-weight:700; color:var(--accent-green); }
+.reward-badge.negative { color:var(--accent-red); }
+
+/* Panel 2 graph summary subtitle */
+.graph-summary {
+  width:100%; font-size:9px; font-family:'JetBrains Mono',monospace;
+  color:var(--text-muted); white-space:nowrap; overflow:hidden; text-overflow:ellipsis;
+  padding-top:1px;
+}
+
+/* Panel 2 legend */
+.graph-legend { display:flex; align-items:center; gap:8px; flex-wrap:wrap; }
+.legend-item  { display:flex; align-items:center; gap:3px; font-size:9px; color:var(--text-secondary); }
+.legend-dot   { width:7px; height:7px; border-radius:50%; }
+.legend-dot.host       { background:var(--accent-blue); }
+.legend-dot.process    { background:var(--accent-amber); border-radius:1px; transform:rotate(45deg); }
+.legend-dot.ioc        { background:var(--accent-red); }
+.legend-dot.alert-node { background:var(--accent-orange); }
+.legend-dot.vuln       { background:var(--accent-green); border-radius:1px; }
+
+/* ============================================================ Alert List (Panel 1) */
+.alert-list {
+  height:100%; overflow-y:auto; padding:7px;
+  display:flex; flex-direction:column; gap:5px;
+  scrollbar-width:thin; scrollbar-color:var(--border) transparent;
+}
+
+.alert-card {
+  background:var(--bg-secondary); border:1px solid var(--border);
+  border-radius:var(--r-sm); padding:7px 9px; cursor:pointer;
+  transition:border-color .2s, box-shadow .2s;
+  animation:slideInRight .3s ease forwards;
+}
+.alert-card:hover { border-color:var(--accent-blue); }
+
+.alert-card.pivot { border-color:var(--accent-red) !important; animation:pivotPulse 1s ease 4; }
+@keyframes pivotPulse { 0%,100%{box-shadow:none} 50%{box-shadow:var(--glow-red)} }
+
+.alert-card-header { display:flex; align-items:center; justify-content:space-between; gap:5px; margin-bottom:3px; }
+
+.severity-badge { padding:1px 5px; border-radius:3px; font-size:8px; font-weight:700; letter-spacing:.07em; flex-shrink:0; }
+.severity-low      { background:rgba(16,185,129,.2);  color:var(--accent-green);  }
+.severity-medium   { background:rgba(245,158,11,.2);  color:var(--accent-amber);  }
+.severity-high     { background:rgba(249,115,22,.2);  color:var(--accent-orange); }
+.severity-critical { background:rgba(239,68,68,.2);   color:var(--accent-red);    border:1px solid rgba(239,68,68,.4); }
+
+.alert-host        { font-family:'JetBrains Mono',monospace; font-size:10px; color:var(--accent-cyan); }
+.alert-description { font-size:10px; color:var(--text-secondary); line-height:1.4; margin-bottom:3px; }
+.alert-iocs        { font-family:'JetBrains Mono',monospace; font-size:9px; color:var(--text-muted); white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
+.alert-footer      { display:flex; align-items:center; gap:5px; margin-top:3px; }
+
+.pivot-badge {
+  display:inline-flex; align-items:center; gap:2px; padding:1px 5px;
+  border-radius:3px; font-size:8px; font-weight:700;
+  background:rgba(239,68,68,.2); color:var(--accent-red); border:1px solid rgba(239,68,68,.5);
+  animation:blink .7s ease infinite;
+}
+.correlated-badge {
+  display:inline-flex; align-items:center; gap:2px; padding:1px 5px;
+  border-radius:3px; font-size:8px; font-weight:700;
+  background:rgba(139,92,246,.2); color:var(--accent-purple); border:1px solid rgba(139,92,246,.4);
+}
+
+/* ============================================================ Threat Graph (Panel 2) */
+.graph-body {
+  padding:0; background:radial-gradient(ellipse at center, #0d1422 0%, var(--bg-card) 100%);
+}
+#threat-graph-svg { width:100%; height:100%; }
+
+.graph-tooltip {
+  position:absolute; background:var(--bg-secondary); border:1px solid var(--border);
+  border-radius:var(--r-sm); padding:7px 9px; font-size:10px;
+  pointer-events:none; z-index:10; max-width:190px;
+  box-shadow:0 4px 16px rgba(0,0,0,.5); transition:opacity .15s;
+}
+.graph-tooltip.hidden { opacity:0; pointer-events:none; }
+.graph-tooltip-title { font-weight:600; font-family:'JetBrains Mono',monospace; margin-bottom:4px; color:var(--accent-cyan); font-size:11px; }
+.graph-tooltip-row   { display:flex; justify-content:space-between; gap:8px; margin-bottom:1px; }
+.graph-tooltip-key   { color:var(--text-muted); }
+.graph-tooltip-value { color:var(--text-primary); font-family:'JetBrains Mono',monospace; }
+
+/* D3 SVG styles */
+.graph-link { fill:none; stroke-width:1.5; }
+.graph-link.runs_on           { stroke:rgba(59,130,246,.5); }
+.graph-link.involves          { stroke:rgba(148,163,184,.35); stroke-dasharray:4,4; }
+.graph-link.communicates_with { stroke:rgba(245,158,11,.5); stroke-dasharray:6,3; }
+.graph-link.exploits          { stroke:rgba(239,68,68,.6); }
+.graph-link.pivoted_from      { stroke:var(--accent-red); stroke-width:3; filter:drop-shadow(0 0 4px rgba(239,68,68,.8)); }
+.graph-link.part_of_chain     { stroke:rgba(100,116,139,.4); stroke-dasharray:3,5; }
+
+.node-label { font-family:'JetBrains Mono',monospace; font-size:9px; fill:rgba(148,163,184,.7); pointer-events:none; user-select:none; }
+
+/* ============================================================ Action Log (Panel 3) */
+.action-log {
+  height:100%; overflow-y:auto; padding:7px;
+  display:flex; flex-direction:column; gap:3px;
+  font-family:'JetBrains Mono',monospace; font-size:10.5px;
+  scrollbar-width:thin; scrollbar-color:var(--border) transparent;
+}
+
+.log-entry {
+  padding:5px 7px; border-radius:4px;
+  border-left:2.5px solid var(--border);
+  background:rgba(255,255,255,.02);
+  animation:slideInRight .25s ease forwards;
+  line-height:1.5;
+}
+.log-entry.investigation { border-left-color:var(--accent-cyan); }
+.log-entry.remediation   { border-left-color:var(--accent-amber); }
+.log-entry.triage        { border-left-color:var(--accent-purple); }
+.log-entry.report        { border-left-color:var(--accent-green); }
+
+.log-step   { color:var(--text-muted); font-size:9px; }
+.log-action { color:var(--accent-cyan); font-weight:700; }
+.log-entry.remediation .log-action { color:var(--accent-amber); }
+.log-entry.triage      .log-action { color:var(--accent-purple); }
+.log-entry.report      .log-action { color:var(--accent-green); }
+.log-target { color:var(--text-primary); }
+.log-result  { font-size:9px; color:var(--text-secondary); margin-top:1px; }
+.log-details {
+  font-size:9px; color:var(--text-muted); margin-top:3px; padding:3px 6px;
+  background:rgba(0,0,0,.2); border-radius:3px; border-left:2px solid var(--border);
+  line-height:1.6;
+}
+.log-reward { font-size:10px; font-weight:700; }
+.log-reward.positive { color:var(--accent-green); }
+.log-reward.negative { color:var(--accent-red); }
+
+/* ============================================================ Network Topology (Panel 4) */
+.network-topology {
+  height:100%; overflow-y:auto; padding:7px;
+  display:flex; flex-direction:column; gap:5px;
+  scrollbar-width:thin; scrollbar-color:var(--border) transparent;
+}
+
+.subnet-section {
+  background:var(--bg-secondary); border:1px solid var(--border);
+  border-radius:var(--r-sm); padding:6px 8px;
+  transition:border-color .3s; position:relative; overflow:hidden;
+}
+.subnet-section.has-compromised { border-color:rgba(239,68,68,.4); }
+.subnet-section.isolated        { border-color:rgba(245,158,11,.6); background:rgba(245,158,11,.04); }
+
+.subnet-header  { display:flex; align-items:center; justify-content:space-between; margin-bottom:5px; }
+.subnet-name    { font-size:10px; font-weight:600; text-transform:uppercase; letter-spacing:.08em; }
+.subnet-stats   { font-size:9px; font-family:'JetBrains Mono',monospace; color:var(--text-muted); }
+.subnet-stats .compromised { color:var(--accent-red); }
+.subnet-stats .isolated    { color:var(--accent-amber); }
+
+.host-grid { display:flex; flex-wrap:wrap; gap:3px; }
+
+.host-dot {
+  width:9px; height:9px; border-radius:2px;
+  cursor:pointer; transition:transform .15s;
+}
+.host-dot:hover { transform:scale(1.6); z-index:1; }
+.host-dot.online       { background:rgba(59,130,246,.5); }
+.host-dot.compromised  { background:var(--accent-red); animation:hostGlow 1.2s ease infinite; }
+.host-dot.isolated     { background:rgba(100,116,139,.5); border:1px solid var(--accent-amber); }
+.host-dot.queried      { background:var(--accent-cyan); }
+.host-dot.healthy      { background:rgba(16,185,129,.5); }
+
+@keyframes hostGlow { 0%,100%{box-shadow:none} 50%{box-shadow:0 0 5px rgba(239,68,68,.9)} }
+
+.isolated-overlay {
+  position:absolute; inset:0; display:flex; align-items:center; justify-content:center;
+  background:rgba(245,158,11,.06); border:1.5px solid rgba(245,158,11,.5);
+  border-radius:var(--r-sm); font-size:9px; font-weight:700;
+  color:var(--accent-amber); letter-spacing:.08em; pointer-events:none;
+}
+
+.topology-stats { display:flex; gap:6px; }
+.topo-stat { font-size:9px; font-family:'JetBrains Mono',monospace; font-weight:600; padding:2px 5px; border-radius:3px; }
+.topo-stat.compromised { background:rgba(239,68,68,.15); color:var(--accent-red); }
+.topo-stat.isolated    { background:rgba(245,158,11,.15); color:var(--accent-amber); }
+
+/* ============================================================ Scores Panel (Panel 5) */
+.scores-body {
+  display:flex; flex-direction:column; gap:6px; padding:8px; overflow:hidden; height:100%;
+}
+.radar-container    { flex:1; position:relative; min-height:0; }
+.timeline-container { flex:0 0 90px; position:relative; }
+
+/* ============================================================ Mission Status (Panel 6) */
+.panel-6 .panel-body {
+  display:flex; flex-direction:column; overflow-y:auto;
+  scrollbar-width:thin; scrollbar-color:var(--border) transparent;
+}
+
+.containment-section,
+.impact-section,
+.threats-section,
+.control-section {
+  padding:7px 11px; border-bottom:1px solid var(--border); flex-shrink:0;
+}
+.containment-section:last-child,
+.impact-section:last-child,
+.threats-section:last-child,
+.control-section:last-child { border-bottom:none; }
+
+.section-label {
+  font-size:9px; font-weight:600; letter-spacing:.08em;
+  color:var(--text-muted); text-transform:uppercase; margin-bottom:5px;
+}
+
+/* Containment bars */
+.containment-bars { display:flex; flex-direction:column; gap:4px; }
+
+.containment-bar-item { display:flex; flex-direction:column; gap:2px; }
+.containment-bar-label {
+  display:flex; justify-content:space-between;
+  font-size:9px; color:var(--text-secondary);
+}
+.containment-bar-label .complete { color:var(--accent-green); }
+.containment-bar-track { height:5px; background:var(--bg-secondary); border-radius:3px; overflow:hidden; border:1px solid var(--border); }
+.containment-bar-fill { height:100%; background:var(--accent-cyan); border-radius:3px; transition:width .5s ease; width:0%; }
+.containment-bar-fill.complete { background:var(--accent-green); box-shadow:var(--glow-green); }
+
+/* Business Impact Gauge */
+.impact-gauge { padding:2px 0; }
+
+.impact-gauge-track {
+  position:relative; height:11px; border-radius:6px; overflow:hidden;
+  display:flex; margin-bottom:3px;
+}
+.impact-zone-green { flex:0 0 40%; background:linear-gradient(90deg,rgba(16,185,129,.4),rgba(16,185,129,.2)); }
+.impact-zone-amber { flex:0 0 35%; background:linear-gradient(90deg,rgba(245,158,11,.25),rgba(245,158,11,.5)); }
+.impact-zone-red   { flex:0 0 25%; background:linear-gradient(90deg,rgba(239,68,68,.35),rgba(239,68,68,.7)); }
+
+.impact-marker {
+  position:absolute; top:-2px; width:3px; height:15px;
+  background:white; border-radius:2px; box-shadow:0 0 8px rgba(255,255,255,.8);
+  transition:left .5s ease; left:0%; transform:translateX(-50%);
+}
+
+.impact-labels { display:flex; justify-content:space-between; font-size:8px; color:var(--text-muted); margin-bottom:3px; }
+.impact-value-display { display:flex; align-items:center; justify-content:space-between; }
+.impact-label { font-size:9px; color:var(--text-muted); }
+.impact-value { font-size:18px; font-weight:700; font-family:'JetBrains Mono',monospace; color:var(--accent-green); transition:color .5s; }
+.impact-value.high     { color:var(--accent-amber); }
+.impact-value.critical { color:var(--accent-red); }
+
+/* Active threats */
+.active-threats-list { display:flex; flex-wrap:wrap; gap:3px; }
+
+.threat-tag {
+  padding:2px 5px; border-radius:3px; font-size:9px; font-weight:600;
+  font-family:'JetBrains Mono',monospace;
+  background:rgba(239,68,68,.15); color:var(--accent-red); border:1px solid rgba(239,68,68,.3);
+}
+.threat-tag.contained {
+  background:rgba(16,185,129,.15); color:var(--accent-green);
+  border-color:rgba(16,185,129,.3); text-decoration:line-through; opacity:.6;
+}
+
+/* Controls */
+.control-section { display:flex; flex-wrap:wrap; align-items:center; gap:5px; padding:8px 11px !important; }
+
+.btn {
+  padding:5px 12px; border-radius:var(--r-sm); font-size:11px; font-weight:600;
+  cursor:pointer; border:1px solid transparent; transition:all .2s;
+  display:inline-flex; align-items:center; gap:3px;
+}
+.btn:disabled { opacity:.5; cursor:not-allowed; }
+.btn-primary  { background:var(--accent-blue); color:#fff; border-color:var(--accent-blue); }
+.btn-primary:hover:not(:disabled)  { background:#2563eb; box-shadow:var(--glow-blue); }
+.btn-secondary { background:var(--bg-secondary); color:var(--text-primary); border-color:var(--border); }
+.btn-secondary:hover { border-color:var(--accent-blue); color:var(--accent-blue); }
+
+.task-selector { display:flex; align-items:center; gap:5px; font-size:11px; color:var(--text-secondary); margin-left:auto; }
+.task-select {
+  background:var(--bg-secondary); color:var(--text-primary);
+  border:1px solid var(--border); border-radius:4px; padding:3px 6px;
+  font-size:11px; cursor:pointer; outline:none;
+}
+.task-select:focus { border-color:var(--accent-blue); }
+
+/* ============================================================ Overlays */
+.overlay {
+  position:fixed; inset:0; z-index:200;
+  display:flex; align-items:center; justify-content:center;
+  background:rgba(10,14,23,.92); backdrop-filter:blur(10px);
+}
+.overlay.hidden { display:none; }
+
+.overlay-content {
+  text-align:center; display:flex; flex-direction:column; align-items:center; gap:14px;
+}
+.overlay-icon { font-size:44px; filter:drop-shadow(0 0 20px rgba(59,130,246,.7)); }
+.overlay h2   { font-size:22px; font-weight:700; }
+
+#connection-status { font-size:13px; color:var(--text-secondary); }
+
+.connection-spinner {
+  width:30px; height:30px; border:2.5px solid var(--border);
+  border-top-color:var(--accent-blue); border-radius:50%; animation:spin 1s linear infinite;
+}
+@keyframes spin { to { transform:rotate(360deg); } }
+
+/* Final Score Overlay */
+.final-score-content {
+  text-align:center; display:flex; flex-direction:column; align-items:center; gap:14px;
+  max-width:480px; width:90%; padding:28px;
+  background:var(--bg-card); border:1px solid var(--accent-green);
+  border-radius:var(--r); box-shadow:var(--glow-green), 0 24px 60px rgba(0,0,0,.7);
+  animation:revealPop .5s cubic-bezier(.175,.885,.32,1.275) forwards;
+}
+@keyframes revealPop { from{opacity:0;transform:scale(.8)} to{opacity:1;transform:scale(1)} }
+
+.mission-complete-banner {
+  font-size:12px; font-weight:700; letter-spacing:.2em; color:var(--accent-green);
+  border:1px solid var(--accent-green); padding:3px 14px; border-radius:3px;
+  animation:bannerGlow 1.5s ease infinite;
+}
+@keyframes bannerGlow { 0%,100%{box-shadow:none} 50%{box-shadow:var(--glow-green)} }
+
+.final-score-label  { font-size:10px; font-weight:600; letter-spacing:.15em; color:var(--text-muted); }
+.final-score-number {
+  font-family:'JetBrains Mono',monospace; font-size:64px; font-weight:700;
+  color:var(--accent-green); line-height:1;
+}
+
+.final-grade-bars { width:100%; display:flex; flex-direction:column; gap:3px; }
+.final-grade-bar-item { display:grid; grid-template-columns:140px 1fr 38px; align-items:center; gap:6px; }
+.final-grade-bar-label { font-size:9px; color:var(--text-secondary); text-align:right; }
+.final-grade-bar-track { height:5px; background:var(--bg-secondary); border-radius:3px; overflow:hidden; }
+.final-grade-bar-fill  { height:100%; background:var(--accent-cyan); border-radius:3px; transition:width 1s ease; }
+.final-grade-bar-value { font-family:'JetBrains Mono',monospace; font-size:9px; color:var(--text-primary); }
+
+.final-penalties-bonuses { width:100%; display:flex; flex-direction:column; gap:2px; max-height:80px; overflow-y:auto; }
+.penalty-item { font-size:10px; color:var(--accent-red); font-family:'JetBrains Mono',monospace; }
+.bonus-item   { font-size:10px; color:var(--accent-green); font-family:'JetBrains Mono',monospace; }
+
+/* ============================================================ Screen Flash */
+.screen-flash { position:fixed; inset:0; pointer-events:none; z-index:999; opacity:0; border-radius:0; }
+.screen-flash.red-flash   { background:rgba(239,68,68,.08); border:5px solid rgba(239,68,68,.6); }
+.screen-flash.green-flash { background:rgba(16,185,129,.07); border:5px solid rgba(16,185,129,.5); }
+
+/* ============================================================ Notifications */
+#notification-container {
+  position:fixed; top:calc(var(--header-h) + 10px); right:10px; z-index:150;
+  display:flex; flex-direction:column; gap:5px; pointer-events:none;
+}
+.notification-toast {
+  padding:7px 13px; border-radius:var(--r-sm); font-size:11px; font-weight:600;
+  color:#fff; animation:toastIn .3s ease forwards; pointer-events:none;
+  max-width:340px;
+}
+.notification-toast.red    { background:rgba(239,68,68,.9);  border:1px solid var(--accent-red);   box-shadow:var(--glow-red); }
+.notification-toast.green  { background:rgba(16,185,129,.9); border:1px solid var(--accent-green); }
+.notification-toast.blue   { background:rgba(59,130,246,.9); border:1px solid var(--accent-blue);  }
+.notification-toast.amber  { background:rgba(245,158,11,.9); border:1px solid var(--accent-amber); }
+@keyframes toastIn { from{opacity:0;transform:translateX(100%)} to{opacity:1;transform:translateX(0)} }
+
+/* ============================================================ Utility */
+.hidden { display:none !important; }
+
+.empty-state { color:var(--text-muted); font-size:11px; text-align:center; padding:16px; font-style:italic; }
+
+/* ============================================================ Animations */
+@keyframes slideInRight { from{opacity:0;transform:translateX(16px)} to{opacity:1;transform:translateX(0)} }
+@keyframes fadeIn       { from{opacity:0} to{opacity:1} }
+@keyframes scaleBounce  { 0%{transform:scale(1)} 50%{transform:scale(1.14)} 100%{transform:scale(1)} }
+
+/* ============================================================ Scrollbars */
+::-webkit-scrollbar       { width:3px; height:3px; }
+::-webkit-scrollbar-track { background:transparent; }
+::-webkit-scrollbar-thumb { background:var(--border); border-radius:2px; }
+::-webkit-scrollbar-thumb:hover { background:var(--border-hover); }

dashboard/index.html

@@ -0,0 +1,261 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>CyberSOC Command Center</title>
+
+  <!-- Fonts -->
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;700&display=swap" rel="stylesheet">
+
+  <!-- D3.js v7 -->
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/d3/7.8.5/d3.min.js"></script>
+
+  <!-- Chart.js v4 -->
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.4.1/chart.umd.min.js"></script>
+
+  <!-- Styles -->
+  <link rel="stylesheet" href="css/styles.css">
+</head>
+<body>
+
+  <!-- ==========================================
+       CONNECTION OVERLAY
+  ========================================== -->
+  <div id="connection-overlay" class="overlay">
+    <div class="overlay-content">
+      <div class="overlay-icon">🛡️</div>
+      <h2>CyberSOC Command Center</h2>
+      <div id="connection-status">Connecting to CyberSOC Server...</div>
+      <div class="connection-spinner"></div>
+      <div style="font-size:11px;color:var(--text-muted);margin-top:4px;">
+        Server: <span style="font-family:monospace;color:var(--accent-cyan)">http://localhost:8000</span>
+      </div>
+    </div>
+  </div>
+
+  <!-- ==========================================
+       FINAL SCORE OVERLAY
+  ========================================== -->
+  <div id="final-score-overlay" class="overlay hidden">
+    <div class="final-score-content">
+      <div class="mission-complete-banner">MISSION COMPLETE</div>
+      <div class="final-score-label">EPISODE FINAL SCORE</div>
+      <div id="final-score-number" class="final-score-number">0.000</div>
+      <div id="final-grade-bars" class="final-grade-bars"></div>
+      <div id="final-penalties-bonuses" class="final-penalties-bonuses"></div>
+      <button class="btn btn-primary" onclick="window.dashboard.closeScoreOverlay()">📊 View Full Report</button>
+    </div>
+  </div>
+
+  <!-- ==========================================
+       HEADER
+  ========================================== -->
+  <header class="header">
+    <div class="header-left">
+      <span class="shield-icon">🛡️</span>
+      <span class="header-title">CyberSOC Command Center</span>
+    </div>
+
+    <div class="header-center">
+      <div class="phase-indicator" id="phase-indicator">
+        <div class="phase-dot" data-phase="triage">
+          <span class="phase-dot-circle"></span>
+          <span class="phase-label">TRIAGE</span>
+        </div>
+        <div class="phase-connector"></div>
+        <div class="phase-dot" data-phase="investigation">
+          <span class="phase-dot-circle"></span>
+          <span class="phase-label">INVESTIGATE</span>
+        </div>
+        <div class="phase-connector"></div>
+        <div class="phase-dot" data-phase="remediation">
+          <span class="phase-dot-circle"></span>
+          <span class="phase-label">REMEDIATE</span>
+        </div>
+        <div class="phase-connector"></div>
+        <div class="phase-dot" data-phase="report">
+          <span class="phase-dot-circle"></span>
+          <span class="phase-label">REPORT</span>
+        </div>
+      </div>
+      <div id="red-team-alert" class="red-team-alert hidden">
+        🔴 RED TEAM ACTIVE — ADAPTIVE PIVOT DETECTED
+      </div>
+    </div>
+
+    <div class="header-right">
+      <div class="header-stat">
+        <span class="header-stat-label">STEP</span>
+        <span class="header-stat-value mono" id="header-step">0/30</span>
+      </div>
+      <div class="header-stat">
+        <span class="header-stat-label">EPISODE</span>
+        <span class="header-stat-value mono" id="header-episode">—</span>
+      </div>
+      <div class="header-stat">
+        <span class="header-stat-label">ELAPSED</span>
+        <span class="header-stat-value mono" id="header-timer">00:00</span>
+      </div>
+      <div id="difficulty-badge" class="difficulty-badge">—</div>
+    </div>
+  </header>
+
+  <!-- ==========================================
+       MAIN GRID
+  ========================================== -->
+  <main class="main-grid">
+
+    <!-- PANEL 1: Alert Queue -->
+    <section class="panel panel-1" id="panel-alerts">
+      <div class="panel-header">
+        <h2 class="panel-title">🚨 Alert Queue</h2>
+        <span class="badge" id="alert-count-badge">0</span>
+      </div>
+      <div class="panel-body">
+        <div id="alert-list" class="alert-list">
+          <div class="empty-state">Awaiting alerts…</div>
+        </div>
+      </div>
+    </section>
+
+    <!-- PANEL 2: Live Threat Graph -->
+    <section class="panel panel-2" id="panel-graph">
+      <div class="panel-header" style="flex-wrap:wrap;gap:4px;">
+        <div style="display:flex;align-items:center;justify-content:space-between;width:100%;">
+          <h2 class="panel-title">🕸️ Live Threat Graph</h2>
+          <div class="graph-legend">
+            <span class="legend-item"><span class="legend-dot host"></span>Host</span>
+            <span class="legend-item"><span class="legend-dot process"></span>Process</span>
+            <span class="legend-item"><span class="legend-dot ioc"></span>IOC</span>
+            <span class="legend-item"><span class="legend-dot alert-node"></span>Alert</span>
+            <span class="legend-item"><span class="legend-dot vuln"></span>Vuln</span>
+          </div>
+        </div>
+        <div id="graph-summary" class="graph-summary"></div>
+      </div>
+      <div class="panel-body graph-body" id="threat-graph-container">
+        <svg id="threat-graph-svg"></svg>
+        <div id="graph-tooltip" class="graph-tooltip hidden"></div>
+      </div>
+    </section>
+
+    <!-- PANEL 3: Agent Action Log -->
+    <section class="panel panel-3" id="panel-actions">
+      <div class="panel-header">
+        <h2 class="panel-title">📋 Agent Actions</h2>
+        <span id="total-reward-badge" class="reward-badge">+0.00</span>
+      </div>
+      <div class="panel-body">
+        <div id="action-log" class="action-log">
+          <div class="empty-state">Awaiting agent actions…</div>
+        </div>
+      </div>
+    </section>
+
+    <!-- PANEL 4: Network Topology -->
+    <section class="panel panel-4" id="panel-network">
+      <div class="panel-header">
+        <h2 class="panel-title">🌐 Network Topology</h2>
+        <div class="topology-stats">
+          <span class="topo-stat compromised" id="topo-compromised">0 compromised</span>
+          <span class="topo-stat isolated"    id="topo-isolated">0 isolated</span>
+        </div>
+      </div>
+      <div class="panel-body">
+        <div id="network-topology" class="network-topology"></div>
+      </div>
+    </section>
+
+    <!-- PANEL 5: Performance Metrics -->
+    <section class="panel panel-5" id="panel-scores">
+      <div class="panel-header">
+        <h2 class="panel-title">📡 Performance Metrics</h2>
+        <span style="font-size:9px;color:var(--text-muted)">10-dim grading · live estimate</span>
+      </div>
+      <div class="panel-body scores-body">
+        <div class="radar-container">
+          <canvas id="radar-chart"></canvas>
+        </div>
+        <div class="timeline-container">
+          <canvas id="reward-timeline"></canvas>
+        </div>
+      </div>
+    </section>
+
+    <!-- PANEL 6: Mission Status -->
+    <section class="panel panel-6" id="panel-mission">
+      <div class="panel-header">
+        <h2 class="panel-title">📊 Mission Status</h2>
+      </div>
+      <div class="panel-body">
+
+        <!-- Containment Progress -->
+        <div class="containment-section">
+          <h3 class="section-label">Containment Progress</h3>
+          <div id="containment-bars" class="containment-bars">
+            <!-- Injected by JS -->
+          </div>
+        </div>
+
+        <!-- Business Impact -->
+        <div class="impact-section">
+          <h3 class="section-label">Business Impact</h3>
+          <div class="impact-gauge">
+            <div class="impact-gauge-track">
+              <div class="impact-zone-green"></div>
+              <div class="impact-zone-amber"></div>
+              <div class="impact-zone-red"></div>
+              <div class="impact-marker" id="impact-marker"></div>
+            </div>
+            <div class="impact-labels">
+              <span>Minimal</span>
+              <span>Moderate</span>
+              <span>Severe</span>
+            </div>
+            <div class="impact-value-display">
+              <span class="impact-label">Score:</span>
+              <span class="impact-value mono" id="impact-value">0.00</span>
+            </div>
+          </div>
+        </div>
+
+        <!-- Active Threats -->
+        <div class="threats-section">
+          <h3 class="section-label">Active Threats</h3>
+          <div id="active-threats-list" class="active-threats-list">
+            <span class="empty-state" style="padding:6px 0">No threats detected</span>
+          </div>
+        </div>
+
+        <!-- Controls -->
+        <div class="control-section">
+          <button class="btn btn-primary" id="btn-start">▶ Start Episode</button>
+          <button class="btn btn-secondary hidden" id="btn-pause">⏸ Pause</button>
+          <button class="btn btn-secondary hidden" id="btn-next">⏭ Step</button>
+          <button class="btn btn-secondary hidden" id="btn-reset">↺ Reset</button>
+          <div class="task-selector">
+            <label for="task-select">Task:</label>
+            <select id="task-select" class="task-select">
+              <option value="easy">Easy</option>
+              <option value="medium">Medium</option>
+              <option value="hard" selected>Hard</option>
+            </select>
+          </div>
+        </div>
+
+      </div>
+    </section>
+
+  </main><!-- /main-grid -->
+
+  <!-- Scripts (order matters) -->
+  <script src="js/animations.js"></script>
+  <script src="js/api.js"></script>
+  <script src="js/graphs.js"></script>
+  <script src="js/app.js"></script>
+
+</body>
+</html>

dashboard/js/animations.js

@@ -0,0 +1,232 @@
+/* ============================================================
+   CyberSOC Dashboard — Animation Utilities
+   ============================================================ */
+
+const AnimationUtils = {
+  _notifContainer: null,
+  _flashEl: null,
+
+  init() {
+    // Notification container
+    let nc = document.getElementById('notification-container');
+    if (!nc) {
+      nc = document.createElement('div');
+      nc.id = 'notification-container';
+      document.body.appendChild(nc);
+    }
+    this._notifContainer = nc;
+
+    // Screen flash element
+    let sf = document.getElementById('screen-flash');
+    if (!sf) {
+      sf = document.createElement('div');
+      sf.id = 'screen-flash';
+      sf.className = 'screen-flash';
+      document.body.appendChild(sf);
+    }
+    this._flashEl = sf;
+  },
+
+  // Animate a number counting up/down
+  countUp(element, from, to, duration = 600, decimals = 2) {
+    if (!element) return;
+    const start = performance.now();
+    const range = to - from;
+    const update = (now) => {
+      const elapsed = now - start;
+      const progress = Math.min(elapsed / duration, 1);
+      const ease = 1 - Math.pow(1 - progress, 3); // cubic ease-out
+      const current = from + range * ease;
+      element.textContent = current.toFixed(decimals);
+      if (progress < 1) requestAnimationFrame(update);
+    };
+    requestAnimationFrame(update);
+  },
+
+  // Count up an integer (no decimals)
+  countUpInt(element, from, to, duration = 400) {
+    if (!element) return;
+    const start = performance.now();
+    const range = to - from;
+    const update = (now) => {
+      const elapsed = now - start;
+      const progress = Math.min(elapsed / duration, 1);
+      const ease = 1 - Math.pow(1 - progress, 3);
+      element.textContent = Math.round(from + range * ease);
+      if (progress < 1) requestAnimationFrame(update);
+    };
+    requestAnimationFrame(update);
+  },
+
+  // Flash the screen border (for Red Team pivots)
+  flashScreen(color = 'red', duration = 800) {
+    if (!this._flashEl) return;
+    this._flashEl.className = `screen-flash ${color}-flash`;
+    this._flashEl.style.opacity = '1';
+    setTimeout(() => {
+      this._flashEl.style.transition = `opacity ${duration}ms ease`;
+      this._flashEl.style.opacity = '0';
+      setTimeout(() => {
+        this._flashEl.style.transition = '';
+        this._flashEl.className = 'screen-flash';
+      }, duration);
+    }, 150);
+  },
+
+  // Show a toast notification
+  showNotification(text, type = 'blue', duration = 3000) {
+    if (!this._notifContainer) return;
+    const toast = document.createElement('div');
+    toast.className = `notification-toast ${type}`;
+    toast.textContent = text;
+    this._notifContainer.appendChild(toast);
+    setTimeout(() => {
+      toast.style.transition = 'opacity 0.4s ease, transform 0.4s ease';
+      toast.style.opacity = '0';
+      toast.style.transform = 'translateX(100%)';
+      setTimeout(() => toast.remove(), 400);
+    }, duration);
+  },
+
+  // Scale bounce for score changes
+  scaleBounce(element, intensity = 1.12) {
+    if (!element) return;
+    element.style.transition = 'transform 0.15s ease';
+    element.style.transform = `scale(${intensity})`;
+    setTimeout(() => {
+      element.style.transform = 'scale(1)';
+    }, 150);
+  },
+
+  // Pulse glow on an element
+  pulseGlow(element, color = 'blue', times = 3) {
+    if (!element) return;
+    const glowMap = {
+      blue: '0 0 20px rgba(59,130,246,0.8)',
+      red: '0 0 20px rgba(239,68,68,0.8)',
+      green: '0 0 15px rgba(16,185,129,0.7)',
+      amber: '0 0 15px rgba(245,158,11,0.7)',
+      purple: '0 0 15px rgba(139,92,246,0.7)',
+    };
+    const glow = glowMap[color] || glowMap.blue;
+    let count = 0;
+    const pulse = () => {
+      if (count >= times * 2) return;
+      const isOn = count % 2 === 0;
+      element.style.transition = 'box-shadow 0.3s ease';
+      element.style.boxShadow = isOn ? glow : 'none';
+      count++;
+      setTimeout(pulse, 300);
+    };
+    pulse();
+  },
+
+  // Checkmark completion animation for progress bars
+  checkmarkComplete(labelElement) {
+    if (!labelElement) return;
+    const check = document.createElement('span');
+    check.textContent = ' ✓';
+    check.style.color = 'var(--accent-green)';
+    check.style.opacity = '0';
+    check.style.transition = 'opacity 0.3s ease';
+    labelElement.appendChild(check);
+    requestAnimationFrame(() => {
+      check.style.opacity = '1';
+    });
+  },
+
+  // Reveal final score with dramatic animation
+  revealFinalScore(finalScore, breakdown, penalties, bonuses) {
+    const overlay = document.getElementById('final-score-overlay');
+    if (!overlay) return;
+    overlay.classList.remove('hidden');
+
+    // Animate the main score number
+    const scoreEl = document.getElementById('final-score-number');
+    if (scoreEl) {
+      scoreEl.textContent = '0.000';
+      setTimeout(() => this.countUp(scoreEl, 0, finalScore, 1500, 3), 300);
+    }
+
+    // Build dimension bars
+    const barsContainer = document.getElementById('final-grade-bars');
+    if (barsContainer && breakdown) {
+      barsContainer.innerHTML = '';
+      const dimLabels = {
+        threat_containment: 'Threat Containment',
+        ioc_blocking: 'IOC Blocking',
+        forensic_investigation: 'Forensic Investigation',
+        siem_correlation: 'SIEM Correlation',
+        threat_intel_usage: 'Threat Intel',
+        vuln_root_cause: 'Vuln Root Cause',
+        business_impact: 'Business Impact',
+        step_efficiency: 'Step Efficiency',
+        plan_coverage: 'Plan Coverage',
+        plan_evidence_quality: 'Plan Evidence',
+      };
+      let delay = 500;
+      Object.entries(breakdown).forEach(([key, value]) => {
+        const item = document.createElement('div');
+        item.className = 'final-grade-bar-item';
+        item.innerHTML = `
+          <span class="final-grade-bar-label">${dimLabels[key] || key}</span>
+          <div class="final-grade-bar-track">
+            <div class="final-grade-bar-fill" data-value="${value}" style="width:0%"></div>
+          </div>
+          <span class="final-grade-bar-value">0.00</span>
+        `;
+        barsContainer.appendChild(item);
+        const fill = item.querySelector('.final-grade-bar-fill');
+        const valEl = item.querySelector('.final-grade-bar-value');
+        setTimeout(() => {
+          fill.style.transition = 'width 0.8s ease';
+          fill.style.width = `${value * 100}%`;
+          this.countUp(valEl, 0, value, 800, 2);
+          if (value >= 0.8) fill.style.background = 'var(--accent-green)';
+          else if (value >= 0.5) fill.style.background = 'var(--accent-cyan)';
+          else fill.style.background = 'var(--accent-amber)';
+        }, delay);
+        delay += 120;
+      });
+    }
+
+    // Build penalties/bonuses
+    const pbContainer = document.getElementById('final-penalties-bonuses');
+    if (pbContainer) {
+      pbContainer.innerHTML = '';
+      (penalties || []).forEach(p => {
+        const el = document.createElement('div');
+        el.className = 'penalty-item';
+        el.textContent = `❌ ${p.type}: ${p.delta.toFixed(2)} (${p.detail})`;
+        pbContainer.appendChild(el);
+      });
+      (bonuses || []).forEach(b => {
+        const el = document.createElement('div');
+        el.className = 'bonus-item';
+        el.textContent = `✅ ${b.type}: +${b.delta.toFixed(2)} (${b.detail})`;
+        pbContainer.appendChild(el);
+      });
+    }
+
+    // Color the score based on value
+    if (scoreEl) {
+      setTimeout(() => {
+        if (finalScore >= 0.7) scoreEl.style.color = 'var(--accent-green)';
+        else if (finalScore >= 0.4) scoreEl.style.color = 'var(--accent-amber)';
+        else scoreEl.style.color = 'var(--accent-red)';
+        this.scaleBounce(scoreEl, 1.05);
+      }, 1600);
+    }
+  },
+
+  // Red team pivot wow moment
+  triggerRedTeamPivot() {
+    this.flashScreen('red', 600);
+    this.showNotification('⚡ RED TEAM PIVOT DETECTED — Adaptive adversary spreading!', 'red', 4000);
+    const rtAlert = document.getElementById('red-team-alert');
+    if (rtAlert) {
+      rtAlert.classList.remove('hidden');
+      setTimeout(() => rtAlert.classList.add('hidden'), 8000);
+    }
+  },
+};

dashboard/js/api.js

@@ -0,0 +1,123 @@
+/* ============================================================
+   CyberSOC Dashboard — API Client
+   Talks to the FastAPI CyberSOCEnv server at localhost:8000
+   ============================================================ */
+
+const API = {
+  // When served from the dashboard_server.py at /dashboard/ use same-origin relative URLs.
+  // When opened as file:// or from any other origin, fall back to absolute localhost:8000.
+  baseUrl: (() => {
+    if (typeof window === 'undefined') return 'http://localhost:8000';
+    const { protocol, hostname, port } = window.location;
+    if (protocol === 'file:') return 'http://localhost:8000';
+    if (hostname === 'localhost' && (port === '8000' || !port)) return '';
+    return 'http://localhost:8000';
+  })(),
+  sessionId: null,
+
+  // Parse the server response — handles both wrapped {observation: {...}}
+  // and flat observation formats
+  _parseResponse(data) {
+    if (!data) return null;
+    // Prefer wrapped format (per client.py's _parse_result)
+    const obs = data.observation || data;
+    return {
+      // Core observation fields
+      episode_id: obs.episode_id || '',
+      alert_queue: obs.alert_queue || [],
+      network_topology: obs.network_topology || { total_hosts: 0, subnets: {}, compromised_count: 0, isolated_count: 0, online_count: 0 },
+      host_forensics: obs.host_forensics || null,
+      timeline: obs.timeline || [],
+      business_impact_score: obs.business_impact_score ?? 0,
+      step_count: obs.step_count ?? 0,
+      active_threats: obs.active_threats || [],
+      max_steps: obs.max_steps || 30,
+      task_id: obs.task_id || 'hard',
+      total_reward: obs.total_reward ?? 0,
+      final_score: obs.final_score ?? null,
+      grade_breakdown: obs.grade_breakdown || null,
+      correlation_results: obs.correlation_results || null,
+      ioc_enrichment: obs.ioc_enrichment || null,
+      vulnerability_results: obs.vulnerability_results || null,
+      playbook_result: obs.playbook_result || null,
+      threat_graph_summary: obs.threat_graph_summary || null,
+      available_playbooks: obs.available_playbooks || [],
+      // Done/reward can be at top level or in obs
+      done: data.done ?? obs.done ?? false,
+      reward: data.reward ?? obs.reward ?? 0,
+    };
+  },
+
+  async reset(taskId = 'hard') {
+    const url = `${this.baseUrl}/reset`;
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ task_id: taskId }),
+    });
+    if (!response.ok) {
+      const errText = await response.text();
+      throw new Error(`Reset failed: ${response.status} — ${errText.substring(0, 200)}`);
+    }
+    const data = await response.json();
+    // Store session ID if the server provides one
+    const sessionHeader = response.headers.get('X-Session-Id') || response.headers.get('x-session-id');
+    if (sessionHeader) this.sessionId = sessionHeader;
+    if (data.session_id) this.sessionId = data.session_id;
+    return this._parseResponse(data);
+  },
+
+  async step(action) {
+    const url = `${this.baseUrl}/step`;
+    const headers = { 'Content-Type': 'application/json' };
+    if (this.sessionId) headers['X-Session-Id'] = this.sessionId;
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(action),
+    });
+    if (!response.ok) {
+      // Try alternate format: {action: {...}}
+      const altResponse = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ action }),
+      });
+      if (!altResponse.ok) {
+        const errText = await altResponse.text();
+        throw new Error(`Step failed: ${altResponse.status} — ${errText.substring(0, 200)}`);
+      }
+      const data = await altResponse.json();
+      return this._parseResponse(data);
+    }
+    const data = await response.json();
+    return this._parseResponse(data);
+  },
+
+  async getState() {
+    const url = `${this.baseUrl}/state`;
+    const headers = {};
+    if (this.sessionId) headers['X-Session-Id'] = this.sessionId;
+    const response = await fetch(url, { headers });
+    if (!response.ok) return null;
+    return response.json();
+  },
+
+  async checkConnection() {
+    try {
+      // Try /state first, fall back to root
+      const r = await fetch(`${this.baseUrl}/state`, {
+        signal: AbortSignal.timeout(3000),
+      });
+      return r.ok || r.status === 404; // 404 = server alive, no state yet
+    } catch {
+      try {
+        const r2 = await fetch(this.baseUrl, { signal: AbortSignal.timeout(3000) });
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  },
+};

dashboard/js/app.js

@@ -0,0 +1,1083 @@
+/* ============================================================
+   CyberSOC Dashboard — Main Application Controller
+   ============================================================ */
+
+class CyberSOCDashboard {
+  constructor() {
+    this.api = API;
+    this.threatGraph = new ClientThreatGraph();
+    this.graphViz = new ThreatGraphViz('threat-graph-container');
+    this.radarChart = new RadarChart('radar-chart');
+    this.rewardTimeline = new RewardTimeline('reward-timeline');
+
+    this.currentObs = null;
+    this.demoActions = [];
+    this.currentStepIndex = 0;
+    this.autoPlayTimer = null;
+    this.episodeStartTime = null;
+    this.timerInterval = null;
+    this.isPaused = false;
+    this.episodeRunning = false;
+    this.prevAlertIds = new Set();
+    this.currentAction = null;
+
+    // Live score estimates (updated heuristically during episode)
+    this.liveScores = {
+      threat_containment: 0, ioc_blocking: 0, forensic_investigation: 0,
+      siem_correlation: 0, threat_intel_usage: 0, vuln_root_cause: 0,
+      business_impact: 1.0, step_efficiency: 0.5, plan_coverage: 0, plan_evidence_quality: 0,
+    };
+    this.containmentState = {
+      processed_killed: 0, processes_total: 0,
+      iocs_blocked: 0, iocs_total: 0,
+      hosts_investigated: 0, hosts_total: 0,
+      playbooks_triggered: 0, playbooks_total: 2,
+    };
+  }
+
+  async init() {
+    AnimationUtils.init();
+    this.graphViz.init();
+    this.radarChart.init();
+    this.rewardTimeline.init();
+    this._bindButtons();
+    this._showConnectionOverlay('Connecting to CyberSOC Server...');
+    await this._waitForServer();
+  }
+
+  async _waitForServer() {
+    let attempts = 0;
+    const maxAttempts = 30;
+    const check = async () => {
+      attempts++;
+      const ok = await this.api.checkConnection();
+      if (ok) {
+        this._hideConnectionOverlay();
+        AnimationUtils.showNotification('✅ Connected to CyberSOC Server', 'green', 2000);
+        document.getElementById('btn-start').disabled = false;
+      } else if (attempts < maxAttempts) {
+        this._showConnectionOverlay(`Connecting to CyberSOC Server... (${attempts}/${maxAttempts})`);
+        setTimeout(check, 2000);
+      } else {
+        this._showConnectionOverlay('⚠️ Server not available. Start with: uvicorn server.app:app --port 8000');
+        document.getElementById('btn-start').disabled = false; // Allow manual start attempt
+      }
+    };
+    await check();
+  }
+
+  _bindButtons() {
+    document.getElementById('btn-start').addEventListener('click', () => this._onStartClick());
+    document.getElementById('btn-pause').addEventListener('click', () => this._onPauseClick());
+    document.getElementById('btn-next').addEventListener('click', () => this._onNextClick());
+    document.getElementById('btn-reset').addEventListener('click', () => this._onResetClick());
+  }
+
+  async _onStartClick() {
+    const taskId = document.getElementById('task-select').value;
+    await this.startEpisode(taskId);
+  }
+
+  _onPauseClick() {
+    this.isPaused = !this.isPaused;
+    const btn = document.getElementById('btn-pause');
+    if (this.isPaused) {
+      btn.textContent = '▶ Resume';
+      if (this.autoPlayTimer) { clearTimeout(this.autoPlayTimer); this.autoPlayTimer = null; }
+    } else {
+      btn.textContent = '⏸ Pause';
+      this._scheduleNextStep();
+    }
+  }
+
+  _onNextClick() {
+    if (this.autoPlayTimer) { clearTimeout(this.autoPlayTimer); this.autoPlayTimer = null; }
+    this.isPaused = true;
+    document.getElementById('btn-pause').textContent = '▶ Resume';
+    this._executeNextStep();
+  }
+
+  async _onResetClick() {
+    this.isPaused = false;
+    this.episodeRunning = false;
+    if (this.autoPlayTimer) { clearTimeout(this.autoPlayTimer); this.autoPlayTimer = null; }
+    if (this.timerInterval) { clearInterval(this.timerInterval); this.timerInterval = null; }
+
+    // Reset UI
+    document.getElementById('btn-start').classList.remove('hidden');
+    document.getElementById('btn-pause').classList.add('hidden');
+    document.getElementById('btn-next').classList.add('hidden');
+    document.getElementById('btn-reset').classList.add('hidden');
+    document.getElementById('task-select').disabled = false;
+
+    this._resetUI();
+  }
+
+  // ============================================================
+  // Episode Management
+  // ============================================================
+
+  async startEpisode(taskId) {
+    document.getElementById('btn-start').classList.add('hidden');
+    document.getElementById('task-select').disabled = true;
+    document.getElementById('btn-pause').classList.remove('hidden');
+    document.getElementById('btn-next').classList.remove('hidden');
+    document.getElementById('btn-reset').classList.remove('hidden');
+
+    AnimationUtils.showNotification(`🚀 Starting ${taskId.toUpperCase()} episode...`, 'blue', 2000);
+
+    try {
+      const obs = await this.api.reset(taskId);
+      this.currentObs = obs;
+      this.episodeRunning = true;
+      this.currentStepIndex = 0;
+      this.episodeStartTime = Date.now();
+      this.prevAlertIds = new Set();
+
+      // Start timer
+      if (this.timerInterval) clearInterval(this.timerInterval);
+      this.timerInterval = setInterval(() => this._updateTimer(), 1000);
+
+      // Build demo action sequence from initial observation
+      this.demoActions = this.buildDemoActions(obs);
+
+      // Initial UI update (staggered alerts)
+      this._resetUIForEpisode();
+      this._updateHeader(obs);
+      this._updatePhase(0, obs.max_steps);
+      await this._populateInitialAlerts(obs.alert_queue);
+      this._updateNetworkTopology(obs.network_topology);
+      this._updateBusinessImpact(obs.business_impact_score);
+      this._updateActiveThreats(obs.active_threats);
+      this._updateContainmentProgress(obs, taskId);
+
+      // Populate threat graph from initial observation
+      this.threatGraph = new ClientThreatGraph();
+      this.threatGraph.updateFromObservation(obs, null);
+      obs.alert_queue.forEach(a => this.prevAlertIds.add(a.alert_id));
+      this.graphViz.update(this.threatGraph.getGraphData());
+
+      // Start auto-play
+      this._scheduleNextStep(2500);
+
+    } catch (err) {
+      console.error('Episode start failed:', err);
+      AnimationUtils.showNotification(`❌ Failed to start episode: ${err.message}`, 'red', 5000);
+      document.getElementById('btn-start').classList.remove('hidden');
+      document.getElementById('task-select').disabled = false;
+      document.getElementById('btn-pause').classList.add('hidden');
+      document.getElementById('btn-next').classList.add('hidden');
+      document.getElementById('btn-reset').classList.add('hidden');
+    }
+  }
+
+  buildDemoActions(obs) {
+    // Parse initial observation to get real data
+    const alerts = obs.alert_queue || [];
+    const alertIds = alerts.map(a => a.alert_id);
+    const taskId = obs.task_id;
+
+    // Collect all IOCs from alerts
+    const allIocs = [];
+    const ipIocs = [];
+    const domainIocs = [];
+    const hashIocs = [];
+    const hostsSeen = new Set();
+    const subnetsSeen = new Set();
+
+    alerts.forEach(a => {
+      if (!hostsSeen.has(a.source_host)) {
+        hostsSeen.add(a.source_host);
+      }
+      if (a.subnet) subnetsSeen.add(a.subnet);
+      (a.ioc_indicators || []).forEach(ioc => {
+        if (!allIocs.includes(ioc)) {
+          allIocs.push(ioc);
+          if (/^\d{1,3}(\.\d{1,3}){3}$/.test(ioc)) ipIocs.push(ioc);
+          else if (/[a-f0-9]{32,64}/i.test(ioc)) hashIocs.push(ioc);
+          else domainIocs.push(ioc);
+        }
+      });
+    });
+
+    const hosts = [...hostsSeen];
+    const firstHost = hosts[0] || 'WS-042';
+    const secondHost = hosts[1] || firstHost;
+    const thirdHost = hosts[2] || firstHost;
+    const firstIp = ipIocs[0] || allIocs[0] || '192.168.1.1';
+    const firstDomain = domainIocs[0] || allIocs[1] || firstIp;
+    const firstHash = hashIocs[0] || allIocs[2] || firstIp;
+
+    // Task-specific action sequences using known data
+    if (taskId === 'hard') {
+      return this._hardDemoActions(alertIds, hosts, ipIocs, domainIocs, hashIocs);
+    } else if (taskId === 'medium') {
+      return this._mediumDemoActions(alertIds, hosts, ipIocs, domainIocs, hashIocs);
+    } else {
+      return this._easyDemoActions(alertIds, hosts, ipIocs, domainIocs, hashIocs);
+    }
+  }
+
+  _hardDemoActions(alertIds, hosts, ipIocs, domainIocs, hashIocs) {
+    return [
+      // TRIAGE: correlate alerts about the C2 activity
+      { type: 'correlate_alerts', alert_ids: [alertIds[0] || 'ALERT-H001', alertIds[1] || 'ALERT-H002'] },
+
+      // INVESTIGATION: executive host (entry point)
+      { type: 'query_host', hostname: 'EXEC-003' },
+      { type: 'run_forensics', hostname: 'EXEC-003' },
+
+      // INVESTIGATION: corporate host with C2 beacon
+      { type: 'query_host', hostname: 'WS-088' },
+      { type: 'run_forensics', hostname: 'WS-088' },
+
+      // THREAT INTEL: enrich the C2 IP
+      { type: 'enrich_ioc', ioc_value: ipIocs[0] || '198.51.100.77', ioc_type: 'ip' },
+
+      // INVESTIGATION: datacenter server (privilege escalation target)
+      { type: 'scan_host_vulnerabilities', hostname: 'SRV-002' },
+      { type: 'run_forensics', hostname: 'SRV-002' },
+
+      // REMEDIATION: kill C2-related processes
+      { type: 'kill_process', hostname: 'EXEC-003', process_name: 'outlook_macro.exe' },
+      { type: 'kill_process', hostname: 'EXEC-003', process_name: 'svchost_c2.exe' },
+      { type: 'kill_process', hostname: 'WS-088', process_name: 'svchost_c2.exe' },
+
+      // REMEDIATION: block C2 infrastructure
+      { type: 'block_ioc', ioc_value: ipIocs[0] || '198.51.100.77', ioc_type: 'ip' },
+      { type: 'block_ioc', ioc_value: domainIocs[0] || 'cdn-update.malware-c2.net', ioc_type: 'domain' },
+
+      // REMEDIATION: isolate executive subnet (triggers pivot if adaptive=true)
+      { type: 'isolate_segment', subnet: 'executive', reason: 'APT lateral movement detected — executive subnet compromised' },
+
+      // REMEDIATION: SOAR playbook for C2 disruption
+      { type: 'trigger_playbook', playbook_name: 'c2_disruption', target: 'EXEC-003' },
+
+      // REMEDIATION: kill exfil and ransomware processes
+      { type: 'kill_process', hostname: 'SRV-002', process_name: 'exploit_kernel.exe' },
+      { type: 'kill_process', hostname: 'SRV-002', process_name: 'data_pump.exe' },
+      { type: 'kill_process', hostname: 'FIN-008', process_name: 'data_pump.exe' },
+      { type: 'kill_process', hostname: 'SRV-010', process_name: 'blackcat_ransom.exe' },
+
+      // REPORT: submit comprehensive containment plan
+      {
+        type: 'submit_containment_plan',
+        plan: [
+          {
+            threat_id: 'T-HARD-001',
+            actions_taken: ['query_host', 'run_forensics', 'kill_process', 'correlate_alerts'],
+            root_cause: 'Spear-phishing email with malicious macro attachment targeting executive VP. Macro executed outlook_macro.exe establishing initial foothold.',
+            confidence: 0.95,
+          },
+          {
+            threat_id: 'T-HARD-002',
+            actions_taken: ['run_forensics', 'kill_process', 'block_ioc', 'trigger_playbook', 'isolate_segment'],
+            root_cause: 'C2 beacon (svchost_c2.exe) established on EXEC-003 and WS-088 communicating to 198.51.100.77 every 60s. C2 infrastructure disrupted.',
+            confidence: 0.92,
+          },
+          {
+            threat_id: 'T-HARD-003',
+            actions_taken: ['scan_host_vulnerabilities', 'run_forensics', 'kill_process'],
+            root_cause: 'Kernel privilege escalation on SRV-002 via exploit_kernel.exe. CVE leveraged for SYSTEM-level access to database server.',
+            confidence: 0.88,
+          },
+          {
+            threat_id: 'T-HARD-004',
+            actions_taken: ['run_forensics', 'kill_process', 'block_ioc'],
+            root_cause: 'Data exfiltration campaign using data_pump.exe on SRV-002 and FIN-008. 2.3GB customer PII transferred to 203.0.113.99. Exfil channel blocked.',
+            confidence: 0.90,
+          },
+          {
+            threat_id: 'T-HARD-005',
+            actions_taken: ['kill_process'],
+            root_cause: 'BlackCat ransomware deployment on datacenter servers SRV-010 and SRV-015. Encryption halted before full deployment. Recovery recommended.',
+            confidence: 0.85,
+          },
+        ],
+        executive_summary: 'APT campaign fully contained. C2 infrastructure at 198.51.100.77 disrupted and blocked. Executive subnet isolated. All 5 threat chains neutralized: phishing entry point, C2 beaconing, kernel privilege escalation, data exfiltration, and ransomware deployment. Estimated data exposure: 2.3GB PII. Recommend: patch SRV-002 kernel CVE, reset all executive credentials, deploy EDR signatures for BlackCat variants.',
+      },
+    ];
+  }
+
+  _mediumDemoActions(alertIds, hosts, ipIocs, domainIocs, hashIocs) {
+    return [
+      { type: 'correlate_alerts', alert_ids: alertIds.slice(0, 2) },
+      { type: 'query_host', hostname: hosts[0] || 'WS-017' },
+      { type: 'run_forensics', hostname: hosts[0] || 'WS-017' },
+      { type: 'enrich_ioc', ioc_value: domainIocs[0] || ipIocs[0] || '203.0.113.50', ioc_type: domainIocs.length > 0 ? 'domain' : 'ip' },
+      { type: 'query_host', hostname: hosts[1] || 'DEV-033' },
+      { type: 'run_forensics', hostname: hosts[1] || 'DEV-033' },
+      { type: 'kill_process', hostname: hosts[0] || 'WS-017', process_name: 'powershell.exe' },
+      { type: 'kill_process', hostname: hosts[0] || 'WS-017', process_name: 'mimikatz.exe' },
+      { type: 'block_ioc', ioc_value: domainIocs[0] || ipIocs[0] || '203.0.113.50', ioc_type: domainIocs.length > 0 ? 'domain' : 'ip' },
+      { type: 'kill_process', hostname: hosts[1] || 'DEV-033', process_name: 'svchost_backdoor.exe' },
+      { type: 'isolate_segment', subnet: 'corporate', reason: 'Credential theft and lateral movement detected' },
+      { type: 'trigger_playbook', playbook_name: 'phishing_response', target: hosts[0] || 'WS-017' },
+      {
+        type: 'submit_containment_plan',
+        plan: [
+          { threat_id: 'T-MED-001', actions_taken: ['query_host', 'run_forensics', 'kill_process'], root_cause: 'Phishing email led to PowerShell execution downloading payload from evil-login.example.com', confidence: 0.9 },
+          { threat_id: 'T-MED-002', actions_taken: ['run_forensics', 'kill_process', 'block_ioc'], root_cause: 'Credential dumping via Mimikatz. LSASS memory access detected.', confidence: 0.88 },
+          { threat_id: 'T-MED-003', actions_taken: ['run_forensics', 'kill_process', 'isolate_segment'], root_cause: 'Lateral movement via compromised admin credentials to DEV-033 and FIN-012', confidence: 0.85 },
+        ],
+        executive_summary: 'Multi-stage phishing → credential theft → lateral movement campaign contained. Three compromised hosts remediated. Corporate subnet isolated pending investigation.',
+      },
+    ];
+  }
+
+  _easyDemoActions(alertIds, hosts, ipIocs, domainIocs, hashIocs) {
+    const host = hosts[0] || 'WS-042';
+    const hash = hashIocs[0] || ipIocs[0] || 'e99a18c428cb38d5f260853678922e03';
+    return [
+      { type: 'correlate_alerts', alert_ids: alertIds.slice(0, 2) },
+      { type: 'query_host', hostname: host },
+      { type: 'run_forensics', hostname: host },
+      { type: 'enrich_ioc', ioc_value: hash, ioc_type: hashIocs.length > 0 ? 'hash' : 'ip' },
+      { type: 'kill_process', hostname: host, process_name: 'cryptolocker.exe' },
+      { type: 'block_ioc', ioc_value: hash, ioc_type: hashIocs.length > 0 ? 'hash' : 'ip' },
+      { type: 'scan_host_vulnerabilities', hostname: host },
+      { type: 'trigger_playbook', playbook_name: 'ransomware_containment', target: host },
+      {
+        type: 'submit_containment_plan',
+        plan: [{
+          threat_id: 'T-EASY-001',
+          actions_taken: ['query_host', 'run_forensics', 'kill_process', 'block_ioc'],
+          root_cause: 'Ransomware (cryptolocker.exe) executing on WS-042, encrypting user documents. Delivered via phishing email attachment.',
+          confidence: 0.95,
+        }],
+        executive_summary: 'Single ransomware endpoint contained. Process killed, IOC hash blocked. Recommend disk restore from backup for WS-042.',
+      },
+    ];
+  }
+
+  // ============================================================
+  // Step Execution
+  // ============================================================
+
+  _scheduleNextStep(delay = 2000) {
+    if (this.isPaused || !this.episodeRunning) return;
+    if (this.autoPlayTimer) clearTimeout(this.autoPlayTimer);
+    this.autoPlayTimer = setTimeout(() => this._executeNextStep(), delay);
+  }
+
+  async _executeNextStep() {
+    if (!this.episodeRunning || this.currentObs?.done) {
+      this.episodeRunning = false;
+      return;
+    }
+    if (this.currentStepIndex >= this.demoActions.length) {
+      AnimationUtils.showNotification('ℹ️ Demo sequence complete. Episode still running.', 'blue', 3000);
+      return;
+    }
+
+    const action = this.demoActions[this.currentStepIndex];
+    this.currentAction = action;
+    this.currentStepIndex++;
+
+    try {
+      const obs = await this.api.step(action);
+      this.currentObs = obs;
+      await this.updateUI(obs, action);
+
+      if (obs.done) {
+        this.episodeRunning = false;
+        if (this.timerInterval) clearInterval(this.timerInterval);
+        this._handleEpisodeComplete(obs);
+      } else if (!this.isPaused) {
+        // Adjust delay based on action type for dramatic effect
+        let delay = 2000;
+        if (action.type === 'isolate_segment') delay = 3000; // Longer for pivot drama
+        if (action.type === 'submit_containment_plan') delay = 500;
+        this._scheduleNextStep(delay);
+      }
+    } catch (err) {
+      console.error('Step failed:', err);
+      AnimationUtils.showNotification(`❌ Step failed: ${err.message.substring(0, 80)}`, 'red', 4000);
+      // Try to continue on error
+      if (!this.isPaused) this._scheduleNextStep(3000);
+    }
+  }
+
+  // ============================================================
+  // UI Updates
+  // ============================================================
+
+  async updateUI(obs, action) {
+    this._updateHeader(obs);
+    this._updatePhase(obs.step_count, obs.max_steps);
+    this._updateActionLog(obs.timeline, action, obs);
+    this._updateNetworkTopology(obs.network_topology);
+    this._updateBusinessImpact(obs.business_impact_score);
+    this._updateActiveThreats(obs.active_threats);
+    this._updateContainmentProgress(obs, obs.task_id);
+    this._updateRewardBadge(obs.total_reward);
+
+    // Check for new pivot alerts
+    const newPivots = [];
+    (obs.alert_queue || []).forEach(alert => {
+      if (alert.alert_id.startsWith('PIVOT-') && !this.prevAlertIds.has(alert.alert_id)) {
+        newPivots.push(alert);
+      }
+    });
+
+    // Update alert queue (add new alerts with animation)
+    await this._updateAlertQueue(obs.alert_queue, newPivots.length > 0);
+
+    // Update threat graph
+    this.threatGraph.updateFromObservation(obs, action);
+    this.graphViz.update(this.threatGraph.getGraphData());
+
+    // Animate forensics result on graph
+    if (action?.type === 'run_forensics' && obs.host_forensics) {
+      this.graphViz.flashNode(obs.host_forensics.hostname, obs.host_forensics.is_compromised ? 'red' : 'green');
+    }
+    if (action?.type === 'block_ioc') {
+      this.graphViz.flashNode(action.ioc_value, 'green');
+    }
+    if (action?.type === 'kill_process') {
+      const procId = `${action.hostname}:${action.process_name}`;
+      this.graphViz.flashNode(procId, 'green');
+      AnimationUtils.showNotification(`💀 Killed: ${action.process_name} on ${action.hostname}`, 'amber', 2000);
+    }
+
+    // Red Team pivot moment
+    if (newPivots.length > 0) {
+      this._handleRedTeamPivot(newPivots[0]);
+      newPivots.forEach(p => {
+        this.prevAlertIds.add(p.alert_id);
+        // Animate pivot edge in graph
+        const pivotLinks = this.threatGraph.links.filter(l => l.edgeType === 'pivoted_from');
+        if (pivotLinks.length > 0) {
+          const pl = pivotLinks[pivotLinks.length - 1];
+          const srcId = pl.source.id || pl.source;
+          const tgtId = pl.target.id || pl.target;
+          this.graphViz.animatePivot(srcId, tgtId);
+        }
+      });
+    }
+
+    // Update reward timeline chart
+    if (obs.step_count > 0) {
+      this.rewardTimeline.addPoint(obs.step_count, obs.total_reward, action?.type);
+    }
+
+    // Update threat graph summary subtitle
+    if (obs.threat_graph_summary) this._updateGraphSummary(obs.threat_graph_summary);
+
+    // Update live score estimates
+    this._updateLiveScores(obs, action);
+
+    // Sync alert IDs
+    (obs.alert_queue || []).forEach(a => this.prevAlertIds.add(a.alert_id));
+  }
+
+  _updateLiveScores(obs, action) {
+    if (!action) return;
+    const scores = { ...this.liveScores };
+
+    if (action.type === 'correlate_alerts') scores.siem_correlation = 1.0;
+    if (action.type === 'run_forensics') {
+      scores.forensic_investigation = Math.min(1, scores.forensic_investigation + 0.2);
+    }
+    if (action.type === 'enrich_ioc') {
+      scores.threat_intel_usage = Math.min(1, scores.threat_intel_usage + 0.25);
+    }
+    if (action.type === 'scan_host_vulnerabilities' && obs.vulnerability_results?.length > 0) {
+      scores.vuln_root_cause = 1.0;
+    }
+    if (action.type === 'block_ioc') {
+      scores.ioc_blocking = Math.min(1, scores.ioc_blocking + 0.2);
+    }
+    if (action.type === 'kill_process') {
+      scores.threat_containment = Math.min(1, scores.threat_containment + 0.15);
+    }
+    if (action.type === 'submit_containment_plan') {
+      scores.plan_coverage = 0.9;
+      scores.plan_evidence_quality = 0.85;
+    }
+
+    // Business impact inversely related to actual business_impact_score
+    scores.business_impact = Math.max(0, 1.0 - obs.business_impact_score);
+
+    // Step efficiency based on step count vs max
+    const ratio = obs.step_count / (obs.max_steps || 30);
+    scores.step_efficiency = Math.max(0.3, 1.0 - Math.max(0, ratio - 0.5) * 1.5);
+
+    this.liveScores = scores;
+    this.radarChart.update(scores);
+  }
+
+  _updateHeader(obs) {
+    const stepEl = document.getElementById('header-step');
+    const episodeEl = document.getElementById('header-episode');
+    const diffBadge = document.getElementById('difficulty-badge');
+
+    if (stepEl) {
+      const old = parseInt(stepEl.textContent.split('/')[0]) || 0;
+      AnimationUtils.countUpInt(stepEl, old, obs.step_count, 300);
+      // Reformat with max_steps after animation
+      setTimeout(() => {
+        if (stepEl) stepEl.textContent = `${obs.step_count}/${obs.max_steps}`;
+      }, 350);
+    }
+
+    if (episodeEl && obs.episode_id) {
+      episodeEl.textContent = obs.episode_id.substring(0, 8) + '…';
+    }
+
+    if (diffBadge && obs.task_id) {
+      diffBadge.textContent = obs.task_id.toUpperCase();
+      diffBadge.className = `difficulty-badge ${obs.task_id}`;
+    }
+  }
+
+  _updateTimer() {
+    if (!this.episodeStartTime) return;
+    const elapsed = Math.floor((Date.now() - this.episodeStartTime) / 1000);
+    const mm = String(Math.floor(elapsed / 60)).padStart(2, '0');
+    const ss = String(elapsed % 60).padStart(2, '0');
+    const el = document.getElementById('header-timer');
+    if (el) el.textContent = `${mm}:${ss}`;
+  }
+
+  _updatePhase(step, maxSteps) {
+    // Phase progression based on step count and action types
+    const dots = document.querySelectorAll('.phase-dot');
+    const connectors = document.querySelectorAll('.phase-connector');
+
+    // Determine current phase
+    let phaseIdx = 0;
+    if (this.currentAction) {
+      const t = this.currentAction.type;
+      if (['correlate_alerts'].includes(t)) phaseIdx = 0; // TRIAGE
+      else if (['query_host', 'run_forensics', 'enrich_ioc', 'scan_host_vulnerabilities'].includes(t)) phaseIdx = 1; // INVESTIGATION
+      else if (['kill_process', 'block_ioc', 'isolate_segment', 'trigger_playbook'].includes(t)) phaseIdx = 2; // REMEDIATION
+      else if (['submit_containment_plan'].includes(t)) phaseIdx = 3; // REPORT
+    }
+
+    dots.forEach((dot, i) => {
+      dot.classList.remove('active', 'completed');
+      if (i < phaseIdx) dot.classList.add('completed');
+      else if (i === phaseIdx) dot.classList.add('active');
+    });
+
+    connectors.forEach((conn, i) => {
+      conn.classList.toggle('completed', i < phaseIdx);
+    });
+  }
+
+  async _populateInitialAlerts(alerts) {
+    const list = document.getElementById('alert-list');
+    if (!list) return;
+    list.innerHTML = '';
+
+    // Stagger alert cards sliding in
+    for (let i = 0; i < alerts.length; i++) {
+      await new Promise(r => setTimeout(r, 180 * i));
+      this._addAlertCard(alerts[i], list, false);
+    }
+
+    this._updateAlertBadge(alerts.length);
+  }
+
+  async _updateAlertQueue(alerts, hasPivot = false) {
+    const list = document.getElementById('alert-list');
+    if (!list) return;
+
+    // Find new alerts
+    const existingIds = new Set([...list.querySelectorAll('.alert-card')].map(c => c.dataset.alertId));
+    const newAlerts = alerts.filter(a => !existingIds.has(a.alert_id));
+
+    newAlerts.forEach(alert => {
+      this._addAlertCard(alert, list, alert.alert_id.startsWith('PIVOT-'));
+    });
+
+    // Update resolved state
+    const resolvedCount = alerts.filter(a => a.is_acknowledged).length;
+    this._updateAlertBadge(alerts.length - resolvedCount);
+  }
+
+  _addAlertCard(alert, container, isPivot = false) {
+    const card = document.createElement('div');
+    card.className = `alert-card${isPivot ? ' pivot' : ''}`;
+    card.dataset.alertId = alert.alert_id;
+
+    const severityClass = `severity-${alert.severity}`;
+    const iocText = (alert.ioc_indicators || []).join(', ');
+    const iocHtml = iocText ? `<div class="alert-iocs">IOCs: ${iocText}</div>` : '';
+    const pivotBadge = isPivot ? `<span class="pivot-badge">⚡ PIVOT</span>` : '';
+    const correlBadge = alert.is_acknowledged ? `<span class="correlated-badge">🔗 CORR</span>` : '';
+
+    card.innerHTML = `
+      <div class="alert-card-header">
+        <span class="${severityClass} severity-badge">${alert.severity.toUpperCase()}</span>
+        <span class="alert-host">${alert.source_host}</span>
+      </div>
+      <div class="alert-description">${alert.description}</div>
+      ${iocHtml}
+      <div class="alert-footer">
+        <span style="font-size:9px;color:var(--text-muted);font-family:monospace">${alert.threat_type}</span>
+        ${pivotBadge}${correlBadge}
+      </div>
+    `;
+
+    card.title = alert.description;
+    container.insertBefore(card, container.firstChild);
+  }
+
+  _updateAlertBadge(count) {
+    const badge = document.getElementById('alert-count-badge');
+    if (badge) badge.textContent = count;
+  }
+
+  _updateActionLog(timeline, lastAction, obs) {
+    const log = document.getElementById('action-log');
+    if (!log || !timeline?.length) return;
+
+    const lastEntry = timeline[timeline.length - 1];
+    if (!lastEntry) return;
+
+    // Remove empty state
+    const empty = log.querySelector('.empty-state');
+    if (empty) empty.remove();
+
+    const category = this._getActionCategory(lastEntry.action_type);
+    const isPos = lastEntry.reward >= 0;
+    const rewardText = `${isPos ? '+' : ''}${lastEntry.reward.toFixed(2)}`;
+    const rewardClass = isPos ? 'positive' : 'negative';
+    const icon = this._getActionIcon(lastEntry.action_type);
+
+    const detailsHtml = this._buildLogDetails(lastEntry.action_type, obs);
+
+    const entry = document.createElement('div');
+    entry.className = `log-entry ${category}`;
+    entry.innerHTML = `
+      <div>
+        <span class="log-step">[Step ${String(lastEntry.step).padStart(2, '0')}]</span>
+        <span class="log-action"> ${icon} ${lastEntry.action_type}</span>
+        <span class="log-target"> → ${lastEntry.target}</span>
+        <span class="log-reward ${rewardClass}" style="float:right">${isPos ? '✅' : '❌'} ${rewardText}</span>
+      </div>
+      <div class="log-result">${lastEntry.result.substring(0, 120)}</div>
+      ${detailsHtml}
+    `;
+
+    log.insertBefore(entry, log.firstChild);
+
+    // Update total reward badge
+    this._updateRewardBadge(obs?.total_reward ?? 0);
+  }
+
+  _buildLogDetails(actionType, obs) {
+    if (!obs) return '';
+    const lines = [];
+
+    if (actionType === 'run_forensics' && obs.host_forensics) {
+      const f = obs.host_forensics;
+      const status = f.is_compromised
+        ? `<span style="color:var(--accent-red)">⚠ COMPROMISED</span>`
+        : `<span style="color:var(--accent-green)">✓ CLEAN</span>`;
+      lines.push(`Status: ${status}`);
+      if (f.malicious_processes?.length) {
+        lines.push(`Procs: <span style="color:var(--accent-amber)">${f.malicious_processes.join(' · ')}</span>`);
+      }
+      if (f.network_connections?.length) {
+        lines.push(`Conns: <span style="color:var(--accent-red)">${f.network_connections.slice(0, 3).join(' · ')}</span>`);
+      }
+    }
+
+    if (actionType === 'enrich_ioc' && obs.ioc_enrichment) {
+      const e = obs.ioc_enrichment;
+      if (e.threat_actor) lines.push(`Actor: <span style="color:var(--accent-red)">${e.threat_actor}</span>`);
+      if (e.reputation !== undefined) lines.push(`Reputation: <span style="color:var(--accent-amber)">${e.reputation}</span>`);
+      if (e.mitre_ttps?.length) lines.push(`TTPs: <span style="color:var(--accent-purple)">${e.mitre_ttps.slice(0, 3).join(' · ')}</span>`);
+    }
+
+    if (actionType === 'scan_host_vulnerabilities' && obs.vulnerability_results?.length) {
+      const vulns = obs.vulnerability_results;
+      const critical = vulns.filter(v => v.cvss_score >= 9).length;
+      const cves = vulns.slice(0, 3).map(v => v.cve_id).join(' · ');
+      lines.push(`Found ${vulns.length} CVEs${critical ? ` (<span style="color:var(--accent-red)">${critical} critical</span>)` : ''}`);
+      if (cves) lines.push(`<span style="color:var(--accent-amber)">${cves}</span>`);
+    }
+
+    if (actionType === 'trigger_playbook' && obs.playbook_result) {
+      const p = obs.playbook_result;
+      const success = p.success ?? p.status === 'success';
+      lines.push(`Result: <span style="color:${success ? 'var(--accent-green)' : 'var(--accent-red)'}">
+        ${success ? '✓ Executed' : '✗ Failed'}</span>`);
+      if (p.actions_taken?.length) lines.push(`Steps: ${p.actions_taken.slice(0, 3).join(' → ')}`);
+    }
+
+    if (actionType === 'correlate_alerts' && obs.correlation_results) {
+      const c = obs.correlation_results;
+      const count = Array.isArray(c) ? c.length : (c.correlated_count ?? 1);
+      lines.push(`Correlated <span style="color:var(--accent-purple)">${count} alerts</span> into chain`);
+      if (c.threat_chain) lines.push(`Chain: <span style="color:var(--accent-cyan)">${c.threat_chain}</span>`);
+    }
+
+    if (!lines.length) return '';
+    return `<div class="log-details">${lines.join('<br>')}</div>`;
+  }
+
+  _updateGraphSummary(summary) {
+    const el = document.getElementById('graph-summary');
+    if (el && summary) el.textContent = summary;
+  }
+
+  _updateRewardBadge(totalReward) {
+    const badge = document.getElementById('total-reward-badge');
+    if (!badge) return;
+    const isPos = totalReward >= 0;
+    badge.textContent = `${isPos ? '+' : ''}${totalReward.toFixed(2)}`;
+    badge.className = `reward-badge${isPos ? '' : ' negative'}`;
+    AnimationUtils.scaleBounce(badge);
+  }
+
+  _updateNetworkTopology(topology) {
+    const container = document.getElementById('network-topology');
+    if (!container) return;
+
+    const subnetConfig = {
+      corporate:   { label: 'Corporate',   color: '#3b82f6' },
+      engineering: { label: 'Engineering', color: '#06b6d4' },
+      finance:     { label: 'Finance',     color: '#f59e0b' },
+      dmz:         { label: 'DMZ',         color: '#94a3b8' },
+      datacenter:  { label: 'Datacenter',  color: '#8b5cf6' },
+      executive:   { label: 'Executive',   color: '#ef4444' },
+    };
+
+    // Build or update subnet section skeletons
+    Object.entries(topology.subnets || {}).forEach(([subnet, count]) => {
+      const cfg = subnetConfig[subnet] || { label: subnet, color: '#94a3b8' };
+      let section = document.getElementById(`subnet-${subnet}`);
+      if (!section) {
+        section = document.createElement('div');
+        section.className = 'subnet-section';
+        section.id = `subnet-${subnet}`;
+        section.innerHTML = `
+          <div class="subnet-header">
+            <span class="subnet-name" style="color:${cfg.color}">${cfg.label}</span>
+            <span class="subnet-stats" id="stats-${subnet}">${count} hosts</span>
+          </div>
+          <div class="host-grid" id="grid-${subnet}"></div>
+        `;
+        container.appendChild(section);
+      }
+
+      // Populate grid with placeholder dots (count-based, no known names yet)
+      const grid = document.getElementById(`grid-${subnet}`);
+      if (grid && grid.children.length === 0) {
+        for (let i = 0; i < count; i++) {
+          const dot = document.createElement('div');
+          dot.className = 'host-dot online';
+          dot.dataset.idx = i;
+          grid.appendChild(dot);
+        }
+      }
+    });
+
+    // Overlay known-host statuses from the threat graph onto the dots
+    // Group graph hosts by subnet
+    const subnetHostStatus = {};  // subnet -> [{hostname, status}]
+    this.threatGraph.nodes.forEach((node) => {
+      if (node.nodeType !== 'host' || !node.subnet) return;
+      if (!subnetHostStatus[node.subnet]) subnetHostStatus[node.subnet] = [];
+      subnetHostStatus[node.subnet].push({ hostname: node.id, status: node.status || 'online' });
+    });
+
+    // For each subnet, update the first N dots with known statuses
+    Object.entries(subnetHostStatus).forEach(([subnet, hosts]) => {
+      const grid = document.getElementById(`grid-${subnet}`);
+      if (!grid) return;
+      const dots = [...grid.querySelectorAll('.host-dot')];
+      hosts.forEach((h, i) => {
+        if (i < dots.length) {
+          dots[i].className = `host-dot ${h.status}`;
+          dots[i].title = `${h.hostname} [${h.status}]`;
+          dots[i].id = `hostdot-${h.hostname}`;
+        }
+      });
+    });
+
+    // Update header stats
+    const topoStatComp = document.getElementById('topo-compromised');
+    const topoStatIso = document.getElementById('topo-isolated');
+    if (topoStatComp) topoStatComp.textContent = `${topology.compromised_count} compromised`;
+    if (topoStatIso) topoStatIso.textContent = `${topology.isolated_count} isolated`;
+
+    // Mark isolated subnets
+    Object.keys(topology.subnets || {}).forEach(subnet => {
+      const section = document.getElementById(`subnet-${subnet}`);
+      if (!section) return;
+      const hosts = subnetHostStatus[subnet] || [];
+      const isIsolated = hosts.some(h => h.status === 'isolated');
+      const hasCompromised = hosts.some(h => h.status === 'compromised');
+      section.classList.toggle('isolated', isIsolated);
+      section.classList.toggle('has-compromised', hasCompromised && !isIsolated);
+
+      let overlay = section.querySelector('.isolated-overlay');
+      if (isIsolated && !overlay) {
+        overlay = document.createElement('div');
+        overlay.className = 'isolated-overlay';
+        overlay.textContent = '🔒 ISOLATED';
+        section.appendChild(overlay);
+      } else if (!isIsolated && overlay) {
+        overlay.remove();
+      }
+    });
+  }
+
+  _updateBusinessImpact(score) {
+    const marker = document.getElementById('impact-marker');
+    const value = document.getElementById('impact-value');
+    if (marker) marker.style.left = `${score * 100}%`;
+    if (value) {
+      const prev = parseFloat(value.textContent) || 0;
+      AnimationUtils.countUp(value, prev, score, 400, 2);
+      value.className = 'impact-value mono' + (score > 0.6 ? ' critical' : score > 0.35 ? ' high' : '');
+    }
+
+    if (score > 0.5) {
+      const impactSection = document.querySelector('.impact-section');
+      if (impactSection) AnimationUtils.pulseGlow(impactSection, score > 0.7 ? 'red' : 'amber', 2);
+    }
+  }
+
+  _updateActiveThreats(threats) {
+    const list = document.getElementById('active-threats-list');
+    if (!list) return;
+    if (!threats || threats.length === 0) {
+      list.innerHTML = '<span style="color:var(--accent-green);font-size:11px;">✅ All threats contained</span>';
+      return;
+    }
+    list.innerHTML = threats.map(t => `<span class="threat-tag">${t}</span>`).join('');
+  }
+
+  _updateContainmentProgress(obs, taskId) {
+    const container = document.getElementById('containment-bars');
+    if (!container) return;
+
+    // Derive progress from timeline
+    const timeline = obs.timeline || [];
+    const killed = timeline.filter(t => t.action_type === 'kill_process');
+    const blocked = timeline.filter(t => t.action_type === 'block_ioc');
+    const forensics = timeline.filter(t => t.action_type === 'run_forensics');
+    const playbooks = timeline.filter(t => t.action_type === 'trigger_playbook');
+    const correlated = timeline.some(t => t.action_type === 'correlate_alerts');
+
+    // Task-specific totals
+    const totals = {
+      hard:   { kill: 8, block: 6, forensics: 5, playbooks: 1 },
+      medium: { kill: 4, block: 5, forensics: 3, playbooks: 1 },
+      easy:   { kill: 1, block: 1, forensics: 1, playbooks: 1 },
+    };
+    const t = totals[taskId] || totals.hard;
+
+    const bars = [
+      { id: 'bar-kill', label: 'Processes Killed', current: Math.min(killed.length, t.kill), total: t.kill },
+      { id: 'bar-block', label: 'IOCs Blocked', current: Math.min(blocked.length, t.block), total: t.block },
+      { id: 'bar-forensics', label: 'Hosts Investigated', current: Math.min(forensics.length, t.forensics), total: t.forensics },
+      { id: 'bar-playbooks', label: 'Playbooks Triggered', current: Math.min(playbooks.length, t.playbooks), total: t.playbooks },
+    ];
+
+    bars.forEach(bar => {
+      let item = document.getElementById(bar.id);
+      if (!item) {
+        item = document.createElement('div');
+        item.id = bar.id;
+        item.className = 'containment-bar-item';
+        container.appendChild(item);
+      }
+      const pct = bar.total > 0 ? Math.round((bar.current / bar.total) * 100) : 0;
+      const isComplete = bar.current >= bar.total;
+      item.innerHTML = `
+        <div class="containment-bar-label">
+          <span>${bar.label}</span>
+          <span class="${isComplete ? 'complete' : ''}">${bar.current}/${bar.total}${isComplete ? ' ✓' : ''}</span>
+        </div>
+        <div class="containment-bar-track">
+          <div class="containment-bar-fill ${isComplete ? 'complete' : ''}" style="width:${pct}%"></div>
+        </div>
+      `;
+    });
+  }
+
+  _handleRedTeamPivot(pivotAlert) {
+    AnimationUtils.triggerRedTeamPivot();
+    // Add the pivot alert to the queue with special styling
+    const list = document.getElementById('alert-list');
+    if (list) {
+      const card = document.createElement('div');
+      card.className = 'alert-card pivot';
+      card.dataset.alertId = pivotAlert.alert_id;
+      card.innerHTML = `
+        <div class="alert-card-header">
+          <span class="severity-critical severity-badge">CRITICAL</span>
+          <span class="alert-host">${pivotAlert.source_host || 'UNKNOWN'}</span>
+        </div>
+        <div class="alert-description" style="color:var(--accent-red)">⚡ ADAPTIVE THREAT — LATERAL PIVOT DETECTED. Adversary moved to new host.</div>
+        <div class="alert-footer">
+          <span class="pivot-badge">⚡ PIVOT</span>
+        </div>
+      `;
+      list.insertBefore(card, list.firstChild);
+    }
+    // Recalculate containment (requirements grew)
+    AnimationUtils.showNotification('⚡ Red Team lateral pivot! Containment requirements updated.', 'red', 5000);
+  }
+
+  _handleEpisodeComplete(obs) {
+    if (this.timerInterval) clearInterval(this.timerInterval);
+    document.getElementById('btn-pause').classList.add('hidden');
+    document.getElementById('btn-next').classList.add('hidden');
+
+    // Update phase to REPORT
+    this.currentAction = { type: 'submit_containment_plan' };
+    this._updatePhase(obs.step_count, obs.max_steps);
+
+    // Update radar with final scores
+    if (obs.grade_breakdown) {
+      this.radarChart.update(obs.grade_breakdown);
+    }
+
+    // Brief delay then show final score overlay
+    setTimeout(() => {
+      const finalScore = obs.final_score ?? obs.total_reward ?? 0;
+      AnimationUtils.revealFinalScore(
+        finalScore,
+        obs.grade_breakdown,
+        [], // penalties would come from grade_result
+        []  // bonuses
+      );
+      AnimationUtils.showNotification(`🏆 Episode complete! Score: ${finalScore.toFixed(3)}`, 'green', 6000);
+    }, 1000);
+  }
+
+  // ============================================================
+  // Helpers
+  // ============================================================
+
+  _getActionCategory(actionType) {
+    if (['correlate_alerts'].includes(actionType)) return 'triage';
+    if (['query_host', 'run_forensics', 'enrich_ioc', 'scan_host_vulnerabilities'].includes(actionType)) return 'investigation';
+    if (['kill_process', 'block_ioc', 'isolate_segment', 'trigger_playbook'].includes(actionType)) return 'remediation';
+    if (['submit_containment_plan'].includes(actionType)) return 'report';
+    return 'investigation';
+  }
+
+  _getActionIcon(actionType) {
+    const icons = {
+      query_host: '🔍',
+      run_forensics: '🧬',
+      enrich_ioc: '🔎',
+      scan_host_vulnerabilities: '🩺',
+      kill_process: '⚔️',
+      block_ioc: '🚫',
+      isolate_segment: '🔒',
+      trigger_playbook: '▶️',
+      correlate_alerts: '🔗',
+      submit_containment_plan: '📝',
+    };
+    return icons[actionType] || '➤';
+  }
+
+  _showConnectionOverlay(msg) {
+    const overlay = document.getElementById('connection-overlay');
+    const status = document.getElementById('connection-status');
+    if (overlay) overlay.classList.remove('hidden');
+    if (status) status.textContent = msg;
+  }
+
+  _hideConnectionOverlay() {
+    const overlay = document.getElementById('connection-overlay');
+    if (overlay) {
+      overlay.style.transition = 'opacity 0.5s ease';
+      overlay.style.opacity = '0';
+      setTimeout(() => {
+        overlay.classList.add('hidden');
+        overlay.style.opacity = '';
+        overlay.style.transition = '';
+      }, 500);
+    }
+  }
+
+  _resetUI() {
+    // Clear all panels to initial state
+    document.getElementById('alert-list').innerHTML = '<div class="empty-state">Awaiting alerts...</div>';
+    document.getElementById('action-log').innerHTML = '<div class="empty-state">Awaiting agent actions...</div>';
+    document.getElementById('active-threats-list').innerHTML = '<span class="empty-state">No threats detected</span>';
+    document.getElementById('containment-bars').innerHTML = '';
+    document.getElementById('network-topology').innerHTML = '';
+    document.getElementById('network-topology').dataset.built = 'false';
+    document.getElementById('header-step').textContent = '0/30';
+    document.getElementById('header-episode').textContent = '—';
+    document.getElementById('header-timer').textContent = '00:00';
+    document.getElementById('impact-value').textContent = '0.00';
+    document.getElementById('impact-marker').style.left = '0%';
+    document.getElementById('total-reward-badge').textContent = '+0.00';
+    document.getElementById('alert-count-badge').textContent = '0';
+    document.getElementById('difficulty-badge').textContent = '—';
+    document.getElementById('difficulty-badge').className = 'difficulty-badge';
+
+    // Reset phase
+    document.querySelectorAll('.phase-dot').forEach(d => d.classList.remove('active', 'completed'));
+    document.querySelectorAll('.phase-connector').forEach(c => c.classList.remove('completed'));
+
+    // Reset charts
+    if (this.rewardTimeline) this.rewardTimeline.reset();
+    if (this.radarChart) this.radarChart.update({
+      threat_containment: 0, ioc_blocking: 0, forensic_investigation: 0,
+      siem_correlation: 0, threat_intel_usage: 0, vuln_root_cause: 0,
+      business_impact: 1.0, step_efficiency: 0.5, plan_coverage: 0, plan_evidence_quality: 0,
+    });
+
+    // Reset threat graph
+    this.threatGraph = new ClientThreatGraph();
+    if (this.graphViz._initialized) {
+      this.graphViz.update({ nodes: [], links: [] });
+    }
+
+    // Show start button
+    document.getElementById('btn-start').classList.remove('hidden');
+    document.getElementById('task-select').disabled = false;
+  }
+
+  _resetUIForEpisode() {
+    document.getElementById('alert-list').innerHTML = '';
+    document.getElementById('action-log').innerHTML = '';
+    document.getElementById('containment-bars').innerHTML = '';
+    document.getElementById('network-topology').innerHTML = '';
+    document.getElementById('network-topology').dataset.built = 'false';
+    if (this.rewardTimeline) this.rewardTimeline.reset();
+    this.liveScores = {
+      threat_containment: 0, ioc_blocking: 0, forensic_investigation: 0,
+      siem_correlation: 0, threat_intel_usage: 0, vuln_root_cause: 0,
+      business_impact: 1.0, step_efficiency: 0.5, plan_coverage: 0, plan_evidence_quality: 0,
+    };
+    if (this.radarChart) this.radarChart.update(this.liveScores);
+  }
+
+  closeScoreOverlay() {
+    const overlay = document.getElementById('final-score-overlay');
+    if (overlay) {
+      overlay.style.transition = 'opacity 0.4s ease';
+      overlay.style.opacity = '0';
+      setTimeout(() => {
+        overlay.classList.add('hidden');
+        overlay.style.opacity = '';
+      }, 400);
+    }
+  }
+}
+
+
+// ============================================================
+// Bootstrap
+// ============================================================
+let dashboard;
+document.addEventListener('DOMContentLoaded', () => {
+  dashboard = new CyberSOCDashboard();
+  window.dashboard = dashboard;
+  dashboard.init();
+});

dashboard/js/graphs.js

@@ -0,0 +1,880 @@
+/* ============================================================
+   CyberSOC Dashboard — Graph Visualizations
+   D3.js v7 Threat Graph + Chart.js Radar + Timeline
+   ============================================================ */
+
+// ============================================================
+// Client-side Threat Graph State
+// ============================================================
+class ClientThreatGraph {
+  constructor() {
+    this.nodes = new Map();   // id -> node object
+    this.links = [];          // {source, target, edgeType, id}
+    this._linkSet = new Set(); // "source|target|type" for dedup
+    this._pivotLinks = new Set();
+  }
+
+  addNode(node) {
+    if (!this.nodes.has(node.id)) {
+      this.nodes.set(node.id, { ...node, _new: true });
+    }
+    return this;
+  }
+
+  updateNode(id, updates) {
+    if (this.nodes.has(id)) {
+      Object.assign(this.nodes.get(id), updates, { _updated: true });
+    }
+    return this;
+  }
+
+  addLink(sourceId, targetId, edgeType) {
+    const key = `${sourceId}|${targetId}|${edgeType}`;
+    const rkey = `${targetId}|${sourceId}|${edgeType}`;
+    if (this._linkSet.has(key) || this._linkSet.has(rkey)) return this;
+    this._linkSet.add(key);
+    const link = { source: sourceId, target: targetId, edgeType, id: key };
+    this.links.push(link);
+    if (edgeType === 'pivoted_from') this._pivotLinks.add(key);
+    return this;
+  }
+
+  hasPivotLinks() { return this._pivotLinks.size > 0; }
+
+  getGraphData() {
+    return {
+      nodes: [...this.nodes.values()],
+      links: [...this.links],
+    };
+  }
+
+  // Update from a full SOCObservation
+  updateFromObservation(obs, lastAction) {
+    // Always sync alert nodes and hosts from alert_queue
+    (obs.alert_queue || []).forEach(alert => {
+      const existing = this.nodes.get(alert.alert_id);
+      if (!existing) {
+        this.addNode({
+          id: alert.alert_id,
+          nodeType: 'alert',
+          label: alert.alert_id,
+          severity: alert.severity,
+          sourceHost: alert.source_host,
+          threatType: alert.threat_type,
+          description: alert.description,
+          isPivot: alert.alert_id.startsWith('PIVOT-'),
+          subnet: alert.subnet,
+        });
+      }
+
+      // Add source host
+      if (!this.nodes.has(alert.source_host)) {
+        this.addNode({
+          id: alert.source_host,
+          nodeType: 'host',
+          label: alert.source_host,
+          status: 'online',
+          subnet: alert.subnet || this._subnetFromHostname(alert.source_host),
+        });
+      } else if (!this.nodes.get(alert.source_host).subnet) {
+        this.updateNode(alert.source_host, { subnet: alert.subnet || this._subnetFromHostname(alert.source_host) });
+      }
+
+      // Link alert to host
+      this.addLink(alert.source_host, alert.alert_id, 'involves');
+
+      // Add IOC nodes
+      (alert.ioc_indicators || []).forEach(ioc => {
+        if (!this.nodes.has(ioc)) {
+          this.addNode({
+            id: ioc,
+            nodeType: 'ioc',
+            label: ioc.length > 22 ? ioc.substring(0, 20) + '…' : ioc,
+            fullLabel: ioc,
+            iocType: this._guessIocType(ioc),
+            blocked: false,
+            enriched: false,
+          });
+        }
+        this.addLink(alert.alert_id, ioc, 'involves');
+      });
+    });
+
+    // Process based on last action
+    if (!lastAction) return;
+
+    const actionType = lastAction.type;
+
+    if (actionType === 'run_forensics' && obs.host_forensics) {
+      const f = obs.host_forensics;
+      this.updateNode(f.hostname, {
+        status: f.is_compromised ? 'compromised' : 'online',
+        forensicsRun: true,
+        maliciousProcs: f.malicious_processes,
+      });
+
+      (f.malicious_processes || []).forEach(proc => {
+        const procId = `${f.hostname}:${proc}`;
+        this.addNode({
+          id: procId,
+          nodeType: 'process',
+          label: proc,
+          hostname: f.hostname,
+          processName: proc,
+          killed: false,
+        });
+        this.addLink(procId, f.hostname, 'runs_on');
+      });
+
+      (f.network_connections || []).forEach(conn => {
+        const ip = conn.split(':')[0];
+        if (!this.nodes.has(ip)) {
+          this.addNode({ id: ip, nodeType: 'ioc', label: ip, iocType: 'ip', blocked: false, enriched: false });
+        }
+        this.addLink(f.hostname, ip, 'communicates_with');
+      });
+    }
+
+    if (actionType === 'query_host') {
+      const hn = lastAction.hostname;
+      const subnet = this._subnetFromHostname(hn);
+      const existing = this.nodes.get(hn);
+      if (existing) {
+        this.updateNode(hn, {
+          status: existing.status === 'compromised' ? 'compromised' : 'queried',
+          subnet: existing.subnet || subnet,
+        });
+      } else {
+        this.addNode({ id: hn, nodeType: 'host', label: hn, status: 'queried', subnet });
+      }
+    }
+
+    if (actionType === 'enrich_ioc') {
+      const iocVal = lastAction.ioc_value;
+      if (!this.nodes.has(iocVal)) {
+        this.addNode({
+          id: iocVal,
+          nodeType: 'ioc',
+          label: iocVal.length > 22 ? iocVal.substring(0, 20) + '…' : iocVal,
+          fullLabel: iocVal,
+          iocType: lastAction.ioc_type || this._guessIocType(iocVal),
+          blocked: false,
+          enriched: false,
+        });
+      }
+      if (obs.ioc_enrichment) {
+        this.updateNode(iocVal, {
+          enriched: true,
+          threatActor: obs.ioc_enrichment.threat_actor,
+          mitreTTPs: obs.ioc_enrichment.mitre_ttps || [],
+          reputation: obs.ioc_enrichment.reputation,
+        });
+      }
+    }
+
+    if (actionType === 'block_ioc') {
+      this.updateNode(lastAction.ioc_value, { blocked: true });
+    }
+
+    if (actionType === 'kill_process') {
+      const procId = `${lastAction.hostname}:${lastAction.process_name}`;
+      this.updateNode(procId, { killed: true });
+      // Also add process node if not seen before
+      if (!this.nodes.has(procId)) {
+        this.addNode({
+          id: procId, nodeType: 'process', label: lastAction.process_name,
+          hostname: lastAction.hostname, killed: true,
+        });
+      }
+    }
+
+    if (actionType === 'isolate_segment') {
+      const subnet = lastAction.subnet;
+      this.nodes.forEach((node, id) => {
+        if (node.nodeType === 'host' && node.subnet === subnet) {
+          this.updateNode(id, { status: 'isolated' });
+        }
+      });
+    }
+
+    if (actionType === 'scan_host_vulnerabilities' && obs.vulnerability_results) {
+      (obs.vulnerability_results || []).forEach(vuln => {
+        const vid = vuln.cve_id || 'CVE-UNKNOWN';
+        this.addNode({
+          id: vid, nodeType: 'vulnerability', label: vid,
+          cvssScore: vuln.cvss_score, exploitability: vuln.exploitability,
+          hostname: lastAction.hostname,
+        });
+        this.addLink(vid, lastAction.hostname, 'exploits');
+      });
+    }
+
+    if (actionType === 'correlate_alerts' && obs.correlation_results) {
+      const aids = lastAction.alert_ids || [];
+      for (let i = 0; i < aids.length - 1; i++) {
+        this.addLink(aids[i], aids[i + 1], 'part_of_chain');
+      }
+      // Mark alerts as correlated
+      aids.forEach(id => this.updateNode(id, { correlated: true }));
+    }
+  }
+
+  _guessIocType(ioc) {
+    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(ioc)) return 'ip';
+    if (/[a-f0-9]{32,64}/i.test(ioc)) return 'hash';
+    return 'domain';
+  }
+
+  _subnetFromHostname(hostname) {
+    if (!hostname) return null;
+    const prefix = hostname.split('-')[0].toUpperCase();
+    const map = { WS: 'corporate', DEV: 'engineering', FIN: 'finance', DMZ: 'dmz', SRV: 'datacenter', EXEC: 'executive' };
+    return map[prefix] || null;
+  }
+
+  // Detect new pivot alerts (PIVOT-xxx)
+  getNewPivotAlerts(prevAlertIds) {
+    const pivots = [];
+    this.nodes.forEach((node, id) => {
+      if (node.nodeType === 'alert' && node.isPivot && !prevAlertIds.has(id)) {
+        pivots.push(node);
+      }
+    });
+    return pivots;
+  }
+}
+
+
+// ============================================================
+// D3.js Force-Directed Threat Graph Visualization
+// ============================================================
+class ThreatGraphViz {
+  constructor(containerId) {
+    this.containerId = containerId;
+    this.svg = null;
+    this.simulation = null;
+    this.graphGroup = null;
+    this.linkGroup = null;
+    this.nodeGroup = null;
+    this.labelGroup = null;
+    this.tooltip = null;
+    this.width = 0;
+    this.height = 0;
+    this._pivotTimers = [];
+    this._nodeData = [];
+    this._linkData = [];
+    this._initialized = false;
+  }
+
+  init() {
+    const container = document.getElementById(this.containerId);
+    if (!container) return;
+    const svg = d3.select('#threat-graph-svg');
+    const rect = container.getBoundingClientRect();
+    this.width = rect.width || 600;
+    this.height = rect.height || 400;
+
+    svg.attr('width', this.width).attr('height', this.height);
+
+    // Add SVG filters for glow effects
+    const defs = svg.append('defs');
+    this._addGlowFilters(defs);
+
+    // Background
+    svg.append('rect')
+      .attr('width', this.width).attr('height', this.height)
+      .attr('fill', 'transparent');
+
+    // Zoom behavior
+    const zoom = d3.zoom()
+      .scaleExtent([0.2, 4])
+      .on('zoom', (event) => {
+        this.graphGroup.attr('transform', event.transform);
+      });
+    svg.call(zoom);
+
+    // Main group
+    this.graphGroup = svg.append('g').attr('class', 'graph-group');
+    this.linkGroup = this.graphGroup.append('g').attr('class', 'links');
+    this.nodeGroup = this.graphGroup.append('g').attr('class', 'nodes');
+    this.labelGroup = this.graphGroup.append('g').attr('class', 'labels');
+
+    // Tooltip
+    this.tooltip = d3.select('#graph-tooltip');
+
+    // Force simulation
+    this.simulation = d3.forceSimulation()
+      .force('link', d3.forceLink().id(d => d.id).distance(d => {
+        if (d.edgeType === 'pivoted_from') return 120;
+        if (d.edgeType === 'runs_on') return 50;
+        return 80;
+      }).strength(0.7))
+      .force('charge', d3.forceManyBody().strength(-180).distanceMax(300))
+      .force('center', d3.forceCenter(this.width / 2, this.height / 2))
+      .force('collision', d3.forceCollide().radius(d => this._nodeRadius(d) + 8))
+      .force('x', d3.forceX(this.width / 2).strength(0.04))
+      .force('y', d3.forceY(this.height / 2).strength(0.04));
+
+    this._initialized = true;
+  }
+
+  _addGlowFilters(defs) {
+    const glows = [
+      { id: 'glow-red', color: '#ef4444', stdDev: 4 },
+      { id: 'glow-blue', color: '#3b82f6', stdDev: 3 },
+      { id: 'glow-green', color: '#10b981', stdDev: 3 },
+      { id: 'glow-amber', color: '#f59e0b', stdDev: 3 },
+      { id: 'glow-purple', color: '#8b5cf6', stdDev: 3 },
+      { id: 'glow-cyan', color: '#06b6d4', stdDev: 3 },
+    ];
+    glows.forEach(g => {
+      const filter = defs.append('filter').attr('id', g.id);
+      filter.append('feGaussianBlur').attr('in', 'SourceGraphic').attr('stdDeviation', g.stdDev).attr('result', 'blur');
+      const merge = filter.append('feMerge');
+      merge.append('feMergeNode').attr('in', 'blur');
+      merge.append('feMergeNode').attr('in', 'SourceGraphic');
+    });
+
+    // Arrowhead markers for directed edges
+    const arrows = [
+      { id: 'arrow-default',    color: 'rgba(148,163,184,0.6)' },
+      { id: 'arrow-pivot',      color: '#ef4444' },
+      { id: 'arrow-c2',         color: 'rgba(245,158,11,0.7)' },
+      { id: 'arrow-exploit',    color: 'rgba(239,68,68,0.7)' },
+      { id: 'arrow-chain',      color: 'rgba(139,92,246,0.7)' },
+    ];
+    arrows.forEach(a => {
+      defs.append('marker')
+        .attr('id', a.id)
+        .attr('viewBox', '0 -5 10 10')
+        .attr('refX', 14)
+        .attr('refY', 0)
+        .attr('markerWidth', 5)
+        .attr('markerHeight', 5)
+        .attr('orient', 'auto')
+        .append('path')
+        .attr('d', 'M0,-5L10,0L0,5')
+        .attr('fill', a.color);
+    });
+  }
+
+  _edgeMarker(edgeType) {
+    if (edgeType === 'pivoted_from') return 'url(#arrow-pivot)';
+    if (edgeType === 'communicates_with') return 'url(#arrow-c2)';
+    if (edgeType === 'exploits') return 'url(#arrow-exploit)';
+    if (edgeType === 'part_of_chain') return 'url(#arrow-chain)';
+    if (edgeType === 'runs_on') return 'url(#arrow-default)';
+    return null;
+  }
+
+  update(graphData) {
+    if (!this._initialized) return;
+
+    const nodes = graphData.nodes;
+    const links = graphData.links.map(l => ({
+      ...l,
+      source: l.source.id || l.source,
+      target: l.target.id || l.target,
+    }));
+
+    this._nodeData = nodes;
+    this._linkData = links;
+
+    // Update links (curved quadratic bezier paths)
+    const linkSel = this.linkGroup.selectAll('.graph-link')
+      .data(links, d => d.id);
+
+    const linkEnter = linkSel.enter().append('path')
+      .attr('class', d => `graph-link ${d.edgeType}`)
+      .attr('fill', 'none')
+      .attr('marker-end', d => this._edgeMarker(d.edgeType))
+      .attr('stroke-opacity', 0)
+      .transition().duration(600)
+      .attr('stroke-opacity', d => d.edgeType === 'pivoted_from' ? 0.9 : 0.6);
+
+    linkSel
+      .attr('class', d => `graph-link ${d.edgeType}`)
+      .attr('marker-end', d => this._edgeMarker(d.edgeType));
+    linkSel.exit().transition().duration(300).attr('stroke-opacity', 0).remove();
+
+    // Update nodes
+    const nodeSel = this.nodeGroup.selectAll('.graph-node')
+      .data(nodes, d => d.id);
+
+    const nodeEnter = nodeSel.enter().append('path')
+      .attr('class', 'graph-node')
+      .attr('d', d => this._nodeSymbol(d))
+      .attr('transform', d => `translate(${this.width / 2},${this.height / 2}) scale(0)`)
+      .attr('fill', d => this._nodeColor(d))
+      .attr('stroke', d => this._nodeStroke(d))
+      .attr('stroke-width', d => d.nodeType === 'host' ? 2 : 1.5)
+      .attr('filter', d => this._nodeFilter(d))
+      .attr('cursor', 'pointer')
+      .on('mouseover', (event, d) => this._showTooltip(event, d))
+      .on('mouseout', () => this._hideTooltip())
+      .on('click', (event, d) => this._highlightNode(d));
+
+    nodeEnter.transition().duration(500).ease(d3.easeBounceOut)
+      .attr('transform', d => `translate(${d.x || this.width/2},${d.y || this.height/2}) scale(1)`);
+
+    nodeSel.transition().duration(300)
+      .attr('fill', d => this._nodeColor(d))
+      .attr('stroke', d => this._nodeStroke(d))
+      .attr('filter', d => this._nodeFilter(d));
+
+    nodeSel.exit().transition().duration(300)
+      .attr('transform', d => `translate(${d.x},${d.y}) scale(0)`)
+      .remove();
+
+    // Update labels
+    const labelSel = this.labelGroup.selectAll('.node-label')
+      .data(nodes.filter(d => d.nodeType === 'host' || d.nodeType === 'vulnerability'), d => d.id);
+
+    const labelEnter = labelSel.enter().append('text')
+      .attr('class', 'node-label')
+      .attr('text-anchor', 'middle')
+      .attr('dy', d => this._nodeRadius(d) + 12)
+      .attr('opacity', 0)
+      .text(d => d.label);
+
+    labelEnter.transition().duration(500).attr('opacity', 0.7);
+    labelSel.text(d => d.label);
+    labelSel.exit().remove();
+
+    // Drag behavior
+    const drag = d3.drag()
+      .on('start', (event, d) => {
+        if (!event.active) this.simulation.alphaTarget(0.3).restart();
+        d.fx = d.x; d.fy = d.y;
+      })
+      .on('drag', (event, d) => { d.fx = event.x; d.fy = event.y; })
+      .on('end', (event, d) => {
+        if (!event.active) this.simulation.alphaTarget(0);
+        d.fx = null; d.fy = null;
+      });
+
+    this.nodeGroup.selectAll('.graph-node').call(drag);
+
+    // Restart simulation
+    this.simulation.nodes(nodes).on('tick', () => this._tick());
+    this.simulation.force('link').links(links);
+    this.simulation.alpha(0.5).restart();
+  }
+
+  _tick() {
+    this.linkGroup.selectAll('.graph-link')
+      .attr('d', d => {
+        const sx = d.source.x || 0, sy = d.source.y || 0;
+        const tx = d.target.x || 0, ty = d.target.y || 0;
+        const dx = tx - sx, dy = ty - sy;
+        const len = Math.sqrt(dx * dx + dy * dy) || 1;
+        // Perpendicular offset — bigger curve for pivot edges
+        const offset = d.edgeType === 'pivoted_from' ? 50 : (d.edgeType === 'part_of_chain' ? 8 : 20);
+        const cx = (sx + tx) / 2 - (dy / len) * offset;
+        const cy = (sy + ty) / 2 + (dx / len) * offset;
+        return `M${sx},${sy} Q${cx},${cy} ${tx},${ty}`;
+      });
+
+    this.nodeGroup.selectAll('.graph-node')
+      .attr('transform', d => `translate(${d.x || 0},${d.y || 0})`);
+
+    this.labelGroup.selectAll('.node-label')
+      .attr('x', d => d.x || 0)
+      .attr('y', d => d.y || 0);
+  }
+
+  _nodeRadius(d) {
+    if (d.nodeType === 'host') return 12;
+    if (d.nodeType === 'process') return 7;
+    if (d.nodeType === 'alert') return 9;
+    if (d.nodeType === 'vulnerability') return 8;
+    return 8; // ioc
+  }
+
+  _nodeSymbol(d) {
+    const size = this._nodeRadius(d) * this._nodeRadius(d) * Math.PI;
+    if (d.nodeType === 'host') return d3.symbol().type(d3.symbolCircle).size(size * 1.2)();
+    if (d.nodeType === 'process') return d3.symbol().type(d3.symbolDiamond).size(size)();
+    if (d.nodeType === 'alert') return d3.symbol().type(d3.symbolTriangle).size(size)();
+    if (d.nodeType === 'vulnerability') return d3.symbol().type(d3.symbolSquare).size(size)();
+    // IOC = hexagon-like using wye
+    return d3.symbol().type(d3.symbolWye).size(size)();
+  }
+
+  _nodeColor(d) {
+    if (d.nodeType === 'host') {
+      if (d.status === 'compromised') return '#ef4444';
+      if (d.status === 'isolated') return '#6b7280';
+      if (d.status === 'queried') return '#06b6d4';
+      return '#3b82f6';
+    }
+    if (d.nodeType === 'process') {
+      return d.killed ? '#6b7280' : '#f59e0b';
+    }
+    if (d.nodeType === 'ioc') {
+      if (d.blocked) return 'transparent';
+      if (d.enriched) return '#8b5cf6';
+      return '#ef4444';
+    }
+    if (d.nodeType === 'alert') {
+      const colors = { critical: '#ef4444', high: '#f97316', medium: '#f59e0b', low: '#10b981' };
+      return d.isPivot ? '#ef4444' : (colors[d.severity] || '#94a3b8');
+    }
+    if (d.nodeType === 'vulnerability') return 'transparent';
+    return '#94a3b8';
+  }
+
+  _nodeStroke(d) {
+    if (d.nodeType === 'ioc') {
+      if (d.blocked) return '#10b981';
+      if (d.enriched) return '#8b5cf6';
+      return '#ef4444';
+    }
+    if (d.nodeType === 'vulnerability') return '#10b981';
+    if (d.nodeType === 'host' && d.status === 'compromised') return '#fca5a5';
+    if (d.nodeType === 'host' && d.status === 'isolated') return '#f59e0b';
+    return 'transparent';
+  }
+
+  _nodeFilter(d) {
+    if (d.nodeType === 'host' && d.status === 'compromised') return 'url(#glow-red)';
+    if (d.nodeType === 'host' && d.status === 'queried') return 'url(#glow-cyan)';
+    if (d.nodeType === 'ioc' && d.enriched) return 'url(#glow-purple)';
+    if (d.nodeType === 'ioc' && d.blocked) return 'url(#glow-green)';
+    if (d.nodeType === 'alert' && d.isPivot) return 'url(#glow-red)';
+    if (d.nodeType === 'alert' && d.severity === 'critical') return 'url(#glow-amber)';
+    if (d.nodeType === 'process' && !d.killed) return 'url(#glow-amber)';
+    return null;
+  }
+
+  _showTooltip(event, d) {
+    const tt = this.tooltip;
+    if (!tt) return;
+    let html = `<div class="graph-tooltip-title">${d.label || d.id}</div>`;
+    html += `<div class="graph-tooltip-row"><span class="graph-tooltip-key">Type:</span><span class="graph-tooltip-value">${d.nodeType}</span></div>`;
+
+    if (d.nodeType === 'host') {
+      html += `<div class="graph-tooltip-row"><span class="graph-tooltip-key">Status:</span><span class="graph-tooltip-value">${d.status || 'online'}</span></div>`;
+      html += `<div class="graph-tooltip-row"><span class="graph-tooltip-key">Subnet:</span><span class="graph-tooltip-value">${d.subnet || '—'}</span></div>`;
+    } else if (d.nodeType === 'ioc') {
+      html += `<div class="graph-tooltip-row"><span class="graph-tooltip-key">IOC Type:</span><span class="graph-tooltip-value">${d.iocType || '—'}</span></div>`;
+      html += `<div class="graph-tooltip-row"><span class="graph-tooltip-key">Blocked:</span><span class="graph-tooltip-value">${d.blocked ? '✅' : '❌'}</span></div>`;
+      html += `<div class="graph-tooltip-row"><span class="graph-tooltip-key">Enriched:</span><span class="graph-tooltip-value">${d.enriched ? '✅' : '❌'}</span></div>`;
+      if (d.threatActor) html += `<div class="graph-tooltip-row"><span class="graph-tooltip-key">Actor:</span><span class="graph-tooltip-value">${d.threatActor}</span></div>`;
+    } else if (d.nodeType === 'process') {
+      html += `<div class="graph-tooltip-row"><span class="graph-tooltip-key">Host:</span><span class="graph-tooltip-value">${d.hostname || '—'}</span></div>`;
+      html += `<div class="graph-tooltip-row"><span class="graph-tooltip-key">Status:</span><span class="graph-tooltip-value">${d.killed ? '💀 Killed' : '⚠️ Running'}</span></div>`;
+    } else if (d.nodeType === 'alert') {
+      html += `<div class="graph-tooltip-row"><span class="graph-tooltip-key">Severity:</span><span class="graph-tooltip-value">${d.severity}</span></div>`;
+      html += `<div class="graph-tooltip-row"><span class="graph-tooltip-key">Host:</span><span class="graph-tooltip-value">${d.sourceHost || '—'}</span></div>`;
+      if (d.isPivot) html += `<div style="color:#ef4444;margin-top:4px;font-size:10px;">⚡ LATERAL PIVOT</div>`;
+    } else if (d.nodeType === 'vulnerability') {
+      html += `<div class="graph-tooltip-row"><span class="graph-tooltip-key">CVSS:</span><span class="graph-tooltip-value">${d.cvssScore}</span></div>`;
+      html += `<div class="graph-tooltip-row"><span class="graph-tooltip-key">Exploitability:</span><span class="graph-tooltip-value">${d.exploitability}</span></div>`;
+    }
+
+    tt.classed('hidden', false)
+      .style('left', (event.offsetX + 12) + 'px')
+      .style('top', (event.offsetY - 10) + 'px')
+      .html(html);
+  }
+
+  _hideTooltip() {
+    if (this.tooltip) this.tooltip.classed('hidden', true);
+  }
+
+  _highlightNode(d) {
+    // Dim all, highlight connected nodes
+    const connectedIds = new Set([d.id]);
+    this._linkData.forEach(l => {
+      const src = l.source.id || l.source;
+      const tgt = l.target.id || l.target;
+      if (src === d.id || tgt === d.id) {
+        connectedIds.add(src); connectedIds.add(tgt);
+      }
+    });
+
+    this.nodeGroup.selectAll('.graph-node')
+      .attr('opacity', n => connectedIds.has(n.id) ? 1 : 0.2);
+    this.linkGroup.selectAll('.graph-link')
+      .attr('opacity', l => {
+        const src = l.source.id || l.source;
+        const tgt = l.target.id || l.target;
+        return (src === d.id || tgt === d.id) ? 1 : 0.1;
+      });
+
+    // Reset after 3s
+    setTimeout(() => {
+      this.nodeGroup.selectAll('.graph-node').attr('opacity', 1);
+      this.linkGroup.selectAll('.graph-link').attr('opacity', l =>
+        l.edgeType === 'pivoted_from' ? 0.9 : 0.6
+      );
+    }, 3000);
+  }
+
+  // Animate a pivot edge with traveling dot
+  animatePivot(sourceId, targetId) {
+    const pivotLink = this._linkData.find(l => {
+      const s = l.source.id || l.source;
+      const t = l.target.id || l.target;
+      return l.edgeType === 'pivoted_from' && ((s === sourceId && t === targetId) || (s === targetId && t === sourceId));
+    });
+    if (!pivotLink) return;
+
+    const dot = this.graphGroup.append('circle')
+      .attr('r', 5)
+      .attr('fill', '#ef4444')
+      .attr('filter', 'url(#glow-red)')
+      .attr('opacity', 0);
+
+    let elapsed = 0;
+    const duration = 1500;
+    const cycles = 5;
+    const total = duration * cycles;
+
+    const timer = d3.timer(t => {
+      elapsed = t;
+      const progress = (t % duration) / duration;
+      const src = pivotLink.source;
+      const tgt = pivotLink.target;
+      if (!src || !tgt) { timer.stop(); dot.remove(); return; }
+      const sx = src.x || 0, sy = src.y || 0;
+      const tx = tgt.x || 0, ty = tgt.y || 0;
+      const x = sx + (tx - sx) * progress;
+      const y = sy + (ty - sy) * progress;
+      dot.attr('cx', x).attr('cy', y).attr('opacity', Math.sin(progress * Math.PI) * 0.9 + 0.1);
+      if (t > total) { timer.stop(); dot.remove(); }
+    });
+
+    this._pivotTimers.push(timer);
+  }
+
+  // Flash a specific node
+  flashNode(nodeId, color = 'red') {
+    const filterMap = { red: 'glow-red', blue: 'glow-blue', green: 'glow-green' };
+    const filter = `url(#${filterMap[color] || 'glow-red'})`;
+    const node = this.nodeGroup.selectAll('.graph-node').filter(d => d.id === nodeId);
+    if (node.empty()) return;
+    node.transition().duration(200).attr('filter', filter)
+      .transition().duration(200).attr('filter', null)
+      .transition().duration(200).attr('filter', filter)
+      .transition().duration(200).attr('filter', null)
+      .transition().duration(200).attr('filter', filter)
+      .transition().duration(500).attr('filter', d => this._nodeFilter(d));
+  }
+}
+
+
+// ============================================================
+// Chart.js — 10-Dimensional Score Radar
+// ============================================================
+class RadarChart {
+  constructor(canvasId) {
+    this.canvasId = canvasId;
+    this.chart = null;
+    this.scores = {
+      threat_containment: 0, ioc_blocking: 0, forensic_investigation: 0,
+      siem_correlation: 0, threat_intel_usage: 0, vuln_root_cause: 0,
+      business_impact: 0, step_efficiency: 0, plan_coverage: 0, plan_evidence_quality: 0,
+    };
+  }
+
+  init() {
+    const canvas = document.getElementById(this.canvasId);
+    if (!canvas || !window.Chart) return;
+    const ctx = canvas.getContext('2d');
+
+    this.chart = new Chart(ctx, {
+      type: 'radar',
+      data: {
+        labels: [
+          'Threat\nContainment',
+          'IOC\nBlocking',
+          'Forensic\nInvest.',
+          'SIEM\nCorrelation',
+          'Threat\nIntel',
+          'Vuln\nRoot Cause',
+          'Business\nImpact',
+          'Step\nEfficiency',
+          'Plan\nCoverage',
+          'Plan\nEvidence',
+        ],
+        datasets: [{
+          data: Object.values(this.scores),
+          backgroundColor: 'rgba(6,182,212,0.15)',
+          borderColor: '#06b6d4',
+          borderWidth: 2,
+          pointBackgroundColor: '#3b82f6',
+          pointBorderColor: '#06b6d4',
+          pointBorderWidth: 1,
+          pointRadius: 3,
+          pointHoverRadius: 5,
+        }],
+      },
+      options: {
+        responsive: true,
+        maintainAspectRatio: false,
+        animation: { duration: 600, easing: 'easeInOutQuart' },
+        scales: {
+          r: {
+            beginAtZero: true,
+            min: 0,
+            max: 1,
+            ticks: {
+              count: 5,
+              color: '#4b5563',
+              font: { family: 'JetBrains Mono', size: 9 },
+              backdropColor: 'transparent',
+              stepSize: 0.25,
+            },
+            grid: { color: 'rgba(42,48,64,0.8)', circular: false },
+            angleLines: { color: 'rgba(42,48,64,0.6)' },
+            pointLabels: {
+              color: '#94a3b8',
+              font: { family: 'Inter', size: 9, weight: '500' },
+            },
+          },
+        },
+        plugins: {
+          legend: { display: false },
+          tooltip: {
+            backgroundColor: '#1a1f2e',
+            borderColor: '#2a3040',
+            borderWidth: 1,
+            titleColor: '#06b6d4',
+            bodyColor: '#94a3b8',
+            titleFont: { family: 'JetBrains Mono', size: 11 },
+            bodyFont: { family: 'JetBrains Mono', size: 10 },
+            callbacks: {
+              label: (ctx) => ` ${ctx.raw.toFixed(3)}`,
+            },
+          },
+        },
+      },
+    });
+  }
+
+  update(breakdown) {
+    if (!this.chart || !breakdown) return;
+    const order = [
+      'threat_containment', 'ioc_blocking', 'forensic_investigation',
+      'siem_correlation', 'threat_intel_usage', 'vuln_root_cause',
+      'business_impact', 'step_efficiency', 'plan_coverage', 'plan_evidence_quality',
+    ];
+    this.chart.data.datasets[0].data = order.map(k => breakdown[k] ?? 0);
+    this.chart.update('active');
+  }
+
+  // Incrementally update a single dimension (for live updates during episode)
+  updateDimension(key, value) {
+    const order = [
+      'threat_containment', 'ioc_blocking', 'forensic_investigation',
+      'siem_correlation', 'threat_intel_usage', 'vuln_root_cause',
+      'business_impact', 'step_efficiency', 'plan_coverage', 'plan_evidence_quality',
+    ];
+    const idx = order.indexOf(key);
+    if (idx < 0 || !this.chart) return;
+    this.chart.data.datasets[0].data[idx] = value;
+    this.chart.update('none');
+  }
+}
+
+
+// ============================================================
+// Chart.js — Cumulative Reward Timeline
+// ============================================================
+class RewardTimeline {
+  constructor(canvasId) {
+    this.canvasId = canvasId;
+    this.chart = null;
+  }
+
+  init() {
+    const canvas = document.getElementById(this.canvasId);
+    if (!canvas || !window.Chart) return;
+    const ctx = canvas.getContext('2d');
+
+    // Gradient fill
+    const gradient = ctx.createLinearGradient(0, 0, 0, 100);
+    gradient.addColorStop(0, 'rgba(16,185,129,0.3)');
+    gradient.addColorStop(1, 'rgba(16,185,129,0.02)');
+
+    this.chart = new Chart(ctx, {
+      type: 'line',
+      data: {
+        labels: [],
+        datasets: [{
+          data: [],
+          borderColor: '#10b981',
+          backgroundColor: gradient,
+          borderWidth: 2,
+          pointRadius: 3,
+          pointBackgroundColor: ctx => {
+            const v = ctx.raw;
+            return v < 0 ? '#ef4444' : '#10b981';
+          },
+          pointBorderColor: 'transparent',
+          tension: 0.3,
+          fill: true,
+        }],
+      },
+      options: {
+        responsive: true,
+        maintainAspectRatio: false,
+        animation: { duration: 300 },
+        scales: {
+          x: {
+            grid: { color: 'rgba(42,48,64,0.5)' },
+            ticks: { color: '#4b5563', font: { family: 'JetBrains Mono', size: 9 }, maxTicksLimit: 10 },
+            title: { display: true, text: 'Step', color: '#4b5563', font: { size: 9 } },
+          },
+          y: {
+            grid: { color: 'rgba(42,48,64,0.5)' },
+            ticks: { color: '#4b5563', font: { family: 'JetBrains Mono', size: 9 } },
+            title: { display: true, text: 'Reward', color: '#4b5563', font: { size: 9 } },
+          },
+        },
+        plugins: {
+          legend: { display: false },
+          tooltip: {
+            backgroundColor: '#1a1f2e',
+            borderColor: '#2a3040',
+            borderWidth: 1,
+            titleColor: '#06b6d4',
+            bodyColor: '#94a3b8',
+            titleFont: { family: 'JetBrains Mono', size: 10 },
+            bodyFont: { family: 'JetBrains Mono', size: 10 },
+          },
+          annotation: {
+            annotations: {
+              zeroLine: {
+                type: 'line',
+                yMin: 0, yMax: 0,
+                borderColor: 'rgba(148,163,184,0.3)',
+                borderWidth: 1,
+                borderDash: [4, 4],
+              },
+            },
+          },
+        },
+      },
+    });
+  }
+
+  addPoint(step, cumulativeReward, actionType) {
+    if (!this.chart) return;
+    this.chart.data.labels.push(`${step}`);
+    this.chart.data.datasets[0].data.push(parseFloat(cumulativeReward.toFixed(3)));
+    // Color negative points red
+    const colors = this.chart.data.datasets[0].data.map(v => v < 0 ? '#ef4444' : '#10b981');
+    this.chart.data.datasets[0].pointBackgroundColor = colors;
+    this.chart.update('none');
+  }
+
+  reset() {
+    if (!this.chart) return;
+    this.chart.data.labels = [];
+    this.chart.data.datasets[0].data = [];
+    this.chart.update('none');
+  }
+}

dashboard_server.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""
+CyberSOC Dashboard Server
+=========================
+Wraps the existing FastAPI app with:
+  - CORS middleware (required when dashboard is served separately)
+  - Static file serving for the dashboard at /dashboard/
+
+Usage:
+    python dashboard_server.py
+    python dashboard_server.py --port 8000
+
+Then open:  http://localhost:8000/dashboard/
+"""
+
+import argparse
+import os
+import sys
+
+# Ensure MetaRound2 root is on sys.path
+ROOT = os.path.dirname(os.path.abspath(__file__))
+if ROOT not in sys.path:
+    sys.path.insert(0, ROOT)
+
+try:
+    from server.app import app
+except ImportError as e:
+    print(f"[ERROR] Could not import CyberSOCEnv app: {e}")
+    print("Make sure you have the openenv package installed.")
+    sys.exit(1)
+
+from fastapi.middleware.cors import CORSMiddleware
+
+# ── CORS (allow all origins for local demo) ─────────────────────────────────
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ── Static dashboard files at /dashboard/ ───────────────────────────────────
+dashboard_dir = os.path.join(ROOT, "dashboard")
+if os.path.isdir(dashboard_dir):
+    try:
+        from fastapi.staticfiles import StaticFiles
+        app.mount("/dashboard", StaticFiles(directory=dashboard_dir, html=True), name="dashboard")
+        _STATIC_OK = True
+    except ImportError:
+        _STATIC_OK = False
+        print("[WARN] aiofiles not installed — static file serving disabled.")
+        print("       Install with: pip install aiofiles")
+else:
+    _STATIC_OK = False
+    print(f"[WARN] Dashboard directory not found: {dashboard_dir}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="CyberSOC Dashboard Server")
+    parser.add_argument("--host", default="0.0.0.0")
+    parser.add_argument("--port", type=int, default=8000)
+    parser.add_argument("--reload", action="store_true")
+    args = parser.parse_args()
+
+    try:
+        import uvicorn
+    except ImportError:
+        print("[ERROR] uvicorn not installed. Run: pip install uvicorn")
+        sys.exit(1)
+
+    print()
+    print("╔══════════════════════════════════════════════╗")
+    print("║   🛡️  CyberSOC Command Center                ║")
+    print("╠══════════════════════════════════════════════╣")
+    print(f"║   API Server : http://localhost:{args.port:<5}        ║")
+    if _STATIC_OK:
+        print(f"║   Dashboard  : http://localhost:{args.port}/dashboard/ ║")
+    else:
+        print("║   Dashboard  : open dashboard/index.html    ║")
+    print("╚══════════════════════════════════════════════╝")
+    print()
+
+    uvicorn.run(
+        app,
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+    )
+
+
+if __name__ == "__main__":
+    main()

inference.py

@@ -0,0 +1,322 @@
+#!/usr/bin/env python3
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+CyberSOCEnv Baseline Inference Script.
+
+HACKATHON RULES:
+  - File must be named inference.py in the project root
+  - Must use OpenAI Client for all LLM calls
+  - Must emit structured stdout logs: [START], [STEP], [END]
+  - Runtime < 20 minutes
+  - Must work on vcpu=2, memory=8gb
+
+Environment Variables:
+    API_BASE_URL  - The API endpoint for the LLM
+    MODEL_NAME    - The model identifier to use for inference
+    HF_TOKEN      - Your Hugging Face / API key
+"""
+
+import asyncio
+import json
+import os
+import textwrap
+from typing import Any, Dict, List, Optional
+
+from openai import OpenAI
+
+from models import SOCActionWrapper, SOCObservation
+from server.play_environment import CyberSOCEnvironment
+
+# =============================================================================
+# Configuration (from environment variables)
+# =============================================================================
+
+API_BASE_URL = os.getenv("API_BASE_URL", "https://router.huggingface.co/v1")
+MODEL_NAME = os.getenv("MODEL_NAME", "Qwen/Qwen2.5-72B-Instruct")
+HF_TOKEN = os.getenv("HF_TOKEN")
+
+BENCHMARK = "cybersocenv"
+TASKS = ["easy", "medium", "hard"]
+MAX_STEPS = {"easy": 15, "medium": 25, "hard": 30}
+TEMPERATURE = 0.1
+MAX_TOKENS = 1024
+
+# Scoring: normalize rewards to [0, 1]
+MAX_POSSIBLE_REWARD = 2.0  # Approximate max reward per episode
+SUCCESS_SCORE_THRESHOLD = 0.3
+
+# =============================================================================
+# System Prompt
+# =============================================================================
+
+SYSTEM_PROMPT = textwrap.dedent("""
+    You are an expert Cybersecurity SOC (Security Operations Center) Analyst AI.
+    You are responding to security incidents on a 500-node enterprise network.
+
+    Your goal: Investigate alerts, contain all threats, and submit a containment plan — while minimizing business downtime.
+
+    Available Actions (respond with exactly ONE JSON object per turn):
+
+    1. Query a host: {"type": "query_host", "hostname": "<HOST>"}
+    2. Isolate a segment (causes downtime): {"type": "isolate_segment", "subnet": "<SUBNET>", "reason": "<WHY>"}
+    3. Block an IOC: {"type": "block_ioc", "ioc_value": "<VALUE>", "ioc_type": "ip|domain|hash"}
+    4. Run forensics: {"type": "run_forensics", "hostname": "<HOST>"}
+    5. Kill a process: {"type": "kill_process", "hostname": "<HOST>", "process_name": "<PROC>"}
+    6. Submit containment plan (ends episode): {"type": "submit_containment_plan", "plan": [{"threat_id": "<ID>", "actions_taken": [...], "root_cause": "<CAUSE>", "confidence": 0.0-1.0}], "executive_summary": "<SUMMARY>"}
+
+    Rules:
+    - Respond with ONLY a valid JSON object. No markdown, no explanation.
+    - Investigate before acting. Query hosts and run forensics to gather evidence.
+    - Block IOCs (IPs, domains, hashes) found in alerts and forensics.
+    - Kill malicious processes found via forensics.
+    - Avoid unnecessary subnet isolation — it increases business impact.
+    - Submit the containment plan once you've contained all threats.
+    - You have a limited number of steps. Be efficient.
+""").strip()
+
+
+# =============================================================================
+# Logging Helpers (EXACT hackathon format — lowercase booleans, null errors)
+# =============================================================================
+
+def log_start(task: str, env: str, model: str) -> None:
+    print(f"[START] task={task} env={env} model={model}", flush=True)
+
+
+def log_step(step: int, action: str, reward: float, done: bool, error: Optional[str]) -> None:
+    error_val = error if error else "null"
+    done_val = str(done).lower()
+    print(
+        f"[STEP] step={step} action={action} reward={reward:.2f} done={done_val} error={error_val}",
+        flush=True,
+    )
+
+
+def log_end(success: bool, steps: int, score: float, rewards: List[float]) -> None:
+    rewards_str = ",".join(f"{r:.2f}" for r in rewards)
+    print(
+        f"[END] success={str(success).lower()} steps={steps} score={score:.3f} rewards={rewards_str}",
+        flush=True,
+    )
+
+
+# =============================================================================
+# Observation Formatting for LLM
+# =============================================================================
+
+def format_observation(obs: SOCObservation) -> str:
+    """Format observation into readable text for the LLM."""
+    parts = []
+
+    # Alert queue
+    if obs.alert_queue:
+        parts.append(f"## Active Alerts ({len(obs.alert_queue)}):")
+        for a in obs.alert_queue:
+            parts.append(
+                f"  - [{a.severity.value.upper()}] {a.alert_id} "
+                f"on {a.source_host} ({a.subnet}): {a.description}"
+            )
+            if a.ioc_indicators:
+                parts.append(f"    IOCs: {', '.join(a.ioc_indicators)}")
+
+    # Network topology
+    topo = obs.network_topology
+    parts.append(f"\n## Network Status:")
+    parts.append(f"  Compromised: {topo.compromised_count} | "
+                 f"Isolated: {topo.isolated_count} | "
+                 f"Online: {topo.online_count}")
+
+    # Forensics
+    if obs.host_forensics:
+        f = obs.host_forensics
+        parts.append(f"\n## Forensics Result ({f.hostname}):")
+        parts.append(f"  Compromised: {f.is_compromised}")
+        parts.append(f"  Malicious processes: {f.malicious_processes}")
+        parts.append(f"  Suspicious files: {f.suspicious_files}")
+        parts.append(f"  Network connections: {f.network_connections}")
+        parts.append(f"  Memory artifacts: {f.memory_artifacts}")
+
+    # Active threats
+    parts.append(f"\n## Active Threats: {obs.active_threats if obs.active_threats else 'None (all contained!)'}")
+    parts.append(f"## Business Impact: {obs.business_impact_score:.2f}")
+    parts.append(f"## Step: {obs.step_count} / {obs.max_steps}")
+
+    # Timeline (last 5)
+    if obs.timeline:
+        parts.append(f"\n## Recent Actions:")
+        for t in obs.timeline[-5:]:
+            parts.append(f"  Step {t.step}: {t.action_type} -> {t.target} (reward={t.reward:.2f})")
+
+    return "\n".join(parts)
+
+
+def parse_llm_action(content: str) -> Dict[str, Any]:
+    """Parse the LLM's response into a valid action dict."""
+    content = content.strip()
+    if content.startswith("```"):
+        lines = content.split("\n")
+        lines = [l for l in lines if not l.strip().startswith("```")]
+        content = "\n".join(lines).strip()
+
+    try:
+        action = json.loads(content)
+        if isinstance(action, dict) and "type" in action:
+            return action
+    except json.JSONDecodeError:
+        pass
+
+    # Try to find JSON in the response
+    for start in range(len(content)):
+        if content[start] == "{":
+            for end in range(len(content), start, -1):
+                if content[end - 1] == "}":
+                    try:
+                        action = json.loads(content[start:end])
+                        if isinstance(action, dict) and "type" in action:
+                            return action
+                    except json.JSONDecodeError:
+                        continue
+
+    raise ValueError(f"Could not parse action from LLM response: {content[:200]}")
+
+
+def get_model_action(
+    client: OpenAI,
+    step: int,
+    obs: SOCObservation,
+    task_id: str,
+    history: List[str],
+) -> str:
+    """Get the next action from the LLM."""
+    obs_text = format_observation(obs)
+
+    if step == 1:
+        user_content = (
+            f"## Incident Briefing (Task: {task_id.upper()})\n\n"
+            f"{obs_text}\n\n"
+            f"Analyze the alerts and begin your investigation. Respond with a single JSON action."
+        )
+    else:
+        user_content = (
+            f"## Observation after your action:\n\n"
+            f"{obs_text}\n\n"
+            f"Continue your investigation. Respond with a single JSON action."
+        )
+
+    try:
+        completion = client.chat.completions.create(
+            model=MODEL_NAME,
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": user_content},
+            ],
+            temperature=TEMPERATURE,
+            max_tokens=MAX_TOKENS,
+            stream=False,
+        )
+        text = (completion.choices[0].message.content or "").strip()
+        return text if text else '{"type": "query_host", "hostname": "WS-001"}'
+    except Exception as exc:
+        if "429" in str(exc) or "RateLimit" in str(exc):
+            raise  # Let the batch runner handle rate limits
+        print(f"[DEBUG] Model request failed: {exc}", flush=True)
+        return '{"type": "query_host", "hostname": "WS-001"}'
+
+
+# =============================================================================
+# Episode Runner
+# =============================================================================
+
+async def run_episode(client: OpenAI, task_id: str) -> tuple:
+    """Run a single episode. Returns (success, steps, score, rewards)."""
+    env = CyberSOCEnvironment()
+    history: List[str] = []
+    rewards: List[float] = []
+    steps_taken = 0
+    score = 0.0
+    success = False
+
+    log_start(task=task_id, env=BENCHMARK, model=MODEL_NAME)
+
+    try:
+        # Reset environment
+        obs = env.reset(task_id=task_id)
+
+        max_steps = MAX_STEPS.get(task_id, 30)
+
+        for step in range(1, max_steps + 1):
+            if obs.done:
+                break
+
+            # Get action from LLM
+            llm_response = get_model_action(client, step, obs, task_id, history)
+
+            # Parse and execute
+            error = None
+            action_str = "unknown"
+            reward = 0.0
+
+            try:
+                action_dict = parse_llm_action(llm_response)
+                action_str = action_dict.get("type", "unknown")
+                action = SOCActionWrapper(**action_dict)
+                obs = env.step(action)
+                reward = obs.reward or 0.0
+                done = obs.done
+            except Exception as exc:
+                error = str(exc)[:200]
+                done = False
+                reward = 0.0
+
+            rewards.append(reward)
+            steps_taken = step
+
+            log_step(step=step, action=action_str, reward=reward, done=done, error=error)
+
+            history.append(f"Step {step}: {action_str} -> reward {reward:+.2f}")
+
+            if done:
+                break
+
+        # Calculate score from final_score if available, else normalize rewards
+        if obs.final_score is not None:
+            score = obs.final_score
+        else:
+            score = sum(rewards) / MAX_POSSIBLE_REWARD if MAX_POSSIBLE_REWARD > 0 else 0.0
+
+        score = min(max(score, 0.0), 1.0)  # clamp to [0, 1]
+        success = score >= SUCCESS_SCORE_THRESHOLD
+
+    finally:
+        log_end(success=success, steps=steps_taken, score=score, rewards=rewards)
+
+    return success, steps_taken, score, rewards
+
+
+# =============================================================================
+# Main
+# =============================================================================
+
+async def main() -> None:
+    """Run baseline inference across all tasks."""
+    client = OpenAI(base_url=API_BASE_URL, api_key=HF_TOKEN)
+
+    total_scores = {}
+    for task_id in TASKS:
+        success, steps, score, rewards = await run_episode(client, task_id)
+        total_scores[task_id] = score
+
+    # Print summary
+    avg = sum(total_scores.values()) / len(total_scores) if total_scores else 0.0
+    print(f"\n# Summary: avg_score={avg:.3f}", flush=True)
+    for tid, s in total_scores.items():
+        print(f"#   {tid}: {s:.3f}", flush=True)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

models.py

@@ -0,0 +1,428 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Data models for the CyberSOCEnv — Enterprise Cybersecurity Operations Center.
+
+Defines strict Pydantic models for:
+- Observation: What the agent sees (alerts, forensics, network state, business impact)
+- Action: What the agent can do (discriminated union of 6 action types)
+- Internal state: Deterministic network graph, attack chains, and task tracking
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated, Any, Dict, List, Literal, Optional, Union
+
+from openenv.core.env_server.types import Action, Observation, State
+from pydantic import BaseModel, ConfigDict, Field
+
+
+# =============================================================================
+# Enums
+# =============================================================================
+
+
+class Severity(str, Enum):
+    """SIEM alert severity levels."""
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class ThreatType(str, Enum):
+    """Classification of threat types in the SOC environment."""
+    RANSOMWARE = "ransomware"
+    PHISHING = "phishing"
+    CREDENTIAL_THEFT = "credential_theft"
+    LATERAL_MOVEMENT = "lateral_movement"
+    C2_COMMUNICATION = "c2_communication"
+    DATA_EXFILTRATION = "data_exfiltration"
+    PRIVILEGE_ESCALATION = "privilege_escalation"
+    MALWARE = "malware"
+    CRYPTOMINING = "cryptomining"
+    SUPPLY_CHAIN = "supply_chain"
+    INSIDER_THREAT = "insider_threat"
+    WEBSHELL = "webshell"
+    BOTNET = "botnet"
+
+
+class HostStatus(str, Enum):
+    """Host operational status."""
+    ONLINE = "online"
+    COMPROMISED = "compromised"
+    ISOLATED = "isolated"
+    OFFLINE = "offline"
+
+
+class SubnetRole(str, Enum):
+    """Business function of a network subnet."""
+    CORPORATE = "corporate"
+    ENGINEERING = "engineering"
+    FINANCE = "finance"
+    DMZ = "dmz"
+    DATACENTER = "datacenter"
+    EXECUTIVE = "executive"
+
+
+# =============================================================================
+# Alert & Network Sub-Models (used in Observation)
+# =============================================================================
+
+
+class Alert(BaseModel):
+    """A single SIEM/EDR alert in the queue."""
+    model_config = ConfigDict(extra="forbid")
+
+    alert_id: str = Field(..., description="Unique alert identifier")
+    timestamp: str = Field(..., description="ISO-8601 timestamp of the alert")
+    source_host: str = Field(..., description="Hostname that generated the alert")
+    severity: Severity = Field(..., description="Alert severity level")
+    threat_type: ThreatType = Field(..., description="Classified threat type")
+    description: str = Field(..., description="Human-readable alert description")
+    ioc_indicators: List[str] = Field(
+        default_factory=list,
+        description="Indicators of compromise (IPs, hashes, domains)",
+    )
+    subnet: str = Field(..., description="Subnet where the alert originated")
+    is_acknowledged: bool = Field(default=False, description="Whether the SOC analyst has acknowledged this alert")
+
+
+class HostInfo(BaseModel):
+    """Summary information about a single network host."""
+    model_config = ConfigDict(extra="forbid")
+
+    hostname: str = Field(..., description="Host FQDN")
+    ip_address: str = Field(..., description="IPv4 address")
+    subnet: str = Field(..., description="Subnet the host belongs to")
+    role: SubnetRole = Field(..., description="Business function")
+    status: HostStatus = Field(default=HostStatus.ONLINE, description="Current status")
+    running_processes: List[str] = Field(default_factory=list, description="Running process names")
+    open_ports: List[int] = Field(default_factory=list, description="Open TCP ports")
+    criticality: float = Field(
+        default=0.5, ge=0.0, le=1.0,
+        description="Business criticality score (0=low, 1=mission-critical)",
+    )
+
+
+class NetworkTopology(BaseModel):
+    """Summarized view of the 500-node enterprise network."""
+    model_config = ConfigDict(extra="forbid")
+
+    total_hosts: int = Field(default=500, description="Total hosts in the network")
+    subnets: Dict[str, int] = Field(
+        default_factory=dict,
+        description="Map of subnet name -> host count",
+    )
+    compromised_count: int = Field(default=0, description="Number of compromised hosts")
+    isolated_count: int = Field(default=0, description="Number of isolated hosts")
+    online_count: int = Field(default=500, description="Number of online hosts")
+
+
+class ForensicsResult(BaseModel):
+    """Results from running forensics on a host."""
+    model_config = ConfigDict(extra="forbid")
+
+    hostname: str = Field(..., description="Analyzed host")
+    malicious_processes: List[str] = Field(default_factory=list, description="Detected malicious processes")
+    suspicious_files: List[str] = Field(default_factory=list, description="Suspicious file paths found")
+    network_connections: List[str] = Field(
+        default_factory=list,
+        description="Suspicious outbound connections (ip:port)",
+    )
+    registry_modifications: List[str] = Field(default_factory=list, description="Modified registry keys")
+    memory_artifacts: List[str] = Field(default_factory=list, description="In-memory IOCs found")
+    is_compromised: bool = Field(default=False, description="Whether forensics confirm compromise")
+
+
+class TimelineEntry(BaseModel):
+    """A single entry in the analyst action timeline."""
+    model_config = ConfigDict(extra="forbid")
+
+    step: int = Field(..., description="Step number when this action was taken")
+    action_type: str = Field(..., description="Type of action taken")
+    target: str = Field(..., description="Target of the action (host, subnet, IOC)")
+    result: str = Field(..., description="Outcome description")
+    reward: float = Field(default=0.0, description="Reward received for this action")
+
+
+# =============================================================================
+# Observation
+# =============================================================================
+
+
+class SOCObservation(Observation):
+    """What the SOC agent sees at each step.
+
+    Extends OpenEnv Observation (inherits: done, reward, metadata).
+    """
+
+    episode_id: str = Field(
+        default="",
+        description="Unique UUID for this episode — used by the RL training loop to prevent hash collisions in GRPO batched rollouts.",
+    )
+    alert_queue: List[Alert] = Field(
+        default_factory=list,
+        description="Current queue of unresolved SIEM/EDR alerts",
+    )
+    network_topology: NetworkTopology = Field(
+        default_factory=NetworkTopology,
+        description="Summary of the enterprise network state",
+    )
+    host_forensics: Optional[ForensicsResult] = Field(
+        default=None,
+        description="Forensics results if RunForensics was the last action, else None",
+    )
+    timeline: List[TimelineEntry] = Field(
+        default_factory=list,
+        description="Chronological log of all actions taken in this episode",
+    )
+    business_impact_score: float = Field(
+        default=0.0, ge=0.0, le=1.0,
+        description="Current business impact (0=no impact, 1=catastrophic outage)",
+    )
+    step_count: int = Field(default=0, ge=0, description="Current step number")
+    active_threats: List[str] = Field(
+        default_factory=list,
+        description="List of threat IDs that are still active/uncontained",
+    )
+    max_steps: int = Field(default=30, description="Maximum steps allowed in this episode")
+    task_id: str = Field(default="easy", description="Current task identifier")
+    total_reward: float = Field(default=0.0, description="Accumulated episode reward")
+    final_score: Optional[float] = Field(
+        default=None,
+        description="Post-episode grader score (0.0-1.0). Only set when done=True and plan submitted.",
+    )
+    grade_breakdown: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Detailed grading breakdown. Only set when done=True and plan submitted.",
+    )
+    correlation_results: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Results from the most recent correlate_alerts call.",
+    )
+    ioc_enrichment: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Results from the most recent enrich_ioc call.",
+    )
+    vulnerability_results: Optional[List[Dict[str, Any]]] = Field(
+        default=None,
+        description="Results from the most recent scan_host_vulnerabilities call.",
+    )
+    playbook_result: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Results from the most recent trigger_playbook call.",
+    )
+    threat_graph_summary: Optional[str] = Field(
+        default=None,
+        description="Compact textual summary of the current threat graph.",
+    )
+    available_playbooks: List[str] = Field(
+        default_factory=list,
+        description="Names of SOAR playbooks available to the agent.",
+    )
+    reward_dimensions: Optional[Dict[str, float]] = Field(
+        default=None,
+        description=(
+            "Running partial scores for each of the 10 grading dimensions, "
+            "updated every step for live GRPO credit-assignment signals. "
+            "Keys match grade_breakdown (threat_containment, ioc_blocking, etc.)."
+        ),
+    )
+
+
+# =============================================================================
+# Actions (Discriminated Union)
+# =============================================================================
+
+
+class QueryHost(Action):
+    """Query a specific host for status, processes, and connections."""
+    type: Literal["query_host"] = Field(default="query_host", description="Action discriminator")
+    hostname: str = Field(..., description="Target hostname to query")
+
+
+class IsolateSegment(Action):
+    """Isolate an entire network segment, or a single host from the network."""
+    type: Literal["isolate_segment"] = Field(default="isolate_segment", description="Action discriminator")
+    subnet: str = Field(default="", description="Subnet name to isolate (mutually exclusive with target_host)")
+    target_host: Optional[str] = Field(
+        default=None,
+        description="If set, isolate only this single host instead of the whole subnet",
+    )
+    reason: str = Field(default="", description="Justification for isolation")
+
+
+class BlockIOC(Action):
+    """Block an Indicator of Compromise at the perimeter firewall."""
+    type: Literal["block_ioc"] = Field(default="block_ioc", description="Action discriminator")
+    ioc_value: str = Field(..., description="The IOC to block (IP, domain, or file hash)")
+    ioc_type: Literal["ip", "domain", "hash"] = Field(..., description="Type of IOC")
+
+
+class RunForensics(Action):
+    """Run deep forensic analysis on a specific host."""
+    type: Literal["run_forensics"] = Field(default="run_forensics", description="Action discriminator")
+    hostname: str = Field(..., description="Target hostname for forensics")
+
+
+class KillProcess(Action):
+    """Terminate a specific process on a host."""
+    type: Literal["kill_process"] = Field(default="kill_process", description="Action discriminator")
+    hostname: str = Field(..., description="Host where the process is running")
+    process_name: str = Field(..., description="Name of the process to terminate")
+
+
+class ContainmentEntry(BaseModel):
+    """A single entry in the containment plan."""
+    model_config = ConfigDict(extra="forbid")
+
+    threat_id: str = Field(..., description="Threat being addressed")
+    actions_taken: List[str] = Field(..., description="List of actions taken to contain this threat")
+    root_cause: str = Field(..., description="Identified root cause")
+    confidence: float = Field(
+        ..., ge=0.0, le=1.0,
+        description="Confidence in the containment (0-1)",
+    )
+
+
+class SubmitContainmentPlan(Action):
+    """Submit the final containment plan to end the episode."""
+    type: Literal["submit_containment_plan"] = Field(
+        default="submit_containment_plan", description="Action discriminator"
+    )
+    plan: List[ContainmentEntry] = Field(
+        ..., description="The containment plan addressing all identified threats"
+    )
+    executive_summary: str = Field(
+        ..., description="Brief executive summary for CISO reporting"
+    )
+
+
+class CorrelateAlerts(Action):
+    """Correlate two or more alerts to find shared entities/IOCs."""
+    type: Literal["correlate_alerts"] = Field(default="correlate_alerts")
+    alert_ids: List[str] = Field(..., min_length=2, description="At least 2 alert IDs to correlate")
+
+
+class EnrichIOC(Action):
+    """Enrich an IOC with threat-intelligence data (actor, MITRE TTPs)."""
+    type: Literal["enrich_ioc"] = Field(default="enrich_ioc")
+    ioc_value: str = Field(..., description="The IOC value to enrich")
+    ioc_type: Literal["ip", "domain", "hash", "filename"] = Field(..., description="Type of IOC")
+
+
+class ScanHostVulnerabilities(Action):
+    """Run a vulnerability scan on a host to discover CVEs."""
+    type: Literal["scan_host_vulnerabilities"] = Field(default="scan_host_vulnerabilities")
+    hostname: str = Field(..., description="Target hostname for vulnerability scan")
+
+
+class TriggerPlaybook(Action):
+    """Trigger a SOAR playbook against a target host."""
+    type: Literal["trigger_playbook"] = Field(default="trigger_playbook")
+    playbook_name: Literal[
+        "ransomware_containment",
+        "c2_disruption",
+        "lateral_movement_lockdown",
+        "phishing_response",
+        "data_exfil_stop",
+    ] = Field(..., description="Name of the SOAR playbook to trigger")
+    target: str = Field(..., description="Target hostname for playbook execution")
+
+
+# Discriminated union of all SOC actions
+SOCAction = Annotated[
+    Union[
+        QueryHost,
+        IsolateSegment,
+        BlockIOC,
+        RunForensics,
+        KillProcess,
+        SubmitContainmentPlan,
+        CorrelateAlerts,
+        EnrichIOC,
+        ScanHostVulnerabilities,
+        TriggerPlaybook,
+    ],
+    Field(discriminator="type"),
+]
+
+# Wrapper model so OpenEnv's create_app can accept it as a single Action class
+class SOCActionWrapper(Action):
+    """Wrapper that deserializes the discriminated union action.
+
+    OpenEnv's create_app expects a single Action subclass. This wrapper
+    uses a discriminated union field so the HTTP/WS layer can parse
+    any of the 6 action types from a flat JSON payload.
+
+    Client sends:  {"action": {"type": "query_host", "hostname": "WS-001"}}
+    The wrapper validates -> QueryHost(hostname="WS-001")
+    """
+    type: str = Field(..., description="Action type discriminator")
+
+    model_config = ConfigDict(extra="allow")  # Allow action-specific fields
+
+    def to_typed_action(self):
+        """Convert the raw wrapper into the correctly typed action."""
+        data = self.model_dump(exclude={"metadata"})
+        action_map = {
+            "query_host": QueryHost,
+            "isolate_segment": IsolateSegment,
+            "block_ioc": BlockIOC,
+            "run_forensics": RunForensics,
+            "kill_process": KillProcess,
+            "submit_containment_plan": SubmitContainmentPlan,
+            "correlate_alerts": CorrelateAlerts,
+            "enrich_ioc": EnrichIOC,
+            "scan_host_vulnerabilities": ScanHostVulnerabilities,
+            "trigger_playbook": TriggerPlaybook,
+        }
+        cls = action_map.get(data["type"])
+        if cls is None:
+            raise ValueError(
+                f"Unknown action type: {data['type']}. "
+                f"Valid types: {list(action_map.keys())}"
+            )
+        return cls(**data)
+
+
+# =============================================================================
+# Internal State (not exposed to agent directly)
+# =============================================================================
+
+
+class SOCState(State):
+    """Internal environment state tracking the attack simulation.
+
+    Extends OpenEnv State (inherits: episode_id, step_count).
+    Uses extra='allow' from base State.
+    """
+
+    task_id: str = Field(default="easy", description="Current task: 'easy', 'medium', or 'hard'")
+    max_steps: int = Field(default=30, description="Maximum steps for this episode")
+    total_reward: float = Field(default=0.0, description="Accumulated reward")
+    business_impact: float = Field(default=0.0, ge=0.0, le=1.0, description="Current business impact score")
+    contained_threats: List[str] = Field(default_factory=list, description="Threat IDs that have been contained")
+    active_threats: List[str] = Field(default_factory=list, description="Currently active threat IDs")
+    blocked_iocs: List[str] = Field(default_factory=list, description="IOCs blocked at perimeter")
+    isolated_subnets: List[str] = Field(default_factory=list, description="Isolated network segments")
+    forensics_run: List[str] = Field(default_factory=list, description="Hosts that had forensics run")
+    killed_processes: List[Dict[str, str]] = Field(default_factory=list, description="Processes killed")
+    queried_hosts: List[str] = Field(default_factory=list, description="Hosts queried")
+    timeline: List[Dict[str, Any]] = Field(default_factory=list, description="Action timeline")
+    is_done: bool = Field(default=False, description="Whether episode has ended")
+    submitted_plan: bool = Field(default=False, description="Whether containment plan was submitted")
+    enriched_iocs: List[str] = Field(default_factory=list, description="IOCs that have been threat-intel enriched")
+    scanned_hosts: List[str] = Field(default_factory=list, description="Hosts that had vulnerability scans")
+    correlated_alert_pairs: List[Any] = Field(default_factory=list, description="Pairs/groups of alert IDs correlated together")
+    triggered_playbooks: List[str] = Field(default_factory=list, description="SOAR playbooks that were triggered")
+    live_requirements: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Mutable copy of containment_requirements (for adaptive grading).",
+    )

pyproject.toml

@@ -0,0 +1,36 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-cybersocenv"
+version = "0.1.0"
+description = "CyberSOCEnv — Enterprise SOC Incident Response environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv runtime (provides FastAPI server + HTTP client types)
+    "openenv-core[core]>=0.2.2",
+    # Inference dependencies
+    "openai>=1.0.0",
+    "websockets>=12.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+server = "play.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["play", "play.server"]
+package-dir = { "play" = ".", "play.server" = "server" }

requirements.txt

@@ -0,0 +1,8 @@
+fastapi
+uvicorn[standard]
+pydantic
+networkx
+websockets
+openai
+tenacity
+openenv-core

server/Dockerfile

@@ -0,0 +1,80 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local OpenEnv sources)
+# - Standalone environments (with openenv from PyPI/Git)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Ensure git is available (required for installing dependencies from VCS)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=play
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+    
+# Install dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""CyberSOCEnv server components."""
+
+from .play_environment import CyberSOCEnvironment
+
+__all__ = ["CyberSOCEnvironment"]

server/action_validation.py

@@ -0,0 +1,99 @@
+"""3-gate action validation middleware: phase whitelist + schema + graph groundedness."""
+
+from __future__ import annotations
+
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .threat_graph import ThreatGraph
+
+
+PHASE_TOOL_WHITELIST = {
+    "triage":        {"read_alerts", "read_topology", "correlate_alerts"},
+    "investigation": {"query_host", "run_forensics", "add_ioc",
+                      "enrich_ioc", "scan_host_vulnerabilities"},
+    "remediation":   {"block_ioc", "kill_process", "isolate_segment",
+                      "trigger_playbook", "request_human_approval"},
+    "report":        {"submit_containment_plan"},
+}
+
+PHASE_VIOLATION = "PHASE_VIOLATION"
+INVALID_PARAMS = "INVALID_PARAMS"
+UNGROUNDED_ACTION = "UNGROUNDED_ACTION"
+
+
+_REQUIRED_ARGS = {
+    "block_ioc":                 ["ioc_value"],
+    "kill_process":              ["hostname", "process_name"],
+    "isolate_segment":           ["target"],
+    "correlate_alerts":          ["alert_ids"],
+    "enrich_ioc":                ["ioc_value", "ioc_type"],
+    "scan_host_vulnerabilities": ["hostname"],
+    "trigger_playbook":          ["playbook_name", "target"],
+}
+
+
+class ActionValidationMiddleware:
+
+    def validate(
+        self,
+        phase: str,
+        tool_name: str,
+        arguments: dict,
+        graph: "ThreatGraph",
+    ) -> Optional[dict]:
+        # Gate 1 — Phase whitelist
+        allowed = PHASE_TOOL_WHITELIST.get(phase, set())
+        if tool_name not in allowed:
+            return {
+                "error": PHASE_VIOLATION,
+                "message": (
+                    f"Tool '{tool_name}' is not allowed in phase '{phase}'. "
+                    f"Allowed tools: {sorted(allowed)}"
+                ),
+                "retry": False,
+            }
+
+        # Gate 2 — Argument presence (basic schema check)
+        required = _REQUIRED_ARGS.get(tool_name, [])
+        for arg in required:
+            if arg not in arguments:
+                return {
+                    "error": INVALID_PARAMS,
+                    "message": f"Missing required argument '{arg}' for tool '{tool_name}'",
+                    "retry": True,
+                }
+        if tool_name == "correlate_alerts":
+            ids = arguments.get("alert_ids", [])
+            if not isinstance(ids, (list, tuple)) or len(ids) < 2:
+                return {
+                    "error": INVALID_PARAMS,
+                    "message": "correlate_alerts requires at least 2 alert_ids",
+                    "retry": True,
+                }
+
+        # Gate 3 — Graph groundedness
+        if tool_name == "block_ioc":
+            if arguments["ioc_value"] not in graph.iocs:
+                return {
+                    "error": UNGROUNDED_ACTION,
+                    "message": "IOC not in Threat Graph. Run investigation first.",
+                    "retry": True,
+                }
+        elif tool_name == "kill_process":
+            key = f"{arguments['hostname']}:{arguments['process_name']}"
+            if key not in graph.processes:
+                return {
+                    "error": UNGROUNDED_ACTION,
+                    "message": "Process not in Threat Graph.",
+                    "retry": True,
+                }
+        elif tool_name == "enrich_ioc":
+            if arguments["ioc_value"] not in graph.iocs:
+                return {
+                    "error": UNGROUNDED_ACTION,
+                    "message": "IOC not known. Discover it during investigation first.",
+                    "retry": True,
+                }
+
+        return None

server/app.py

@@ -0,0 +1,73 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the CyberSOCEnv Environment.
+
+Endpoints:
+    - POST /reset: Reset the environment (pass task_id in body)
+    - POST /step: Execute an action
+    - GET /state: Get current environment state
+    - GET /schema: Get action/observation schemas
+    - WS /ws: WebSocket endpoint for persistent sessions
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+"""
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as e:  # pragma: no cover
+    raise ImportError(
+        "openenv is required. Install with: pip install 'openenv-core[core]'"
+    ) from e
+
+try:
+    from ..models import SOCObservation, SOCActionWrapper
+    from .play_environment import CyberSOCEnvironment
+except (ImportError, ModuleNotFoundError):
+    from models import SOCObservation, SOCActionWrapper
+    from server.play_environment import CyberSOCEnvironment
+
+
+# Create the app with the CyberSOCEnv environment
+app = create_app(
+    CyberSOCEnvironment,
+    SOCActionWrapper,
+    SOCObservation,
+    env_name="cybersocenv",
+    max_concurrent_envs=16,
+)
+
+# CORS middleware — allows the dashboard frontend to communicate with the server
+from starlette.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    """Entry point for direct execution.
+
+    Usage:
+        python -m play.server.app
+        python -m play.server.app --port 8001
+    """
+    import uvicorn
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

server/episode_sandbox.py

@@ -0,0 +1,98 @@
+"""Episode sandbox — wall-clock + step-limit guard with state-integrity rollback."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from copy import deepcopy
+
+
+def _snapshot_hash(value) -> str:
+    """Deterministic SHA-256 hash of an arbitrary value.
+
+    Uses json.dumps with sort_keys=True and default=str so that dict-type
+    protected fields (task_def, live_requirements) are compared by content
+    rather than by object identity, preventing false-positive rollbacks.
+    """
+    serialized = json.dumps(value, sort_keys=True, default=str)
+    return hashlib.sha256(serialized.encode()).hexdigest()
+
+
+EPISODE_TIMEOUT_SECONDS = 300
+MAX_STEPS_PER_EPISODE = 20
+PROTECTED_STATE_FIELDS = [
+    "_task_def",
+    "_live_requirements",
+    "_threat_graph",
+    "_step_count",
+    "_network",
+    "_host_index",
+]
+
+
+class EpisodeTimeout(Exception):
+    pass
+
+
+class StateIntegrityViolation(Exception):
+    pass
+
+
+class EpisodeSandbox:
+    def __init__(self, env):
+        self.env = env
+        self._start_time = None
+        self._protected_snapshot: dict = {}   # field -> deepcopy for rollback
+        self._snapshot_hashes: dict = {}      # field -> SHA-256 of snapshot
+        self._hacking_attempts: list[str] = []
+
+    def __enter__(self):
+        self._start_time = time.time()
+        self._protected_snapshot = {}
+        self._snapshot_hashes = {}
+        for field in PROTECTED_STATE_FIELDS:
+            if hasattr(self.env, field):
+                original = deepcopy(getattr(self.env, field))
+                self._protected_snapshot[field] = original
+                self._snapshot_hashes[field] = _snapshot_hash(original)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if exc_type is not None and exc_type is not EpisodeTimeout:
+            return False
+
+        elapsed = time.time() - self._start_time
+        if elapsed > EPISODE_TIMEOUT_SECONDS:
+            raise EpisodeTimeout(
+                f"Episode exceeded {EPISODE_TIMEOUT_SECONDS}s wall-clock limit"
+            )
+
+        # Compare by content hash to avoid false-positives from identity comparison
+        for field, original_value in self._protected_snapshot.items():
+            current_value = getattr(self.env, field, None)
+            current_hash = _snapshot_hash(current_value)
+            if current_hash != self._snapshot_hashes[field]:
+                setattr(self.env, field, original_value)
+                self._hacking_attempts.append(
+                    f"Protected field '{field}' was mutated externally"
+                )
+        return False
+
+    def check_step_limit(self, step_count: int) -> None:
+        """Raise EpisodeTimeout if step_count >= MAX_STEPS_PER_EPISODE."""
+        if step_count >= MAX_STEPS_PER_EPISODE:
+            raise EpisodeTimeout(
+                f"Episode exceeded {MAX_STEPS_PER_EPISODE} step limit"
+            )
+
+    def elapsed_seconds(self) -> float:
+        if self._start_time is None:
+            return 0.0
+        return time.time() - self._start_time
+
+    def was_hacked(self) -> bool:
+        return len(self._hacking_attempts) > 0
+
+    def hacking_report(self) -> list[str]:
+        return self._hacking_attempts.copy()

server/graders.py

@@ -0,0 +1,358 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+10-dimensional deterministic graders for CyberSOCEnv.
+
+grade_episode() returns a structured dict with per-dimension breakdown,
+penalties, bonuses, and reward signals suitable for GRPO. Wrappers
+grade_easy/medium/hard preserve their backward-compatible float return.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .threat_graph import ThreatGraph
+
+
+_DIMENSION_WEIGHTS = {
+    "threat_containment":     0.20,
+    "ioc_blocking":           0.12,
+    "forensic_investigation": 0.10,
+    "siem_correlation":       0.08,
+    "threat_intel_usage":     0.08,
+    "vuln_root_cause":        0.08,
+    "business_impact":        0.10,
+    "step_efficiency":        0.07,
+    "plan_coverage":          0.10,
+    "plan_evidence_quality":  0.07,
+}
+
+_PER_OCCURRENCE_CAP = 0.15
+
+
+def _clamp(x: float, lo: float = 0.0, hi: float = 1.0) -> float:
+    return max(lo, min(hi, x))
+
+
+def _capped(delta: float) -> float:
+    return max(-_PER_OCCURRENCE_CAP, min(_PER_OCCURRENCE_CAP, delta))
+
+
+def grade_episode(
+    episode_actions: List[Dict[str, Any]],
+    final_plan: Optional[Dict[str, Any]],
+    graph: "ThreatGraph",
+    task_def: Dict[str, Any],
+    state,
+) -> Dict[str, Any]:
+    """Score the episode across 10 dimensions and return structured output."""
+
+    requirements = task_def.get("containment_requirements", {}) or {}
+    must_kill = requirements.get("must_kill", []) or []
+    must_block = requirements.get("must_block_iocs", []) or []
+    breakdown: Dict[str, float] = {}
+    penalties: List[Dict[str, Any]] = []
+    bonuses: List[Dict[str, Any]] = []
+
+    killed_processes = list(getattr(state, "killed_processes", []) or [])
+    blocked_iocs = list(getattr(state, "blocked_iocs", []) or [])
+    isolated_subnets = list(getattr(state, "isolated_subnets", []) or [])
+    scanned_hosts = list(getattr(state, "scanned_hosts", []) or [])
+    enriched_iocs = list(getattr(state, "enriched_iocs", []) or [])
+    correlated_pairs = list(getattr(state, "correlated_alert_pairs", []) or [])
+    triggered_playbooks = list(getattr(state, "triggered_playbooks", []) or [])
+
+    # ---- 1. threat_containment ----
+    if must_kill:
+        matched = 0
+        for req in must_kill:
+            req_host = req.get("hostname") if isinstance(req, dict) else None
+            req_proc = req.get("process") if isinstance(req, dict) else None
+            for k in killed_processes:
+                if k.get("hostname") == req_host and k.get("process") == req_proc:
+                    matched += 1
+                    break
+        breakdown["threat_containment"] = matched / len(must_kill)
+    else:
+        breakdown["threat_containment"] = 1.0
+
+    # ---- 2. ioc_blocking ----
+    if must_block:
+        matched_blocks = sum(1 for ioc in must_block if ioc in blocked_iocs)
+        breakdown["ioc_blocking"] = matched_blocks / len(must_block)
+    else:
+        breakdown["ioc_blocking"] = 1.0
+
+    # blind blocking penalty: blocked IOCs that were never enriched
+    blind_count = sum(1 for ioc in blocked_iocs if ioc not in enriched_iocs)
+    if blind_count > 0:
+        delta = _capped(-0.05 * blind_count)
+        penalties.append({
+            "type": "blind_blocking",
+            "delta": delta,
+            "detail": f"{blind_count} IOC(s) blocked without enrichment",
+        })
+        breakdown["ioc_blocking"] = _clamp(breakdown["ioc_blocking"] + delta)
+
+    # ---- 3. forensic_investigation ----
+    compromised_hosts = [
+        h for h, node in graph.hosts.items() if node.status == "compromised"
+    ]
+    if compromised_hosts:
+        examined = sum(1 for h in compromised_hosts if h in scanned_hosts)
+        breakdown["forensic_investigation"] = examined / len(compromised_hosts)
+    else:
+        breakdown["forensic_investigation"] = 1.0
+
+    # ---- 4. siem_correlation ----
+    if correlated_pairs:
+        # Build a set of alert_ids that belong to the same threat chain
+        alert_to_threat: Dict[str, str] = {}
+        for threat in task_def.get("attack_chain", []) or []:
+            tid = threat.get("threat_id", "")
+            for a in task_def.get("initial_alerts", []) or []:
+                src = a.get("source_host", "")
+                if src in (threat.get("compromised_hosts", []) or []):
+                    alert_to_threat[a.get("alert_id", "")] = tid
+
+        correct_pairs = 0
+        incorrect_pairs = 0
+        for pair in correlated_pairs:
+            if isinstance(pair, (list, tuple)) and len(pair) == 2:
+                t1 = alert_to_threat.get(pair[0], "__UNK1__")
+                t2 = alert_to_threat.get(pair[1], "__UNK2__")
+                if t1 == t2 and t1 != "__UNK1__":
+                    correct_pairs += 1
+                else:
+                    incorrect_pairs += 1
+            else:
+                correct_pairs += 1  # legacy format: assume valid
+
+        expected_pairs = max(1, len(set(alert_to_threat.values())))
+        raw_corr = max(0.0, (correct_pairs - incorrect_pairs * 0.5)) / expected_pairs
+        breakdown["siem_correlation"] = _clamp(raw_corr)
+
+        # bonus if correlation happened before any remediation action
+        first_remediation_idx = next(
+            (i for i, a in enumerate(episode_actions)
+             if a.get("action_type") in {"block_ioc", "kill_process",
+                                          "isolate_segment", "trigger_playbook"}),
+            None,
+        )
+        first_correlation_idx = next(
+            (i for i, a in enumerate(episode_actions)
+             if a.get("action_type") == "correlate_alerts"),
+            None,
+        )
+        if first_correlation_idx is not None and (
+            first_remediation_idx is None or first_correlation_idx < first_remediation_idx
+        ):
+            delta = _capped(0.03)
+            bonuses.append({
+                "type": "early_correlation",
+                "delta": delta,
+                "detail": "correlation occurred before any remediation",
+            })
+            breakdown["siem_correlation"] = _clamp(breakdown["siem_correlation"] + delta)
+    else:
+        breakdown["siem_correlation"] = 0.0
+
+    # ---- 5. threat_intel_usage ----
+    total_iocs = len(graph.iocs)
+    if total_iocs == 0:
+        breakdown["threat_intel_usage"] = 0.5
+    else:
+        enriched_in_graph = sum(1 for ioc in graph.iocs.values() if ioc.enriched)
+        breakdown["threat_intel_usage"] = enriched_in_graph / total_iocs
+
+    # ---- 6. vuln_root_cause ----
+    cve_found = any(
+        v.exploited_by_threat is not None for v in graph.vulnerabilities.values()
+    )
+    breakdown["vuln_root_cause"] = 1.0 if cve_found else 0.0
+    if cve_found and final_plan:
+        cve_ids = {v.cve_id for v in graph.vulnerabilities.values()
+                   if v.exploited_by_threat is not None}
+        plan_blob = str(final_plan)
+        if any(cid in plan_blob for cid in cve_ids):
+            delta = _capped(0.05)
+            bonuses.append({
+                "type": "cve_in_plan",
+                "delta": delta,
+                "detail": "CVE root-cause referenced in final plan",
+            })
+            breakdown["vuln_root_cause"] = _clamp(breakdown["vuln_root_cause"] + delta)
+
+    # ---- 7. business_impact ----
+    base = 1.0
+    must_not_isolate = requirements.get("must_not_isolate", []) or []
+    for s in [s for s in isolated_subnets if s in must_not_isolate]:
+        delta = _capped(-0.10)
+        penalties.append({
+            "type": "unnecessary_isolation",
+            "delta": delta,
+            "detail": f"subnet '{s}' isolated unnecessarily",
+        })
+        base += delta
+
+    # Per healthy-host isolation (graph view): every isolated host costs -0.10
+    healthy_isolated = sum(1 for h in graph.hosts.values() if h.status == "isolated")
+    for _ in range(healthy_isolated):
+        delta = _capped(-0.10)
+        penalties.append({
+            "type": "healthy_host_isolated",
+            "delta": delta,
+            "detail": "host was isolated (potential downtime)",
+        })
+        base += delta
+
+    total_hosts = len(graph.hosts)
+    if total_hosts > 0:
+        isolated_count = healthy_isolated
+        if isolated_count / total_hosts > 0.20:
+            # Spec specifies -0.30 here; bypass the per-occurrence cap so the
+            # over-isolation flag can dominate as intended.
+            delta = -0.30
+            penalties.append({
+                "type": "over_isolation",
+                "delta": delta,
+                "detail": ">20% of hosts isolated",
+            })
+            base += delta
+
+    breakdown["business_impact"] = max(0.0, base)
+
+    # ---- 8. step_efficiency ----
+    eff_base = 1.0 if triggered_playbooks else 0.5
+    playbook_bonus_total = 0.0
+    for _ in triggered_playbooks:
+        delta = _capped(0.10)
+        bonuses.append({
+            "type": "playbook_triggered",
+            "delta": delta,
+            "detail": "SOAR playbook used",
+        })
+        playbook_bonus_total += delta
+    playbook_bonus_total = min(playbook_bonus_total, 0.30)
+    eff_base += playbook_bonus_total
+
+    steps_used = len(episode_actions)
+    over = max(0, steps_used - 15)
+    if over > 0:
+        delta = _capped(-0.05 * over)
+        penalties.append({
+            "type": "step_overrun",
+            "delta": delta,
+            "detail": f"used {steps_used} steps, over budget by {over}",
+        })
+        eff_base += delta
+    breakdown["step_efficiency"] = _clamp(eff_base)
+
+    # ---- 9. plan_coverage ----
+    if final_plan is None:
+        breakdown["plan_coverage"] = 0.0
+    else:
+        # total known threats = unique threat IDs in containment_requirements
+        known_threats = set()
+        for k in ("must_kill", "must_block_iocs", "must_forensics"):
+            for entry in requirements.get(k, []) or []:
+                if isinstance(entry, dict) and "threat_id" in entry:
+                    known_threats.add(entry["threat_id"])
+        # also include attack_chain threats
+        for t in task_def.get("attack_chain", []) or []:
+            if isinstance(t, dict) and "threat_id" in t:
+                known_threats.add(t["threat_id"])
+
+        if not known_threats:
+            breakdown["plan_coverage"] = 1.0
+        else:
+            plan_blob = str(final_plan)
+            covered = sum(1 for t in known_threats if t in plan_blob)
+            raw_coverage = covered / len(known_threats)
+
+            # Plan padding penalty: entries with no evidence are punished
+            plan_entries = final_plan.get("entries", []) if isinstance(final_plan, dict) else []
+            padded = sum(
+                1 for e in plan_entries
+                if isinstance(e, dict) and (
+                    (e.get("confidence", 1.0) < 0.2) or
+                    (not e.get("root_cause"))
+                )
+            )
+            if padded > 0:
+                delta = _capped(-0.10 * padded)
+                penalties.append({
+                    "type": "plan_padding",
+                    "delta": delta,
+                    "detail": f"{padded} plan entries lack evidence (confidence<0.2 or empty root_cause)",
+                })
+                raw_coverage = max(0.0, raw_coverage + delta)
+
+            breakdown["plan_coverage"] = _clamp(raw_coverage)
+
+    # ---- 10. plan_evidence_quality ----
+    if final_plan is None:
+        breakdown["plan_evidence_quality"] = 0.0
+    else:
+        primary = final_plan.get("primary_threat_id", "") if isinstance(final_plan, dict) else ""
+        rubric_items = (
+            len(must_kill)
+            + len(must_block)
+            + len(requirements.get("must_forensics", []) or [])
+        )
+        breakdown["plan_evidence_quality"] = _clamp(
+            graph.compute_evidence_confidence(primary, rubric_item_count=rubric_items)
+        )
+
+    # Final weighted score
+    raw_score = sum(_DIMENSION_WEIGHTS[k] * v for k, v in breakdown.items())
+    final_score = _clamp(raw_score)
+
+    reward_functions = {f"reward_{k}": v for k, v in breakdown.items()}
+
+    return {
+        "final_score": final_score,
+        "breakdown": breakdown,
+        "penalties": penalties,
+        "bonuses": bonuses,
+        "reward_functions": reward_functions,
+    }
+
+
+def grade_easy(
+    episode_actions: List[Dict[str, Any]],
+    final_plan: Optional[Dict[str, Any]],
+    graph: "ThreatGraph",
+    task_def: Dict[str, Any],
+    state,
+) -> float:
+    """Backward-compatible: returns final_score float for the easy task."""
+    return grade_episode(episode_actions, final_plan, graph, task_def, state)["final_score"]
+
+
+def grade_medium(
+    episode_actions: List[Dict[str, Any]],
+    final_plan: Optional[Dict[str, Any]],
+    graph: "ThreatGraph",
+    task_def: Dict[str, Any],
+    state,
+) -> float:
+    """Backward-compatible: returns final_score float for the medium task."""
+    return grade_episode(episode_actions, final_plan, graph, task_def, state)["final_score"]
+
+
+def grade_hard(
+    episode_actions: List[Dict[str, Any]],
+    final_plan: Optional[Dict[str, Any]],
+    graph: "ThreatGraph",
+    task_def: Dict[str, Any],
+    state,
+) -> float:
+    """Backward-compatible: returns final_score float for the hard task."""
+    return grade_episode(episode_actions, final_plan, graph, task_def, state)["final_score"]

server/play_environment.py

@@ -0,0 +1,1315 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+CyberSOCEnv — Enterprise Cybersecurity Operations Center Environment.
+
+Implements the OpenEnv Environment interface for a deterministic SOC
+incident response simulation on a 500-node enterprise network.
+
+The agent receives SIEM/EDR alerts, queries hosts, runs forensics,
+isolates segments, blocks IOCs, kills processes, and submits a
+containment plan — all while minimizing business downtime.
+"""
+
+from __future__ import annotations
+
+import copy
+import random
+import uuid
+from typing import Any, Dict, List, Optional
+from uuid import uuid4
+
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import State
+
+try:
+    from ..models import (
+        SOCObservation,
+        SOCActionWrapper,
+        SOCState,
+        Alert,
+        NetworkTopology,
+        ForensicsResult,
+        TimelineEntry,
+        QueryHost,
+        IsolateSegment,
+        BlockIOC,
+        RunForensics,
+        KillProcess,
+        SubmitContainmentPlan,
+        CorrelateAlerts,
+        EnrichIOC,
+        ScanHostVulnerabilities,
+        TriggerPlaybook,
+    )
+except ImportError:
+    from models import (
+        SOCObservation,
+        SOCActionWrapper,
+        SOCState,
+        Alert,
+        NetworkTopology,
+        ForensicsResult,
+        TimelineEntry,
+        QueryHost,
+        IsolateSegment,
+        BlockIOC,
+        RunForensics,
+        KillProcess,
+        SubmitContainmentPlan,
+        CorrelateAlerts,
+        EnrichIOC,
+        ScanHostVulnerabilities,
+        TriggerPlaybook,
+    )
+
+from .tasks import get_task, build_network
+from .graders import grade_episode
+from .threat_graph import (
+    ThreatGraph,
+    HostNode,
+    ProcessNode,
+    IOCNode,
+    VulnerabilityNode,
+    AlertNode,
+    Edge,
+)
+from .soar_playbooks import PLAYBOOKS, check_prerequisites
+
+
+class ActionMiddleware:
+    """Pre-flight validation for SOC actions.
+
+    Detects phase violations (action out of order) and graph-ungrounded actions
+    (action references an entity not yet discovered in the ThreatGraph).
+    Returns None if the action is valid, or an error dict otherwise.
+    """
+
+    def validate(
+        self,
+        current_phase: str,
+        action_type: str,
+        args: Dict[str, Any],
+        graph,
+    ) -> Optional[Dict[str, str]]:
+        # Phase violation: plan submission before any investigation
+        if action_type == "submit_containment_plan" and current_phase == "triage":
+            return {
+                "error_type": "PHASE_VIOLATION",
+                "message": "submit_containment_plan requires investigation phase first",
+            }
+
+        # Graph-groundedness: IOC must be discovered before enrichment
+        if action_type == "enrich_ioc":
+            ioc_val = args.get("ioc_value", "")
+            if ioc_val and graph is not None and ioc_val not in graph.iocs:
+                return {
+                    "error_type": "GRAPH_FAILURE",
+                    "message": f"IOC '{ioc_val}' not in threat graph; receive an alert or run forensics first",
+                }
+
+        # Graph-groundedness: host must be known before vulnerability scan
+        if action_type == "scan_host_vulnerabilities":
+            hostname = args.get("hostname", "")
+            if hostname and graph is not None and hostname not in graph.hosts:
+                return {
+                    "error_type": "GRAPH_FAILURE",
+                    "message": f"Host '{hostname}' not in threat graph; run query_host first",
+                }
+
+        return None
+
+
+class CyberSOCEnvironment(Environment):
+    """
+    Deterministic SOC incident response environment.
+
+    Simulates a 500-node enterprise network under attack. The agent must
+    investigate alerts, contain threats, and submit a containment plan
+    while minimizing business downtime.
+
+    Supports concurrent WebSocket sessions (each gets own instance).
+
+    Example:
+        >>> env = CyberSOCEnvironment()
+        >>> obs = env.reset(task_id="easy")
+        >>> print(len(obs.alert_queue))  # Initial alerts
+        >>> obs = env.step(SOCActionWrapper(type="query_host", hostname="WS-042"))
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self, adaptive: bool = False):
+        """Initialize the environment (actual state set in reset)."""
+        super().__init__()
+        self._adaptive = adaptive
+        self._live_requirements: Dict[str, Any] = {}
+        self._threat_graph = None  # will be initialized on reset()
+        self._state = SOCState(episode_id=str(uuid4()), step_count=0)
+        self._network: Dict[str, List[Dict[str, Any]]] = {}
+        self._task_def: Dict[str, Any] = {}
+        self._alert_queue: List[Dict[str, Any]] = []
+        self._host_index: Dict[str, Dict[str, Any]] = {}  # hostname -> host dict
+        self._plan_entries: List[Dict[str, Any]] = []
+        self._last_forensics: Optional[ForensicsResult] = None
+        self._middleware = ActionMiddleware()
+        self._rng = random.Random(0)  # overwritten in reset()
+
+    def _reset_rubric(self):
+        """Initialize live containment requirements for dynamic grading in adaptive mode."""
+        import copy
+        self._live_requirements = copy.deepcopy(
+            self._task_def.get("containment_requirements", {})
+        )
+
+    # ===========================================================================
+    # reset()
+    # ===========================================================================
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> SOCObservation:
+        """Reset the environment for a specific task.
+
+        Args:
+            seed: Ignored (environment is fully deterministic).
+            episode_id: Optional custom episode ID.
+            **kwargs: Must include task_id ('easy', 'medium', or 'hard').
+
+        Returns:
+            Initial SOCObservation with alert queue and network state.
+        """
+        task_id = kwargs.get("task_id", "easy")
+        self._rng = random.Random(hash(task_id))
+        self._task_def = get_task(task_id)
+        self._recent_actions = []  # reset stall detector
+
+        # Build deterministic network (cached per task for GRPO throughput)
+        if not hasattr(CyberSOCEnvironment, "_network_cache"):
+            CyberSOCEnvironment._network_cache = {}
+        cache_key = task_id
+        if cache_key in CyberSOCEnvironment._network_cache:
+            self._network = copy.deepcopy(CyberSOCEnvironment._network_cache[cache_key])
+        else:
+            self._network = build_network()
+            CyberSOCEnvironment._network_cache[cache_key] = copy.deepcopy(self._network)
+
+        # Build hostname index for O(1) lookups
+        self._host_index = {}
+        for subnet_name, hosts in self._network.items():
+            for host in hosts:
+                self._host_index[host["hostname"]] = host
+
+        # Inject attack chain: mark compromised hosts, add malicious processes
+        for threat in self._task_def["attack_chain"]:
+            for hostname in threat["compromised_hosts"]:
+                if hostname in self._host_index:
+                    host = self._host_index[hostname]
+                    host["status"] = "compromised"
+                    for proc in threat["malicious_processes"]:
+                        if proc not in host["running_processes"]:
+                            host["running_processes"].append(proc)
+
+        # Initialize alert queue (deep copy so mutations don't affect task def)
+        self._alert_queue = copy.deepcopy(self._task_def["initial_alerts"])
+
+        # Reset state
+        eid = episode_id or str(uuid4())
+        self._state = SOCState(
+            episode_id=eid,
+            step_count=0,
+            task_id=task_id,
+            max_steps=self._task_def["max_steps"],
+            total_reward=0.0,
+            business_impact=self._task_def["initial_business_impact"],
+            contained_threats=[],
+            active_threats=[t["threat_id"] for t in self._task_def["attack_chain"]],
+            blocked_iocs=[],
+            isolated_subnets=[],
+            forensics_run=[],
+            killed_processes=[],
+            queried_hosts=[],
+            timeline=[],
+            is_done=False,
+            submitted_plan=False,
+        )
+
+        self._plan_entries = []
+        self._last_forensics = None
+        self._reset_rubric()
+        self._fired_step_rewards: set = set()
+        self._step_reward_total: float = 0.0
+
+        # Initialize threat graph from task definition
+        self._threat_graph = ThreatGraph()
+        self._populate_threat_graph()
+        self._last_obs_extras: Dict[str, Any] = {}
+
+        return self._build_observation(reward=0.0, done=False)
+
+    def _populate_threat_graph(self) -> None:
+        """Seed the threat graph with hosts, processes, IOCs, and alerts from task_def."""
+        graph = self._threat_graph
+
+        # Hosts: include compromised hosts from attack chain + every host they live on
+        compromised_set: set[str] = set()
+        for threat in self._task_def.get("attack_chain", []):
+            for hn in threat.get("compromised_hosts", []):
+                compromised_set.add(hn)
+
+        for hostname in compromised_set:
+            host_dict = self._host_index.get(hostname)
+            if host_dict is None:
+                continue
+            graph.add_host(HostNode(
+                hostname=hostname,
+                subnet=host_dict.get("subnet", "corporate"),
+                business_criticality="high" if host_dict.get("criticality", 0.5) >= 0.7 else "medium",
+                status="compromised",
+            ))
+
+        # Processes: malicious processes per compromised host
+        for threat in self._task_def.get("attack_chain", []):
+            tid = threat.get("threat_id", "T?")
+            for hostname in threat.get("compromised_hosts", []):
+                if hostname not in graph.hosts:
+                    continue
+                for proc in threat.get("malicious_processes", []):
+                    pid = f"{hostname}:{proc}"
+                    if pid not in graph.processes:
+                        graph.add_process(ProcessNode(
+                            process_id=pid,
+                            hostname=hostname,
+                            process_name=proc,
+                        ))
+                # Add part_of_chain edge
+                graph.add_edge(Edge(
+                    edge_type="part_of_chain",
+                    source_id=tid,
+                    target_id=hostname,
+                ))
+
+        # IOCs from attack chain
+        for threat in self._task_def.get("attack_chain", []):
+            iocs = threat.get("iocs", {}) or {}
+            for ioc_value in iocs.get("hashes", []):
+                if ioc_value not in graph.iocs:
+                    graph.add_ioc(IOCNode(ioc_value=ioc_value, ioc_type="hash", confidence=0.85))
+            for ioc_value in iocs.get("ips", []):
+                if ioc_value not in graph.iocs:
+                    graph.add_ioc(IOCNode(ioc_value=ioc_value, ioc_type="ip", confidence=0.85))
+            for ioc_value in iocs.get("domains", []):
+                if ioc_value not in graph.iocs:
+                    graph.add_ioc(IOCNode(ioc_value=ioc_value, ioc_type="domain", confidence=0.85))
+            for c2 in threat.get("c2_servers", []):
+                if c2 not in graph.iocs:
+                    graph.add_ioc(IOCNode(ioc_value=c2, ioc_type="ip", confidence=0.95))
+
+        # Alerts
+        for a in self._task_def.get("initial_alerts", []):
+            aid = a.get("alert_id")
+            if aid and aid not in graph.alerts:
+                graph.add_alert(AlertNode(
+                    alert_id=aid,
+                    severity=a.get("severity", "medium"),
+                    priority_score=1.0,
+                    source_host=a.get("source_host", ""),
+                ))
+
+    # ===========================================================================
+    # step()
+    # ===========================================================================
+
+    def step(
+        self,
+        action: SOCActionWrapper,  # type: ignore[override]
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> SOCObservation:
+        """Process one agent action.
+
+        Args:
+            action: SOCActionWrapper containing the typed action.
+            timeout_s: Ignored.
+
+        Returns:
+            SOCObservation with updated state, reward, and done flag.
+        """
+        if self._state.is_done:
+            return self._build_observation(reward=0.0, done=True)
+
+        # Convert wrapper to typed action (before consuming a step)
+        typed_action = action.to_typed_action()
+        args = typed_action.model_dump(exclude={"metadata", "type"})
+
+        # Pre-flight validation — invalid actions are penalised without consuming a step
+        current_phase = self._get_current_phase()
+        validation_error = self._middleware.validate(
+            current_phase, typed_action.type, args, self._threat_graph
+        )
+        if validation_error:
+            error_type = validation_error.get("error_type", "")
+            penalty = -0.10 if error_type == "PHASE_VIOLATION" else -0.05
+            self._state.total_reward += penalty
+            return self._build_observation(reward=penalty, done=False)
+
+        # Action is valid — now consume the step
+        self._state.step_count += 1
+
+        # Dispatch to handler
+        reward = 0.0
+        result_description = "unknown action"
+
+        # Reset per-step observation extras at the start of every step
+        self._last_obs_extras = {}
+
+        if isinstance(typed_action, QueryHost):
+            reward, result_description = self._handle_query_host(typed_action)
+        elif isinstance(typed_action, IsolateSegment):
+            reward, result_description = self._handle_isolate_segment(typed_action)
+        elif isinstance(typed_action, BlockIOC):
+            reward, result_description = self._handle_block_ioc(typed_action)
+        elif isinstance(typed_action, RunForensics):
+            reward, result_description = self._handle_run_forensics(typed_action)
+        elif isinstance(typed_action, KillProcess):
+            reward, result_description = self._handle_kill_process(typed_action)
+        elif isinstance(typed_action, SubmitContainmentPlan):
+            reward, result_description = self._handle_submit_plan(typed_action)
+        elif isinstance(typed_action, CorrelateAlerts):
+            result = self._handle_correlate_alerts(typed_action)
+            self._last_obs_extras.update(result)
+            reward = 0.05 if "error" not in result else -0.05
+            result_description = result.get("description", "correlate_alerts")
+        elif isinstance(typed_action, EnrichIOC):
+            result = self._handle_enrich_ioc(typed_action)
+            self._last_obs_extras.update(result)
+            reward = 0.05 if "error" not in result else -0.05
+            result_description = result.get("description", "enrich_ioc")
+        elif isinstance(typed_action, ScanHostVulnerabilities):
+            result = self._handle_scan_vulnerabilities(typed_action)
+            self._last_obs_extras.update(result)
+            reward = 0.05 if "error" not in result else -0.05
+            result_description = result.get("description", "scan_host_vulnerabilities")
+        elif isinstance(typed_action, TriggerPlaybook):
+            result = self._handle_trigger_playbook(typed_action)
+            self._last_obs_extras.update(result)
+            reward = 0.10 if "error" not in result else -0.05
+            result_description = result.get("description", "trigger_playbook")
+
+        # Step reward (idempotent per triple)
+        target = self._get_action_target(typed_action)
+        step_r = self._get_step_reward(phase="investigation", action_type=typed_action.type, target=target)
+        reward += step_r
+        self._step_reward_total += step_r
+
+        # Stall detection: penalise 3+ consecutive identical actions
+        stall_key = (typed_action.type, target)
+        if not hasattr(self, "_recent_actions"):
+            self._recent_actions = []
+        self._recent_actions.append(stall_key)
+        if len(self._recent_actions) >= 3:
+            last_three = self._recent_actions[-3:]
+            if last_three[0] == last_three[1] == last_three[2]:
+                reward -= 0.05  # stall penalty
+
+        # Adaptive adversary reaction
+        self._adversary_react(action_type=typed_action.type, target=target)
+
+        # Business impact grows each step (attacker progresses)
+        if not self._state.is_done:
+            impact_rate = self._task_def.get("impact_per_step", 0.02)
+            # Reduce impact growth if threats are being contained
+            active_ratio = len(self._state.active_threats) / max(1, len(self._task_def["attack_chain"]))
+            self._state.business_impact = min(
+                1.0,
+                self._state.business_impact + impact_rate * active_ratio,
+            )
+
+        # Record timeline
+        self._state.timeline.append({
+            "step": self._state.step_count,
+            "action_type": typed_action.type,
+            "target": self._get_action_target(typed_action),
+            "result": result_description,
+            "reward": reward,
+        })
+
+        # Accumulate reward
+        self._state.total_reward += reward
+
+        # Check termination
+        done = False
+        if self._state.submitted_plan:
+            done = True
+            self._state.is_done = True
+        elif self._state.step_count >= self._state.max_steps:
+            done = True
+            self._state.is_done = True
+            reward -= 0.20  # Penalty for running out of time
+            self._state.total_reward += (-0.20)
+
+        return self._build_observation(reward=reward, done=done)
+
+    # ===========================================================================
+    # Action Handlers (return (reward, description))
+    # ===========================================================================
+
+    def _handle_query_host(self, action: QueryHost) -> tuple[float, str]:
+        """Query a host for status info."""
+        hostname = action.hostname
+        self._last_forensics = None  # Clear forensics from previous step
+
+        if hostname not in self._host_index:
+            return -0.05, f"Host '{hostname}' not found in network"
+
+        host = self._host_index[hostname]
+
+        # Reward for querying compromised hosts (useful investigation)
+        reward = 0.0
+        if host["status"] == "compromised" and hostname not in self._state.queried_hosts:
+            reward = 0.05  # Good: investigating a compromised host
+        elif hostname in self._state.queried_hosts:
+            reward = -0.02  # Penalty: re-querying same host wastes time
+
+        self._state.queried_hosts.append(hostname)
+
+        # Enhanced observation extras: process_tree + network_connections from graph
+        process_tree = []
+        if self._threat_graph is not None:
+            for p in self._threat_graph.processes.values():
+                if p.hostname == hostname:
+                    process_tree.append({
+                        "process_id": p.process_id,
+                        "process_name": p.process_name,
+                        "killed": p.killed,
+                    })
+        network_connections = []
+        if self._threat_graph is not None:
+            for e in self._threat_graph.edges:
+                if e.edge_type == "communicates_with" and (
+                    e.source_id == hostname or e.target_id == hostname
+                ):
+                    other = e.target_id if e.source_id == hostname else e.source_id
+                    if other in self._threat_graph.iocs:
+                        network_connections.append(other)
+        self._last_obs_extras["process_tree"] = process_tree
+        self._last_obs_extras["network_connections"] = network_connections
+
+        return reward, f"Queried {hostname}: status={host['status']}, procs={len(host['running_processes'])}"
+
+    def _handle_isolate_segment(self, action: IsolateSegment) -> tuple[float, str]:
+        """Isolate a network segment, or a single host if target_host is set."""
+        self._last_forensics = None
+
+        # Single-host isolation path
+        target_host = getattr(action, "target_host", None)
+        if target_host:
+            if target_host not in self._host_index:
+                return -0.05, f"Host '{target_host}' not found"
+            self._host_index[target_host]["status"] = "isolated"
+            if self._threat_graph is not None and target_host in self._threat_graph.hosts:
+                self._threat_graph.hosts[target_host].status = "isolated"
+            return 0.10, f"Isolated single host '{target_host}'"
+
+        subnet = action.subnet
+
+        if subnet not in self._network:
+            return -0.05, f"Subnet '{subnet}' does not exist"
+
+        if subnet in self._state.isolated_subnets:
+            return -0.02, f"Subnet '{subnet}' is already isolated"
+
+        # Isolate all hosts in the subnet
+        for host in self._network[subnet]:
+            host["status"] = "isolated"
+            if self._threat_graph is not None and host["hostname"] in self._threat_graph.hosts:
+                self._threat_graph.hosts[host["hostname"]].status = "isolated"
+
+        self._state.isolated_subnets.append(subnet)
+
+        # Check if this contains any active threats
+        reward = 0.0
+        threats_contained = []
+        for threat in self._task_def["attack_chain"]:
+            if threat["threat_id"] in self._state.active_threats:
+                # Check if any compromised hosts are in this subnet
+                for ch in threat["compromised_hosts"]:
+                    if ch in self._host_index and self._host_index[ch]["subnet"] == subnet:
+                        threats_contained.append(threat["threat_id"])
+                        break
+
+        if threats_contained:
+            reward = 0.15 * len(threats_contained)  # Good: containing lateral movement
+            for tid in threats_contained:
+                if tid not in self._state.contained_threats:
+                    self._state.contained_threats.append(tid)
+                if tid in self._state.active_threats:
+                    self._state.active_threats.remove(tid)
+
+        # Check if this is an unnecessary isolation (business downtime)
+        must_not_isolate = self._task_def["containment_requirements"].get("must_not_isolate", [])
+        if subnet in must_not_isolate:
+            reward -= 0.10  # Penalty: unnecessary downtime
+            self._state.business_impact = min(1.0, self._state.business_impact + 0.08)
+
+        return reward, f"Isolated subnet '{subnet}'. Threats contained: {threats_contained}"
+
+    def _handle_block_ioc(self, action: BlockIOC) -> tuple[float, str]:
+        """Block an IOC at the perimeter."""
+        ioc = action.ioc_value
+        self._last_forensics = None
+
+        if ioc in self._state.blocked_iocs:
+            return -0.02, f"IOC '{ioc}' is already blocked"
+
+        self._state.blocked_iocs.append(ioc)
+
+        # Check if this IOC is relevant to any active threat
+        reward = 0.0
+        relevant = False
+        for threat in self._task_def["attack_chain"]:
+            all_iocs = (
+                threat["iocs"].get("hashes", [])
+                + threat["iocs"].get("ips", [])
+                + threat["iocs"].get("domains", [])
+            )
+            if ioc in all_iocs:
+                relevant = True
+                # Extra reward for blocking C2 server IPs
+                if ioc in threat.get("c2_servers", []):
+                    reward += 0.15  # High value: cutting C2
+                else:
+                    reward += 0.10  # Good: blocking relevant IOC
+                break
+
+        if not relevant:
+            reward = -0.03  # Noise: blocking irrelevant IOC
+
+        return reward, f"Blocked IOC '{ioc}' (type={action.ioc_type}). Relevant: {relevant}"
+
+    def _handle_run_forensics(self, action: RunForensics) -> tuple[float, str]:
+        """Run forensic analysis on a host."""
+        hostname = action.hostname
+
+        if hostname not in self._host_index:
+            self._last_forensics = None
+            return -0.05, f"Host '{hostname}' not found"
+
+        host = self._host_index[hostname]
+
+        # Build forensics result based on actual host state
+        is_compromised = host["status"] == "compromised"
+        malicious_procs = []
+        suspicious_files = []
+        network_conns = []
+        registry_mods = []
+        memory_artifacts = []
+
+        if is_compromised:
+            # Find which threat(s) affect this host
+            for threat in self._task_def["attack_chain"]:
+                if hostname in threat["compromised_hosts"]:
+                    malicious_procs.extend(threat["malicious_processes"])
+                    # Generate deterministic forensic artifacts
+                    for proc in threat["malicious_processes"]:
+                        suspicious_files.append(f"C:\\Windows\\Temp\\{proc}.dat")
+                        registry_mods.append(f"HKLM\\Software\\Microsoft\\Windows\\CurrentVersion\\Run\\{proc}")
+                    for c2 in threat.get("c2_servers", []):
+                        network_conns.append(f"{c2}:443")
+                    for ioc_hash in threat["iocs"].get("hashes", []):
+                        memory_artifacts.append(f"memory_inject_{ioc_hash[:8]}")
+
+        self._last_forensics = ForensicsResult(
+            hostname=hostname,
+            malicious_processes=malicious_procs,
+            suspicious_files=suspicious_files,
+            network_connections=network_conns,
+            registry_modifications=registry_mods,
+            memory_artifacts=memory_artifacts,
+            is_compromised=is_compromised,
+        )
+
+        # Reward
+        reward = 0.0
+        if hostname not in self._state.forensics_run:
+            if is_compromised:
+                reward = 0.10  # Good: found evidence
+            else:
+                reward = 0.02  # Cleared a host (some value)
+            self._state.forensics_run.append(hostname)
+        else:
+            reward = -0.02  # Re-running forensics wastes time
+
+        # Enhanced: behavioral_chain and network_flows from graph
+        behavioral_chain = []
+        network_flows = []
+        if self._threat_graph is not None:
+            for e in self._threat_graph.edges:
+                if e.source_id == hostname or e.target_id == hostname:
+                    behavioral_chain.append({
+                        "edge_type": e.edge_type,
+                        "source_id": e.source_id,
+                        "target_id": e.target_id,
+                    })
+            for e in self._threat_graph.edges:
+                if e.edge_type == "communicates_with":
+                    if e.source_id == hostname or e.target_id == hostname:
+                        other = e.target_id if e.source_id == hostname else e.source_id
+                        if other in self._threat_graph.iocs:
+                            network_flows.append(other)
+        self._last_obs_extras["behavioral_chain"] = behavioral_chain
+        self._last_obs_extras["network_flows"] = network_flows
+
+        return reward, f"Forensics on {hostname}: compromised={is_compromised}, procs={malicious_procs}"
+
+    def _handle_kill_process(self, action: KillProcess) -> tuple[float, str]:
+        """Kill a process on a host."""
+        hostname = action.hostname
+        process = action.process_name
+        self._last_forensics = None
+
+        if hostname not in self._host_index:
+            return -0.05, f"Host '{hostname}' not found"
+
+        host = self._host_index[hostname]
+
+        if host["status"] == "isolated":
+            return -0.02, f"Host '{hostname}' is isolated — cannot interact"
+
+        if process not in host["running_processes"]:
+            return -0.03, f"Process '{process}' not running on {hostname}"
+
+        # Kill the process
+        host["running_processes"].remove(process)
+        self._state.killed_processes.append({"hostname": hostname, "process": process})
+
+        # Check if this was a malicious process
+        reward = 0.0
+        was_malicious = False
+        for threat in self._task_def["attack_chain"]:
+            if hostname in threat["compromised_hosts"] and process in threat["malicious_processes"]:
+                was_malicious = True
+                reward = 0.15  # Major reward: stopping malicious activity
+
+                # Check if all processes for this threat are killed
+                all_killed = True
+                for th_host in threat["compromised_hosts"]:
+                    for th_proc in threat["malicious_processes"]:
+                        still_running = (
+                            th_host in self._host_index
+                            and th_proc in self._host_index[th_host]["running_processes"]
+                        )
+                        if still_running:
+                            all_killed = False
+                            break
+
+                if all_killed and threat["threat_id"] in self._state.active_threats:
+                    self._state.active_threats.remove(threat["threat_id"])
+                    if threat["threat_id"] not in self._state.contained_threats:
+                        self._state.contained_threats.append(threat["threat_id"])
+                    reward += 0.10  # Bonus: fully contained a threat
+                break
+
+        if not was_malicious:
+            reward = -0.08  # Penalty: killing legitimate process = downtime
+            self._state.business_impact = min(1.0, self._state.business_impact + 0.03)
+
+        if was_malicious:
+            self._maybe_reinfect(hostname, process)
+
+        return reward, f"Killed '{process}' on {hostname}. Malicious: {was_malicious}"
+
+    def _handle_submit_plan(self, action: SubmitContainmentPlan) -> tuple[float, str]:
+        """Submit the final containment plan."""
+        self._last_forensics = None
+        self._state.submitted_plan = True
+        self._plan_entries = [entry.model_dump() for entry in action.plan]
+
+        # Grade the episode using new 10-dim grader
+        final_plan_dict = {
+            "entries": self._plan_entries,
+            "primary_threat_id": (self._plan_entries[0]["threat_id"]
+                                  if self._plan_entries else ""),
+        }
+        grade_result = grade_episode(
+            episode_actions=list(self._state.timeline),
+            final_plan=final_plan_dict,
+            graph=self._threat_graph,
+            task_def=self._task_def,
+            state=self._state,
+        )
+        final_score = grade_result["final_score"]
+
+        # Reward proportional to final grade
+        reward = final_score * 1.0  # Scale: perfect score = 1.0 reward
+        description = (
+            f"Containment plan submitted. "
+            f"Grade: {final_score:.3f}. "
+            f"Threats contained: {len(self._state.contained_threats)}/{len(self._task_def['attack_chain'])}. "
+            f"Business impact: {self._state.business_impact:.2f}"
+        )
+
+        return reward, description
+
+    # ===========================================================================
+    # New Action Handlers (return observation-update dict)
+    # ===========================================================================
+
+    def _handle_correlate_alerts(self, action: CorrelateAlerts) -> dict:
+        """Correlate alerts to find shared hosts/IOCs."""
+        if len(action.alert_ids) < 2:
+            return {"error": "correlate_alerts requires at least 2 alert IDs",
+                    "description": "correlate_alerts error"}
+
+        graph = self._threat_graph
+        known_alerts = {aid: graph.alerts[aid] for aid in action.alert_ids if aid in graph.alerts}
+        if len(known_alerts) < 2:
+            return {"error": "fewer than 2 alert IDs found in graph",
+                    "description": "correlate_alerts error"}
+
+        # Find shared source hosts
+        source_hosts: dict[str, list[str]] = {}
+        for aid, alert in known_alerts.items():
+            source_hosts.setdefault(alert.source_host, []).append(aid)
+        shared_hosts = [h for h, aids in source_hosts.items() if len(aids) >= 2]
+
+        # Find shared IOCs via "involves" edges
+        shared_iocs: set[str] = set()
+        for e in graph.edges:
+            if e.edge_type == "involves" and e.source_id in known_alerts:
+                if any(
+                    e2.edge_type == "involves" and e2.target_id == e.target_id
+                    and e2.source_id in known_alerts and e2.source_id != e.source_id
+                    for e2 in graph.edges
+                ):
+                    shared_iocs.add(e.target_id)
+
+        # Update correlated_with on each alert
+        all_ids = list(known_alerts.keys())
+        for aid, alert in known_alerts.items():
+            for other_id in all_ids:
+                if other_id != aid and other_id not in alert.correlated_with:
+                    alert.correlated_with.append(other_id)
+
+        self._state.correlated_alert_pairs.append(tuple(all_ids))
+
+        shared_count = len(shared_hosts) + len(shared_iocs)
+        correlation_score = min(1.0, shared_count / len(all_ids))
+
+        result = {
+            "correlation_results": {
+                "shared_hosts": shared_hosts,
+                "shared_iocs": list(shared_iocs),
+                "correlation_score": correlation_score,
+            },
+            "description": f"Correlated {len(all_ids)} alerts: {len(shared_hosts)} shared hosts",
+        }
+        return result
+
+    def _handle_enrich_ioc(self, action: EnrichIOC) -> dict:
+        """Enrich an IOC with threat-intel data."""
+        graph = self._threat_graph
+
+        if action.ioc_value not in graph.iocs:
+            return {"error": "IOC not yet discovered",
+                    "description": "enrich_ioc error"}
+
+        intel = self._task_def.get("threat_intel_data", {}) or {}
+        data = intel.get(action.ioc_value, {
+            "reputation": 0.5,
+            "threat_actor": "unknown",
+            "mitre_ttps": [],
+        })
+
+        # Update IOC node in graph
+        ioc_node = graph.iocs[action.ioc_value]
+        ioc_node.enriched = True
+        ioc_node.threat_actor = data.get("threat_actor")
+        ioc_node.mitre_ttps = data.get("mitre_ttps", [])
+
+        if action.ioc_value not in self._state.enriched_iocs:
+            self._state.enriched_iocs.append(action.ioc_value)
+
+        return {
+            "ioc_enrichment": data,
+            "description": f"Enriched IOC {action.ioc_value}: actor={data.get('threat_actor')}",
+        }
+
+    def _handle_scan_vulnerabilities(self, action: ScanHostVulnerabilities) -> dict:
+        """Scan a host for CVE vulnerabilities."""
+        graph = self._threat_graph
+        hostname = action.hostname
+
+        if hostname not in graph.hosts:
+            return {"error": f"Host '{hostname}' not in Threat Graph",
+                    "description": "scan_host_vulnerabilities error"}
+
+        vuln_chain = self._task_def.get("vulnerability_chain", []) or []
+        vuln_results: list[dict] = []
+        for entry in vuln_chain:
+            if not isinstance(entry, dict):
+                continue
+            if entry.get("hostname") == hostname or entry.get("affected_hosts") and hostname in entry["affected_hosts"]:
+                cve_id = entry.get("cve_id", "CVE-UNKNOWN")
+                vuln_node = VulnerabilityNode(
+                    cve_id=cve_id,
+                    hostname=hostname,
+                    cvss_score=entry.get("cvss_score", 5.0),
+                    exploitability=entry.get("exploitability", "theoretical"),
+                    patch_available=entry.get("patch_available", False),
+                    exploited_by_threat=entry.get("threat_id"),
+                )
+                graph.add_vulnerability(vuln_node)
+                graph.add_edge(Edge(
+                    edge_type="exploits",
+                    source_id=cve_id,
+                    target_id=hostname,
+                ))
+                vuln_results.append(entry)
+
+        # Mark host as scanned
+        graph.hosts[hostname].scanned = True
+        if hostname not in self._state.scanned_hosts:
+            self._state.scanned_hosts.append(hostname)
+
+        return {
+            "vulnerability_results": vuln_results,
+            "description": f"Scanned {hostname}: found {len(vuln_results)} CVEs",
+        }
+
+    def _handle_trigger_playbook(self, action: TriggerPlaybook) -> dict:
+        """Trigger a SOAR playbook against a target host."""
+        ok, reason = check_prerequisites(
+            action.playbook_name, action.target, self._state, self._threat_graph
+        )
+        if not ok:
+            return {"error": reason,
+                    "description": f"trigger_playbook failed: {reason}"}
+
+        sub_actions = PLAYBOOKS[action.playbook_name]["sub_actions"]
+        if action.playbook_name not in self._state.triggered_playbooks:
+            self._state.triggered_playbooks.append(action.playbook_name)
+
+        return {
+            "playbook_result": {
+                "playbook": action.playbook_name,
+                "sub_actions": sub_actions,
+                "status": "executed",
+            },
+            "description": f"Executed playbook '{action.playbook_name}' on {action.target}",
+        }
+
+    # ===========================================================================
+    # Helpers
+    # ===========================================================================
+
+    def _compute_reward_dimensions(self) -> Dict[str, float]:
+        """Per-step heuristic partial scores for all 10 grading dimensions.
+
+        Updated every step so GRPO can assign credit without waiting for the
+        terminal grade.  Scores are in [0, 1]; the terminal grade_breakdown
+        (from grade_episode) supersedes these once the plan is submitted.
+        """
+        state = self._state
+        task_chain = self._task_def.get("attack_chain", [])
+        total_threats = max(1, len(task_chain))
+
+        total_compromised = max(1, sum(len(t.get("compromised_hosts", [])) for t in task_chain))
+        total_iocs = max(1, sum(
+            len(t.get("iocs", {}).get("hashes", []))
+            + len(t.get("iocs", {}).get("ips", []))
+            + len(t.get("iocs", {}).get("domains", []))
+            for t in task_chain
+        ))
+
+        # 1. threat_containment — fraction of threats neutralised
+        threat_containment = min(1.0, len(state.contained_threats) / total_threats)
+
+        # 2. ioc_blocking — fraction of known IOCs blocked
+        ioc_blocking = min(1.0, len(state.blocked_iocs) / total_iocs)
+
+        # 3. forensic_investigation — fraction of compromised hosts investigated
+        forensic_investigation = min(1.0, len(state.forensics_run) / total_compromised)
+
+        # 4. siem_correlation — binary: did the agent correlate alerts?
+        siem_correlation = 1.0 if state.correlated_alert_pairs else 0.0
+
+        # 5. threat_intel_usage — fraction of IOCs enriched with threat intel
+        threat_intel_usage = min(1.0, len(state.enriched_iocs) / total_iocs)
+
+        # 6. vuln_root_cause — fraction of threats with a scanned host
+        vuln_root_cause = min(1.0, len(state.scanned_hosts) / total_threats)
+
+        # 7. business_impact — lower impact is better
+        business_impact = max(0.0, 1.0 - state.business_impact)
+
+        # 8. step_efficiency — reward early resolution
+        ratio = state.step_count / max(1, state.max_steps)
+        step_efficiency = max(0.0, 1.0 - max(0.0, ratio - 0.5) * 1.5)
+
+        # 9. plan_coverage — partial credit scales with threats addressed
+        if state.submitted_plan:
+            plan_coverage = min(1.0, len(self._plan_entries) / total_threats)
+        else:
+            plan_coverage = min(0.5, len(state.contained_threats) / total_threats * 0.5)
+
+        # 10. plan_evidence_quality — confidence of submitted plan; else proxy from investigation depth
+        if state.submitted_plan and self._plan_entries:
+            avg_conf = sum(e.get("confidence", 0.0) for e in self._plan_entries) / len(self._plan_entries)
+            plan_evidence_quality = float(avg_conf)
+        else:
+            evidence_count = len(state.forensics_run) + len(state.enriched_iocs) + len(state.scanned_hosts)
+            plan_evidence_quality = min(0.5, evidence_count / (total_compromised * 3) * 0.5)
+
+        return {
+            "threat_containment":    round(threat_containment,    4),
+            "ioc_blocking":          round(ioc_blocking,          4),
+            "forensic_investigation":round(forensic_investigation, 4),
+            "siem_correlation":      round(siem_correlation,      4),
+            "threat_intel_usage":    round(threat_intel_usage,    4),
+            "vuln_root_cause":       round(vuln_root_cause,       4),
+            "business_impact":       round(business_impact,       4),
+            "step_efficiency":       round(step_efficiency,       4),
+            "plan_coverage":         round(plan_coverage,         4),
+            "plan_evidence_quality": round(plan_evidence_quality, 4),
+        }
+
+    def _get_current_phase(self) -> str:
+        """Derive episode phase from the action history in the timeline."""
+        action_types = {t["action_type"] for t in self._state.timeline}
+        if any(t in action_types for t in ["kill_process", "block_ioc", "isolate_segment", "trigger_playbook"]):
+            return "remediation"
+        if any(t in action_types for t in ["run_forensics", "enrich_ioc", "scan_host_vulnerabilities", "query_host"]):
+            return "investigation"
+        return "triage"
+
+    def _build_observation(self, reward: float, done: bool) -> SOCObservation:
+        """Build the observation from current state."""
+        # Compute network topology summary
+        subnet_counts = {name: len(hosts) for name, hosts in self._network.items()}
+        compromised = sum(
+            1 for hosts in self._network.values()
+            for h in hosts if h["status"] == "compromised"
+        )
+        isolated = sum(
+            1 for hosts in self._network.values()
+            for h in hosts if h["status"] == "isolated"
+        )
+        total = sum(len(hosts) for hosts in self._network.values())
+
+        topology = NetworkTopology(
+            total_hosts=total,
+            subnets=subnet_counts,
+            compromised_count=compromised,
+            isolated_count=isolated,
+            online_count=total - compromised - isolated,
+        )
+
+        # Build alert list
+        alerts = [Alert(**a) for a in self._alert_queue]
+
+        # Build timeline
+        timeline = [
+            TimelineEntry(
+                step=t["step"],
+                action_type=t["action_type"],
+                target=t["target"],
+                result=t["result"],
+                reward=t["reward"],
+            )
+            for t in self._state.timeline
+        ]
+
+        # Compute final grade if done
+        final_score_val = None
+        grade_breakdown_val = None
+
+        if done and self._state.submitted_plan:
+            final_plan_dict = {
+                "entries": self._plan_entries,
+                "primary_threat_id": (self._plan_entries[0]["threat_id"]
+                                      if self._plan_entries else ""),
+            }
+            computed = grade_episode(
+                episode_actions=list(self._state.timeline),
+                final_plan=final_plan_dict,
+                graph=self._threat_graph,
+                task_def=self._task_def,
+                state=self._state,
+            )
+            final_score_val = round(computed["final_score"], 4)
+            grade_breakdown_val = computed["breakdown"]
+
+        # Merge per-step observation extras (process_tree, correlation_results, etc.)
+        extras = getattr(self, "_last_obs_extras", {}) or {}
+        threat_graph_summary = None
+        if self._threat_graph is not None:
+            threat_graph_summary = self._threat_graph.get_context_summary()
+
+        # Per-step partial reward dimensions for GRPO credit assignment
+        reward_dimensions = self._compute_reward_dimensions()
+
+        return SOCObservation(
+            episode_id=self._state.episode_id or "",
+            alert_queue=alerts,
+            network_topology=topology,
+            host_forensics=self._last_forensics,
+            timeline=timeline,
+            business_impact_score=round(self._state.business_impact, 4),
+            step_count=self._state.step_count,
+            active_threats=list(self._state.active_threats),
+            max_steps=self._state.max_steps,
+            task_id=self._state.task_id,
+            total_reward=round(self._state.total_reward, 4),
+            final_score=final_score_val,
+            grade_breakdown=grade_breakdown_val,
+            done=done,
+            reward=round(reward, 4),
+            correlation_results=extras.get("correlation_results"),
+            ioc_enrichment=extras.get("ioc_enrichment"),
+            vulnerability_results=extras.get("vulnerability_results"),
+            playbook_result=extras.get("playbook_result"),
+            threat_graph_summary=threat_graph_summary,
+            available_playbooks=list(PLAYBOOKS.keys()),
+            reward_dimensions=reward_dimensions,
+        )
+
+    def _get_action_target(self, action: Any) -> str:
+        """Extract the target string from a typed action for timeline logging."""
+        if isinstance(action, QueryHost):
+            return action.hostname
+        elif isinstance(action, IsolateSegment):
+            return getattr(action, "target_host", None) or action.subnet
+        elif isinstance(action, BlockIOC):
+            return f"{action.ioc_type}:{action.ioc_value}"
+        elif isinstance(action, RunForensics):
+            return action.hostname
+        elif isinstance(action, KillProcess):
+            return f"{action.hostname}/{action.process_name}"
+        elif isinstance(action, SubmitContainmentPlan):
+            return f"{len(action.plan)} entries"
+        elif isinstance(action, CorrelateAlerts):
+            return ",".join(action.alert_ids)
+        elif isinstance(action, EnrichIOC):
+            return action.ioc_value
+        elif isinstance(action, ScanHostVulnerabilities):
+            return action.hostname
+        elif isinstance(action, TriggerPlaybook):
+            return f"{action.playbook_name}@{action.target}"
+        return "unknown"
+
+    # ===========================================================================
+    # Adaptive Red Team + Step Rewards (Task 10)
+    # ===========================================================================
+
+    STEP_REWARDS: Dict[Any, float] = {
+        ("investigation", "run_forensics"):              +0.10,
+        ("investigation", "enrich_ioc"):                 +0.05,
+        ("investigation", "scan_host_vulnerabilities"):  +0.05,
+        ("triage",        "correlate_alerts"):            +0.05,
+        "phase_violation_attempt":                       -0.20,
+        "ungrounded_action_attempt":                     -0.10,
+    }
+
+    def _get_step_reward(self, phase: str, action_type: str, target: str) -> float:
+        """Idempotent step reward — fires only once per (phase, action_type, target) triple.
+
+        Hard cap: total step rewards per episode never exceed 0.40.
+        """
+        if not hasattr(self, "_fired_step_rewards"):
+            self._fired_step_rewards = set()
+        # Hard cap: once we've reached 0.40 in step rewards, return 0 for all subsequent
+        if getattr(self, "_step_reward_total", 0.0) >= 0.40:
+            return 0.0
+        key = (phase, action_type, target)
+        if key in self._fired_step_rewards:
+            return 0.0
+        reward = self.STEP_REWARDS.get((phase, action_type), 0.0)
+        if reward != 0.0:
+            self._fired_step_rewards.add(key)
+        return reward
+
+    def _maybe_reinfect(self, hostname: str, process_name: str) -> None:
+        """30 % chance to reinfect with a _v2 variant when unblocked IOCs exist in the threat chain."""
+        if not self._adaptive:
+            return
+        graph = self._threat_graph
+        if graph is None:
+            return
+
+        # Check whether any IOC in the host's threat chain is still unblocked
+        unblocked_chain_iocs = False
+        for ioc_node in graph.iocs.values():
+            if not ioc_node.blocked:
+                # Is this IOC linked (via any edge) to the same host's chain?
+                for e in graph.edges:
+                    if e.target_id == hostname or e.source_id == hostname:
+                        unblocked_chain_iocs = True
+                        break
+            if unblocked_chain_iocs:
+                break
+
+        if not unblocked_chain_iocs:
+            return
+
+        if self._rng.random() >= 0.3:
+            return
+
+        # Reinfect: spawn a _v2 variant process on the host
+        variant_name = f"{process_name}_v2"
+        if hostname in self._host_index:
+            host = self._host_index[hostname]
+            if variant_name not in host["running_processes"]:
+                host["running_processes"].append(variant_name)
+                host["status"] = "compromised"
+
+        # Add the variant to the threat graph
+        pid = f"{hostname}:{variant_name}"
+        if pid not in graph.processes:
+            graph.add_process(ProcessNode(
+                process_id=pid,
+                hostname=hostname,
+                process_name=variant_name,
+                killed=False,
+            ))
+
+        # Emit a CRITICAL alert to signal the reinfection
+        alert_id = f"REINFECT-{uuid.uuid4().hex[:6].upper()}"
+        graph.add_alert(AlertNode(
+            alert_id=alert_id,
+            severity="critical",
+            priority_score=18.0,
+            source_host=hostname,
+        ))
+        self._alert_queue.append({
+            "alert_id": alert_id,
+            "timestamp": "2024-01-01T00:00:00Z",
+            "source_host": hostname,
+            "severity": "critical",
+            "threat_type": "malware",
+            "description": f"Reinfection detected: {variant_name} spawned on {hostname} (IOC-assisted persistence)",
+            "ioc_indicators": [],
+            "subnet": self._host_index.get(hostname, {}).get("subnet", "unknown"),
+            "is_acknowledged": False,
+        })
+
+    def _adversary_react(self, action_type: str, target: str) -> None:
+        """Adaptive red team response — fires after each step when adaptive=True."""
+        if not self._adaptive:
+            return
+
+        difficulty = self._task_def.get("difficulty") or getattr(self._state, "task_id", "easy")
+        # Reduced medium base probability for better GRPO credit assignment
+        pivot_probability = {"easy": 0.0, "medium": 0.3, "hard": 1.0}.get(difficulty, 0.0)
+
+        # Time-pressure escalation: attacker moves faster when uncontained and late in episode
+        if self._state.step_count > 10 and len(self._state.contained_threats) == 0:
+            pivot_probability += 0.2
+
+        # Trigger on isolate_segment OR kill_process (extended pivot trigger)
+        if action_type in ("isolate_segment", "kill_process") and pivot_probability > 0:
+            if self._rng.random() < pivot_probability:
+                self._execute_lateral_pivot(source_host=target)
+
+    def _execute_lateral_pivot(self, source_host: str) -> None:
+        """Copy-not-move lateral pivot: spread to an adjacent healthy host.
+
+        Rubric is capped at MAX_RUBRIC_ITEMS to prevent competent agents from
+        being penalised by an impossible-to-complete rubric.
+        """
+        MAX_RUBRIC_ITEMS = 12
+        graph = self._threat_graph
+        if graph is None:
+            return
+
+        # Rubric cap: stop pivoting once live_requirements is full
+        if self._live_requirements:
+            current_items = (
+                len(self._live_requirements.get("must_kill", []))
+                + len(self._live_requirements.get("must_isolate", []))
+            )
+            if current_items >= MAX_RUBRIC_ITEMS:
+                return
+
+        adjacent_hosts = [
+            e.target_id for e in graph.edges
+            if e.source_id == source_host and e.target_id in graph.hosts
+            and graph.hosts[e.target_id].status == "healthy"
+        ]
+        if not adjacent_hosts:
+            # Try graph hosts first, then fall back to full host_index
+            healthy_hosts = [
+                h for h, node in graph.hosts.items()
+                if node.status == "healthy" and h != source_host
+            ]
+            if not healthy_hosts:
+                # Expand search to the full network
+                healthy_hosts = [
+                    h for h, hd in self._host_index.items()
+                    if hd.get("status", "online") not in ("compromised", "isolated")
+                    and h != source_host
+                    and h not in graph.hosts
+                ]
+            if not healthy_hosts:
+                return
+            adjacent_hosts = healthy_hosts
+
+        dest_host = self._rng.choice(adjacent_hosts)
+
+        # Ensure destination host is in graph
+        if dest_host not in graph.hosts:
+            hd = self._host_index.get(dest_host, {})
+            graph.add_host(HostNode(
+                hostname=dest_host,
+                subnet=hd.get("subnet", "corporate"),
+                business_criticality="medium",
+                status="healthy",
+            ))
+
+        source_processes = [p for p in graph.processes.values() if p.hostname == source_host]
+        if not source_processes:
+            return
+        original = source_processes[0]
+
+        new_pid = str(uuid.uuid4())[:8]  # uuid imported at module level
+        new_process = ProcessNode(
+            process_id=f"{dest_host}:{new_pid}",
+            hostname=dest_host,
+            process_name=original.process_name,
+            killed=False,
+        )
+        graph.add_process(new_process)
+
+        graph.add_edge(Edge(
+            edge_type="pivoted_from",
+            source_id=dest_host,
+            target_id=source_host,
+            evidence={"trigger_action": "isolate_segment", "step": self._state.step_count},
+        ))
+
+        if self._live_requirements is None:
+            self._live_requirements = {}
+        self._live_requirements.setdefault("must_kill", []).append(
+            f"{dest_host}:{original.process_name}"
+        )
+        self._live_requirements.setdefault("must_isolate", []).append(dest_host)
+
+        new_alert = AlertNode(
+            alert_id=f"PIVOT-{new_pid}",
+            severity="critical",
+            priority_score=15.0,
+            source_host=dest_host,
+        )
+        graph.add_alert(new_alert)
+
+    @property
+    def state(self) -> SOCState:
+        """Get the current internal environment state."""
+        return self._state

server/requirements.txt

@@ -0,0 +1,3 @@
+openenv-core[core]>=0.2.2
+openai>=1.0.0
+websockets>=12.0

server/soar_playbooks.py

@@ -0,0 +1,125 @@
+"""SOAR Playbook Library — 5 deterministic playbooks + prerequisite checker."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .threat_graph import ThreatGraph
+
+
+PLAYBOOKS = {
+    "ransomware_containment": {
+        "name": "ransomware_containment",
+        "description": "Kill encryption processes and block malware hashes",
+        "prerequisites": ["forensics_run_on_target", "process_identified"],
+        "sub_actions": ["kill_process", "block_ioc"],
+        "target_attack_types": ["ransomware", "encryption"],
+    },
+    "c2_disruption": {
+        "name": "c2_disruption",
+        "description": "Block C2 IPs and disrupt command and control channel",
+        "prerequisites": ["ioc_enriched", "c2_ip_identified"],
+        "sub_actions": ["block_ioc", "isolate_segment"],
+        "target_attack_types": ["c2", "backdoor", "remote_access"],
+    },
+    "lateral_movement_lockdown": {
+        "name": "lateral_movement_lockdown",
+        "description": "Block east-west traffic and kill lateral movement backdoors",
+        "prerequisites": ["forensics_run_on_target", "lateral_movement_detected"],
+        "sub_actions": ["kill_process", "isolate_segment"],
+        "target_attack_types": ["lateral_movement", "pivot"],
+    },
+    "phishing_response": {
+        "name": "phishing_response",
+        "description": "Enrich phishing IOCs and block phishing domains",
+        "prerequisites": ["phishing_vector_confirmed"],
+        "sub_actions": ["enrich_ioc", "block_ioc"],
+        "target_attack_types": ["phishing", "spearphishing"],
+    },
+    "data_exfil_stop": {
+        "name": "data_exfil_stop",
+        "description": "Block exfil destinations and kill exfil processes",
+        "prerequisites": ["forensics_run_on_target", "exfil_destination_identified"],
+        "sub_actions": ["block_ioc", "kill_process"],
+        "target_attack_types": ["exfiltration", "data_theft"],
+    },
+}
+
+
+def _check_single_prerequisite(
+    prereq: str,
+    target_hostname: str,
+    state,
+    graph: "ThreatGraph",
+) -> tuple[bool, str]:
+    if prereq == "forensics_run_on_target":
+        scanned = getattr(state, "scanned_hosts", []) or []
+        if target_hostname in scanned:
+            return True, ""
+        # Also accept if a forensic-type edge (exploits / runs_on) exists for this host
+        for e in graph.edges:
+            if e.edge_type in ("exploits", "runs_on") and (
+                e.target_id == target_hostname or e.source_id == target_hostname
+            ):
+                return True, ""
+        return False, f"forensics not run on {target_hostname}"
+
+    if prereq == "process_identified":
+        for p in graph.processes.values():
+            if p.hostname == target_hostname:
+                return True, ""
+        return False, f"no process identified on {target_hostname}"
+
+    if prereq == "ioc_enriched":
+        for ioc in graph.iocs.values():
+            if ioc.enriched:
+                return True, ""
+        return False, "no IOC has been enriched yet"
+
+    if prereq == "c2_ip_identified":
+        for ioc in graph.iocs.values():
+            if ioc.ioc_type == "ip" and ioc.confidence > 0.7:
+                return True, ""
+        return False, "no high-confidence C2 IP identified"
+
+    if prereq == "lateral_movement_detected":
+        for e in graph.edges:
+            if e.edge_type == "pivoted_from":
+                return True, ""
+        return False, "no lateral movement detected in graph"
+
+    if prereq == "phishing_vector_confirmed":
+        for a in graph.alerts.values():
+            if a.source_host == target_hostname:
+                return True, ""
+        return False, f"no alert confirms phishing vector on {target_hostname}"
+
+    if prereq == "exfil_destination_identified":
+        for ioc in graph.iocs.values():
+            if (
+                ioc.ioc_type in ("ip", "domain")
+                and ioc.confidence > 0.6
+                and not ioc.blocked
+            ):
+                return True, ""
+        return False, "no unblocked exfil destination identified"
+
+    return False, f"unknown prerequisite: {prereq}"
+
+
+def check_prerequisites(
+    playbook_name: str,
+    target_hostname: str,
+    state,
+    graph: "ThreatGraph",
+) -> tuple[bool, str]:
+    """Validate all prerequisites for a playbook against state + graph."""
+    if playbook_name not in PLAYBOOKS:
+        raise KeyError(f"Unknown playbook: {playbook_name}")
+
+    for prereq in PLAYBOOKS[playbook_name]["prerequisites"]:
+        ok, reason = _check_single_prerequisite(prereq, target_hostname, state, graph)
+        if not ok:
+            return False, reason
+    return True, ""

server/task_generator.py

@@ -0,0 +1,674 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Procedural Task Generator for CyberSOCEnv.
+
+Generates 1000+ unique, deterministic attack scenarios from a task_id seed.
+Each task_id (e.g. 'gen_0001') always produces the exact same scenario.
+
+Design:
+    - hash(task_id) -> deterministic seed -> random.Random instance
+    - Seed drives ALL choices: attack type, hosts, processes, IOCs, alerts
+    - 12 attack categories, 50+ malware names, 40+ C2 domains
+    - 3 difficulty tiers based on task number
+
+No actual randomness — reproducible across runs and platforms.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import random
+import itertools
+from typing import Any, Dict, List, Tuple
+
+# =============================================================================
+# Validation & Exclusions
+# =============================================================================
+
+INCOMPATIBLE_THREATS = {
+    ("ransomware", "cryptomining"),      # Ransomware kills host, no mining possible
+    ("data_exfiltration", "ransomware"), # Exfil needs host alive
+}
+
+def validate_task_def(task_def: dict) -> List[str]:
+    errors = []
+    compromised_hosts = set()
+    for threat in task_def.get("attack_chain", []):
+        compromised_hosts.update(threat.get("compromised_hosts", []))
+
+    reqs = task_def.get("containment_requirements", {})
+    for req in reqs.get("must_kill", []):
+        hostname = req.get("hostname") if isinstance(req, dict) else req.split(":")[0]
+        if hostname not in compromised_hosts:
+            errors.append(f"must_kill references non-compromised host: {hostname}")
+
+    for host in reqs.get("must_isolate", []):
+        if host not in compromised_hosts:
+            errors.append(f"must_isolate references non-compromised host: {host}")
+
+    return errors
+
+
+# =============================================================================
+# Template Pools (the "vocabulary" of the generator)
+# =============================================================================
+
+# --- Malware process names by category ---
+MALWARE_PROCESSES = {
+    "ransomware": [
+        "cryptolocker.exe", "wannacry.exe", "blackcat_ransom.exe",
+        "lockbit3.exe", "revil_encrypt.exe", "hive_locker.exe",
+        "conti_crypt.exe", "ryuk_payload.exe", "maze_encrypt.exe",
+        "darkside_enc.exe", "babuk_lock.exe", "avaddon_crypt.exe",
+    ],
+    "phishing": [
+        "outlook_macro.exe", "word_dropper.exe", "macro_loader.exe",
+        "vba_agent.exe", "pdf_exploit.exe", "html_smuggler.exe",
+        "iso_mounter.exe", "lnk_runner.exe",
+    ],
+    "credential_theft": [
+        "mimikatz.exe", "lazagne.exe", "hashdump.exe",
+        "procdump_lsass.exe", "rubeus.exe", "kerbrute.exe",
+        "sharphound.exe", "bloodhound_collect.exe",
+    ],
+    "lateral_movement": [
+        "svchost_backdoor.exe", "psexec_svc.exe", "wmic_lateral.exe",
+        "rdp_hijack.exe", "ssh_brute.exe", "evil_winrm.exe",
+        "dcom_exec.exe", "smb_relay.exe",
+    ],
+    "c2_communication": [
+        "svchost_c2.exe", "cobalt_beacon.exe", "sliver_implant.exe",
+        "meterpreter.exe", "covenant_grunt.exe", "mythic_agent.exe",
+        "dns_tunnel.exe", "icmp_beacon.exe",
+    ],
+    "privilege_escalation": [
+        "exploit_kernel.exe", "potato_exploit.exe", "uac_bypass.exe",
+        "printspoofer.exe", "juicy_potato.exe", "named_pipe_exploit.exe",
+        "token_impersonate.exe", "dll_hijack.exe",
+    ],
+    "data_exfiltration": [
+        "data_pump.exe", "rclone_sync.exe", "mega_upload.exe",
+        "ftp_exfil.exe", "dns_exfil.exe", "cloud_sync_mal.exe",
+        "archive_send.exe", "stealer_agent.exe",
+    ],
+    "cryptomining": [
+        "xmrig_miner.exe", "ethminer.exe", "cpuminer.exe",
+        "nicehash_mal.exe", "coinhive_svc.exe", "monero_mine.exe",
+    ],
+    "supply_chain": [
+        "update_agent_mal.exe", "npm_backdoor.exe", "pip_trojan.exe",
+        "vscode_ext_mal.exe", "docker_implant.exe", "nuget_poison.exe",
+    ],
+    "insider_threat": [
+        "usb_copy.exe", "screen_capture.exe", "keylogger_svc.exe",
+        "email_forward.exe", "cloud_upload.exe", "print_spooler_mal.exe",
+    ],
+    "webshell": [
+        "cmd_webshell.php", "asp_backdoor.exe", "jsp_shell.exe",
+        "python_rshell.exe", "nodejs_shell.exe", "perl_cgi_shell.exe",
+    ],
+    "botnet": [
+        "mirai_bot.exe", "emotet_loader.exe", "trickbot_svc.exe",
+        "qbot_agent.exe", "dridex_dll.exe", "zloader_inject.exe",
+    ],
+}
+
+# --- C2 domains ---
+C2_DOMAINS = [
+    "cdn-update.malware-c2.net", "api.darkc2.io", "telemetry-svc.ru",
+    "secure-update.evil.net", "cdn.payload-delivery.com", "api.shadownet.io",
+    "sync.cloud-c2.xyz", "update.legit-looking.com", "beacon.covert-ops.net",
+    "dns.tunnel-relay.org", "img.cdn-malware.com", "static.evil-cdn.net",
+    "api.stealthc2.io", "ws.encrypted-relay.net", "feed.darkweb-proxy.com",
+    "auth.phish-server.net", "login.fake-portal.com", "mail.spoof-relay.org",
+    "git.supply-chain.dev", "npm.compromised-pkg.io", "pypi.trojan-lib.org",
+    "dl.ransomware-pay.onion", "tor.exit-node-c2.net", "i2p.covert-chan.net",
+    "iot.botnet-c2.xyz", "cam.mirai-variant.net", "mqtt.iot-exploit.io",
+    "ftp.exfil-server.ru", "sftp.data-steal.com", "mega.cloud-drop.io",
+    "gist.code-exfil.dev", "paste.data-dump.xyz", "bin.steganography.net",
+    "vpn.tunnel-c2.com", "proxy.relay-beacon.org", "socks.covert-proxy.io",
+    "wpad.evil-config.net", "ntp.time-beacon.com", "ldap.ad-exploit.org",
+    "kerberos.ticket-steal.net",
+]
+
+# --- C2 IPs (RFC 5737 documentation ranges + realistic-looking) ---
+C2_IPS = [
+    "198.51.100.10", "198.51.100.22", "198.51.100.33", "198.51.100.44",
+    "198.51.100.55", "198.51.100.66", "198.51.100.77", "198.51.100.88",
+    "198.51.100.99", "198.51.100.110", "198.51.100.121", "198.51.100.132",
+    "203.0.113.10", "203.0.113.21", "203.0.113.32", "203.0.113.43",
+    "203.0.113.54", "203.0.113.65", "203.0.113.76", "203.0.113.87",
+    "203.0.113.98", "203.0.113.109", "203.0.113.120", "203.0.113.131",
+    "192.0.2.10", "192.0.2.21", "192.0.2.32", "192.0.2.43",
+    "192.0.2.54", "192.0.2.65", "192.0.2.76", "192.0.2.87",
+    "100.64.0.10", "100.64.0.22", "100.64.0.33", "100.64.0.44",
+]
+
+# --- Subnet definitions (must match build_network() in tasks.py) ---
+SUBNETS = {
+    "corporate":   {"prefix": "WS",   "count": 90,  "criticality": 0.3},
+    "engineering": {"prefix": "DEV",  "count": 36,  "criticality": 0.5},
+    "finance":     {"prefix": "FIN",  "count": 14,  "criticality": 0.8},
+    "dmz":         {"prefix": "DMZ",  "count": 3,   "criticality": 0.6},
+    "datacenter":  {"prefix": "SRV",  "count": 20,  "criticality": 0.9},
+    "executive":   {"prefix": "EXEC", "count": 5,   "criticality": 1.0},
+}
+
+# --- Attack phases in kill-chain order ---
+ATTACK_PHASES = [
+    "initial_access", "execution", "persistence", "privilege_escalation",
+    "credential_access", "lateral_movement", "command_and_control",
+    "exfiltration", "impact",
+]
+
+# --- Alert description templates ---
+ALERT_TEMPLATES = {
+    "ransomware": [
+        "EDR detected file encryption activity on {host}. Process '{proc}' is encrypting files in user directories.",
+        "Anomalous file system activity: {count} files renamed with .{ext} extension in {secs} seconds on {host}.",
+        "Ransomware signature detected in process '{proc}' on {host}. Volume shadow copies being deleted.",
+    ],
+    "phishing": [
+        "User on {host} clicked suspicious link in email. {proc} execution detected downloading payload from {domain}.",
+        "Macro-enabled document opened on {host}. Outbound connection to {domain} detected.",
+        "Suspicious email attachment executed on {host}. Process '{proc}' spawned child processes.",
+    ],
+    "credential_theft": [
+        "LSASS memory access detected on {host} — possible credential dumping via {proc}.",
+        "Kerberos ticket request anomaly on {host}. Process '{proc}' attempting ticket manipulation.",
+        "SAM database access detected on {host}. Credential harvesting tool '{proc}' identified.",
+    ],
+    "lateral_movement": [
+        "Suspicious RDP login to {host} from compromised source using admin credentials. Process '{proc}' spawned.",
+        "SMB lateral movement detected: '{proc}' deployed on {host} via remote service creation.",
+        "WMI remote execution detected on {host}. Process '{proc}' launched from external host.",
+    ],
+    "c2_communication": [
+        "Periodic beaconing detected from {host} to {ip} every {interval} seconds. Encrypted payload exchange observed.",
+        "DNS tunneling activity from {host}. Suspicious queries to {domain} with encoded payloads.",
+        "Cobalt Strike beacon profile detected on {host}. Process '{proc}' communicating with {ip}.",
+    ],
+    "privilege_escalation": [
+        "Kernel exploit attempt on {host}. Process '{proc}' gained SYSTEM privileges.",
+        "UAC bypass detected on {host}. Process '{proc}' elevated to admin without user consent.",
+        "Token impersonation attack on {host}. Process '{proc}' obtained domain admin token.",
+    ],
+    "data_exfiltration": [
+        "Large data transfer ({size} GB) to external IP {ip} from {host}. Possible exfiltration of {data_type}.",
+        "Staging activity detected on {host}. Process '{proc}' archiving sensitive directories for extraction.",
+        "Cloud storage upload from {host} to unauthorized account. Process '{proc}' transferring {data_type}.",
+    ],
+    "cryptomining": [
+        "High CPU usage (98%) on {host}. Process '{proc}' identified as cryptocurrency miner.",
+        "Mining pool connection from {host} to {ip}:{port}. Process '{proc}' consuming all available cores.",
+        "Stratum protocol detected on {host}. Unauthorized mining process '{proc}' active.",
+    ],
+    "supply_chain": [
+        "Compromised package detected in CI/CD pipeline on {host}. Process '{proc}' executing post-install scripts.",
+        "Backdoored update agent on {host}. Process '{proc}' downloading payloads from {domain}.",
+        "Malicious dependency loaded on {host}. Process '{proc}' establishing covert communication channels.",
+    ],
+    "insider_threat": [
+        "Unusual data access pattern on {host}. Process '{proc}' accessing files outside user's normal scope.",
+        "USB mass storage device connected on {host}. Process '{proc}' copying sensitive files to removable media.",
+        "After-hours bulk file download on {host}. Process '{proc}' archiving {data_type} documents.",
+    ],
+    "webshell": [
+        "Web shell detected on {host}. Process '{proc}' executing system commands via HTTP POST requests.",
+        "Suspicious file upload on {host}. Process '{proc}' created in web-accessible directory with bash capabilities.",
+        "Remote code execution on {host}. Process '{proc}' spawned from web server with SYSTEM context.",
+    ],
+    "botnet": [
+        "Bot agent detected on {host}. Process '{proc}' joining command pool at {ip}.",
+        "DDoS toolkit loaded on {host}. Process '{proc}' ready to receive attack instructions from {domain}.",
+        "Worm propagation from {host}. Process '{proc}' scanning network for vulnerable hosts.",
+    ],
+}
+
+# --- Severity levels with weights ---
+SEVERITIES = ["low", "medium", "high", "critical"]
+SEVERITY_WEIGHTS = {"easy": [0.1, 0.4, 0.4, 0.1], "medium": [0.0, 0.2, 0.5, 0.3], "hard": [0.0, 0.1, 0.3, 0.6]}
+
+# --- Data types for exfil descriptions ---
+DATA_TYPES = [
+    "customer PII", "financial records", "employee credentials",
+    "source code", "trade secrets", "medical records",
+    "encryption keys", "database backups", "API tokens",
+    "board meeting minutes", "M&A documents", "patent filings",
+]
+
+# --- File extensions for ransomware ---
+RANSOM_EXTENSIONS = [
+    "locked", "encrypted", "crypted", "crypt", "enc", "pay",
+    "ransom", "darkside", "blackcat", "hive", "lockbit", "ryuk",
+]
+
+
+# =============================================================================
+# Deterministic Seed Helper
+# =============================================================================
+
+def _seed_from_task_id(task_id: str) -> int:
+    """Create a deterministic integer seed from a task_id string."""
+    h = hashlib.sha256(task_id.encode("utf-8")).hexdigest()
+    return int(h[:16], 16)
+
+
+def _make_hash(rng: random.Random) -> str:
+    """Generate a fake MD5-like hash deterministically."""
+    return "".join(rng.choice("0123456789abcdef") for _ in range(32))
+
+
+# =============================================================================
+# Difficulty Classification
+# =============================================================================
+
+def _get_difficulty(task_id: str, rng: random.Random) -> str:
+    """Determine difficulty from task_id pattern or seed."""
+    # If task_id has an explicit difficulty prefix, use it
+    if task_id.startswith("easy_") or task_id.startswith("gen_easy_"):
+        return "easy"
+    if task_id.startswith("medium_") or task_id.startswith("gen_medium_"):
+        return "medium"
+    if task_id.startswith("hard_") or task_id.startswith("gen_hard_"):
+        return "hard"
+
+    # For gen_NNNN pattern, use number ranges
+    if task_id.startswith("gen_"):
+        try:
+            num = int(task_id.split("_")[1])
+            if num <= 333:
+                return "easy"
+            elif num <= 666:
+                return "medium"
+            else:
+                return "hard"
+        except (ValueError, IndexError):
+            pass
+
+    # Fallback: use seed-based distribution
+    return rng.choice(["easy", "medium", "hard"])
+
+
+# =============================================================================
+# Core Generator
+# =============================================================================
+
+def _pick_hosts(rng: random.Random, subnet: str, count: int) -> List[str]:
+    """Pick `count` unique host names from a subnet."""
+    info = SUBNETS[subnet]
+    prefix = info["prefix"]
+    max_idx = info["count"]
+    indices = rng.sample(range(1, max_idx + 1), min(count, max_idx))
+    return [f"{prefix}-{idx:03d}" for idx in indices]
+
+
+def _pick_subnets(rng: random.Random, count: int) -> List[str]:
+    """Pick `count` unique subnet names."""
+    all_subnets = list(SUBNETS.keys())
+    return rng.sample(all_subnets, min(count, len(all_subnets)))
+
+
+def _generate_threat(
+    rng: random.Random,
+    threat_id: str,
+    attack_type: str,
+    phase: str,
+    available_subnets: List[str],
+    used_hosts: set,
+) -> Tuple[Dict[str, Any], List[str]]:
+    """Generate a single threat in the attack chain.
+
+    Returns:
+        (threat_dict, list_of_compromised_hosts)
+    """
+    # Pick target subnet and hosts
+    subnet = rng.choice(available_subnets)
+    num_hosts = rng.randint(1, 3) if attack_type != "ransomware" else rng.randint(1, 2)
+
+    hosts = _pick_hosts(rng, subnet, num_hosts + 3)  # Pick extra to avoid collisions
+    hosts = [h for h in hosts if h not in used_hosts][:num_hosts]
+    if not hosts:
+        # Fallback: pick from any subnet
+        fallback_subnet = rng.choice(list(SUBNETS.keys()))
+        hosts = _pick_hosts(rng, fallback_subnet, num_hosts + 5)
+        hosts = [h for h in hosts if h not in used_hosts][:max(1, num_hosts)]
+
+    # Pick malware process
+    procs = MALWARE_PROCESSES.get(attack_type, MALWARE_PROCESSES["lateral_movement"])
+    proc = rng.choice(procs)
+
+    # Generate IOCs
+    num_hashes = rng.randint(1, 2)
+    hashes = [_make_hash(rng) for _ in range(num_hashes)]
+
+    num_ips = rng.randint(0, 2) if attack_type in ("c2_communication", "data_exfiltration", "cryptomining", "botnet") else rng.randint(0, 1)
+    ips = rng.sample(C2_IPS, min(num_ips, len(C2_IPS))) if num_ips > 0 else []
+
+    num_domains = rng.randint(0, 2) if attack_type in ("c2_communication", "phishing", "supply_chain", "botnet") else rng.randint(0, 1)
+    domains = rng.sample(C2_DOMAINS, min(num_domains, len(C2_DOMAINS))) if num_domains > 0 else []
+
+    # C2 servers (subset of IPs for c2/exfil types)
+    c2_servers = ips[:1] if attack_type in ("c2_communication", "data_exfiltration", "botnet") else []
+
+    # Lateral targets (for movement-type threats)
+    lateral_targets: List[str] = []
+    if attack_type in ("lateral_movement", "credential_theft", "c2_communication"):
+        lat_subnet = rng.choice(list(SUBNETS.keys()))
+        lat_hosts = _pick_hosts(rng, lat_subnet, 2)
+        lateral_targets = [h for h in lat_hosts if h not in used_hosts and h not in hosts][:rng.randint(0, 2)]
+
+    # Exfil targets
+    exfil_targets: List[str] = []
+    if attack_type == "data_exfiltration":
+        exfil_targets = list(hosts)
+
+    threat = {
+        "threat_id": threat_id,
+        "threat_type": attack_type,
+        "phase": phase,
+        "compromised_hosts": hosts,
+        "malicious_processes": [proc],
+        "c2_servers": c2_servers,
+        "iocs": {
+            "hashes": hashes,
+            "ips": ips,
+            "domains": domains,
+        },
+        "lateral_targets": lateral_targets,
+        "exfil_targets": exfil_targets,
+    }
+
+    return threat, hosts
+
+
+def _generate_alert(
+    rng: random.Random,
+    alert_idx: int,
+    task_prefix: str,
+    threat: Dict[str, Any],
+    timestamp_base: int,
+) -> Dict[str, Any]:
+    """Generate a single SIEM alert for a threat."""
+    attack_type = threat["threat_type"]
+    host = rng.choice(threat["compromised_hosts"])
+    proc = threat["malicious_processes"][0]
+
+    # Pick template
+    templates = ALERT_TEMPLATES.get(attack_type, ALERT_TEMPLATES["lateral_movement"])
+    template = rng.choice(templates)
+
+    # Fill template
+    description = template.format(
+        host=host,
+        proc=proc,
+        domain=rng.choice(threat["iocs"]["domains"]) if threat["iocs"]["domains"] else "unknown.example.com",
+        ip=rng.choice(threat["iocs"]["ips"]) if threat["iocs"]["ips"] else "0.0.0.0",
+        count=rng.randint(50, 500),
+        ext=rng.choice(RANSOM_EXTENSIONS),
+        secs=rng.randint(10, 120),
+        interval=rng.choice([30, 60, 90, 120, 300]),
+        size=round(rng.uniform(0.5, 15.0), 1),
+        data_type=rng.choice(DATA_TYPES),
+        port=rng.choice([3333, 4444, 5555, 8080, 8443, 9090]),
+    )
+
+    # Collect IOC indicators for the alert
+    ioc_indicators = []
+    if threat["iocs"]["hashes"]:
+        ioc_indicators.append(rng.choice(threat["iocs"]["hashes"]))
+    if threat["iocs"]["ips"]:
+        ioc_indicators.append(rng.choice(threat["iocs"]["ips"]))
+    if threat["iocs"]["domains"]:
+        ioc_indicators.append(rng.choice(threat["iocs"]["domains"]))
+
+    # Determine subnet from host prefix
+    subnet = "corporate"
+    for sn, info in SUBNETS.items():
+        if host.startswith(info["prefix"]):
+            subnet = sn
+            break
+
+    # Severity
+    severity_weights = SEVERITY_WEIGHTS.get(
+        "hard" if attack_type in ("data_exfiltration", "ransomware", "privilege_escalation") else "medium",
+        SEVERITY_WEIGHTS["medium"]
+    )
+    severity = rng.choices(SEVERITIES, weights=severity_weights, k=1)[0]
+
+    # Timestamp (spread across a few hours)
+    minutes_offset = timestamp_base + alert_idx * rng.randint(5, 45)
+    hour = 6 + (minutes_offset // 60)
+    minute = minutes_offset % 60
+    timestamp = f"2025-01-15T{hour:02d}:{minute:02d}:00Z"
+
+    return {
+        "alert_id": f"ALERT-{task_prefix}{alert_idx + 1:03d}",
+        "timestamp": timestamp,
+        "source_host": host,
+        "severity": severity,
+        "threat_type": attack_type,
+        "description": description,
+        "ioc_indicators": ioc_indicators,
+        "subnet": subnet,
+        "is_acknowledged": False,
+    }
+
+
+# =============================================================================
+# Main Generator Function
+# =============================================================================
+
+def generate_task(task_id: str, eval_mode: bool = False) -> Dict[str, Any]:
+    """Generate a complete, deterministic task definition from a task_id.
+
+    The task_id is hashed to create a seed, ensuring the same task_id
+    always produces the exact same scenario.
+
+    Args:
+        task_id: Any string (e.g. 'gen_0001', 'gen_0500', 'phishing_test')
+
+    Returns:
+        A task_def dict compatible with CyberSOCEnvironment.reset()
+    """
+    seed_offset = 0
+    # Add offset if eval_mode to ensure different data for same ID format
+    if eval_mode:
+        seed_offset += 10000
+
+    while True:
+        seed = _seed_from_task_id(task_id) + seed_offset
+        rng = random.Random(seed)
+
+        # Determine difficulty
+        difficulty = _get_difficulty(task_id, rng)
+
+        # Configure parameters based on difficulty
+        if difficulty == "easy":
+            num_threats = 1
+            max_steps = rng.randint(12, 18)
+            initial_impact = round(rng.uniform(0.02, 0.08), 2)
+            impact_per_step = round(rng.uniform(0.01, 0.03), 3)
+            num_subnets = rng.randint(1, 2)
+        elif difficulty == "medium":
+            num_threats = rng.randint(2, 3)
+            max_steps = rng.randint(20, 28)
+            initial_impact = round(rng.uniform(0.08, 0.15), 2)
+            impact_per_step = round(rng.uniform(0.02, 0.04), 3)
+            num_subnets = rng.randint(2, 4)
+        else:  # hard
+            num_threats = rng.randint(3, 6)
+            max_steps = rng.randint(25, 35)
+            initial_impact = round(rng.uniform(0.15, 0.25), 2)
+            impact_per_step = round(rng.uniform(0.03, 0.05), 3)
+            num_subnets = rng.randint(3, 6)
+
+        # Pick attack types for this scenario
+        all_attack_types = list(MALWARE_PROCESSES.keys())
+        if difficulty == "easy":
+            # Easy: single focused attack
+            attack_types = [rng.choice(all_attack_types)]
+        elif difficulty == "medium":
+            # Medium: multi-stage, pick a plausible chain
+            chains = [
+                ["phishing", "credential_theft", "lateral_movement"],
+                ["phishing", "c2_communication", "data_exfiltration"],
+                ["webshell", "privilege_escalation", "lateral_movement"],
+                ["supply_chain", "c2_communication", "credential_theft"],
+                ["botnet", "cryptomining", "lateral_movement"],
+                ["insider_threat", "data_exfiltration"],
+            ]
+            chain = rng.choice(chains)
+            attack_types = chain[:num_threats]
+        else:
+            # Hard: complex multi-phase APT
+            chains = [
+                ["phishing", "c2_communication", "privilege_escalation", "data_exfiltration", "ransomware"],
+                ["supply_chain", "c2_communication", "lateral_movement", "credential_theft", "data_exfiltration", "ransomware"],
+                ["webshell", "privilege_escalation", "c2_communication", "lateral_movement", "data_exfiltration"],
+                ["phishing", "credential_theft", "lateral_movement", "cryptomining", "botnet"],
+                ["insider_threat", "privilege_escalation", "data_exfiltration", "c2_communication"],
+                ["botnet", "lateral_movement", "privilege_escalation", "ransomware", "data_exfiltration"],
+            ]
+            chain = rng.choice(chains)
+            attack_types = chain[:num_threats]
+
+        # Re-roll if incompatible threats are chosen
+        if any((t1, t2) in INCOMPATIBLE_THREATS or (t2, t1) in INCOMPATIBLE_THREATS
+               for t1, t2 in itertools.combinations(attack_types, 2)):
+            seed_offset += 1
+            continue
+
+        # Pick subnets involved
+        involved_subnets = _pick_subnets(rng, num_subnets)
+
+        # Generate attack chain
+        attack_chain: List[Dict[str, Any]] = []
+        used_hosts: set = set()
+        task_prefix = task_id.replace("gen_", "G").upper()[:6]
+
+        for i, attack_type in enumerate(attack_types):
+            phase_idx = min(i, len(ATTACK_PHASES) - 1)
+            # Use realistic phase based on attack type
+            phase_map = {
+                "phishing": "initial_access",
+                "webshell": "initial_access",
+                "supply_chain": "initial_access",
+                "credential_theft": "credential_access",
+                "privilege_escalation": "privilege_escalation",
+                "lateral_movement": "lateral_movement",
+                "c2_communication": "command_and_control",
+                "data_exfiltration": "exfiltration",
+                "ransomware": "impact",
+                "cryptomining": "impact",
+                "insider_threat": "exfiltration",
+                "botnet": "command_and_control",
+            }
+            phase = phase_map.get(attack_type, ATTACK_PHASES[phase_idx])
+
+            threat_id = f"T-{task_prefix}-{i + 1:03d}"
+            threat, new_hosts = _generate_threat(
+                rng, threat_id, attack_type, phase, involved_subnets, used_hosts
+            )
+            attack_chain.append(threat)
+            used_hosts.update(new_hosts)
+
+        # Generate alerts (1-2 per threat)
+        initial_alerts: List[Dict[str, Any]] = []
+        timestamp_base = rng.randint(0, 60)
+        for i, threat in enumerate(attack_chain):
+            num_alerts = rng.randint(1, 2)
+            for j in range(num_alerts):
+                alert = _generate_alert(
+                    rng, len(initial_alerts), task_prefix, threat, timestamp_base
+                )
+                initial_alerts.append(alert)
+
+        # Generate containment requirements
+        must_kill = []
+        must_block_iocs = []
+        must_forensics = []
+        must_not_isolate = []
+
+        for threat in attack_chain:
+            for host in threat["compromised_hosts"]:
+                for proc in threat["malicious_processes"]:
+                    must_kill.append({"hostname": host, "process": proc})
+                if host not in must_forensics:
+                    must_forensics.append(host)
+
+            # Collect all IOCs as required blocks
+            for h in threat["iocs"]["hashes"]:
+                if h not in must_block_iocs:
+                    must_block_iocs.append(h)
+            for ip in threat["iocs"]["ips"]:
+                if ip not in must_block_iocs:
+                    must_block_iocs.append(ip)
+            for d in threat["iocs"]["domains"]:
+                if d not in must_block_iocs:
+                    must_block_iocs.append(d)
+
+        # Subnets that should NOT be isolated (business-critical ones not in the attack)
+        non_involved = [s for s in SUBNETS if s not in involved_subnets]
+        if difficulty == "easy":
+            must_not_isolate = non_involved
+        elif difficulty == "medium":
+            must_not_isolate = [s for s in non_involved if SUBNETS[s]["criticality"] >= 0.8]
+
+        # Build description
+        type_names = list(set(t["threat_type"] for t in attack_chain))
+        host_count = len(used_hosts)
+        desc = (
+            f"[{difficulty.upper()}] {', '.join(type_names).replace('_', ' ').title()} "
+            f"across {host_count} host(s) in {', '.join(involved_subnets)}."
+        )
+
+        task_def = {
+            "description": desc,
+            "max_steps": max_steps,
+            "initial_business_impact": initial_impact,
+            "impact_per_step": impact_per_step,
+            "attack_chain": attack_chain,
+            "initial_alerts": initial_alerts,
+            "optimal_actions": [
+                "run_forensics", "kill_process", "block_ioc", "submit_containment_plan"
+            ],
+            "containment_requirements": {
+                "must_kill": must_kill,
+                "must_block_iocs": must_block_iocs,
+                "must_forensics": must_forensics,
+                "must_not_isolate": must_not_isolate,
+            },
+        }
+
+        errors = validate_task_def(task_def)
+        if not errors:
+            return task_def
+
+        # If validation fails, try again with a different seed
+        seed_offset += 1
+
+
+# =============================================================================
+# Batch Generation (for openenv.yaml and validation)
+# =============================================================================
+
+def list_generated_task_ids(count: int = 1000) -> List[str]:
+    """Return the list of generated task IDs."""
+    return [f"gen_{i:04d}" for i in range(1, count + 1)]
+
+
+def get_task_summary(task_id: str) -> Dict[str, str]:
+    """Get a short summary of a generated task (for openenv.yaml)."""
+    task_def = generate_task(task_id)
+    difficulty = _get_difficulty(task_id, random.Random(_seed_from_task_id(task_id)))
+    return {
+        "description": task_def["description"],
+        "max_steps": task_def["max_steps"],
+        "difficulty": difficulty,
+    }

server/tasks.py

@@ -0,0 +1,530 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Deterministic task definitions for CyberSOCEnv.
+
+Each task defines a fixed attack chain, network layout, and expected
+containment actions. No randomness — every run of the same task_id
+produces identical initial state.
+
+Tasks:
+    - easy:   Single ransomware endpoint on the corporate subnet.
+    - medium: Multi-stage lateral movement (phishing -> cred theft -> 3 subnets).
+    - hard:   APT + ransomware with C2, exfiltration, and executive pressure.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+
+# =============================================================================
+# Network Topology Builder (deterministic, 500-node)
+# =============================================================================
+
+def _build_subnet(
+    name: str,
+    role: str,
+    prefix: str,
+    ip_base: str,
+    count: int,
+    start_idx: int,
+    criticality: float,
+    default_ports: List[int],
+    default_procs: List[str],
+) -> List[Dict[str, Any]]:
+    """Build a list of host dicts for a subnet."""
+    hosts = []
+    for i in range(count):
+        idx = start_idx + i
+        hosts.append({
+            "hostname": f"{prefix}-{idx:03d}",
+            "ip_address": f"{ip_base}.{idx}",
+            "subnet": name,
+            "role": role,
+            "status": "online",
+            "running_processes": list(default_procs),
+            "open_ports": list(default_ports),
+            "criticality": criticality,
+        })
+    return hosts
+
+
+def build_network() -> Dict[str, List[Dict[str, Any]]]:
+    """Build the deterministic enterprise network (~50 active hosts).
+
+    Reduced from 400 to ~50 nodes for GRPO training throughput (target ≥8 eps/min).
+    Host indices are chosen to cover all hand-crafted task references (WS-042, WS-088,
+    DEV-033, FIN-008, FIN-012, SRV-002..SRV-015, EXEC-003) plus a small buffer for
+    procedural generation and lateral pivot targets. The README still describes a
+    "500-node enterprise" — the simulation covers the same topology, but only
+    materializes the operationally relevant hosts.
+
+    Returns:
+        Dict mapping subnet name -> list of host dicts.
+    """
+    network: Dict[str, List[Dict[str, Any]]] = {}
+
+    # Corporate: WS-001..WS-005 (buffer) + WS-015..WS-020 (covers WS-017)
+    #            + WS-040..WS-045 (covers WS-042) + WS-085..WS-090 (covers WS-088)
+    corporate: List[Dict[str, Any]] = []
+    for start, count in [(1, 5), (15, 6), (40, 6), (85, 6)]:
+        corporate.extend(_build_subnet(
+            name="corporate", role="corporate", prefix="WS",
+            ip_base="10.1.1", count=count, start_idx=start,
+            criticality=0.3,
+            default_ports=[135, 445, 3389],
+            default_procs=["outlook.exe", "chrome.exe", "explorer.exe"],
+        ))
+    network["corporate"] = corporate  # 23 hosts
+
+    # Engineering: DEV-001..DEV-005 + DEV-030..DEV-036 (covers DEV-033)
+    engineering: List[Dict[str, Any]] = []
+    for start, count in [(1, 5), (30, 7)]:
+        engineering.extend(_build_subnet(
+            name="engineering", role="engineering", prefix="DEV",
+            ip_base="10.2.1", count=count, start_idx=start,
+            criticality=0.5,
+            default_ports=[22, 443, 8080, 3389],
+            default_procs=["vscode.exe", "python.exe", "docker.exe", "git.exe"],
+        ))
+    network["engineering"] = engineering  # 12 hosts
+
+    # Finance: FIN-001..FIN-005 + FIN-008..FIN-014 (covers FIN-008, FIN-012)
+    finance: List[Dict[str, Any]] = []
+    for start, count in [(1, 5), (8, 7)]:
+        finance.extend(_build_subnet(
+            name="finance", role="finance", prefix="FIN",
+            ip_base="10.3.1", count=count, start_idx=start,
+            criticality=0.8,
+            default_ports=[443, 1433, 3389],
+            default_procs=["excel.exe", "sap.exe", "sqlcmd.exe"],
+        ))
+    network["finance"] = finance  # 12 hosts
+
+    # DMZ: DMZ-001..DMZ-003 (no tasks reference DMZ hosts)
+    network["dmz"] = _build_subnet(
+        name="dmz", role="dmz", prefix="DMZ",
+        ip_base="10.4.1", count=3, start_idx=1,
+        criticality=0.6,
+        default_ports=[80, 443, 8443],
+        default_procs=["nginx", "node", "java"],
+    )  # 3 hosts
+
+    # Datacenter: SRV-001..SRV-020 (covers SRV-002, SRV-005, SRV-010, SRV-015)
+    network["datacenter"] = _build_subnet(
+        name="datacenter", role="datacenter", prefix="SRV",
+        ip_base="10.5.1", count=20, start_idx=1,
+        criticality=0.9,
+        default_ports=[22, 443, 5432, 6379, 9200],
+        default_procs=["postgres", "redis-server", "elasticsearch", "kubelet"],
+    )  # 20 hosts
+
+    # Executive: EXEC-001..EXEC-005 (covers EXEC-003)
+    network["executive"] = _build_subnet(
+        name="executive", role="executive", prefix="EXEC",
+        ip_base="10.6.1", count=5, start_idx=1,
+        criticality=1.0,
+        default_ports=[443, 3389],
+        default_procs=["outlook.exe", "teams.exe", "chrome.exe"],
+    )  # 5 hosts
+
+    return network  # Total: ~75 hosts
+
+
+# =============================================================================
+# Attack Chain Definitions
+# =============================================================================
+
+TASKS: Dict[str, Dict[str, Any]] = {
+    # ----- EASY: Single ransomware endpoint -----
+    "easy": {
+        "description": "Ransomware detected on a single corporate workstation. Isolate and contain.",
+        "max_steps": 15,
+        "initial_business_impact": 0.05,
+        "impact_per_step": 0.02,  # Impact grows slowly per step
+        "attack_chain": [
+            {
+                "threat_id": "T-EASY-001",
+                "threat_type": "ransomware",
+                "phase": "execution",
+                "compromised_hosts": ["WS-042"],
+                "malicious_processes": ["cryptolocker.exe"],
+                "c2_servers": [],
+                "iocs": {
+                    "hashes": ["e99a18c428cb38d5f260853678922e03"],
+                    "ips": [],
+                    "domains": [],
+                },
+                "lateral_targets": [],
+                "exfil_targets": [],
+            },
+        ],
+        "initial_alerts": [
+            {
+                "alert_id": "ALERT-E001",
+                "timestamp": "2025-01-15T09:23:17Z",
+                "source_host": "WS-042",
+                "severity": "critical",
+                "threat_type": "ransomware",
+                "description": "EDR detected file encryption activity on WS-042. Process 'cryptolocker.exe' is encrypting files in C:\\Users\\jsmith\\Documents.",
+                "ioc_indicators": ["e99a18c428cb38d5f260853678922e03"],
+                "subnet": "corporate",
+                "is_acknowledged": False,
+            },
+            {
+                "alert_id": "ALERT-E002",
+                "timestamp": "2025-01-15T09:23:45Z",
+                "source_host": "WS-042",
+                "severity": "high",
+                "threat_type": "ransomware",
+                "description": "Anomalous file system activity: 147 files renamed with .locked extension in 28 seconds.",
+                "ioc_indicators": [],
+                "subnet": "corporate",
+                "is_acknowledged": False,
+            },
+        ],
+        # Optimal containment: kill process, run forensics, block hash, submit plan
+        "optimal_actions": ["kill_process", "run_forensics", "block_ioc", "submit_containment_plan"],
+        "containment_requirements": {
+            "must_kill": [{"hostname": "WS-042", "process": "cryptolocker.exe"}],
+            "must_block_iocs": ["e99a18c428cb38d5f260853678922e03"],
+            "must_forensics": ["WS-042"],
+            "must_not_isolate": ["finance", "engineering", "datacenter"],  # Unnecessary isolation = downtime
+        },
+    },
+
+    # ----- MEDIUM: Multi-stage lateral movement -----
+    "medium": {
+        "description": "Phishing attack led to credential theft and lateral movement across 3 subnets.",
+        "max_steps": 25,
+        "initial_business_impact": 0.10,
+        "impact_per_step": 0.03,
+        "attack_chain": [
+            {
+                "threat_id": "T-MED-001",
+                "threat_type": "phishing",
+                "phase": "initial_access",
+                "compromised_hosts": ["WS-017"],
+                "malicious_processes": ["powershell.exe"],
+                "c2_servers": [],
+                "iocs": {
+                    "hashes": ["d41d8cd98f00b204e9800998ecf8427e"],
+                    "ips": [],
+                    "domains": ["evil-login.example.com"],
+                },
+                "lateral_targets": [],
+                "exfil_targets": [],
+            },
+            {
+                "threat_id": "T-MED-002",
+                "threat_type": "credential_theft",
+                "phase": "credential_access",
+                "compromised_hosts": ["WS-017"],
+                "malicious_processes": ["mimikatz.exe"],
+                "c2_servers": [],
+                "iocs": {
+                    "hashes": ["aabbccdd11223344eeff5566778899aa"],
+                    "ips": [],
+                    "domains": [],
+                },
+                "lateral_targets": ["DEV-033", "FIN-012"],
+                "exfil_targets": [],
+            },
+            {
+                "threat_id": "T-MED-003",
+                "threat_type": "lateral_movement",
+                "phase": "lateral_movement",
+                "compromised_hosts": ["DEV-033", "FIN-012"],
+                "malicious_processes": ["svchost_backdoor.exe"],
+                "c2_servers": [],
+                "iocs": {
+                    "hashes": ["112233445566778899aabbccddeeff00"],
+                    "ips": ["203.0.113.50"],
+                    "domains": [],
+                },
+                "lateral_targets": ["SRV-005"],
+                "exfil_targets": [],
+            },
+        ],
+        "initial_alerts": [
+            {
+                "alert_id": "ALERT-M001",
+                "timestamp": "2025-01-15T08:15:00Z",
+                "source_host": "WS-017",
+                "severity": "medium",
+                "threat_type": "phishing",
+                "description": "User clicked suspicious link in email. PowerShell execution detected downloading payload from evil-login.example.com.",
+                "ioc_indicators": ["evil-login.example.com"],
+                "subnet": "corporate",
+                "is_acknowledged": False,
+            },
+            {
+                "alert_id": "ALERT-M002",
+                "timestamp": "2025-01-15T08:32:00Z",
+                "source_host": "WS-017",
+                "severity": "high",
+                "threat_type": "credential_theft",
+                "description": "LSASS memory access detected — possible credential dumping via Mimikatz.",
+                "ioc_indicators": ["aabbccdd11223344eeff5566778899aa"],
+                "subnet": "corporate",
+                "is_acknowledged": False,
+            },
+            {
+                "alert_id": "ALERT-M003",
+                "timestamp": "2025-01-15T09:05:00Z",
+                "source_host": "DEV-033",
+                "severity": "high",
+                "threat_type": "lateral_movement",
+                "description": "Suspicious RDP login from WS-017 using admin credentials. New process svchost_backdoor.exe spawned.",
+                "ioc_indicators": ["203.0.113.50", "112233445566778899aabbccddeeff00"],
+                "subnet": "engineering",
+                "is_acknowledged": False,
+            },
+            {
+                "alert_id": "ALERT-M004",
+                "timestamp": "2025-01-15T09:12:00Z",
+                "source_host": "FIN-012",
+                "severity": "critical",
+                "threat_type": "lateral_movement",
+                "description": "Unauthorized access to FIN-012 from compromised credentials. Backdoor process active.",
+                "ioc_indicators": ["112233445566778899aabbccddeeff00"],
+                "subnet": "finance",
+                "is_acknowledged": False,
+            },
+        ],
+        "optimal_actions": [
+            "query_host", "run_forensics", "kill_process", "block_ioc",
+            "isolate_segment", "run_forensics", "submit_containment_plan",
+        ],
+        "containment_requirements": {
+            "must_kill": [
+                {"hostname": "WS-017", "process": "powershell.exe"},
+                {"hostname": "WS-017", "process": "mimikatz.exe"},
+                {"hostname": "DEV-033", "process": "svchost_backdoor.exe"},
+                {"hostname": "FIN-012", "process": "svchost_backdoor.exe"},
+            ],
+            "must_block_iocs": [
+                "evil-login.example.com",
+                "203.0.113.50",
+                "d41d8cd98f00b204e9800998ecf8427e",
+                "aabbccdd11223344eeff5566778899aa",
+                "112233445566778899aabbccddeeff00",
+            ],
+            "must_forensics": ["WS-017", "DEV-033", "FIN-012"],
+            "must_not_isolate": ["executive", "datacenter"],
+        },
+    },
+
+    # ----- HARD: APT + Ransomware, C2, exfiltration, executive pressure -----
+    "hard": {
+        "description": "Advanced Persistent Threat with active C2 comms, data exfiltration in progress, and ransomware deployment imminent. Board is watching — minimize downtime.",
+        "max_steps": 30,
+        "initial_business_impact": 0.20,
+        "impact_per_step": 0.04,
+        "attack_chain": [
+            {
+                "threat_id": "T-HARD-001",
+                "threat_type": "phishing",
+                "phase": "initial_access",
+                "compromised_hosts": ["EXEC-003"],
+                "malicious_processes": ["outlook_macro.exe"],
+                "c2_servers": ["198.51.100.77"],
+                "iocs": {
+                    "hashes": ["deadbeef0123456789abcdef01234567"],
+                    "ips": ["198.51.100.77"],
+                    "domains": ["cdn-update.malware-c2.net"],
+                },
+                "lateral_targets": ["WS-088"],
+                "exfil_targets": [],
+            },
+            {
+                "threat_id": "T-HARD-002",
+                "threat_type": "c2_communication",
+                "phase": "command_and_control",
+                "compromised_hosts": ["EXEC-003", "WS-088"],
+                "malicious_processes": ["svchost_c2.exe"],
+                "c2_servers": ["198.51.100.77"],
+                "iocs": {
+                    "hashes": ["cafebabe9876543210fedcba98765432"],
+                    "ips": ["198.51.100.77"],
+                    "domains": ["cdn-update.malware-c2.net", "exfil.malware-c2.net"],
+                },
+                "lateral_targets": ["SRV-002", "FIN-008"],
+                "exfil_targets": [],
+            },
+            {
+                "threat_id": "T-HARD-003",
+                "threat_type": "privilege_escalation",
+                "phase": "privilege_escalation",
+                "compromised_hosts": ["SRV-002"],
+                "malicious_processes": ["exploit_kernel.exe"],
+                "c2_servers": ["198.51.100.77"],
+                "iocs": {
+                    "hashes": ["1122334455667788aabbccddeeff0011"],
+                    "ips": ["198.51.100.77"],
+                    "domains": [],
+                },
+                "lateral_targets": ["SRV-010", "SRV-015"],
+                "exfil_targets": ["SRV-002"],
+            },
+            {
+                "threat_id": "T-HARD-004",
+                "threat_type": "data_exfiltration",
+                "phase": "exfiltration",
+                "compromised_hosts": ["SRV-002", "FIN-008"],
+                "malicious_processes": ["data_pump.exe"],
+                "c2_servers": ["198.51.100.77"],
+                "iocs": {
+                    "hashes": ["ffeeddccbbaa99887766554433221100"],
+                    "ips": ["198.51.100.77", "203.0.113.99"],
+                    "domains": ["exfil.malware-c2.net"],
+                },
+                "lateral_targets": [],
+                "exfil_targets": ["SRV-002", "FIN-008"],
+            },
+            {
+                "threat_id": "T-HARD-005",
+                "threat_type": "ransomware",
+                "phase": "impact",
+                "compromised_hosts": ["SRV-010", "SRV-015"],
+                "malicious_processes": ["blackcat_ransom.exe"],
+                "c2_servers": [],
+                "iocs": {
+                    "hashes": ["aabb0011ccdd2233eeff4455667788"],
+                    "ips": [],
+                    "domains": [],
+                },
+                "lateral_targets": [],
+                "exfil_targets": [],
+            },
+        ],
+        "initial_alerts": [
+            {
+                "alert_id": "ALERT-H001",
+                "timestamp": "2025-01-15T06:00:00Z",
+                "source_host": "EXEC-003",
+                "severity": "medium",
+                "threat_type": "phishing",
+                "description": "Executive VP opened macro-enabled document. Outbound connection to cdn-update.malware-c2.net detected.",
+                "ioc_indicators": ["cdn-update.malware-c2.net", "198.51.100.77"],
+                "subnet": "executive",
+                "is_acknowledged": False,
+            },
+            {
+                "alert_id": "ALERT-H002",
+                "timestamp": "2025-01-15T06:45:00Z",
+                "source_host": "WS-088",
+                "severity": "high",
+                "threat_type": "c2_communication",
+                "description": "Periodic beaconing detected to 198.51.100.77 every 60 seconds. Encrypted payload exchange observed.",
+                "ioc_indicators": ["198.51.100.77", "cafebabe9876543210fedcba98765432"],
+                "subnet": "corporate",
+                "is_acknowledged": False,
+            },
+            {
+                "alert_id": "ALERT-H003",
+                "timestamp": "2025-01-15T07:30:00Z",
+                "source_host": "SRV-002",
+                "severity": "critical",
+                "threat_type": "privilege_escalation",
+                "description": "Kernel exploit attempt on SRV-002 (database server). Process exploit_kernel.exe gained SYSTEM privileges.",
+                "ioc_indicators": ["1122334455667788aabbccddeeff0011"],
+                "subnet": "datacenter",
+                "is_acknowledged": False,
+            },
+            {
+                "alert_id": "ALERT-H004",
+                "timestamp": "2025-01-15T08:00:00Z",
+                "source_host": "SRV-002",
+                "severity": "critical",
+                "threat_type": "data_exfiltration",
+                "description": "Large data transfer (2.3 GB) to external IP 203.0.113.99 from database server SRV-002. Possible exfiltration of customer PII.",
+                "ioc_indicators": ["203.0.113.99", "exfil.malware-c2.net"],
+                "subnet": "datacenter",
+                "is_acknowledged": False,
+            },
+            {
+                "alert_id": "ALERT-H005",
+                "timestamp": "2025-01-15T08:10:00Z",
+                "source_host": "FIN-008",
+                "severity": "critical",
+                "threat_type": "data_exfiltration",
+                "description": "Financial records being staged for exfiltration on FIN-008. Process data_pump.exe accessing sensitive directories.",
+                "ioc_indicators": ["ffeeddccbbaa99887766554433221100"],
+                "subnet": "finance",
+                "is_acknowledged": False,
+            },
+            {
+                "alert_id": "ALERT-H006",
+                "timestamp": "2025-01-15T08:30:00Z",
+                "source_host": "SRV-010",
+                "severity": "critical",
+                "threat_type": "ransomware",
+                "description": "BlackCat ransomware deployment detected on SRV-010! File encryption starting on production storage.",
+                "ioc_indicators": ["aabb0011ccdd2233eeff4455667788"],
+                "subnet": "datacenter",
+                "is_acknowledged": False,
+            },
+        ],
+        "optimal_actions": [
+            "block_ioc", "kill_process", "run_forensics", "isolate_segment",
+            "kill_process", "block_ioc", "run_forensics", "kill_process",
+            "submit_containment_plan",
+        ],
+        "containment_requirements": {
+            "must_kill": [
+                {"hostname": "EXEC-003", "process": "outlook_macro.exe"},
+                {"hostname": "EXEC-003", "process": "svchost_c2.exe"},
+                {"hostname": "WS-088", "process": "svchost_c2.exe"},
+                {"hostname": "SRV-002", "process": "exploit_kernel.exe"},
+                {"hostname": "SRV-002", "process": "data_pump.exe"},
+                {"hostname": "FIN-008", "process": "data_pump.exe"},
+                {"hostname": "SRV-010", "process": "blackcat_ransom.exe"},
+                {"hostname": "SRV-015", "process": "blackcat_ransom.exe"},
+            ],
+            "must_block_iocs": [
+                "198.51.100.77",
+                "203.0.113.99",
+                "cdn-update.malware-c2.net",
+                "exfil.malware-c2.net",
+                "deadbeef0123456789abcdef01234567",
+                "cafebabe9876543210fedcba98765432",
+            ],
+            "must_forensics": ["EXEC-003", "WS-088", "SRV-002", "FIN-008", "SRV-010"],
+            "must_not_isolate": [],  # In APT scenario, any isolation decision is valid
+        },
+    },
+}
+
+
+def get_task(task_id: str) -> Dict[str, Any]:
+    """Retrieve a task definition by ID.
+
+    Supports:
+        - 'easy', 'medium', 'hard': Hand-crafted curated benchmarks
+        - 'gen_0001' through 'gen_1000': Procedurally generated scenarios
+        - Any other string: Generated on-the-fly via seeded procedural generation
+
+    Args:
+        task_id: Task identifier string.
+
+    Returns:
+        Task definition dict.
+    """
+    # Check hand-crafted tasks first
+    if task_id in TASKS:
+        return TASKS[task_id]
+
+    # Fall back to procedural generation
+    try:
+        from .task_generator import generate_task
+    except ImportError:
+        from server.task_generator import generate_task
+
+    return generate_task(task_id)
+

server/threat_graph.py

@@ -0,0 +1,207 @@
+"""ThreatGraph — typed knowledge graph of SOC entities, edges, and evidence."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class HostNode(BaseModel):
+    hostname: str
+    subnet: str
+    business_criticality: Literal["low", "medium", "high", "critical"]
+    status: Literal["healthy", "suspicious", "compromised", "isolated", "contained"]
+    first_seen_suspicious: Optional[datetime] = None
+    scanned: bool = False
+
+
+class ProcessNode(BaseModel):
+    process_id: str  # format: "hostname:pid"
+    hostname: str
+    process_name: str
+    killed: bool = False
+
+
+class IOCNode(BaseModel):
+    ioc_value: str
+    ioc_type: Literal["ip", "domain", "hash", "filename"]
+    confidence: float
+    blocked: bool = False
+    enriched: bool = False
+    threat_actor: Optional[str] = None
+    mitre_ttps: list[str] = Field(default_factory=list)
+
+
+class VulnerabilityNode(BaseModel):
+    cve_id: str
+    hostname: str
+    cvss_score: float
+    exploitability: Literal["active", "theoretical", "patched"]
+    patch_available: bool
+    exploited_by_threat: Optional[str] = None
+
+
+class AlertNode(BaseModel):
+    alert_id: str
+    severity: Literal["low", "medium", "high", "critical"]
+    priority_score: float
+    source_host: str
+    correlated_with: list[str] = Field(default_factory=list)
+
+
+class Edge(BaseModel):
+    edge_type: Literal[
+        "runs_on", "involves", "communicates_with",
+        "pivoted_from", "part_of_chain", "exploits",
+    ]
+    source_id: str
+    target_id: str
+    evidence: dict = Field(default_factory=dict)
+
+
+MAX_GRAPH_NODES = 200
+
+
+class ThreatGraph:
+    def __init__(self):
+        self.hosts: dict[str, HostNode] = {}
+        self.processes: dict[str, ProcessNode] = {}
+        self.iocs: dict[str, IOCNode] = {}
+        self.vulnerabilities: dict[str, VulnerabilityNode] = {}
+        self.alerts: dict[str, AlertNode] = {}
+        self.edges: list[Edge] = []
+        self.version: int = 0
+        # changelog entries: (version_after_add, entity_type, entity_id)
+        self._changelog: list[tuple[int, str, str]] = []
+        # insertion-order tracking for IOC pruning (oldest first)
+        self._ioc_insertion_order: list[str] = []
+
+    def _total_nodes(self) -> int:
+        return (
+            len(self.hosts) + len(self.processes) + len(self.iocs)
+            + len(self.vulnerabilities) + len(self.alerts)
+        )
+
+    def _prune_oldest_iocs(self, needed: int = 1) -> None:
+        """Remove the oldest `needed` IOCNodes to stay under MAX_GRAPH_NODES."""
+        pruned = 0
+        while pruned < needed and self._ioc_insertion_order:
+            oldest = self._ioc_insertion_order.pop(0)
+            if oldest in self.iocs:
+                del self.iocs[oldest]
+                pruned += 1
+
+    def add_host(self, node: HostNode) -> None:
+        self.hosts[node.hostname] = node
+        self.version += 1
+        self._changelog.append((self.version, "host", node.hostname))
+
+    def add_process(self, node: ProcessNode) -> None:
+        self.processes[node.process_id] = node
+        self.version += 1
+        self._changelog.append((self.version, "process", node.process_id))
+
+    def add_ioc(self, node: IOCNode) -> None:
+        if node.ioc_value in self.iocs:
+            return  # already present — no cap action needed
+        if self._total_nodes() >= MAX_GRAPH_NODES:
+            self._prune_oldest_iocs(needed=1)
+        self.iocs[node.ioc_value] = node
+        self._ioc_insertion_order.append(node.ioc_value)
+        self.version += 1
+        self._changelog.append((self.version, "ioc", node.ioc_value))
+
+    def add_vulnerability(self, node: VulnerabilityNode) -> None:
+        key = f"{node.hostname}:{node.cve_id}"
+        self.vulnerabilities[key] = node
+        self.version += 1
+        self._changelog.append((self.version, "vulnerability", key))
+
+    def add_alert(self, node: AlertNode) -> None:
+        self.alerts[node.alert_id] = node
+        self.version += 1
+        self._changelog.append((self.version, "alert", node.alert_id))
+
+    def add_edge(self, edge: Edge) -> None:
+        self.edges.append(edge)
+        self.version += 1
+        edge_id = f"{edge.edge_type}:{edge.source_id}->{edge.target_id}"
+        self._changelog.append((self.version, "edge", edge_id))
+
+    def delta_since(self, version: int) -> dict:
+        """Return compact summary of nodes/edges added since `version`."""
+        if version <= 0:
+            entries = list(self._changelog)
+        else:
+            entries = [e for e in self._changelog if e[0] > version]
+
+        counts: dict[str, int] = {}
+        ids_by_type: dict[str, list[str]] = {}
+        for _, etype, eid in entries:
+            counts[etype] = counts.get(etype, 0) + 1
+            ids_by_type.setdefault(etype, []).append(eid)
+
+        # Truncate each id list to keep summary compact
+        compact_ids = {k: v[:5] for k, v in ids_by_type.items()}
+
+        summary_parts = [f"{t}={counts[t]}" for t in sorted(counts.keys())]
+        summary_text = f"Δ since v{version}: " + ", ".join(summary_parts) if summary_parts else f"Δ since v{version}: (no changes)"
+
+        return {
+            "from_version": version,
+            "to_version": self.version,
+            "counts": counts,
+            "ids": compact_ids,
+            "summary": summary_text,
+        }
+
+    def compute_evidence_confidence(
+        self, threat_id: str, rubric_item_count: int = 3
+    ) -> float:
+        """Confidence that a threat is well-evidenced.
+
+        Denominator is normalized to task complexity: max(3, rubric_item_count * 1.5).
+        This prevents reward hacking via forensics spam — a spammer who generates
+        10 graph nodes only scores against the rubric-sized baseline, not 10.
+        """
+        linked_ids: set[str] = set()
+        for edge in self.edges:
+            if edge.source_id == threat_id:
+                linked_ids.add(edge.target_id)
+            elif edge.target_id == threat_id:
+                linked_ids.add(edge.source_id)
+
+        if not linked_ids:
+            return 0.0
+
+        non_alert_count = 0
+        for nid in linked_ids:
+            if nid in self.alerts:
+                continue
+            if (
+                nid in self.hosts
+                or nid in self.processes
+                or nid in self.iocs
+                or nid in self.vulnerabilities
+            ):
+                non_alert_count += 1
+
+        denominator = max(3.0, rubric_item_count * 1.5)
+        confidence = non_alert_count / denominator
+        return max(0.0, min(1.0, confidence))
+
+    def get_context_summary(self) -> str:
+        """Compact LLM-injectable summary of current graph state."""
+        compromised = sum(1 for h in self.hosts.values() if h.status == "compromised")
+        critical_alerts = sum(1 for a in self.alerts.values() if a.severity == "critical")
+        blocked = sum(1 for i in self.iocs.values() if i.blocked)
+        enriched = sum(1 for i in self.iocs.values() if i.enriched)
+        return (
+            f"Hosts: {len(self.hosts)} ({compromised} compromised) "
+            f"Alerts: {len(self.alerts)} ({critical_alerts} critical) "
+            f"IOCs: {len(self.iocs)} ({blocked} blocked, {enriched} enriched) "
+            f"Vulns: {len(self.vulnerabilities)} "
+            f"Edges: {len(self.edges)}"
+        )

server/tool_router.py

@@ -0,0 +1,146 @@
+"""Deterministic Tool Router (phase machine) + Triage Solver."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .threat_graph import ThreatGraph, AlertNode, HostNode
+
+
+class ToolRouter:
+    PHASE_ORDER = ["triage", "investigation", "remediation", "report"]
+    MAX_INVESTIGATION_LOOPS = 4
+    MAX_REMEDIATION_LOOPS = 3
+
+    def __init__(self):
+        self._investigation_loop_count = 0
+        self._remediation_loop_count = 0
+
+    def next_phase(
+        self,
+        current_phase: str,
+        graph: "ThreatGraph",
+        steps_remaining: int,
+    ) -> str:
+        if current_phase == "triage":
+            if len(graph.alerts) > 0:
+                return "investigation"
+            return "report"
+
+        if current_phase == "investigation":
+            if (
+                self._has_sufficient_evidence(graph)
+                or steps_remaining < 4
+                or self._investigation_loop_count >= self.MAX_INVESTIGATION_LOOPS
+            ):
+                return "remediation"
+            self._investigation_loop_count += 1
+            return "investigation"
+
+        if current_phase == "remediation":
+            if (
+                self._all_threats_contained(graph)
+                or steps_remaining < 2
+                or self._remediation_loop_count >= self.MAX_REMEDIATION_LOOPS
+            ):
+                return "report"
+            if (
+                self._remediation_loop_count < self.MAX_REMEDIATION_LOOPS
+                and not self._all_threats_contained(graph)
+                and steps_remaining >= 4
+            ):
+                self._remediation_loop_count += 1
+                return "investigation"
+            return "report"
+
+        if current_phase == "report":
+            return "done"
+
+        return "done"
+
+    def _has_sufficient_evidence(self, graph: "ThreatGraph") -> bool:
+        has_unhealthy_host = any(h.status != "healthy" for h in graph.hosts.values())
+        has_ioc = len(graph.iocs) > 0
+        has_process = len(graph.processes) > 0
+        return has_unhealthy_host and has_ioc and has_process
+
+    def _all_threats_contained(self, graph: "ThreatGraph") -> bool:
+        suspicious_or_compromised = [
+            h for h in graph.hosts.values()
+            if h.status in ("suspicious", "compromised")
+        ]
+        if not suspicious_or_compromised:
+            return True
+        return all(
+            h.status in ("isolated", "contained") for h in graph.hosts.values()
+        )
+
+    def reset(self):
+        self._investigation_loop_count = 0
+        self._remediation_loop_count = 0
+
+    def honor_pushback(
+        self,
+        proposed_next_phase: str,
+        justification_graph_refs: list[str],
+        graph: "ThreatGraph",
+    ) -> tuple[bool, str]:
+        if proposed_next_phase not in self.PHASE_ORDER and proposed_next_phase != "done":
+            return False, f"invalid phase '{proposed_next_phase}'"
+        if not justification_graph_refs:
+            return False, "no justification graph references provided"
+
+        all_node_ids = (
+            set(graph.alerts.keys())
+            | set(graph.hosts.keys())
+            | set(graph.processes.keys())
+            | set(graph.iocs.keys())
+            | set(graph.vulnerabilities.keys())
+        )
+        for ref in justification_graph_refs:
+            if ref not in all_node_ids:
+                return False, f"reference '{ref}' not present in graph"
+
+        has_critical_alert = any(
+            ref in graph.alerts and graph.alerts[ref].severity in ("high", "critical")
+            for ref in justification_graph_refs
+        )
+        if not has_critical_alert:
+            return False, "at least one referenced alert must be high/critical severity"
+
+        return True, ""
+
+
+# ===========================================================================
+# Triage Solver
+# ===========================================================================
+
+SEVERITY_W = {"low": 1, "medium": 3, "high": 7, "critical": 15}
+CRITICALITY_W = {"low": 1, "medium": 2, "high": 4, "critical": 8}
+REACHABILITY_SCALE = 10
+
+
+def compute_triage_priority(
+    alert: "AlertNode",
+    host: "HostNode",
+    graph: "ThreatGraph",
+) -> float:
+    blast_radius = sum(1 for e in graph.edges if e.source_id == host.hostname)
+    return (
+        SEVERITY_W[alert.severity]
+        * CRITICALITY_W[host.business_criticality]
+        * (1 + blast_radius / REACHABILITY_SCALE)
+    )
+
+
+def solve_triage_order(graph: "ThreatGraph") -> list[str]:
+    scored: list[tuple[float, str]] = []
+    for alert in graph.alerts.values():
+        host = graph.hosts.get(alert.source_host)
+        if host is None:
+            continue
+        score = compute_triage_priority(alert, host, graph)
+        scored.append((score, alert.alert_id))
+    scored.sort(key=lambda t: t[0], reverse=True)
+    return [aid for _, aid in scored]

server/visualize_graph.py

@@ -0,0 +1,158 @@
+"""Red Line Demo Visualizer — renders ThreatGraph as a PNG.
+
+Usage:
+    from server.visualize_graph import visualize_graph
+    visualize_graph(env._threat_graph, "snapshot.png")
+
+Pivot edges (edge_type == 'pivoted_from') are drawn as thick bright-red lines
+so the adaptive red-team lateral movement is visually undeniable in demos.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .threat_graph import ThreatGraph
+
+
+_NODE_COLORS = {
+    "host": "#4A90D9",
+    "process": "#F5A623",
+    "ioc": "#D0021B",
+    "alert": "#9B9B9B",
+    "vulnerability": "#7ED321",
+}
+
+_EDGE_STYLES: dict[str, dict] = {
+    "pivoted_from":      {"color": "red",     "width": 3.0, "style": "solid"},
+    "part_of_chain":     {"color": "#555555", "width": 1.5, "style": "dashed"},
+    "exploits":          {"color": "#D0021B", "width": 1.5, "style": "solid"},
+    "runs_on":           {"color": "#4A90D9", "width": 1.0, "style": "solid"},
+    "involves":          {"color": "#9B9B9B", "width": 1.0, "style": "dotted"},
+    "communicates_with": {"color": "#F5A623", "width": 1.0, "style": "dashed"},
+}
+
+
+def visualize_graph(threat_graph: "ThreatGraph", output_path: str = "threat_graph.png") -> None:
+    """Render the ThreatGraph to a PNG file.
+
+    Args:
+        threat_graph: A populated ThreatGraph instance.
+        output_path: Destination file path for the PNG.
+    """
+    try:
+        import networkx as nx
+        import matplotlib
+        matplotlib.use("Agg")  # headless backend — safe in CI / server contexts
+        import matplotlib.pyplot as plt
+        import matplotlib.patches as mpatches
+    except ImportError as exc:
+        raise ImportError(
+            "visualize_graph requires networkx and matplotlib. "
+            "Install them with: pip install networkx matplotlib"
+        ) from exc
+
+    G = nx.DiGraph()
+
+    # --- Add nodes ---
+    node_color_map: dict[str, str] = {}
+
+    for hostname in threat_graph.hosts:
+        G.add_node(hostname)
+        node_color_map[hostname] = _NODE_COLORS["host"]
+
+    for proc_id, proc in threat_graph.processes.items():
+        G.add_node(proc_id)
+        node_color_map[proc_id] = _NODE_COLORS["process"]
+
+    for ioc_value in threat_graph.iocs:
+        G.add_node(ioc_value)
+        node_color_map[ioc_value] = _NODE_COLORS["ioc"]
+
+    for alert_id in threat_graph.alerts:
+        G.add_node(alert_id)
+        node_color_map[alert_id] = _NODE_COLORS["alert"]
+
+    for vuln_key in threat_graph.vulnerabilities:
+        G.add_node(vuln_key)
+        node_color_map[vuln_key] = _NODE_COLORS["vulnerability"]
+
+    # --- Add edges, split by type for drawing ---
+    pivot_edges: list[tuple[str, str]] = []
+    other_edges: list[tuple[str, str]] = []
+    other_edge_styles: list[dict] = []
+
+    for edge in threat_graph.edges:
+        src, tgt = edge.source_id, edge.target_id
+        # Ensure both endpoints exist as nodes (may be threat-IDs not in node sets)
+        if src not in G:
+            G.add_node(src)
+            node_color_map[src] = "#CCCCCC"
+        if tgt not in G:
+            G.add_node(tgt)
+            node_color_map[tgt] = "#CCCCCC"
+        G.add_edge(src, tgt, edge_type=edge.edge_type)
+
+        if edge.edge_type == "pivoted_from":
+            pivot_edges.append((src, tgt))
+        else:
+            style = _EDGE_STYLES.get(edge.edge_type, {"color": "#AAAAAA", "width": 1.0, "style": "solid"})
+            other_edges.append((src, tgt))
+            other_edge_styles.append(style)
+
+    # --- Layout ---
+    fig, ax = plt.subplots(figsize=(14, 10))
+    ax.set_title("CyberSOC Threat Graph", fontsize=14, fontweight="bold")
+    ax.axis("off")
+
+    pos = nx.spring_layout(G, seed=42, k=1.5)
+
+    node_list = list(G.nodes())
+    colors = [node_color_map.get(n, "#CCCCCC") for n in node_list]
+
+    nx.draw_networkx_nodes(G, pos, nodelist=node_list, node_color=colors,
+                           node_size=600, ax=ax, alpha=0.9)
+    nx.draw_networkx_labels(G, pos, font_size=6, ax=ax)
+
+    # Draw non-pivot edges grouped by style
+    _style_map: dict[str, list[tuple[str, str]]] = {}
+    for (src, tgt), style in zip(other_edges, other_edge_styles):
+        key = f"{style['color']}|{style['width']}|{style['style']}"
+        _style_map.setdefault(key, []).append((src, tgt))
+
+    for key, elist in _style_map.items():
+        color, width_s, linestyle = key.split("|")
+        nx.draw_networkx_edges(
+            G, pos, edgelist=elist,
+            edge_color=color, width=float(width_s), style=linestyle,
+            arrows=True, arrowsize=12, ax=ax, alpha=0.7,
+        )
+
+    # CRITICAL: pivot edges — thick bright red, drawn last so they sit on top
+    if pivot_edges:
+        nx.draw_networkx_edges(
+            G, pos, edgelist=pivot_edges,
+            edge_color="red", width=3.0, style="solid",
+            arrows=True, arrowsize=18, ax=ax, alpha=1.0,
+        )
+
+    # --- Legend ---
+    legend_handles = [
+        mpatches.Patch(color=c, label=label)
+        for label, c in [
+            ("Host", _NODE_COLORS["host"]),
+            ("Process", _NODE_COLORS["process"]),
+            ("IOC", _NODE_COLORS["ioc"]),
+            ("Alert", _NODE_COLORS["alert"]),
+            ("Vulnerability", _NODE_COLORS["vulnerability"]),
+        ]
+    ]
+    legend_handles.append(
+        mpatches.Patch(color="red", label="Lateral Pivot (pivoted_from)")
+    )
+    ax.legend(handles=legend_handles, loc="lower left", fontsize=8, framealpha=0.8)
+
+    plt.tight_layout()
+    plt.savefig(output_path, dpi=150, bbox_inches="tight")
+    plt.close(fig)

tests/test_integration.py

@@ -0,0 +1,189 @@
+"""Integration tests — Task 10."""
+
+import os
+import sys
+import subprocess
+
+import pytest
+
+_PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+if _PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, _PROJECT_ROOT)
+
+from server.play_environment import CyberSOCEnvironment
+from server.episode_sandbox import EpisodeTimeout
+from server.graders import grade_episode
+from models import SOCActionWrapper
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _first_host(env):
+    return next(iter(env._threat_graph.hosts), "WS-042")
+
+
+def _first_alert(env):
+    return next(iter(env._threat_graph.alerts), None)
+
+
+def _valid_action(action_type, **kwargs):
+    return SOCActionWrapper(type=action_type, **kwargs)
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+def test_easy_episode_completes():
+    env = CyberSOCEnvironment()
+    obs = env.reset(task_id="easy")
+    hostname = _first_host(env)
+    for _ in range(5):
+        obs = env.step(_valid_action("query_host", hostname=hostname))
+    assert obs is not None
+
+
+def test_medium_episode_with_all_10_actions():
+    env = CyberSOCEnvironment()
+    obs = env.reset(task_id="medium")
+    hostname = _first_host(env)
+    ioc_value = next(iter(env._threat_graph.iocs), None)
+
+    # Triage phase
+    alerts = list(env._threat_graph.alerts.keys())
+    if len(alerts) >= 2:
+        obs = env.step(_valid_action("correlate_alerts", alert_ids=alerts[:2]))
+
+    # Investigation phase
+    obs = env.step(_valid_action("query_host", hostname=hostname))
+    obs = env.step(_valid_action("run_forensics", hostname=hostname))
+
+    if ioc_value:
+        obs = env.step(_valid_action("enrich_ioc", ioc_value=ioc_value, ioc_type="ip"))
+    obs = env.step(_valid_action("scan_host_vulnerabilities", hostname=hostname))
+
+    # Remediation phase
+    if ioc_value:
+        obs = env.step(_valid_action("block_ioc", ioc_value=ioc_value, ioc_type="ip"))
+    obs = env.step(_valid_action("kill_process", hostname=hostname, process_name="nonexistent.exe"))
+    obs = env.step(_valid_action("isolate_segment", subnet="corporate", reason="test"))
+
+    # Trigger playbook (prereqs may or may not be met — just must not crash)
+    try:
+        obs = env.step(_valid_action("trigger_playbook", playbook_name="c2_disruption", target=hostname))
+    except Exception:
+        pass
+
+    # Submit plan
+    obs = env.step(_valid_action(
+        "submit_containment_plan",
+        plan=[{"threat_id": "T1", "actions_taken": ["kill"], "root_cause": "malware", "confidence": 0.8}],
+        executive_summary="Contained ransomware.",
+    ))
+    assert obs is not None
+
+
+def test_phase_violation_returns_error():
+    """kill_process during triage should record negative reward (not crash)."""
+    env = CyberSOCEnvironment()
+    env.reset(task_id="easy")
+    hostname = _first_host(env)
+    # This action is dispatched — may return low reward but must not raise
+    obs = env.step(_valid_action("kill_process", hostname=hostname, process_name="fake.exe"))
+    assert obs is not None
+
+
+def test_adaptive_pivot_fires_on_hard():
+    env = CyberSOCEnvironment(adaptive=True)
+    env.reset(task_id="hard")
+
+    # Force pivot probability to 1.0 (hard task)
+    # We need to isolate_segment where the host is the source_host for an edge
+    # OR just call _execute_lateral_pivot directly for test certainty
+    hostname = _first_host(env)
+    env._execute_lateral_pivot(source_host=hostname)
+
+    pivot_edges = [e for e in env._threat_graph.edges if e.edge_type == "pivoted_from"]
+    assert len(pivot_edges) >= 1
+
+
+def test_step_reward_accumulates():
+    env = CyberSOCEnvironment()
+    env.reset(task_id="easy")
+    hostname = _first_host(env)
+
+    before = env._step_reward_total
+    # run_forensics in investigation phase earns +0.10
+    for h in list(env._threat_graph.hosts.keys())[:3]:
+        if h in env._host_index:
+            env.step(_valid_action("run_forensics", hostname=h))
+
+    assert env._step_reward_total > before
+
+
+def test_step_reward_idempotent():
+    env = CyberSOCEnvironment()
+    env.reset(task_id="easy")
+    hostname = _first_host(env)
+
+    env.step(_valid_action("run_forensics", hostname=hostname))
+    after_first = env._step_reward_total
+    env.step(_valid_action("run_forensics", hostname=hostname))
+    after_second = env._step_reward_total
+
+    # Second call on same host earns 0 extra step reward (though may earn -0.02 from handler)
+    step_reward_delta = after_second - after_first
+    # The idempotent part: _get_step_reward returns 0 on second call for same triple
+    key = ("investigation", "run_forensics", hostname)
+    assert key in env._fired_step_rewards
+
+
+def test_grader_returns_10_dim():
+    env = CyberSOCEnvironment()
+    env.reset(task_id="easy")
+    hostname = _first_host(env)
+    env.step(_valid_action("query_host", hostname=hostname))
+
+    result = grade_episode(
+        episode_actions=list(env._state.timeline),
+        final_plan=None,
+        graph=env._threat_graph,
+        task_def=env._task_def,
+        state=env._state,
+    )
+    assert len(result["breakdown"]) == 10
+
+
+def test_sandbox_step_limit():
+    from server.episode_sandbox import EpisodeSandbox, MAX_STEPS_PER_EPISODE
+
+    env = CyberSOCEnvironment()
+    env.reset(task_id="easy")
+    sb = EpisodeSandbox(env)
+
+    with pytest.raises(EpisodeTimeout):
+        sb.check_step_limit(MAX_STEPS_PER_EPISODE)
+
+
+def test_openenv_validate_compatible():
+    """Run openenv validate and assert it exits 0 (env is valid with adaptive=False)."""
+    python = os.path.join(_PROJECT_ROOT, "..", "venv", "Scripts", "python.exe")
+    python = os.path.abspath(python)
+    if not os.path.exists(python):
+        pytest.skip("venv python not found")
+
+    result = subprocess.run(
+        [python, "-c",
+         "from server.play_environment import CyberSOCEnvironment; "
+         "env = CyberSOCEnvironment(adaptive=False); "
+         "obs = env.reset(task_id='easy'); "
+         "print('OK', len(obs.alert_queue))"],
+        cwd=_PROJECT_ROOT,
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+    assert result.returncode == 0, f"stderr: {result.stderr}"
+    assert "OK" in result.stdout

tests/test_task1.py

@@ -0,0 +1,34 @@
+"""Tests for Task 1 — Fix Crash Bug + Project Scaffold."""
+
+import os
+import sys
+
+# Ensure project root (MetaRound2) is on sys.path before importing server.*
+_PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+if _PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, _PROJECT_ROOT)
+
+from server.play_environment import CyberSOCEnvironment
+
+
+def test_reset_does_not_crash():
+    env = CyberSOCEnvironment()
+    obs = env.reset(task_id="easy")
+    assert obs is not None
+
+
+def test_live_requirements_populated():
+    env = CyberSOCEnvironment()
+    env.reset(task_id="easy")
+    assert env._live_requirements is not None
+    assert isinstance(env._live_requirements, dict)
+
+
+def test_adaptive_flag_default():
+    env = CyberSOCEnvironment()
+    assert env._adaptive is False
+
+
+def test_adaptive_flag_set():
+    env = CyberSOCEnvironment(adaptive=True)
+    assert env._adaptive is True

tests/test_task2.py

@@ -0,0 +1,107 @@
+"""Tests for Task 2 — Threat Graph Core."""
+
+import os
+import sys
+
+_PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+if _PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, _PROJECT_ROOT)
+
+from server.threat_graph import (
+    ThreatGraph,
+    HostNode,
+    ProcessNode,
+    IOCNode,
+    VulnerabilityNode,
+    AlertNode,
+    Edge,
+)
+
+
+def _make_host(name="WS-001"):
+    return HostNode(
+        hostname=name,
+        subnet="corporate",
+        business_criticality="medium",
+        status="compromised",
+    )
+
+
+def _make_ioc(value="1.2.3.4", **kw):
+    return IOCNode(ioc_value=value, ioc_type="ip", confidence=0.9, **kw)
+
+
+def test_add_and_retrieve_host():
+    g = ThreatGraph()
+    g.add_host(_make_host("WS-001"))
+    assert "WS-001" in g.hosts
+
+
+def test_add_ioc_with_enrichment():
+    g = ThreatGraph()
+    g.add_ioc(_make_ioc("8.8.8.8", enriched=True))
+    assert g.iocs["8.8.8.8"].enriched is True
+
+
+def test_version_increments():
+    g = ThreatGraph()
+    assert g.version == 0
+    g.add_host(_make_host("WS-001"))
+    assert g.version == 1
+    g.add_ioc(_make_ioc("1.1.1.1"))
+    assert g.version == 2
+
+
+def test_delta_since_zero_returns_all():
+    g = ThreatGraph()
+    g.add_host(_make_host("WS-001"))
+    g.add_host(_make_host("WS-002"))
+    g.add_ioc(_make_ioc("1.1.1.1"))
+    delta = g.delta_since(0)
+    counts = delta["counts"]
+    assert counts.get("host", 0) == 2
+    assert counts.get("ioc", 0) == 1
+
+
+def test_delta_since_version_filters():
+    g = ThreatGraph()
+    g.add_host(_make_host("WS-001"))   # version becomes 1
+    g.add_ioc(_make_ioc("1.1.1.1"))    # version becomes 2
+    delta = g.delta_since(1)
+    counts = delta["counts"]
+    assert counts.get("host", 0) == 0
+    assert counts.get("ioc", 0) == 1
+
+
+def test_evidence_confidence_zero_when_no_edges():
+    g = ThreatGraph()
+    assert g.compute_evidence_confidence("THREAT-XYZ") == 0.0
+
+
+def test_evidence_confidence_partial():
+    g = ThreatGraph()
+    g.add_host(_make_host("WS-001"))
+    g.add_edge(Edge(edge_type="part_of_chain", source_id="THREAT-1", target_id="WS-001"))
+    conf = g.compute_evidence_confidence("THREAT-1")
+    assert 0.0 < conf < 1.0
+
+
+def test_context_summary_under_100_words():
+    g = ThreatGraph()
+    g.add_host(_make_host("WS-001"))
+    g.add_ioc(_make_ioc("1.1.1.1"))
+    summary = g.get_context_summary()
+    assert len(summary.split()) <= 100
+
+
+def test_add_vulnerability():
+    g = ThreatGraph()
+    vuln = VulnerabilityNode(
+        cve_id="CVE-2024-0001",
+        hostname="WS-001",
+        cvss_score=9.8,
+        exploitability="active",
+        patch_available=True,
+    )
+    g.add_vulnerability(vuln)
+    assert "WS-001:CVE-2024-0001" in g.vulnerabilities

tests/test_task3.py

@@ -0,0 +1,81 @@
+"""Tests for Task 3 — Action Models (10 actions)."""
+
+import os
+import sys
+
+import pytest
+from pydantic import ValidationError
+
+_PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+if _PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, _PROJECT_ROOT)
+
+from models import (
+    CorrelateAlerts,
+    EnrichIOC,
+    ScanHostVulnerabilities,
+    TriggerPlaybook,
+    SOCActionWrapper,
+    SOCObservation,
+    SOCState,
+)
+
+
+def test_correlate_alerts_model():
+    a = CorrelateAlerts(alert_ids=["A1", "A2"])
+    assert a.type == "correlate_alerts"
+
+
+def test_enrich_ioc_model():
+    a = EnrichIOC(ioc_value="1.2.3.4", ioc_type="ip")
+    assert a.type == "enrich_ioc"
+
+
+def test_scan_host_vulnerabilities_model():
+    a = ScanHostVulnerabilities(hostname="WS-001")
+    assert a.type == "scan_host_vulnerabilities"
+
+
+def test_trigger_playbook_valid():
+    a = TriggerPlaybook(playbook_name="ransomware_containment", target="WS-001")
+    assert a.type == "trigger_playbook"
+
+
+def test_trigger_playbook_invalid_name():
+    with pytest.raises(ValidationError):
+        TriggerPlaybook(playbook_name="fake_playbook", target="WS-001")
+
+
+def test_wrapper_routes_correlate_alerts():
+    w = SOCActionWrapper(type="correlate_alerts", alert_ids=["A", "B"])
+    assert isinstance(w.to_typed_action(), CorrelateAlerts)
+
+
+def test_wrapper_routes_enrich_ioc():
+    w = SOCActionWrapper(type="enrich_ioc", ioc_value="x", ioc_type="ip")
+    assert isinstance(w.to_typed_action(), EnrichIOC)
+
+
+def test_observation_has_new_fields():
+    obs = SOCObservation()
+    for attr in [
+        "correlation_results",
+        "ioc_enrichment",
+        "vulnerability_results",
+        "playbook_result",
+        "threat_graph_summary",
+        "available_playbooks",
+    ]:
+        assert hasattr(obs, attr), f"missing {attr}"
+
+
+def test_state_has_new_fields():
+    st = SOCState(episode_id="e", step_count=0)
+    for attr in [
+        "enriched_iocs",
+        "scanned_hosts",
+        "correlated_alert_pairs",
+        "triggered_playbooks",
+        "live_requirements",
+    ]:
+        assert hasattr(st, attr), f"missing {attr}"

tests/test_task4.py

@@ -0,0 +1,72 @@
+"""Tests for Task 4 — SOAR Playbook Library."""
+
+import os
+import sys
+
+import pytest
+
+_PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+if _PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, _PROJECT_ROOT)
+
+from server.soar_playbooks import PLAYBOOKS, check_prerequisites
+from server.threat_graph import ThreatGraph, HostNode, ProcessNode, IOCNode
+from models import SOCState
+
+
+def _fresh_state():
+    return SOCState(episode_id="e", step_count=0)
+
+
+def _empty_graph():
+    return ThreatGraph()
+
+
+def test_all_five_playbooks_defined():
+    for k in [
+        "ransomware_containment",
+        "c2_disruption",
+        "lateral_movement_lockdown",
+        "phishing_response",
+        "data_exfil_stop",
+    ]:
+        assert k in PLAYBOOKS
+
+
+def test_playbook_structure():
+    for name, p in PLAYBOOKS.items():
+        for key in ["name", "description", "prerequisites", "sub_actions", "target_attack_types"]:
+            assert key in p, f"{name} missing {key}"
+
+
+def test_ransomware_containment_sub_actions():
+    assert PLAYBOOKS["ransomware_containment"]["sub_actions"] == ["kill_process", "block_ioc"]
+
+
+def test_check_prerequisites_fails_no_forensics():
+    ok, reason = check_prerequisites("ransomware_containment", "WS-001", _fresh_state(), _empty_graph())
+    assert ok is False
+    assert isinstance(reason, str) and len(reason) > 0
+
+
+def test_check_prerequisites_passes_when_met():
+    state = _fresh_state()
+    state.scanned_hosts = ["WS-001"]
+    g = ThreatGraph()
+    g.add_process(ProcessNode(process_id="WS-001:1234", hostname="WS-001", process_name="evil.exe"))
+    ok, reason = check_prerequisites("ransomware_containment", "WS-001", state, g)
+    assert ok is True
+    assert reason == ""
+
+
+def test_unknown_playbook_raises():
+    with pytest.raises((KeyError, ValueError)):
+        check_prerequisites("nonexistent_playbook", "WS-001", _fresh_state(), _empty_graph())
+
+
+def test_c2_disruption_needs_enriched_ioc():
+    g = ThreatGraph()
+    # add IP IOC but not enriched
+    g.add_ioc(IOCNode(ioc_value="1.2.3.4", ioc_type="ip", confidence=0.9, enriched=False))
+    ok, reason = check_prerequisites("c2_disruption", "WS-001", _fresh_state(), g)
+    assert ok is False

tests/test_task5.py

@@ -0,0 +1,86 @@
+"""Tests for Task 5 — Episode Sandbox."""
+
+import os
+import sys
+
+import pytest
+
+_PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+if _PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, _PROJECT_ROOT)
+
+from server.episode_sandbox import (
+    EpisodeSandbox,
+    EpisodeTimeout,
+    MAX_STEPS_PER_EPISODE,
+)
+
+
+class _MockEnv:
+    def __init__(self):
+        self._task_def = {"difficulty": "easy", "attack_chain": []}
+        self._live_requirements = {"must_kill": []}
+        self._threat_graph = None
+        self._step_count = 0
+
+
+def test_sandbox_enters_and_exits_cleanly():
+    env = _MockEnv()
+    with EpisodeSandbox(env):
+        pass
+
+
+def test_elapsed_seconds_positive():
+    env = _MockEnv()
+    with EpisodeSandbox(env) as sb:
+        # Even fast: elapsed should be >= 0 immediately, > 0 after a tick.
+        # Force a small wait-free tick by reading time twice.
+        e1 = sb.elapsed_seconds()
+        # Busy-loop a small amount to guarantee elapsed > 0
+        end = e1 + 1e-3
+        while sb.elapsed_seconds() <= end:
+            pass
+        assert sb.elapsed_seconds() > 0.0
+
+
+def test_step_limit_raises_at_max():
+    env = _MockEnv()
+    sb = EpisodeSandbox(env)
+    with pytest.raises(EpisodeTimeout):
+        sb.check_step_limit(MAX_STEPS_PER_EPISODE)
+
+
+def test_step_limit_ok_below_max():
+    env = _MockEnv()
+    sb = EpisodeSandbox(env)
+    sb.check_step_limit(MAX_STEPS_PER_EPISODE - 1)
+
+
+def test_state_integrity_violation_detected():
+    env = _MockEnv()
+    with EpisodeSandbox(env) as sb:
+        env._step_count = 9999  # mutate protected field
+    assert sb.was_hacked() is True
+
+
+def test_state_rollback_on_violation():
+    env = _MockEnv()
+    original = dict(env._task_def)
+    with EpisodeSandbox(env):
+        env._task_def["difficulty"] = "hacked"
+    assert env._task_def == original
+
+
+def test_no_false_hacking_on_clean_run():
+    env = _MockEnv()
+    with EpisodeSandbox(env) as sb:
+        pass
+    assert sb.was_hacked() is False
+
+
+def test_hacking_report_lists_violated_fields():
+    env = _MockEnv()
+    with EpisodeSandbox(env) as sb:
+        env._step_count = 42
+    report = sb.hacking_report()
+    assert any("_step_count" in r for r in report)

tests/test_task6.py

@@ -0,0 +1,101 @@
+"""Tests for Task 6 — Action Validation Middleware."""
+
+import os
+import sys
+
+_PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+if _PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, _PROJECT_ROOT)
+
+from server.action_validation import (
+    ActionValidationMiddleware,
+    PHASE_VIOLATION,
+    INVALID_PARAMS,
+    UNGROUNDED_ACTION,
+)
+from server.threat_graph import ThreatGraph, IOCNode, ProcessNode
+
+
+def _empty():
+    return ThreatGraph()
+
+
+def _graph_with_ioc(value="1.2.3.4"):
+    g = ThreatGraph()
+    g.add_ioc(IOCNode(ioc_value=value, ioc_type="ip", confidence=0.9))
+    return g
+
+
+def _graph_with_process(host="H", proc_name="evil.exe"):
+    g = ThreatGraph()
+    g.add_process(ProcessNode(process_id=f"{host}:{proc_name}", hostname=host, process_name=proc_name))
+    return g
+
+
+def test_gate1_rejects_wrong_phase():
+    m = ActionValidationMiddleware()
+    err = m.validate("triage", "kill_process", {}, _empty())
+    assert err is not None
+    assert err["error"] == PHASE_VIOLATION
+
+
+def test_gate1_passes_correct_phase():
+    m = ActionValidationMiddleware()
+    err = m.validate("remediation", "kill_process", {"hostname": "H", "process_name": "evil.exe"}, _graph_with_process())
+    assert err is None
+
+
+def test_gate1_error_lists_allowed_tools():
+    m = ActionValidationMiddleware()
+    err = m.validate("triage", "kill_process", {}, _empty())
+    assert err is not None
+    msg = err["message"].lower()
+    assert any(t in msg for t in ["read_alerts", "read_topology", "correlate_alerts"])
+
+
+def test_gate2_rejects_missing_ioc_value():
+    m = ActionValidationMiddleware()
+    err = m.validate("remediation", "block_ioc", {}, _empty())
+    assert err is not None and err["error"] == INVALID_PARAMS
+
+
+def test_gate2_rejects_correlate_with_one_alert():
+    m = ActionValidationMiddleware()
+    err = m.validate("triage", "correlate_alerts", {"alert_ids": ["A1"]}, _empty())
+    assert err is not None and err["error"] == INVALID_PARAMS
+
+
+def test_gate3_rejects_ungrounded_block():
+    m = ActionValidationMiddleware()
+    err = m.validate("remediation", "block_ioc", {"ioc_value": "1.2.3.4"}, _empty())
+    assert err is not None and err["error"] == UNGROUNDED_ACTION
+
+
+def test_gate3_passes_grounded_block():
+    m = ActionValidationMiddleware()
+    err = m.validate("remediation", "block_ioc", {"ioc_value": "1.2.3.4"}, _graph_with_ioc())
+    assert err is None
+
+
+def test_gate3_rejects_ungrounded_kill():
+    m = ActionValidationMiddleware()
+    err = m.validate("remediation", "kill_process", {"hostname": "H", "process_name": "unknown.exe"}, _empty())
+    assert err is not None and err["error"] == UNGROUNDED_ACTION
+
+
+def test_all_gates_pass_returns_none():
+    m = ActionValidationMiddleware()
+    err = m.validate("remediation", "block_ioc", {"ioc_value": "1.2.3.4"}, _graph_with_ioc())
+    assert err is None
+
+
+def test_retry_flag_false_for_phase_violation():
+    m = ActionValidationMiddleware()
+    err = m.validate("triage", "kill_process", {}, _empty())
+    assert err["retry"] is False
+
+
+def test_retry_flag_true_for_invalid_params():
+    m = ActionValidationMiddleware()
+    err = m.validate("remediation", "block_ioc", {}, _empty())
+    assert err["retry"] is True

tests/test_task7.py

@@ -0,0 +1,113 @@
+"""Tests for Task 7 — Tool Router + Triage Solver."""
+
+import os
+import sys
+
+_PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+if _PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, _PROJECT_ROOT)
+
+from server.tool_router import (
+    ToolRouter,
+    compute_triage_priority,
+    solve_triage_order,
+)
+from server.threat_graph import (
+    ThreatGraph,
+    AlertNode,
+    HostNode,
+    IOCNode,
+    ProcessNode,
+)
+
+
+def _alert(aid="A1", severity="high", source="WS-001"):
+    return AlertNode(alert_id=aid, severity=severity, priority_score=1.0, source_host=source)
+
+
+def _host(name="WS-001", crit="medium", status="compromised"):
+    return HostNode(hostname=name, subnet="corporate", business_criticality=crit, status=status)
+
+
+def _full_evidence_graph():
+    g = ThreatGraph()
+    g.add_host(_host("WS-001"))
+    g.add_ioc(IOCNode(ioc_value="1.1.1.1", ioc_type="ip", confidence=0.9))
+    g.add_process(ProcessNode(process_id="WS-001:1", hostname="WS-001", process_name="x"))
+    return g
+
+
+def test_triage_to_investigation_with_alerts():
+    g = ThreatGraph()
+    g.add_alert(_alert())
+    r = ToolRouter()
+    assert r.next_phase("triage", g, 10) == "investigation"
+
+
+def test_triage_to_report_no_alerts():
+    g = ThreatGraph()
+    r = ToolRouter()
+    assert r.next_phase("triage", g, 10) == "report"
+
+
+def test_investigation_loops_then_exits():
+    g = ThreatGraph()  # evidence-free
+    r = ToolRouter()
+    out = "investigation"
+    for _ in range(r.MAX_INVESTIGATION_LOOPS + 1):
+        out = r.next_phase("investigation", g, 10)
+    assert out == "remediation"
+
+
+def test_investigation_exits_on_sufficient_evidence():
+    r = ToolRouter()
+    assert r.next_phase("investigation", _full_evidence_graph(), 10) == "remediation"
+
+
+def test_remediation_exits_when_contained():
+    r = ToolRouter()
+    g = ThreatGraph()
+    g.add_host(_host("WS-001", status="isolated"))
+    assert r.next_phase("remediation", g, 10) == "report"
+
+
+def test_report_returns_done():
+    r = ToolRouter()
+    assert r.next_phase("report", ThreatGraph(), 10) == "done"
+
+
+def test_honor_pushback_rejects_no_graph_refs():
+    r = ToolRouter()
+    ok, _ = r.honor_pushback("investigation", [], ThreatGraph())
+    assert ok is False
+
+
+def test_honor_pushback_accepts_valid_critical_alert():
+    g = ThreatGraph()
+    g.add_alert(_alert("A1", severity="critical"))
+    r = ToolRouter()
+    ok, _ = r.honor_pushback("investigation", ["A1"], g)
+    assert ok is True
+
+
+def test_triage_priority_higher_for_critical():
+    g = ThreatGraph()
+    a_crit = _alert("A1", severity="critical")
+    a_low = _alert("A2", severity="low", source="WS-002")
+    h_crit = _host("WS-001", crit="critical")
+    h_low = _host("WS-002", crit="low")
+    s_crit = compute_triage_priority(a_crit, h_crit, g)
+    s_low = compute_triage_priority(a_low, h_low, g)
+    assert s_crit > s_low
+
+
+def test_solve_triage_order_descending():
+    g = ThreatGraph()
+    g.add_host(_host("WS-001", crit="critical"))
+    g.add_host(_host("WS-002", crit="medium"))
+    g.add_host(_host("WS-003", crit="low"))
+    g.add_alert(_alert("A1", severity="critical", source="WS-001"))
+    g.add_alert(_alert("A2", severity="medium", source="WS-002"))
+    g.add_alert(_alert("A3", severity="low", source="WS-003"))
+    order = solve_triage_order(g)
+    assert order == ["A1", "A2", "A3"]

tests/test_task8.py

@@ -0,0 +1,132 @@
+"""Tests for Task 8 — 10-dimensional Grader."""
+
+import os
+import sys
+
+_PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+if _PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, _PROJECT_ROOT)
+
+from server.graders import grade_episode, grade_easy
+from server.threat_graph import (
+    ThreatGraph,
+    HostNode,
+    ProcessNode,
+    IOCNode,
+    VulnerabilityNode,
+    AlertNode,
+)
+from models import SOCState
+
+
+def _state(**overrides):
+    s = SOCState(episode_id="e", step_count=0)
+    for k, v in overrides.items():
+        setattr(s, k, v)
+    return s
+
+
+def _task_def_simple():
+    return {
+        "containment_requirements": {
+            "must_kill": [{"hostname": "WS-001", "process": "evil.exe", "threat_id": "T1"}],
+            "must_block_iocs": ["1.2.3.4"],
+            "must_forensics": ["WS-001"],
+            "must_not_isolate": [],
+        },
+        "attack_chain": [{"threat_id": "T1"}],
+    }
+
+
+def _empty_graph():
+    return ThreatGraph()
+
+
+def test_returns_correct_keys():
+    res = grade_episode([], None, _empty_graph(), _task_def_simple(), _state())
+    for k in ("final_score", "breakdown", "penalties", "bonuses", "reward_functions"):
+        assert k in res
+
+
+def test_breakdown_has_10_keys():
+    res = grade_episode([], None, _empty_graph(), _task_def_simple(), _state())
+    assert len(res["breakdown"]) == 10
+
+
+def test_reward_functions_has_10_keys():
+    res = grade_episode([], None, _empty_graph(), _task_def_simple(), _state())
+    assert len(res["reward_functions"]) == 10
+
+
+def test_all_rubric_met_scores_high():
+    g = ThreatGraph()
+    g.add_host(HostNode(hostname="WS-001", subnet="corporate",
+                         business_criticality="medium", status="contained"))
+    g.add_ioc(IOCNode(ioc_value="1.2.3.4", ioc_type="ip", confidence=0.9, enriched=True, blocked=True))
+    g.add_process(ProcessNode(process_id="WS-001:1", hostname="WS-001",
+                               process_name="evil.exe", killed=True))
+    g.add_vulnerability(VulnerabilityNode(
+        cve_id="CVE-1", hostname="WS-001", cvss_score=9.0,
+        exploitability="active", patch_available=True,
+        exploited_by_threat="T1",
+    ))
+    state = _state(
+        killed_processes=[{"hostname": "WS-001", "process": "evil.exe"}],
+        blocked_iocs=["1.2.3.4"],
+        scanned_hosts=["WS-001"],
+        enriched_iocs=["1.2.3.4"],
+        correlated_alert_pairs=[("A1", "A2")],
+        triggered_playbooks=["ransomware_containment"],
+    )
+    actions = [
+        {"action_type": "correlate_alerts", "target": "A"},
+        {"action_type": "kill_process", "target": "WS-001"},
+    ]
+    plan = {"entries": [{"threat_id": "T1", "actions_taken": ["kill"], "root_cause": "CVE-1", "confidence": 0.9}],
+            "primary_threat_id": "T1"}
+    res = grade_episode(actions, plan, g, _task_def_simple(), state)
+    assert res["final_score"] >= 0.7
+
+
+def test_no_actions_scores_low():
+    res = grade_episode([], None, _empty_graph(), _task_def_simple(), _state())
+    assert res["final_score"] <= 0.3
+
+
+def test_blind_blocking_penalty():
+    state = _state(blocked_iocs=["1.2.3.4"], enriched_iocs=[])
+    res = grade_episode([], None, _empty_graph(), _task_def_simple(), state)
+    pen_types = [p["type"] for p in res["penalties"]]
+    assert "blind_blocking" in pen_types
+
+
+def test_business_impact_penalises_over_isolation():
+    g = ThreatGraph()
+    # 10 hosts, 3 isolated -> 30%
+    for i in range(10):
+        status = "isolated" if i < 3 else "healthy"
+        g.add_host(HostNode(hostname=f"H{i}", subnet="corporate",
+                             business_criticality="medium", status=status))
+    res = grade_episode([], None, g, _task_def_simple(), _state())
+    assert res["breakdown"]["business_impact"] < 0.5
+
+
+def test_step_efficiency_bonus_for_playbook():
+    state = _state(triggered_playbooks=["ransomware_containment"])
+    res = grade_episode([], None, _empty_graph(), _task_def_simple(), state)
+    assert res["breakdown"]["step_efficiency"] > 0.5
+
+
+def test_plan_coverage_zero_without_plan():
+    res = grade_episode([], None, _empty_graph(), _task_def_simple(), _state())
+    assert res["breakdown"]["plan_coverage"] == 0.0
+
+
+def test_final_score_clamped_0_to_1():
+    res = grade_episode([], None, _empty_graph(), _task_def_simple(), _state())
+    assert 0.0 <= res["final_score"] <= 1.0
+
+
+def test_wrappers_still_return_float():
+    val = grade_easy([], None, _empty_graph(), _task_def_simple(), _state())
+    assert isinstance(val, float)

tests/test_task9.py

@@ -0,0 +1,173 @@
+"""Tests for Task 9 — 4 New Action Handlers + Enhanced Existing Handlers."""
+
+import os
+import sys
+
+_PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir))
+if _PROJECT_ROOT not in sys.path:
+    sys.path.insert(0, _PROJECT_ROOT)
+
+from server.play_environment import CyberSOCEnvironment
+from server.threat_graph import HostNode, ProcessNode, IOCNode, AlertNode, Edge
+from models import CorrelateAlerts, EnrichIOC, ScanHostVulnerabilities, TriggerPlaybook
+
+
+def _env_with_graph():
+    """Return a reset env with a seeded threat graph."""
+    env = CyberSOCEnvironment()
+    env.reset(task_id="easy")
+    return env
+
+
+def _add_alerts(env, alert_ids):
+    """Add AlertNodes to the threat graph."""
+    for aid in alert_ids:
+        if aid not in env._threat_graph.alerts:
+            env._threat_graph.add_alert(AlertNode(
+                alert_id=aid, severity="high", priority_score=5.0, source_host="WS-001"
+            ))
+
+
+def _add_ioc(env, value="1.2.3.4"):
+    if value not in env._threat_graph.iocs:
+        env._threat_graph.add_ioc(IOCNode(ioc_value=value, ioc_type="ip", confidence=0.9))
+
+
+def _add_host(env, hostname="WS-FAKE"):
+    if hostname not in env._threat_graph.hosts:
+        env._threat_graph.add_host(HostNode(
+            hostname=hostname, subnet="corporate",
+            business_criticality="medium", status="compromised"
+        ))
+
+
+def test_correlate_alerts_returns_correlation_results():
+    env = _env_with_graph()
+    _add_alerts(env, ["A1", "A2"])
+    result = env._handle_correlate_alerts(CorrelateAlerts(alert_ids=["A1", "A2"]))
+    assert "correlation_results" in result
+    assert "correlation_score" in result["correlation_results"]
+
+
+def test_correlate_alerts_error_on_single_id():
+    env = _env_with_graph()
+    _add_alerts(env, ["A1"])
+    result = env._handle_correlate_alerts(CorrelateAlerts(alert_ids=["A1", "MISSING"]))
+    # fewer than 2 alerts found in graph → error
+    assert "error" in result
+
+
+def test_enrich_ioc_updates_graph():
+    env = _env_with_graph()
+    # Grab any IOC already in graph (seeded from task def)
+    ioc_value = next(iter(env._threat_graph.iocs), None)
+    if ioc_value is None:
+        _add_ioc(env)
+        ioc_value = "1.2.3.4"
+    env._handle_enrich_ioc(EnrichIOC(ioc_value=ioc_value, ioc_type="ip"))
+    assert env._threat_graph.iocs[ioc_value].enriched is True
+
+
+def test_enrich_ioc_error_when_not_in_graph():
+    env = _env_with_graph()
+    result = env._handle_enrich_ioc(EnrichIOC(ioc_value="not.in.graph", ioc_type="ip"))
+    assert "error" in result
+
+
+def test_scan_vulnerabilities_adds_vuln_nodes():
+    env = _env_with_graph()
+    # Use a host that exists in the graph
+    hostname = next(iter(env._threat_graph.hosts), None)
+    if hostname is None:
+        _add_host(env)
+        hostname = "WS-FAKE"
+    # Seed a vulnerability_chain entry for this host
+    env._task_def["vulnerability_chain"] = [{
+        "hostname": hostname,
+        "cve_id": "CVE-2024-9999",
+        "cvss_score": 9.8,
+        "exploitability": "active",
+        "patch_available": True,
+        "threat_id": "T1",
+    }]
+    env._handle_scan_vulnerabilities(ScanHostVulnerabilities(hostname=hostname))
+    assert len(env._threat_graph.vulnerabilities) > 0
+
+
+def test_scan_vulnerabilities_marks_host_scanned():
+    env = _env_with_graph()
+    hostname = next(iter(env._threat_graph.hosts), None)
+    if hostname is None:
+        _add_host(env)
+        hostname = "WS-FAKE"
+    env._task_def["vulnerability_chain"] = []
+    env._handle_scan_vulnerabilities(ScanHostVulnerabilities(hostname=hostname))
+    assert env._threat_graph.hosts[hostname].scanned is True
+
+
+def test_trigger_playbook_fails_without_prerequisites():
+    env = _env_with_graph()
+    hostname = next(iter(env._threat_graph.hosts), "WS-001")
+    result = env._handle_trigger_playbook(
+        TriggerPlaybook(playbook_name="ransomware_containment", target=hostname)
+    )
+    assert "error" in result
+
+
+def test_trigger_playbook_adds_to_triggered_list():
+    env = _env_with_graph()
+    hostname = next(iter(env._threat_graph.hosts), None)
+    if hostname is None:
+        _add_host(env)
+        hostname = "WS-FAKE"
+
+    # Satisfy prerequisites: forensics_run_on_target + process_identified
+    env._state.scanned_hosts.append(hostname)
+    if not any(p.hostname == hostname for p in env._threat_graph.processes.values()):
+        env._threat_graph.add_process(ProcessNode(
+            process_id=f"{hostname}:1", hostname=hostname, process_name="evil.exe"
+        ))
+
+    result = env._handle_trigger_playbook(
+        TriggerPlaybook(playbook_name="ransomware_containment", target=hostname)
+    )
+    assert "error" not in result
+    assert "ransomware_containment" in env._state.triggered_playbooks
+
+
+def test_query_host_returns_process_tree():
+    env = _env_with_graph()
+    hostname = next(iter(env._threat_graph.hosts), None)
+    if hostname is None:
+        _add_host(env)
+        hostname = "WS-FAKE"
+        # also add to host_index
+        env._host_index[hostname] = {
+            "hostname": hostname, "subnet": "corporate",
+            "status": "compromised", "running_processes": [], "criticality": 0.5
+        }
+    env._last_obs_extras = {}
+    env._handle_query_host(type("QH", (), {"hostname": hostname})())
+    assert "process_tree" in env._last_obs_extras
+
+
+def test_isolate_single_host_sets_isolated():
+    env = _env_with_graph()
+    hostname = next(iter(env._threat_graph.hosts), None)
+    if hostname is None:
+        _add_host(env)
+        hostname = "WS-FAKE"
+        env._host_index[hostname] = {
+            "hostname": hostname, "subnet": "corporate",
+            "status": "compromised", "running_processes": [], "criticality": 0.5
+        }
+
+    from models import IsolateSegment
+    action = IsolateSegment(target_host=hostname, reason="test")
+    env._handle_isolate_segment(action)
+    assert env._host_index[hostname]["status"] == "isolated"
+    # Only this host isolated, not all of its subnet
+    subnet = env._host_index[hostname].get("subnet", "corporate")
+    subnet_hosts = env._network.get(subnet, [])
+    still_up = sum(1 for h in subnet_hosts if h["status"] != "isolated")
+    assert still_up > 0

training/collect_sft_data.py

@@ -0,0 +1,104 @@
+"""
+Collect SFT data by running a scripted 'perfect' agent through Easy tasks.
+This satisfies Daniel's Law of RL: ensuring the base model can emit valid JSON
+actions before starting GRPO.
+"""
+
+import json
+import os
+import sys
+
+# Ensure server module can be imported
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from server.play_environment import CyberSOCEnvironment
+from server.tasks import get_task
+from models import SOCActionWrapper
+
+def _format_as_chat(history: list) -> dict:
+    """Format a sequence of observations and actions into a chat trace."""
+    messages = [
+        {
+            "role": "system",
+            "content": "You are an autonomous CyberSOC Agent. Analyze the environment and output JSON tool calls to contain the threat."
+        }
+    ]
+    for step in history:
+        if step["type"] == "observation":
+            messages.append({"role": "user", "content": json.dumps(step["data"], indent=2)})
+        elif step["type"] == "action":
+            messages.append({"role": "assistant", "content": json.dumps(step["data"])})
+    return {"messages": messages}
+
+def collect_winning_traces(num_traces=100, output_file="training/sft_data.jsonl"):
+    print(f"Collecting {num_traces} SFT traces...")
+    os.makedirs(os.path.dirname(output_file), exist_ok=True)
+    
+    env = CyberSOCEnvironment()
+    traces = []
+    
+    for i in range(1, num_traces + 1):
+        task_id = f"gen_{i:04d}"
+        task_def = get_task(task_id)
+        
+        history = []
+        obs = env.reset(task_id=task_id)
+        history.append({"type": "observation", "data": obs.model_dump()})
+        
+        # Scripted "Perfect" Agent
+        reqs = task_def.get("containment_requirements", {})
+        
+        # 1. Run forensics on compromised hosts
+        for host in reqs.get("must_forensics", []):
+            action = {"type": "run_forensics", "hostname": host}
+            history.append({"type": "action", "data": action})
+            obs = env.step(SOCActionWrapper(**action))
+            history.append({"type": "observation", "data": obs.model_dump()})
+            
+        # 2. Kill malicious processes
+        for proc in reqs.get("must_kill", []):
+            action = {"type": "kill_process", "hostname": proc["hostname"], "process_name": proc["process"]}
+            history.append({"type": "action", "data": action})
+            obs = env.step(SOCActionWrapper(**action))
+            history.append({"type": "observation", "data": obs.model_dump()})
+            
+        # 3. Block IOCs
+        for ioc in reqs.get("must_block_iocs", []):
+            action = {"type": "block_ioc", "ioc_type": "hash" if len(ioc) > 30 else "ip", "ioc_value": ioc}
+            history.append({"type": "action", "data": action})
+            obs = env.step(SOCActionWrapper(**action))
+            history.append({"type": "observation", "data": obs.model_dump()})
+            
+        # 4. Submit plan
+        plan_entries = []
+        for threat in task_def.get("attack_chain", []):
+            plan_entries.append({
+                "threat_id": threat.get("threat_id"),
+                "actions_taken": ["run_forensics", "kill_process", "block_ioc"],
+                "root_cause": "Initial access via " + threat.get("threat_type"),
+                "confidence": 0.95,
+            })
+            
+        action = {
+            "type": "submit_containment_plan",
+            "plan": plan_entries,
+            "executive_summary": "All threats contained. Malicious processes killed, IOCs blocked, forensics completed.",
+        }
+        history.append({"type": "action", "data": action})
+        obs = env.step(SOCActionWrapper(**action))
+        history.append({"type": "observation", "data": obs.model_dump()})
+        
+        if obs.final_score > 0.3:
+            traces.append(_format_as_chat(history))
+            print(f"Task {task_id}: Score = {obs.final_score:.2f} (Added)")
+        else:
+            print(f"Task {task_id}: Score = {obs.final_score:.2f} (Skipped - Score too low)")
+            
+    with open(output_file, "w") as f:
+        for trace in traces:
+            f.write(json.dumps(trace) + "\n")
+            
+    print(f"Saved {len(traces)} traces to {output_file}")
+
+if __name__ == "__main__":
+    collect_winning_traces()

training/reward_funcs.py

@@ -0,0 +1,164 @@
+"""TRL-compatible reward functions for GRPO training on CyberSOCEnv.
+
+Usage:
+    from training.reward_funcs import make_soc_reward_funcs
+
+    reward_fns = make_soc_reward_funcs("http://localhost:8000")
+    # reward_fns is a list of 10 callables — one per grading dimension.
+    # Pass them directly to trl.GRPOTrainer(reward_funcs=reward_fns).
+
+Each reward function matches the TRL GRPO signature::
+
+    def reward_fn(completions: List[str], **kwargs) -> List[float]: ...
+
+Completions should be JSON strings encoding a list of SOC action dicts, e.g.::
+
+    '[{"type": "query_host", "hostname": "WS-042"},
+      {"type": "run_forensics", "hostname": "WS-042"},
+      {"type": "submit_containment_plan", "plan": [...], "executive_summary": "..."}]'
+
+The function resets the environment, replays all actions, and returns the
+requested dimension's score from the terminal grade_breakdown.  Non-parseable
+completions return 0.0.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Callable, List, Optional
+
+try:
+    import requests as _requests
+except ImportError:  # pragma: no cover
+    _requests = None  # type: ignore[assignment]
+
+
+DIMENSION_NAMES: List[str] = [
+    "threat_containment",
+    "ioc_blocking",
+    "forensic_investigation",
+    "siem_correlation",
+    "threat_intel_usage",
+    "vuln_root_cause",
+    "business_impact",
+    "step_efficiency",
+    "plan_coverage",
+    "plan_evidence_quality",
+]
+
+
+def _execute_completion(
+    env_url: str,
+    completion: str,
+    task_id: str = "hard",
+    timeout: int = 30,
+) -> Optional[dict]:
+    """Parse a completion and replay it against the live env server.
+
+    Returns the final observation dict on success, or None on any failure
+    (parse error, network error, server error).
+    """
+    if _requests is None:
+        raise RuntimeError("requests library is required: pip install requests")
+
+    # Parse the completion as a JSON list of action dicts
+    try:
+        actions = json.loads(completion)
+        if not isinstance(actions, list):
+            return None
+    except (json.JSONDecodeError, ValueError):
+        return None
+
+    try:
+        # Reset the environment for a fresh episode
+        resp = _requests.post(
+            f"{env_url}/reset",
+            json={"task_id": task_id},
+            timeout=timeout,
+        )
+        resp.raise_for_status()
+        obs = resp.json()
+
+        # Replay each action
+        for action in actions:
+            if not isinstance(action, dict) or "type" not in action:
+                continue
+            resp = _requests.post(f"{env_url}/step", json=action, timeout=timeout)
+            if not resp.ok:
+                break
+            obs = resp.json()
+            obs_data = obs.get("observation", obs)
+            if obs_data.get("done", False):
+                break
+
+        return obs.get("observation", obs)
+
+    except Exception:
+        return None
+
+
+def _make_dimension_reward_fn(env_url: str, dimension: str) -> Callable:
+    """Return a single TRL GRPO reward function for one grading dimension."""
+
+    def reward_fn(completions: List[str], **kwargs) -> List[float]:
+        """TRL GRPO reward function for the ``{dim}`` dimension.
+
+        Args:
+            completions: Batch of model completions (JSON action-list strings).
+            **kwargs: Extra keyword arguments passed by TRL (ignored).
+
+        Returns:
+            List of floats in [0, 1], one score per completion.
+        """
+        scores: List[float] = []
+        for completion in completions:
+            obs = _execute_completion(env_url, completion)
+            if obs is None:
+                scores.append(0.0)
+                continue
+            # Prefer terminal grade_breakdown; fall back to per-step reward_dimensions
+            breakdown: dict = obs.get("grade_breakdown") or obs.get("reward_dimensions") or {}
+            scores.append(float(breakdown.get(dimension, 0.0)))
+        return scores
+
+    reward_fn.__name__ = f"soc_{dimension}"
+    reward_fn.__doc__ = reward_fn.__doc__.replace("{dim}", dimension)  # type: ignore[union-attr]
+    return reward_fn
+
+
+def make_soc_reward_funcs(env_url: str) -> List[Callable]:
+    """Return 10 TRL GRPO reward functions, one per grading dimension.
+
+    The functions are ordered to match ``DIMENSION_NAMES``:
+      0  threat_containment     (weight 0.20)
+      1  ioc_blocking           (weight 0.12)
+      2  forensic_investigation (weight 0.10)
+      3  siem_correlation       (weight 0.08)
+      4  threat_intel_usage     (weight 0.08)
+      5  vuln_root_cause        (weight 0.08)
+      6  business_impact        (weight 0.10)
+      7  step_efficiency        (weight 0.07)
+      8  plan_coverage          (weight 0.10)
+      9  plan_evidence_quality  (weight 0.07)
+
+    Args:
+        env_url: Base URL of the running CyberSOCEnv FastAPI server,
+                 e.g. ``"http://localhost:8000"``.
+
+    Returns:
+        List of 10 callables matching the TRL GRPO signature
+        ``reward_fn(completions, **kwargs) -> List[float]``.
+
+    Example::
+
+        from trl import GRPOTrainer, GRPOConfig
+        from training.reward_funcs import make_soc_reward_funcs
+
+        reward_fns = make_soc_reward_funcs("http://localhost:8000")
+        trainer = GRPOTrainer(
+            model=model,
+            reward_funcs=reward_fns,
+            args=GRPOConfig(...),
+        )
+    """
+    return [_make_dimension_reward_fn(env_url, dim) for dim in DIMENSION_NAMES]

validate_submission.sh

@@ -0,0 +1,159 @@
+#!/bin/bash
+set -uo pipefail
+
+DOCKER_BUILD_TIMEOUT=600
+if [ -t 1 ]; then
+  RED='\033[0;31m'
+  GREEN='\033[0;32m'
+  YELLOW='\033[1;33m'
+  BOLD='\033[1m'
+  NC='\033[0m'
+else
+  RED='' GREEN='' YELLOW='' BOLD='' NC=''
+fi
+
+run_with_timeout() {
+  local secs="$1"; shift
+  if command -v timeout &>/dev/null; then
+    timeout "$secs" "$@"
+  elif command -v gtimeout &>/dev/null; then
+    gtimeout "$secs" "$@"
+  else
+    "$@" &
+    local pid=$!
+    ( sleep "$secs" && kill "$pid" 2>/dev/null ) &
+    local watcher=$!
+    wait "$pid" 2>/dev/null
+    local rc=$?
+    kill "$watcher" 2>/dev/null
+    wait "$watcher" 2>/dev/null
+    return $rc
+  fi
+}
+
+portable_mktemp() {
+  local prefix="${1:-validate}"
+  mktemp "${TMPDIR:-/tmp}/${prefix}-XXXXXX" 2>/dev/null || mktemp
+}
+
+CLEANUP_FILES=()
+cleanup() { rm -f "${CLEANUP_FILES[@]+"${CLEANUP_FILES[@]}"}"; }
+trap cleanup EXIT
+
+PING_URL="${1:-}"
+REPO_DIR="${2:-.}"
+
+if [ -z "$PING_URL" ]; then
+  printf "Usage: %s <ping_url> [repo_dir]\n" "$0"
+  printf "\n"
+  printf "  ping_url   Your HuggingFace Space URL (e.g. https://your-space.hf.space)\n"
+  printf "  repo_dir   Path to your repo (default: current directory)\n"
+  exit 1
+fi
+
+if ! REPO_DIR="$(cd "$REPO_DIR" 2>/dev/null && pwd)"; then
+  printf "Error: directory '%s' not found\n" "${2:-.}"
+  exit 1
+fi
+PING_URL="${PING_URL%/}"
+export PING_URL
+PASS=0
+
+log()  { printf "[%s] %b\n" "$(date -u +%H:%M:%S)" "$*"; }
+pass() { log "${GREEN}PASSED${NC} -- $1"; PASS=$((PASS + 1)); }
+fail() { log "${RED}FAILED${NC} -- $1"; }
+hint() { printf "  ${YELLOW}Hint:${NC} %b\n" "$1"; }
+stop_at() {
+  printf "\n"
+  printf "${RED}${BOLD}Validation stopped at %s.${NC} Fix the above before continuing.\n" "$1"
+  exit 1
+}
+
+printf "\n"
+printf "${BOLD}========================================${NC}\n"
+printf "${BOLD}  OpenEnv Submission Validator${NC}\n"
+printf "${BOLD}========================================${NC}\n"
+log "Repo:     $REPO_DIR"
+log "Ping URL: $PING_URL"
+printf "\n"
+
+log "${BOLD}Step 1/3: Pinging HF Space${NC} ($PING_URL/reset) ..."
+
+CURL_OUTPUT=$(portable_mktemp "validate-curl")
+CLEANUP_FILES+=("$CURL_OUTPUT")
+HTTP_CODE=$(curl -s -o "$CURL_OUTPUT" -w "%{http_code}" -X POST \
+  -H "Content-Type: application/json" -d '{}' \
+  "$PING_URL/reset" --max-time 30 2>"$CURL_OUTPUT" || printf "000")
+
+if [ "$HTTP_CODE" = "200" ]; then
+  pass "HF Space is live and responds to /reset"
+elif [ "$HTTP_CODE" = "000" ]; then
+  fail "HF Space not reachable (connection failed or timed out)"
+  hint "Check your network connection and that the Space is running."
+  hint "Try: curl -s -o /dev/null -w '%%{http_code}' -X POST $PING_URL/reset"
+  stop_at "Step 1"
+else
+  fail "HF Space /reset returned HTTP $HTTP_CODE (expected 200)"
+  hint "Make sure your Space is running and the URL is correct."
+  hint "Try opening $PING_URL in your browser first."
+  stop_at "Step 1"
+fi
+
+log "${BOLD}Step 2/3: Running docker build${NC} ..."
+
+if ! command -v docker &>/dev/null; then
+  fail "docker command not found"
+  hint "Install Docker: https://docs.docker.com/get-docker/"
+  stop_at "Step 2"
+fi
+
+if [ -f "$REPO_DIR/Dockerfile" ]; then
+  DOCKER_CONTEXT="$REPO_DIR"
+elif [ -f "$REPO_DIR/server/Dockerfile" ]; then
+  DOCKER_CONTEXT="$REPO_DIR/server"
+else
+  fail "No Dockerfile found in repo root or server/ directory"
+  stop_at "Step 2"
+fi
+
+log "  Found Dockerfile in $DOCKER_CONTEXT"
+
+BUILD_OK=false
+BUILD_OUTPUT=$(run_with_timeout "$DOCKER_BUILD_TIMEOUT" docker build "$DOCKER_CONTEXT" 2>&1) && BUILD_OK=true
+
+if [ "$BUILD_OK" = true ]; then
+  pass "Docker build succeeded"
+else
+  fail "Docker build failed (timeout=${DOCKER_BUILD_TIMEOUT}s)"
+  printf "%s\n" "$BUILD_OUTPUT" | tail -20
+  stop_at "Step 2"
+fi
+
+log "${BOLD}Step 3/3: Running openenv validate${NC} ..."
+
+if ! command -v openenv &>/dev/null; then
+  fail "openenv command not found"
+  hint "Install it: pip install openenv-core"
+  stop_at "Step 3"
+fi
+
+VALIDATE_OK=false
+VALIDATE_OUTPUT=$(cd "$REPO_DIR" && openenv validate 2>&1) && VALIDATE_OK=true
+
+if [ "$VALIDATE_OK" = true ]; then
+  pass "openenv validate passed"
+  [ -n "$VALIDATE_OUTPUT" ] && log "  $VALIDATE_OUTPUT"
+else
+  fail "openenv validate failed"
+  printf "%s\n" "$VALIDATE_OUTPUT"
+  stop_at "Step 3"
+fi
+
+printf "\n"
+printf "${BOLD}========================================${NC}\n"
+printf "${GREEN}${BOLD}  All 3/3 checks passed!${NC}\n"
+printf "${GREEN}${BOLD}  Your submission is ready to submit.${NC}\n"
+printf "${BOLD}========================================${NC}\n"
+printf "\n"
+
+exit 0