A browser-based hacking simulation game that provides educational cybersecurity training through gamified red-team and blue-team scenarios. Players learn real-world security concepts in a safe, sandboxed environment.
PortScan is an addictive cybersecurity simulation game featuring:
- Dual Team Gameplay: Choose between red-team (offensive security) or blue-team (defensive security) missions
- Terminal-Style Interface: Authentic hacker aesthetic with simulated laptop screen experience
- Progressive Learning: Rank-based progression system with XP rewards and achievements
- Safe Environment: All commands are simulated and educational-only - no real network activity
- Mission-Based Structure: Complete challenges based on real-world cybersecurity techniques
- Monetization Ready: Built-in support for ads, in-app purchases, and subscription models
- Python 3.7+
- Modern web browser
-
Clone the repository
git clone https://github.com/frank-bordonaro/portscan.git cd portscan -
Set up Python environment
python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -r requirements.txt
-
Initialize the database
python seed_data.py
-
Start the server
python server.py
-
Play the game Open your browser and navigate to:
http://127.0.0.1:5000
- Enter a username (no password required for demo)
- Choose your team:
- Red Team: Offensive security (penetration testing, exploitation)
- Blue Team: Defensive security (forensics, incident response, hardening)
- Complete missions using simulated terminal commands
All commands are simulated and safe - they produce educational output without performing real actions:
scan <target>- Simulate network reconnaissancephish <target>- Craft simulated phishing attemptsexploit simulate- Execute safe exploitation scenariosinspect <snapshot>- Analyze simulated forensic evidenceapply-patch <id>- Simulate security hardeninghelporhint- View available commands
- XP System: Earn experience points by completing missions
- Rank Progression:
- Novice (0 XP)
- Operator (100 XP)
- Specialist (300 XP)
- Elite (700 XP)
- Master (1500 XP)
- Mission Variety: Randomly assigned missions based on your chosen team
- Backend: Flask (Python web framework)
- Database: SQLite (default) with MySQL support
- Frontend: HTML5, CSS3, JavaScript (ES6+)
- Authentication: Flask-Login with simple username-based auth
- ORM: SQLAlchemy for database operations
PortScan/
├── server.py # Main Flask application
├── game_engine.py # Command simulation engine
├── models.py # Database models and ORM
├── config.py # Configuration settings
├── seed_data.py # Database initialization
├── requirements.txt # Python dependencies
├── templates/ # HTML templates
│ ├── layout.html # Base template
│ ├── index.html # Landing page
│ ├── game.html # Main game interface
│ └── admin.html # Admin panel
├── static/
│ ├── css/ # Stylesheets
│ └── js/
│ └── app.js # Frontend JavaScript
└── data/ # SQLite database storage
- Processes simulated commands safely
- Provides educational output without real system interaction
- Handles mission completion logic
- Maintains game state and command history
- User Management: Simple username-based authentication
- Mission System: Flexible mission storage with JSON payloads
- Progress Tracking: XP, ranks, and mission completion
- Site Configuration: Dynamic game settings
- All commands are simulated and non-actionable
- Input sanitization prevents malicious input
- No real network or system commands are executed
- Educational disclaimers on all outputs
# Game branding
GAME_NAME="PortScan" # Customize game name
# Database configuration
DATABASE_URL="sqlite:///data/game.db" # Default SQLite
# DATABASE_URL="mysql+pymysql://user:pass@host/dbname" # MySQL option
# Security
ADMIN_TOKEN="your-secure-admin-token" # Admin panel access
APP_SECRET="your-flask-secret-key" # Session encryption
# Server settings
PORT=5000 # Server portSQLite (Default)
- Zero configuration required
- Perfect for development and small deployments
- Database file stored in
data/game.db
MySQL (Production)
- Set
DATABASE_URLenvironment variable - Supports concurrent users and better performance
- Recommended for production deployments
Access the admin panel at /admin?token=<ADMIN_TOKEN> to:
- Configure game settings
- Manage site-wide options
- Monitor game statistics
- Dynamic Missions: JSON-based mission definitions
- Team-Specific Content: Different missions for red/blue teams
- Flexible Payloads: Extensible mission data structure
- Random Assignment: Keeps gameplay fresh and challenging
- Ad Integration: Placeholder ad spots ready for implementation
- In-App Purchases: Skip missions, buy hints, premium content
- Subscription Model: Ready for premium tier implementation
- Hint System: Watch ads for mission hints
- Responsive Design: Works on desktop and mobile browsers
- Terminal Aesthetic: Authentic hacker interface
- Real-time Feedback: Immediate command responses
- Progress Visualization: Clear XP and rank displays
- Edit
game_engine.py - Add command logic in
simulate_command()function - Ensure all output includes safety disclaimers
- Test thoroughly for security
# Example mission creation
Mission.create(
team='red',
slug='recon-basic',
title='Basic Reconnaissance',
payload=json.dumps({
'desc': 'Scan the target to identify open ports',
'required_sim_cmd': 'scan',
'hint': 'Use: scan target-host'
})
)- users: User accounts and authentication
- missions: Mission definitions and metadata
- progress: User progression and statistics
- siteconfig: Dynamic configuration storage
python server.py
# Server runs on http://127.0.0.1:8675- Set production environment variables
- Configure MySQL database (recommended)
- Use a production WSGI server (gunicorn, uWSGI)
- Set up reverse proxy (nginx, Apache)
- Enable HTTPS for security
- SiteGround: Optimized for Flask applications
- Heroku: Easy deployment with git integration
- DigitalOcean: Full control over server environment
- AWS/GCP: Scalable cloud deployment options
- No Real Commands: All terminal commands are simulated
- Input Sanitization: User input is cleaned and validated
- Educational Only: Clear disclaimers on all outputs
- Sandboxed Environment: No system or network access
- Change default admin token in production
- Use strong Flask secret keys
- Enable HTTPS in production
- Regular security updates for dependencies
- Monitor for suspicious activity
- Micro-tasks: Break features into small, manageable tasks
- No Core Changes: Don't modify existing game loops without approval
- Security First: Ensure all new features maintain safety
- Documentation: Update README for significant changes
- Testing: Verify changes work locally before submission
- Follow PEP 8 for Python code
- Use meaningful variable names
- Comment complex logic
- Maintain modular structure
This project is licensed under the MIT License - see the LICENSE file for details.
PortScan bridges the gap between cybersecurity education and engaging gameplay. By simulating real-world security scenarios in a safe environment, players develop practical knowledge while having fun. The game emphasizes:
- Learning by Doing: Hands-on experience with security tools and techniques
- Safe Exploration: Risk-free environment to experiment and learn
- Progressive Difficulty: Gradual skill building from novice to expert
- Real-World Relevance: Scenarios based on actual cybersecurity practices
- Multiplayer Competitions: Team-based challenges and tournaments
- Advanced Missions: More complex multi-step scenarios
- Certification Paths: Structured learning tracks for different roles
- Integration APIs: Connect with real security tools and platforms
- Mobile App: Native mobile experience
- VR/AR Support: Immersive cybersecurity training
Ready to start your cybersecurity journey? Clone the repo and begin your training today!