JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 4
  • Score
    100M100P100Q83586F
  • License MIT

AI-powered cybersecurity education platform with Docker-based Linux terminals and intelligent tutoring

Package Exports

    This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (hax-ai-warp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

    Readme

    HAX AI Warp 🚀

    AI-powered cybersecurity education platform with Docker-based Linux terminals and intelligent tutoring

    HAX AI Warp provides students and educators with an interactive, browser-based Linux terminal environment enhanced with AI-powered assistance. Perfect for cybersecurity courses, Linux training, and hands-on learning.

    ✨ Features

    • 🖥️ Browser-based Linux terminals - No local Linux setup required
    • 🤖 AI-powered tutoring - Intelligent suggestions and error help (OpenAI/Claude)
    • 🐳 Docker-based isolation - Safe, sandboxed learning environments
    • 🎓 Educational focus - Designed for cybersecurity and Linux courses
    • 🔒 Secure by default - Isolated containers with controlled access
    • 📱 Multi-user support - Multiple students can use simultaneously
    • ⚡ Real-time assistance - Get help as you type commands

    🎯 Perfect For

    • Cybersecurity courses - Practice with security tools in safe environments
    • Linux training - Learn command line skills with AI guidance
    • Remote learning - Consistent environment accessible from anywhere
    • Computer labs - Easy deployment for educational institutions
    • Self-study - Personal learning with intelligent assistance

    📋 Prerequisites

    Before installing, ensure you have:

    Required

    🚀 Quick Start

    # Install and run in one command
npx hax-ai-warp

# Or run setup first
npx hax-ai-warp --setup

    Option 2: Manual Installation

    # Clone the repository
git clone https://github.com/djfusco/hax-ai-warp.git
cd hax-ai-warp

# Install dependencies
npm install

# Run setup
npm run setup

# Start the server
npm start

    ⚙️ Configuration

    1. Environment Setup

    The system will create a .env file automatically. Edit it to configure:

    # Student password for Docker containers
STUDENT_PASSWORD=haxwarp123

# AI Configuration (choose one)
OPENAI_API_KEY=your-openai-api-key-here
# OR
ANTHROPIC_API_KEY=your-anthropic-api-key-here

# Server Configuration
PORT=3000

    2. Get Your AI API Key

    Option A: OpenAI (GPT)

    1. Go to OpenAI Platform
    2. Create an account and add billing information
    3. Generate a new API key
    4. Add it to your .env file as OPENAI_API_KEY

    Option B: Anthropic Claude (Recommended)

    1. Go to Anthropic Console
    2. Create an account and add billing information
    3. Generate a new API key
    4. Add it to your .env file as ANTHROPIC_API_KEY

    3. Start the Server

    # Using NPX
npx hax-ai-warp

# Or if installed locally
npm start

# Custom port
npx hax-ai-warp --port 8080

    🌐 Usage

    1. Open your browser to http://localhost:3000
    2. Enter student information - Student ID and course name
    3. Start your terminal session - A Docker container will be created
    4. Begin learning! - The AI will provide suggestions as you work

    Example Session

    # In the web terminal:
student@container:~$ ls
README.txt

student@container:~$ lss
-bash: lss: command not found

# AI suggests: "Did you mean 'ls'? This command lists directory contents."

student@container:~$ nmap --help
# AI explains: "nmap is a network scanning tool. Use 'nmap -sn 192.168.1.0/24' to scan for hosts."

    🎓 Educational Use

    For Instructors

    1. Deploy once - Students access via web browser
    2. Consistent environment - Everyone uses the same Linux setup
    3. Safe experimentation - Docker containers are isolated
    4. Monitor progress - See student activity in real-time
    5. AI assistance - Students get help without interrupting class

    For Students

    1. No setup required - Just open a web browser
    2. AI guidance - Get help with commands and concepts
    3. Safe learning - Experiment without breaking anything
    4. Accessible anywhere - Learn from any device with a browser
    5. Real Linux environment - Practice with actual tools

    🔧 Command Line Options

    npx hax-ai-warp [options]

Options:
  --port <port>     Server port (default: 3000)
  --help, -h        Show help message
  --version, -v     Show version
  --setup           Run setup wizard

Examples:
  npx hax-ai-warp                 # Start on port 3000
  npx hax-ai-warp --port 8080     # Start on port 8080
  npx hax-ai-warp --setup         # Run setup wizard

    🐳 Docker Requirements

    The system automatically manages Docker containers but requires:

    • Docker Desktop running
    • Internet connection for downloading Ubuntu images
    • Sufficient disk space (~500MB for base Ubuntu image)

    Each student session creates an isolated Ubuntu 22.04 container with:

    • Common cybersecurity tools
    • Development utilities
    • Network analysis tools
    • Text editors and compilers

    🔒 Security Features

    • Isolated containers - Each student gets their own environment
    • No host access - Containers cannot access the host system
    • Automatic cleanup - Containers are removed after sessions
    • Configurable passwords - Set secure access credentials
    • API key security - Keys stored locally, never transmitted

    🚨 Troubleshooting

    Docker Issues

    # Check Docker is running
docker ps

# If not running, start Docker Desktop
# Then restart HAX AI Warp

    Port Already in Use

    # Use a different port
npx hax-ai-warp --port 8080

    AI Not Working

    1. Check your API key in .env file
    2. Verify you have billing set up with AI provider
    3. Check API key permissions
    4. Look for error messages in terminal

    Performance Issues

    • Ensure Docker has enough memory allocated (4GB+ recommended)
    • Close unused containers: docker container prune
    • Monitor disk space: docker system df

    📈 Monitoring

    View real-time information:

    • Active sessions: Server shows connected students
    • Container status: Docker containers are managed automatically
    • AI usage: Monitor API calls and responses
    • Resource usage: Check Docker Desktop for container resources

    🛡️ Privacy & Data

    • No data collection - All processing happens locally
    • API keys stay local - Never transmitted to our servers
    • Student privacy - No personal data stored or transmitted
    • Session isolation - Student work is contained within their session

    📚 Examples

    Cybersecurity Course Setup

    # Start server for class
npx hax-ai-warp --port 3000

# Students access: http://your-server:3000
# Each student creates their own isolated environment
# AI helps with nmap, netcat, wireshark, etc.

    Linux Training

    # Focus on command line skills
# AI provides explanations for:
# - File system navigation
# - Permission management
# - Process control
# - Network configuration

    🤝 Contributing

    We welcome contributions! Please see our Contributing Guide for details.

    📄 License

    MIT License - see LICENSE file for details.

    🆘 Support

    🎉 Acknowledgments

    Built with:

    Made with ❤️ for education

    Transform your cybersecurity and Linux education with AI-powered assistance! 2. Node.js: Download Node.js (version 18+ recommended)

    Installation

    1. Clone and setup:

      git clone <repository-url>
cd hax-ai-warp
npm install
npm run setup

    2. Start the server:

      npm start

    3. Access the interface:

      • Open http://localhost:3000 in your browser
      • Enter student ID and course name
      • Wait for container to be ready (first time may take 1-2 minutes)

    AI Assistant Configuration

    Pattern-Matching Mode (Default)

    Works immediately without API keys - provides basic cybersecurity guidance and error detection.

    Full AI Mode (Warp.dev-like)

    For advanced AI features, set up an API key:

    1. Get an API key:

    2. Configure environment:

      # Copy example file
cp .env.example .env

# Edit .env file and add your API key:
OPENAI_API_KEY=your-actual-api-key-here
# OR
ANTHROPIC_API_KEY=your-actual-api-key-here

    3. Test AI functionality:

      node test-ai.js

    4. Restart server to activate full AI features

    AI Features

    • Real-time monitoring: Watches all terminal activity
    • Error detection: Identifies and explains command failures
    • Educational guidance: Provides context-aware learning suggestions
    • Next-step recommendations: Suggests logical follow-up commands
    • Tool-specific help: Specialized knowledge for cybersecurity tools

    Container Architecture

    Cybersecurity Lab Image

    The system uses a pre-built Docker image (dfusco/hax-ai-cyber-lab) with:

    • Base: Ubuntu 22.04 LTS
    • Tools: nmap, netcat, tcpdump, wireshark, john, hydra, python3
    • User: student with sudo access (password: set in .env file)
    • SSH: Enabled for terminal connections

    Container Lifecycle

    • Creation: Automatic per student/course combination
    • Naming: hax-{course}-{studentid} (sanitized)
    • Persistence: Containers persist until manually removed
    • Isolation: Full network and filesystem isolation

    Usage

    For Students

    1. Enter your student ID and course name
    2. Wait for "Container ready" message
    3. Use the password from your .env file when prompted
    4. Access cybersecurity tools in your isolated environment

    For Instructors

    • Access instructor panel: http://localhost:3000?instructor=true
    • View active containers and terminals
    • Monitor student sessions

    Available Commands in Container

    # Network scanning
nmap -sV target.com

# Password cracking
john hashfile.txt

# Network capture
tcpdump -i eth0

# Web security testing
python3 -m http.server 8080

    API Endpoints

    • POST /api/sessions - Create student session
    • GET /api/containers - List Docker containers
    • GET /api/terminals - List active terminals
    • GET /api/health - Health check

    Configuration

    Environment Variables

    # Server Configuration
PORT=3000                    # Server port
DOCKER_MEMORY_LIMIT=512m     # Container memory limit
DOCKER_CPU_LIMIT=0.5         # Container CPU limit

# Security Configuration
STUDENT_PASSWORD=your_secure_password_here  # Student container password

# AI Configuration (Optional)
OPENAI_API_KEY=your_openai_key      # For AI assistance
ANTHROPIC_API_KEY=your_anthropic_key # Alternative AI provider

    Security Notes

    🔒 Important: The .env file contains sensitive configuration and should never be committed to version control.

    • Student Password: Set STUDENT_PASSWORD in your .env file instead of using hardcoded passwords
    • API Keys: Keep your AI provider API keys secure in the .env file
    • Environment Isolation: Each student gets an isolated container with the configured password
    • Default Fallback: If no password is set, defaults to defaultpass123

    Docker Settings

    • Memory: 512MB per container (configurable)
    • CPU: 0.5 cores per container (configurable)
    • Network: Bridge mode with SSH port mapping
    • Capabilities: NET_ADMIN and SYS_ADMIN for security tools

    Development

    Project Structure

    hax-ai-warp/
├── server.js                 # Main Express server
├── lib/
│   ├── docker-container-manager.js  # Docker operations
│   ├── terminal-manager.js          # Terminal connections
│   └── auth-manager.js              # Session management
├── public/                   # Frontend assets
├── scripts/
│   └── setup.js             # Installation script
└── test-docker.js           # Integration tests

    Scripts

    npm start              # Start production server
npm run dev            # Start with nodemon (development)
npm run setup          # Setup Docker environment
node test-docker.js    # Test Docker integration

    Docker Commands

    # List containers
docker ps -a

# View container logs
docker logs hax-cyber362-student1

# Execute command in container
docker exec hax-cyber362-student1 whoami

# Remove container
docker stop hax-cyber362-student1
docker rm hax-cyber362-student1

    Troubleshooting

    Docker Issues

    • "Docker not found": Install Docker Desktop and ensure it's running
    • "Permission denied": Add user to docker group or run with sudo
    • "Container won't start": Check Docker Desktop memory/CPU limits

    Connection Issues

    • "Connecting..." stuck: Container may still be starting (wait 1-2 minutes)
    • SSH timeout: Check if container SSH service is running
    • Port conflicts: Ensure no other services on port 3000

    Performance Issues

    • Slow container startup: First-time Docker image build takes time
    • High memory usage: Adjust DOCKER_MEMORY_LIMIT in environment
    • Too many containers: Clean up old containers with docker container prune

    Security Considerations

    • Containers run with limited capabilities
    • Student user has sudo access (required for security tools)
    • SSH keys are auto-generated and temporary
    • Containers are isolated from host filesystem
    • Default password should be changed in production

    License

    MIT License - see LICENSE file for details

    Contributing

    1. Fork the repository
    2. Create feature branch
    3. Test with node test-docker.js
    4. Submit pull request

    For issues or questions, please create a GitHub issue. 2. Create a feature branch 3. Make your changes 4. Test thoroughly 5. Submit a pull request

    Built for educators who want to give students real Linux experience without the complexity of individual VM setup.