# CyberSim OS **Phase 2 MVP: Scenario-Driven Cybersecurity Simulation Platform** CyberSim OS is an offline-first, browser-native cybersecurity simulation platform designed for ordinary end users. Learners enter a convincing fictional enterprise desktop, perform routine workplace activities, investigate ambiguous events, encounter realistic threats (credential phishing, malicious attachments) and legitimate false flags, receive a multi-axis behavioral after-action assessment, and earn cryptographically verifiable completion certificates (`*.cybercert`). **Phase 2** transforms CyberSim from a single hard-coded simulation into a **reusable, scenario-driven platform**. Complete experiences are authored through portable declarative JSON scenario packages — no application code changes required. --- ## Key Features - **Scenario-Driven Architecture**: Complete simulations are defined through JSON scenario packages. No code changes needed to create new experiences. - **Convincing Fictional Desktop**: Original Windows-like theme with draggable/resizable windows, active/inactive focus states, taskbar, Start launcher, simulation clock, and system toast notifications with audio cues. - **Core Simulated Workplace Applications**: - **Inlook**: Email client with header inspector (RFC sender vs. friendly name), link hover destination tooltips, phishing report workflow, and reply/delete actions. - **Navigator**: Web browser supporting intranet directories, policy hubs, and external spoofed credential-harvesting portals. - **Files**: Virtual filesystem managing Documents, Downloads, and Company Shared folders. - **Doc Viewer**: Lightweight renderer for spreadsheets (`.xlsx`), policies (`.pdf`), and memos. - **Security Center**: Endpoint protection dashboard, real-time alert logs, incident report confirmations, and delayed alert triggers. - **Declarative Event System**: Scenario events with time-based, action-based, and state-based triggers execute through a restricted behavior vocabulary. - **Data-Driven Scoring**: Scoring categories, rules, and thresholds are defined in the scenario package. The engine evaluates them generically. - **Delayed Consequences Engine**: Unsafe actions trigger delayed consequence events without giving immediate arcade-like game-over feedback. - **Verifiable Cryptographic Certificates**: - Web Crypto SHA-256 scenario fingerprinting. - Portable, structured `*.cybercert` JSON credential export. - Standalone offline certificate validator (`verify.html`). - **100% Offline-First & Zero Dependencies**: Runs directly from any static web server, GitHub Pages, or the bundled `launcher.py` with zero npm/node/external CDN requirements. --- ## Quick Start ### Option 1: Standalone Local Launcher (Python 3) Run the lightweight local launcher to start the server at `http://127.0.0.1:8080`: ```bash python launcher.py ``` Your default web browser will open automatically with the default scenario. ### Option 2: Static Web Server Serve the `src/` directory with any static HTTP server: ```bash cd src python -m http.server 8000 ``` Open [http://127.0.0.1:8000](http://127.0.0.1:8000) in your browser. ### Loading a Specific Scenario Use the `?scenario=` query parameter to load a scenario package: ``` http://127.0.0.1:8080?scenario=scenarios/nexacore-orientation/scenario.json http://127.0.0.1:8080?scenario=scenarios/quickstart-example/scenario.json ``` If no `?scenario=` parameter is specified, the engine loads `scenarios/nexacore-orientation/scenario.json` by default. --- ## Included Scenarios | Scenario | Description | |----------|-------------| | **NexaCore Orientation** (`nexacore-orientation`) | Full-featured scenario: 5 emails, 3 web pages, 3 documents, 6 scoring categories, credential phishing + malicious attachment threats, 2 false flags. ~15 min. | | **Meridian Health Quickstart** (`quickstart-example`) | Minimal scenario: 3 emails, 1 web page, 2 documents, 3 scoring categories, 1 credential phishing threat. ~5 min. | --- ## Creating a Scenario Scenarios are self-contained JSON packages stored in a directory: ``` scenarios/my-scenario/ ├── scenario.json # Scenario definition (required) ├── assets/ # Optional images, media └── README.md # Author notes (optional) ``` The `scenario.json` file defines everything the learner experiences: - **People** and **organizations** (contacts, domains, trust boundaries) - **Messages** (emails with links, attachments, threat indicators) - **Pages** (simulated websites with forms) - **Files** (virtual documents, spreadsheets, policies) - **Events** (time-triggered, action-triggered, state-triggered with delays) - **Scoring** (categories, rules, conditions, thresholds) - **Findings** and **feedback** (behavioral evaluation with pedagogical notes) See `docs/scenario-format.md` for the full format reference. --- ## Certificate Verification To verify a `*.cybercert` certificate issued by CyberSim OS: 1. Open `src/verify.html` in your web browser. 2. Drag and drop the `*.cybercert` file into the verification area. 3. The offline verifier recalculates the SHA-256 integrity hash, verifies the scenario fingerprint, and confirms the passing score and learner identity. --- ## Architecture & Directory Structure ``` CyberSim-OS/ ├── .labyricorn/ # Labyricorn exhibition & devlog publishing records ├── scenarios/ │ ├── nexacore-orientation/ # Phase 1 scenario (fully declarative) │ │ └── scenario.json │ └── quickstart-example/ # Second example scenario │ └── scenario.json ├── docs/ │ └── scenario-format.md # Scenario format reference (TODO) ├── src/ │ ├── index.html # Main desktop simulation interface │ ├── verify.html # Standalone offline certificate verifier │ ├── css/ │ │ ├── theme-windows.css # Fictional Windows-like enterprise theme tokens │ │ ├── desktop.css # Window manager, taskbar, start menu, tray, toasts │ │ ├── components.css # Modals, form inputs, buttons, badges, tabs │ │ └── apps.css # Inlook, Navigator, Files, DocViewer, SecurityCenter │ ├── js/ │ │ ├── main.js # Application bootstrapper & scenario loader │ │ ├── core/ │ │ │ ├── window_manager.js# Window lifecycle, stacking, drag, min/max/close │ │ │ ├── desktop.js # Desktop shell, launcher, clock, simulation controls │ │ │ └── notifications.js # Toast notifications & Web Audio synth audio chime │ │ ├── apps/ │ │ │ ├── inlook.js # Email client with RFC header/link inspection │ │ │ ├── navigator.js # Simulated browser with data-driven pages & forms │ │ │ ├── files.js # Virtual filesystem explorer │ │ │ ├── docviewer.js # Spreadsheet and document viewer │ │ │ └── security_center.js # Endpoint status & incident report dashboard │ │ ├── engine/ │ │ │ ├── event_bus.js # Behavioral telemetry logger │ │ │ ├── consequence.js # Consequence tracking (Phase 2 thin wrapper) │ │ │ ├── scenario_state.js# Central mutable scenario state manager │ │ │ ├── condition_evaluator.js # Declarative condition tree evaluator │ │ │ ├── event_scheduler.js # Time/action/state-driven event executor │ │ │ └── action_dispatcher.js # Restricted behavior vocabulary dispatcher │ │ ├── scenario/ │ │ │ ├── schema.js # JSON schema validation │ │ │ ├── loader.js # Scenario package loader & sanitizer │ │ │ ├── validator.js # Deep reference integrity validation │ │ │ ├── diagnostics.js # Dev-mode diagnostics overlay │ │ │ └── fingerprint.js # Web Crypto SHA-256 scenario fingerprinting │ │ ├── scoring/ │ │ │ ├── scorer.js # Data-driven behavioral scoring engine │ │ │ └── aar.js # After-Action Report modal │ │ └── cert/ │ │ ├── cert_generator.js# *.cybercert JSON generator & printable certificate │ │ └── cert_verifier.js # Offline cryptographic certificate verifier │ └── assets/ # Embedded SVG icons and media ├── launcher.py # Zero-dependency local 127.0.0.1 web server ├── devlog_editor.py # Labyricorn devlog validation & editing tool └── README.md # Project documentation ``` --- ## Development Mode Add `?dev=true` to the URL to enable the diagnostics overlay: ``` http://127.0.0.1:8080?scenario=../scenarios/nexacore-orientation/scenario.json&dev=true ``` The diagnostics panel shows: - Scenario validation results (errors, warnings) - Object counts (people, messages, events, etc.) - Live event states and scores - Scenario fingerprint --- ## Validation & Devlog Maintenance Run the validation suite to ensure `.labyricorn/` records and devlog entries adhere to the schema: ```bash python devlog_editor.py --validate ``` --- ## License MIT License. See `LICENSE` for details.