mirror of
https://github.com/cliffe/BreakEscape.git
synced 2026-02-21 19:28:03 +00:00
e70e4cf9dd
Stage 0 COMPLETE! All foundation documents created: Document 1: Scenario Initialization (820 lines) ✅ - Mission overview (tier, playtime, ENTROPY cell, SecGen scenario) - CyBOK knowledge areas (NSS, SS, ACS, SOC, HF, AB) - 3-act structure with scene preview - Key NPCs (Victoria Sterling, James Park, Cipher, Agent 0x99) - 4 LORE fragments with campaign significance - Victory conditions (100%, 80%, 60%) - Educational objectives - Campaign arc connections (M1-M2-M4-M6-M7-9) - Post-mission debrief script - Critical decisions: RFID (proximity + social eng), scanning (auto + tutorial), double agent (long-term vs immediate), Architect (name only) Document 2: Technical Challenges (812 lines) ✅ Break Escape In-Game: - RFID Cloning (NEW): Proximity (2 GU, 10s), visual feedback, tutorial, alt paths - Lockpicking: 4 locks (cabinet, office, security, safe PIN 2010) - Guard Patrol: 60s loop, LOS detection, timing strategies - Social Engineering: Victoria trust (0-100), James intel, guard cover stories - Multi-Encoding: ROT13, Hex, Base64, double-encoded (ROT13+Base64) VM/SecGen Challenges: - Network Scanning: nmap, flag{network_scan_complete} - Banner Grabbing: netcat FTP, flag{ftp_intel_gathered}, GHOST codename - HTTP Analysis: Base64 HTML, flag{pricing_intel_decoded} - distcc Exploit: CVE-2004-2687, flag{distcc_legacy_compromised}, M2 connection! Integration: 9 challenges (5 in-game, 4 VM), difficulty scaling, educational rubric Document 3: Narrative Themes (600+ lines) ✅ Theme: Corporate Espionage / Intelligence Gathering Setting: WhiteHat Security Services (Zero Day front company) - Daytime: Professional corporate facade - Nighttime: Espionage thriller tension - Contrast: Same location, two faces NPCs Detailed: - Victoria Sterling: Free-market ideologue, true believer, double agent candidate - James Park: Innocent employee, moral complexity, protection choice - "Cipher": Cell leader (referenced), future villain setup - Agent 0x99: Handler, tutorials, debrief narrator Tone: Espionage thriller (Michael Clayton, Tinker Tailor Soldier Spy) Stakes: Personal (James), Organizational (SAFETYNET vs Zero Day), Societal (exploit marketplace) Central Conflict: Player vs Victoria ideology, vs Zero Day operations, vs Architect (background) Document 4: Hybrid Architecture Plan (700+ lines) ✅ VM Component (SecGen "Information Gathering: Scanning"): - Validates network reconnaissance (nmap, netcat, distcc) - 4 flags represent ENTROPY intercepts - Stable (pre-built, unchanged for assessment consistency) ERB Component (Narrative Content): - Encoded messages (ROT13, Hex, Base64, double-encoded) - LORE fragments (client list, exploit catalog, Architect directives) - NPC dialogues (Ink scripts) - Environmental storytelling Dead Drop Integration: - VM flag → submit at drop-site terminal → unlock in-game resource - flag{network_scan_complete} → workstation access - flag{ftp_intel_gathered} → client codename list - flag{pricing_intel_decoded} → pricing spreadsheet, LORE 2 access - flag{distcc_legacy_compromised} → M2 connection reveal, Agent 0x99 "aha moment" Correlation Matrix: - FTP banner (VM) "GHOST" ↔ Hex client list "Ransomware Inc" ↔ distcc log "ProFTPD sale" - ROT13 whiteboard "THE ARCHITECT" ↔ Double-encoded USB "Architect directives" - Base64 email "$12,500 ProFTPD" ↔ distcc log "ProFTPD sale $12,500" (exact match!) Educational Integration: - Agent 0x99 tutorials (RFID, nmap, netcat, encoding) - Drop-site terminal annotations (port explanations) - CyberChef workstation hints (after failed attempts) Key Mission Features: 🆕 RFID Keycard Cloning (2 GU proximity, 10s clone, progress bar, tutorial) 🎯 M2 Revelation (ProFTPD sold to Ghost for $12,500, hospital ransomware connection) 🎯 Architect Introduction (First direct communication, Q4 priorities, cell coordination) ⚖️ Moral Choices (Victoria: arrest vs double agent | James: protect vs ignore) 📚 Educational (NSS: nmap/netcat, SS: distcc CVE, ACS: multi-encoding, SOC: correlation) Victory Conditions: - 100%: All 4 VM flags + 4 encoded messages + 3 LORE + choices + stealth - 80%: 3 VM flags + 3 messages + 2 LORE + choices - 60%: 2 VM flags + 2 messages + choices Campaign Impact: - Confirms ENTROPY coordination (not independent cells) - Reveals The Architect as real coordinator (not myth) - Proves Zero Day is central exploit supplier - Sets up M4 (Critical Mass SCADA), M6 (Crypto Anarchists), M7-9 (Architect hunt) Stage 0 Status: ✅ COMPLETE (4/4 documents, ~2,900 lines) Next: Stage 1 - Narrative Structure Development (scene-by-scene breakdown)
BreakEscape Rails Engine
Cybersecurity training escape room game as a mountable Rails Engine.
Features
- 24+ cybersecurity escape room scenarios
- Server-side progress tracking with 2-table schema
- Randomized passwords per game instance via ERB
- JIT Ink script compilation for NPC dialogue
- Polymorphic player support (User/DemoUser)
- Pundit authorization
- RESTful API for game state management
- Session-based state persistence
Installation
In your Gemfile:
gem 'break_escape', path: 'path/to/break_escape'
Then:
bundle install
rails break_escape:install:migrations
rails db:migrate
rails db:seed # Optional: creates missions from scenarios
Mounting in Host App
In your config/routes.rb:
mount BreakEscape::Engine => "/break_escape"
Usage
Standalone Mode (Development)
export BREAK_ESCAPE_STANDALONE=true
rails server
# Visit http://localhost:3000/break_escape/
Mounted Mode (Production)
Mount in Hacktivity or another Rails app. The engine will use the host app's current_user via Devise.
Configuration
# config/initializers/break_escape.rb
BreakEscape.configure do |config|
config.standalone_mode = false # true for development
config.demo_user_handle = 'demo_player'
end
Database Schema
break_escape_missions- Scenario metadata (name, display_name, published, difficulty)break_escape_games- Player state + scenario snapshot (JSONB)break_escape_demo_users- Standalone mode only (optional)
API Endpoints
GET /games/:id/scenario- Scenario JSON (ERB-generated)GET /games/:id/ink?npc=X- NPC script (JIT compiled from .ink)GET /games/:id/bootstrap- Initial game dataPUT /games/:id/sync_state- Sync player statePOST /games/:id/unlock- Validate unlock attemptPOST /games/:id/inventory- Update inventory
Architecture
ERB Scenario Generation
Scenarios are stored as .json.erb templates and rendered on-demand with randomized values:
<%= random_password %>- Generates unique password per game<%= random_pin %>- Generates unique 4-digit PIN<%= random_code %>- Generates unique hex code
JIT Ink Compilation
NPC dialogue scripts compile on first request (~300ms):
- Check if
.jsonexists and is newer than.ink - If needed, run
inklecateto compile - Cache compiled JSON for subsequent requests
State Management
Player state stored in JSONB column:
- Current room and unlocked rooms
- Inventory and collected items
- NPC encounters
- Global variables (synced with client)
- Health and minigame state
Testing
rails test
License
AGPL v3 - See LICENSE file for details
Documentation
See HACKTIVITY_INTEGRATION.md for integration guide.