BanditGUI: A Web Interface for OverTheWire Bandit - v0.5.1

---

BanditGUI is a web-based interface for the popular OverTheWire Bandit wargame. It aims to make learning cybersecurity fundamentals more approachable by providing a browser-based terminal, structured level information, and an AI-powered assistant.

---

Why BanditGUI?

The command-line nature of challenges like Bandit can be a hurdle for beginners. BanditGUI lowers this barrier by:

• Providing an integrated terminal in your browser.
• Offering easy access to level goals, commands, and learning resources.
• Assisting with hints and explanations through an AI chat interface.
• Tracking your progress and learning patterns.
• Providing comprehensive security features for safe learning.

Core Features

️ Interactive Web Terminal

• Full-featured xterm.js terminal in your browser
• Real SSH connections to Bandit servers
• Command history and auto-completion
• Secure command validation and injection protection

🎯 Level Guidance System

• Access information and relevant commands for each Bandit level
• Goal descriptions and learning resources
• Command cheatsheet and quick references
• Level progression tracking

🤖 AI-Powered Chat Assistant

• Intelligent hints and explanations from LLM-powered chat
• Supports various models via LiteLLM (OpenAI, Gemini, Anthropic, etc.)
• Context-aware assistance based on current level
• Learning pattern analysis and personalized guidance

📊 Comprehensive Progress Tracking

• Time tracking: Monitor time spent per level
• Command analysis: Track commands used and efficiency
• Hint usage: Monitor assistance utilization
• Completion statistics: View overall progress metrics
• Learning analytics: Analyze learning patterns and improvement
• Automatic progression: Seamless level advancement
• Password management: Secure storage of level passwords

Theme System

• Dark theme: Easy on the eyes for extended sessions
• Light theme: Clean and professional appearance
• High-contrast theme: WCAG compliant for accessibility
• Retro theme: Classic terminal aesthetic

🛡️ Enterprise-Grade Security

• SSH Security: Strict host key verification (no AutoAddPolicy)
• Session Management: Secure cookie-based sessions with CSRF protection
• Rate Limiting: Token bucket-based rate limiting per endpoint
• API Key Security: Secure hashing and automatic rotation
• Input Validation: Comprehensive command injection protection
• Security Logging: Detailed audit trails and monitoring
• Environment Variables: Secure configuration management

♿ Accessibility Features

• Full keyboard navigation support
• Screen reader compatibility
• High-contrast theme for visual accessibility
• Adjustable font sizes
• Color contrast optimization
• WCAG 2.1 AA compliance

🔧 Developer-Friendly

• Modular Design: Maintainable Python Flask backend
• Comprehensive Testing: 45+ security test cases
• Security Auditing: Automated and manual security scans
• Documentation: Complete guides and API documentation
• Error Handling: Structured error responses and logging
• Code Quality: Consistent patterns and best practices

Progress Tracking System

BanditGUI includes a comprehensive progress tracking system that helps you monitor your learning journey:

Features

1. Level Completion Detection

   • Automatic detection of level completion via regex pattern matching
   • Recovery and storage of level passwords
   • Display of completion statistics
   • Automatic progression to next levels

2. Statistics Tracking

   • Time taken per level
   • Number of commands used
   • Hint usage statistics
   • Command efficiency metrics
   • Level completion rate

3. Progress Visualization

   • Completion percentage across all levels
   • Most used commands
   • Command efficiency scores
   • Learning patterns analysis

4. Level Progression

   • Automatic SSH connection management
   • Password recovery and storage
   • Next level connection information
   • Session-based progress tracking

How It Works

1. When you complete a level:

   • The system detects completion via the level completion message
   • Automatically extracts and stores the recovered password
   • Calculates time taken and commands used
   • Displays a congratulatory message with statistics
   • Provides next level connection information
   • Updates your progress tracking

2. Progress is automatically saved:

   • Level completion times
   • Commands used
   • Hint usage
   • Overall completion rate

3. The system helps you progress:

   • Automatically closes current SSH connection
   • Provides next level connection details
   • Clears terminal history for next level
   • Maintains password recovery for future reference

Benefits

• Learning Analytics: Track your progress and identify areas for improvement
• Motivation: See your improvement over time
• Efficiency: Learn from your command usage patterns
• Security: Secure password storage and management
• Guidance: Clear progression path through all levels

Security Features

SSH Security

• Host Key Verification: Strict host key verification using paramiko.RejectPolicy()
• Known Hosts Management: Automatic host key saving and verification
• Connection Security: Secure SSH connection establishment
• Command Validation: Protection against command injection attacks

Session Security

• Secure Cookies: HTTPOnly, Secure, SameSite=Lax cookies
• CSRF Protection: Token-based CSRF protection on all endpoints
  • The frontend now automatically fetches the CSRF token from the backend on startup and includes it in the X-CSRF-Token header for all API requests. The token is updated from response headers as needed. This is required for the app to function and resolves the 'Invalid CSRF token' error.
• Session Timeouts: Configurable session timeouts and refresh
• Session Validation: JSON Schema validation for session data

API Security

• Rate Limiting: Token bucket-based rate limiting per IP and endpoint
• API Key Management: Secure hashing and automatic rotation
• Input Validation: Comprehensive input sanitization
• Error Handling: Generic error responses to prevent information leakage

Data Protection

• Encryption: Data encryption at rest
• Validation: JSON Schema validation for all data
• Backup: Automatic data backup and recovery
• Audit Logging: Comprehensive security event logging

Tech Stack

• Backend: Python (Flask with Flask-Session)
• Frontend: HTML, CSS, JavaScript (xterm.js)
• SSH: Paramiko with strict security
• LLM Integration: LiteLLM (supports multiple providers)
• Security:
  • Flask-Session for secure sessions
  • Custom CSRF protection
  • Rate limiter middleware
  • Secure cookie handling
  • Host key verification
• Testing: pytest with comprehensive security tests
• Documentation: Complete security and API documentation

Getting Started

Prerequisites

• Python 3.8 or higher
• Git
• SSH access to OverTheWire Bandit servers

Installation

1. Clone the repository:

   git clone https://github.com/therealfredp3D/Making-BanditGUI.git
   cd Making-BanditGUI

2. Set up environment variables: Create a .env file in the root directory and add your API keys:

   # .env file
   FLASK_SECRET_KEY=your-secret-key-here
   OPENAI_API_KEY=your-openai-key
   # Add other provider API keys as needed

3. Run the installation script: This script will set up a virtual environment, install dependencies, and create run scripts.

   python install.py
   # or python3 install.py on some systems

4. Follow on-screen instructions. The script will guide you through any necessary checks.

Security Requirements

• Ensure your .env file is never committed to version control
• Use strong, unique session secret keys
• Keep API keys secure and rotate them regularly
• Regularly update dependencies to latest secure versions
• Review security documentation before deployment

Running BanditGUI

• Windows: Execute run.bat (Generated by install.py)
• Linux/macOS: Execute ./run.sh (Generated by install.py)

Once started, the application is typically available at http://127.0.0.1:5000.

SSH Configuration

BanditGUI uses strict SSH security. For first-time connections:

1. Manual Setup (Recommended):

   ssh-keyscan -H bandit.labs.overthewire.org >> ~/.ssh/known_hosts

2. Automatic Setup: BanditGUI will automatically save host keys after successful connections

For detailed SSH configuration, see SSH Security Documentation.

Security Audit

BanditGUI includes comprehensive security auditing capabilities:

Automated Audits

• GitHub Actions: Weekly dependency vulnerability scans
• Security Script: Run python scripts/security_audit.py for comprehensive audit
• Pre-commit Checks: Security validation before code submission

Manual Audits

# Run comprehensive security audit
python scripts/security_audit.py

# Check dependencies
pip-audit

# Analyze code security
bandit -r banditgui/

For complete security audit process, see Security Documentation.

Testing

BanditGUI includes comprehensive testing with 45+ security test cases:

Running Tests

# Run all tests
pytest

# Run security tests only
pytest tests/test_ssh_security.py tests/test_api_key_manager.py tests/test_security_integration.py

# Run with coverage
pytest --cov=banditgui

Test Coverage

• SSH Security: Host key verification, connection security, error handling
• API Key Management: Hashing, validation, rotation, security logging
• Integration: Cross-component security testing
• Error Handling: Comprehensive edge case testing

How to Contribute

We welcome contributions! Please follow these general steps:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Make your changes.
4. Test your changes thoroughly.
   • Ensure security features are maintained
   • Verify session handling
   • Test API rate limiting
   • Run security audits
5. Commit your changes with a clear message.
6. Open a Pull Request to the main branch.

Security Considerations for Contributors

• Always validate user input
• Follow secure coding practices
• Maintain proper session handling
• Respect rate limits
• Never commit sensitive information
• Run security audits before submitting
• Follow the security guidelines in the documentation

Development Setup

1. Install development dependencies:

   pip install -r requirements-dev.txt

2. Run security audit:

   python scripts/security_audit.py

3. Run tests:

   pytest

Documentation

Core Documentation

• Security Overview - Comprehensive security documentation
• SSH Security Guide - SSH configuration and troubleshooting
• API Documentation - Co