mirror of
https://github.com/cliffe/BreakEscape.git
synced 2026-02-21 11:18:08 +00:00
92db4b3cfe
Stage 0: Scenario Initialization - Complete mission overview with hospital ransomware crisis - Ransomware Incorporated cell integration - Hybrid architecture plan (VM ProFTPD exploitation + ERB narrative) - Concrete stakes: 47 patients, 12-hour deadline, $87K ransom - Ghost as true believer antagonist (calculated patient deaths) - 3 LORE fragments planned (manifesto, CryptoSecure, ZDS invoice) Stage 1: Narrative Structure - Complete 3-act structure (18 scenes) - Act 1: Infiltration (Dr. Kim, Marcus, guard tutorial) - Act 2: Exploitation (VM challenges, safe puzzle, LORE discoveries) - Act 3: Impossible choices (ransom dilemma, hospital exposure) - Emotional beat timeline with intensity mapping - Tutorial integration for new mechanics (guards, PIN safe, ROT13) Stage 2: Character Development - Dr. Sarah Kim: Desperate CTO with guilt over budget cuts - Marcus Webb: Defensive IT admin, scapegoat victim - Ghost: Unrepentant ENTROPY operative, true believer - Agent 0x99: Supportive handler, growing ENTROPY concern - Voice examples with 3-line dialogue rule - Character arcs defined (Marcus varies by player choice) Stage 3: Moral Choices and Consequences - Choice 1: Marcus trust building (sympathize/professional/blame) - Choice 2: Marcus protection (warn/plant evidence/ignore) - Choice 3: Ransom payment (pay/independent recovery) - NO RIGHT ANSWER - Choice 4: Hospital exposure (public/quiet) - transparency vs pragmatism - Optional: Ghost confrontation (argue/acknowledge/silent) - All choices have meaningful campaign consequences (M6 financial trail) - Utilitarian vs Consequentialist ethical frameworks - Debrief variations reflect all choices (4 ransom+exposure combos) Stage 4: Player Objectives and Tasks - 5 required aims, 3 optional aims - 23 required tasks, 4 optional tasks (27 total) - Hybrid objectives: VM flag submissions + in-game tasks - Success tiers: 60% minimal, 80% standard, 100% perfect - Progressive unlocking validated (no soft locks) - Ink tag integration (#complete_task, #unlock_aim, #give_item) - Optional achievements: Ghost Hunter, Code Breaker, Ethical Hacker Technical Challenges (Detailed Breakdown): - New mechanics: Patrolling guards (60s predictable), PIN safe puzzle - Reinforced mechanics: Lockpicking (4 doors), social engineering, Base64 - New encoding: ROT13 (Caesar cipher introduction) - VM: ProFTPD CVE-2010-4652 exploitation, SSH brute force, Linux nav - CyBOK coverage: Malware, Incident Response, Cryptography, Human Factors Key Design Decisions: - Ransom dilemma has no 'right' answer (both ethically valid) - Ghost remains unrepentant (true believer, no redemption arc) - Marcus's fate controllable by player (justice possible) - Guard patrols beginner-friendly (forgiving, predictable, alternate paths) - PIN puzzle accessible (multiple clues, hint system, fallback device) - Campaign integration: M3 ZDS connection, M6 financial trail Ready for Stage 5: Room Layout Design
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.