CyberSim-OS/README.md

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:

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:

cd src
python -m http.server 8000

Open 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:

python devlog_editor.py --validate

---

License

MIT License. See LICENSE for details.