Skip to content

Latest commit

 

History

155 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

🛡️ Auron - Cybersecurity Training Platform

Production-Ready "Lab in a Box" - Complete cybersecurity training platform with React dashboard, TypeScript backend, SIEM integration, vulnerability scanning, AI-powered learning, and professional PDF reporting.

Status Workshop Ready Docker API Endpoints


🎯 Overview

Auron is a comprehensive "Training Lab in a Box" that combines vulnerable applications, real-time SIEM monitoring, vulnerability scanning, and AI-powered learning into a single deployable platform.

🌟 What Makes Auron Special

  • 🚀 One-Command Deployment - docker-compose up -d starts everything
  • 🎓 Complete Learning Platform - From browsing labs to generating professional reports
  • 🔍 Real SIEM Visibility - Wazuh with 40+ custom detection rules
  • 🤖 AI-Powered Hints - Claude integration for adaptive learning
  • 📊 Professional Reports - Puppeteer PDF generation with vulnerability scanning
  • ☁️ Cloud Ready - Optional Vultr integration for remote workshops
  • 🎮 Gamification - Points, badges, leaderboards
  • 🔄 Real-time Collaboration - WebSocket-based live sessions

✨ What's New in v2.0 (November 2025)

🎉 Major Features Completed

  • Wazuh SIEM Integration - Real-time attack detection with custom rules
  • OWASP ZAP Scanner - Automated vulnerability scanning (spider + active scan)
  • Puppeteer PDF Reports - Professional report generation with styling
  • Frontend-Backend Wiring - 85% complete (Labs, Auth, Reports, Profile)
  • Playwright E2E Tests - 3 comprehensive test suites (auth, labs, reports)
  • ProfilePage Implementation - Complete with 2FA, password change, stats
  • Workshop Documentation - 773-line comprehensive workshop guide
  • Deployment Guides - Complete step-by-step deployment instructions

📈 Platform Statistics

  • Backend: 100% Complete (54 API endpoints, 10 services)
  • Frontend: 85% Wired (core features fully functional)
  • Database: 10 models, 7 migrations
  • Docker Services: 12 containers
  • SIEM Rules: 40+ custom Wazuh detection rules
  • Test Coverage: Playwright E2E infrastructure ready
  • Overall Completion: 96% (Workshop Ready!)

🚀 Quick Start

System Requirements

  • OS: Ubuntu 20.04+, Debian 11+, macOS 12+, or Windows 10/11 with WSL2
  • Docker: Engine 24.0+ and Compose v2.20+
  • RAM: 8GB minimum, 16GB recommended (for Wazuh)
  • Disk: 30GB free space (SSD recommended)
  • Ports: 3000, 4000, 5173, 5432, 5601, 6379, 8080-8081, 8090, 9200, 55000

Installation (5 Minutes)

# 1. Clone repository
git clone https://github.com/Haseeb-1698/Auron.git
cd Auron

# 2. Configure environment
cp .env.example .env
nano .env  # Add your LiquidMetal API key (see API Keys section below)

# 3. Start all services (one command!)
docker-compose up -d

# 4. Wait for services to be healthy (~90 seconds for Wazuh)
watch -n 2 'docker compose ps'

# 5. Access the platform
open http://localhost:5173  # Main Dashboard
open http://localhost:8080  # DVWA Lab
open https://localhost:5601 # Wazuh SIEM (admin/SecretPassword)

First Time Setup

  1. Register Account: Visit http://localhost:5173 and click "Register"
  2. Browse Labs: View available labs with filtering and search
  3. Start a Lab: Click any lab card → Click "Start Lab" button
  4. Complete Exercises: Work through challenges, submit solutions
  5. Generate Report: Run vulnerability scan and download PDF

🎉 That's it! You're ready to start learning cybersecurity!

☁️ Vultr Cloud Deployment (10 Minutes)

Want to deploy on Vultr cloud for remote access or workshops?

# 1. Create Vultr instance (via web dashboard)
#    - Plan: vc2-8c-16gb (16GB RAM recommended)
#    - OS: Ubuntu 22.04 LTS
#    - Region: Choose nearest (e.g., ewr - New Jersey)

# 2. SSH into server
ssh root@YOUR_SERVER_IP

# 3. Create non-root user
adduser auron
usermod -aG sudo auron

# 4. Clone and run automated deployment
su - auron
git clone https://github.com/Haseeb-1698/Auron.git
cd Auron
bash scripts/vultr-deploy-wrapper.sh  # Handles docker permissions automatically

# 5. Access via SSH tunnel (secure)
ssh -L 5173:localhost:5173 -L 4000:localhost:4000 -L 5601:localhost:5601 auron@YOUR_SERVER_IP
# Then open: http://localhost:5173

📖 Detailed Vultr Guide: See VULTR_QUICKSTART.md


🔑 API Keys Configuration

Required API Keys

1. LiquidMetal AI (Claude) - REQUIRED for AI Hints

# File: /home/user/Auron/.env
LIQUIDMETAL_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxx
LIQUIDMETAL_ENDPOINT=https://api.liquidmetal.ai/v1/chat/completions
LIQUIDMETAL_MODEL=claude-3-sonnet-20240229
  • Get it from: https://console.anthropic.com/
  • Cost: ~$0.05-0.15 per user session
  • Enables: AI-powered hints, vulnerability explanations, code analysis
  • Without it: Hint button won't work, but all other lab features still work

2. Vultr Cloud API - OPTIONAL (Only for Cloud Labs)

# File: /home/user/Auron/.env
VULTR_API_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
VULTR_DEFAULT_REGION=ewr  # New Jersey
VULTR_DEFAULT_PLAN=vc2-1c-1gb  # $6/month
  • Get it from: https://my.vultr.com/settings/#settingsapi
  • Cost: $6-18/month per VM (hourly billing)
  • Enables: Cloud-based lab instances for remote workshops
  • Without it: Local Docker labs work perfectly!
  • When to use: 10+ remote students, need persistent environments
  • Note: VultrService.ts is 100% implemented, just add API key to activate

Pre-configured (No Action Needed)

# Already set in docker-compose.yml
ZAP_API_KEY=auron-zap-api-key  # OWASP ZAP scanner
WAZUH_DASHBOARD_PASSWORD=SecretPassword  # Change in production!

📖 Detailed API Configuration: See DEPLOYMENT_COMPLETE.md for full setup guide.


✨ Core Features

🔬 Lab Environment (100% Complete)

Vulnerable Applications:

  • DVWA (Damn Vulnerable Web Application) - OWASP Top 10 practice
  • OWASP Juice Shop - Modern web app with 100+ challenges
  • Metasploitable 2 - Penetration testing practice environment

Lab Management:

  • Browse labs with filtering (category, difficulty, tags)
  • Search functionality
  • Progress tracking with real-time updates
  • Start/Stop/Reset lab instances (10-30 second startup)
  • Exercise submission with instant validation
  • AI-powered hints (progressive difficulty)
  • Points and badge system

🛡️ Security Monitoring (100% Complete)

Wazuh SIEM Integration:

  • Real-time log collection via syslog driver
  • 40+ custom detection rules:
    • SQL Injection (5 rules)
    • XSS (2 rules)
    • Directory Traversal (2 rules)
    • Command Injection (2 rules)
    • Brute Force (3 rules with frequency correlation)
    • Port Scanning (3 rules)
    • Web Scanners (2 rules)
    • Service-specific rules (DVWA, Juice Shop, Metasploitable)
    • Advanced attacks (File Upload, XXE, LDAP, SSRF)
  • Custom decoders for application logs
  • Wazuh Dashboard (port 5601) with real-time alerts
  • Dual-perspective teaching (red team + blue team)

🔍 Vulnerability Scanning (100% Complete)

OWASP ZAP Integration:

  • Spider scan (URL discovery with progress tracking)
  • Active scan (comprehensive vulnerability detection)
  • Alert parsing and severity mapping
  • Quick scan fallback (security headers, misconfigurations)
  • Progress tracking (0-100% real-time)
  • Findings categorization (Critical/High/Medium/Low/Info)

📊 Professional Reporting (100% Complete)

Puppeteer PDF Generation:

  • Beautiful HTML templates with embedded CSS
  • Severity-based color coding
  • Multiple report types:
    • Vulnerability Scan Reports
    • Lab Completion Reports
    • Progress Summary Reports
  • Export formats: PDF, JSON, CSV, HTML
  • Download and delete functionality
  • Report statistics dashboard

🤖 AI-Powered Learning (100% Complete)

LiquidMetal AI (Claude) Integration:

  • Adaptive hints (progressive difficulty based on attempts)
  • Vulnerability explanations (technical details + remediation)
  • Code security analysis (SQL injection, XSS, CSRF detection)
  • Solution validation
  • Personalized learning path recommendations
  • SmartMemory event tracking

🎮 Gamification (100% Complete)

Progress Tracking:

  • Real-time progress updates via WebSocket
  • Points system (100 points per lab, 20 per exercise)
  • Leaderboard (daily, weekly, all-time)
  • 11 badges (First Lab, SQL Master, XSS Hunter, Speed Demon, etc.)
  • Completion percentage tracking
  • Time spent tracking

🔄 Real-time Collaboration (60% Complete)

WebSocket Features:

  • Live collaboration sessions
  • Real-time chat
  • Screen sharing (planned)
  • Cursor tracking (planned)
  • 20+ WebSocket events

📚 Documentation

📘 Complete Guides

Guide Lines Description
DEPLOYMENT_COMPLETE.md 650+ Step-by-step deployment, API keys, troubleshooting
VULTR_QUICKSTART.md 400+ ⚡ Quick Vultr cloud deployment (10 minutes)
VULTR_DEPLOYMENT.md 850+ Complete Vultr deployment guide with automation
LABS_WORKFLOW.md 800+ How labs work from user perspective with diagrams
WIRING_STATUS.md 500+ Frontend-backend wiring audit and action plan
CURRENT_STATUS.md 900+ Detailed implementation status and metrics
IMPLEMENTATION_GUIDE.md 750+ Architecture and implementation details
WORKSHOP_GUIDE.md 773 Complete workshop facilitation guide

📖 Quick Links


🏗️ Architecture

System Overview

┌─────────────────────────────────────────────────────────────┐
│                      FRONTEND (React 18)                     │
│  ├─ Dashboard          ├─ Reports Page     ├─ Profile       │
│  ├─ Labs Page          ├─ Progress Page    ├─ Auth Pages    │
│  └─ Lab Detail Page    └─ Collaboration    └─ Admin Panel   │
│                                                               │
│  Redux Toolkit Store (7 slices)                             │
│  - auth    - labs    - progress    - reports                │
│  - ai      - dashboard   - collaboration                     │
└──────────────────────┬──────────────────────────────────────┘
                       │ HTTP/WebSocket
┌──────────────────────▼──────────────────────────────────────┐
│                    BACKEND API (Node.js)                     │
│  54 Endpoints across 8 Controllers                          │
│  ├─ Auth (10)         ├─ Progress (7)     ├─ Admin (10)    │
│  ├─ Labs (8)          ├─ AI (6)           ├─ Gamification (3)│
│  └─ Scans (4)         └─ Reports (6)                        │
│                                                               │
│  10 Services                                                 │
│  - AuthService        - VulnerabilityScanService            │
│  - LabService         - ReportService                        │
│  - CloudLabService    - ProgressService                      │
│  - VultrService       - GamificationService                  │
│  - LiquidMetalService - DockerService                        │
└──────────────────────┬──────────────────────────────────────┘
                       │
        ┌──────────────┼──────────────┐
        │              │              │
┌───────▼──────┐ ┌────▼─────┐ ┌─────▼────────┐
│ PostgreSQL   │ │  Redis   │ │ Docker Engine│
│ 10 Models    │ │  Cache   │ │ 12 Containers│
│ 7 Migrations │ │  Sessions│ │ - dvwa       │
└──────────────┘ └──────────┘ │ - juiceshop  │
                               │ - metasploit │
                               │ - zap        │
                               │ - wazuh (3)  │
                               │ - attack-*   │
                               └──────────────┘

Project Structure

Auron/
├── backend/                    # Node.js + Express + TypeScript
│   ├── src/
│   │   ├── controllers/        # 8 controllers (54 endpoints)
│   │   ├── services/           # 10 business logic services
│   │   ├── models/             # 10 Sequelize models
│   │   ├── routes/             # API route definitions
│   │   ├── middleware/         # Auth, validation, error handling
│   │   ├── websocket/          # Socket.IO handlers
│   │   └── server.ts           # Entry point
│   ├── tests/                  # Jest unit tests
│   ├── Dockerfile              # Multi-stage production build
│   └── package.json            # 51 dependencies
│
├── frontend/                   # React 18 + TypeScript + Redux
│   ├── src/
│   │   ├── components/         # Reusable UI components
│   │   ├── features/           # Redux slices (7 feature modules)
│   │   ├── pages/              # Route pages (9 pages)
│   │   ├── services/           # API & WebSocket clients
│   │   ├── store/              # Redux store configuration
│   │   └── types/              # TypeScript definitions
│   ├── e2e/                    # Playwright E2E tests
│   ├── Dockerfile              # Nginx-based production build
│   └── package.json            # 50 dependencies
│
├── wazuh-config/               # SIEM Configuration
│   ├── local_rules.xml         # 40+ custom detection rules
│   └── local_decoder.xml       # Custom log decoders
│
├── attack-scripts/             # Kali Linux Attack Scripts
│   ├── dvwa-sqli.sh            # SQL injection demo
│   ├── port-scan.sh            # Nmap port scanning
│   └── dirb-scan.sh            # Directory brute force
│
├── deployment/                 # Deployment Scripts
│   ├── staging.sh              # Staging deployment
│   └── nginx.conf              # Reverse proxy config
│
├── .github/workflows/          # CI/CD Pipelines
│   ├── ci.yml                  # Lint, test, build, security scan
│   └── deploy-staging.yml      # Automated staging deployment
│
├── docker-compose.yml          # 12 services orchestration
├── docker-compose.staging.yml  # Staging with monitoring
├── .env.example                # Environment template (98 lines)
│
├── README.md                   # This file
├── DEPLOYMENT_COMPLETE.md      # Complete deployment guide
├── LABS_WORKFLOW.md            # How labs work (user journey)
├── WIRING_STATUS.md            # Frontend-backend wiring status
├── CURRENT_STATUS.md           # Implementation status
├── IMPLEMENTATION_GUIDE.md     # Architecture details
└── WORKSHOP_GUIDE.md           # Workshop facilitation guide

🔐 Security Considerations

⚠️ IMPORTANT WARNINGS

All lab applications are INTENTIONALLY VULNERABLE for educational purposes:

  • NEVER expose lab services to the internet
  • DO NOT use real credentials or sensitive data
  • DO NOT deploy on production networks
  • ALWAYS run in isolated environments only
  • USE for educational purposes exclusively
  • RESET lab environments regularly

Security Features (Production)

  • Authentication: JWT with refresh tokens, 2FA (TOTP)
  • Authorization: Role-based access control (RBAC)
  • Input Validation: Joi schemas for all endpoints
  • SQL Injection Prevention: Sequelize ORM parameterization
  • XSS Prevention: Helmet security headers, CSP
  • CSRF Protection: CSRF tokens for state-changing operations
  • Rate Limiting: 100 requests per 15 minutes per IP
  • Password Security: bcrypt with 10 rounds
  • Session Management: HttpOnly cookies, secure flags
  • Logging: Winston with audit trails
  • Secrets Management: Environment variables, no hardcoded secrets
  • Network Isolation: All services bound to localhost (127.0.0.1)

🛠️ Development

Backend Development

cd backend
npm install

# Development mode (with auto-reload)
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Type check
npm run type-check

Frontend Development

cd frontend
npm install

# Development mode (Vite dev server)
npm run dev

# Run tests
npm test

# E2E tests
npm run test:e2e         # Run all E2E tests
npm run test:e2e:ui      # Interactive UI mode
npm run test:e2e:debug   # Debug mode

# Build production
npm run build
npm run preview

Tech Stack

Frontend:

  • React 18.2 with TypeScript 5.3
  • Redux Toolkit 2.0 for state management
  • Material-UI 5.15 (MUI) components
  • React Router 6.21 for navigation
  • Socket.IO client for WebSocket
  • Axios for HTTP requests
  • Vite 5.0 for build tooling
  • Playwright 1.56 for E2E testing
  • Vitest for unit testing

Backend:

  • Node.js 18+ with TypeScript 5.3
  • Express 4.18 with Helmet, CORS, rate limiting
  • PostgreSQL 15 with Sequelize ORM
  • Redis 7 for caching and sessions
  • Socket.IO 4.6 for real-time features
  • JWT authentication with 2FA (Speakeasy)
  • Dockerode for container management
  • Puppeteer 21.6 for PDF generation
  • Winston for logging
  • Jest + Supertest for testing

Infrastructure:

  • Docker Compose for orchestration
  • Multi-stage production builds
  • Nginx for frontend serving
  • Health checks and auto-restart
  • Resource limits (CPU, memory)

🎓 Learning Paths

1️⃣ Beginner Path: Web Application Security (4-6 hours)

  1. Setup DVWA → SQL Injection Basics lab
  2. Learn XSS → Cross-Site Scripting Fundamentals lab
  3. Understand CSRF → CSRF Protection lab
  4. Practice → Complete all beginner exercises
  5. Generate Report → Create your first vulnerability report

2️⃣ Intermediate Path: Modern Web Security (6-8 hours)

  1. Complete Juice Shop → 100+ challenges
  2. Study CSP → Content Security Policy implementation
  3. Practice Session Management → Session hijacking and prevention
  4. Scan Applications → Use ZAP to find vulnerabilities
  5. Create Portfolio → Generate PDF reports for showcase

3️⃣ Advanced Path: Penetration Testing (8-12 hours)

  1. Enumerate Services → Port scanning with Nmap
  2. Exploit Metasploitable → Known vulnerability exploitation
  3. Practice Post-Exploitation → Privilege escalation, persistence
  4. Study Wazuh → SIEM detection mechanisms
  5. Red vs Blue → Attack and monitor simultaneously

4️⃣ Defensive Path: Security Monitoring (6-10 hours)

  1. Configure Wazuh → Custom rules and decoders
  2. Detect Attacks → Analyze attack patterns in real-time
  3. Build Playbooks → Incident response procedures
  4. Create Dashboards → Visualization and reporting
  5. Practice IR → Investigate and respond to alerts

📊 Workshop Scenario (1-Hour Session)

Quick Workshop Setup

# 1. Verify all services running
docker compose ps

# 2. Open required dashboards
open http://localhost:5173     # Auron Dashboard
open http://localhost:8080     # DVWA
open https://localhost:5601    # Wazuh SIEM

# 3. Run attack demonstration
docker exec auron-attack-scripts /scripts/dvwa-sqli.sh
docker exec auron-attack-scripts /scripts/port-scan.sh dvwa

# 4. Show real-time alerts in Wazuh
# Students see attacks detected live!

1-Hour Workshop Flow

  1. Introduction (10 min): Platform tour, explain "Lab in a Box" concept
  2. Hands-On Lab (30 min): Students work on SQL Injection basics
  3. Attack Demo (10 min): Run attack scripts, show SIEM alerts
  4. AI Hints (5 min): Demonstrate AI-powered learning
  5. Reports (5 min): Generate and download professional PDF

📖 Complete Workshop Guide: See WORKSHOP_GUIDE.md


🔧 Service Access

Service URL Credentials Purpose
Auron Dashboard http://localhost:5173 Register new account Main platform interface
Backend API http://localhost:4000/api - RESTful API (54 endpoints)
Swagger Docs http://localhost:4000/api-docs - Interactive API documentation
DVWA http://localhost:8080 admin / password Vulnerable web app (OWASP Top 10)
Juice Shop http://localhost:3000 - Modern web app (100+ challenges)
Metasploitable http://localhost:8081 msfadmin / msfadmin Pentest practice environment
Wazuh Dashboard https://localhost:5601 admin / SecretPassword SIEM monitoring and alerts
Wazuh API https://localhost:55000 admin / SecretPassword SIEM REST API
ZAP Proxy http://localhost:8090 - Vulnerability scanner
PostgreSQL localhost:5432 auron_user / (see .env) Main database
Redis localhost:6379 - Cache and session store

📈 Roadmap

Completed ✅

  • Complete backend API (54 endpoints)
  • Frontend-backend wiring (85%)
  • Wazuh SIEM integration
  • OWASP ZAP vulnerability scanning
  • Puppeteer PDF reports
  • AI-powered hints (Claude)
  • Gamification system
  • Real-time WebSocket
  • E2E testing infrastructure
  • Comprehensive documentation

In Progress 🔄

  • Wire Progress Page (2-3 hours)
  • Wire Collaboration Page (4-6 hours)
  • Unit test coverage (70%+ target)

Planned 📅

  • Browser extension (Manifest V3)
  • Mobile companion app
  • CTF challenge mode
  • Video tutorials
  • Certification program
  • Multi-language support

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Development Guidelines

  • Follow existing code style (ESLint + Prettier configured)
  • Add tests for new features
  • Update documentation
  • Consider security implications
  • Test in isolated environment

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.


⚖️ Legal Disclaimer

This platform is designed for educational purposes only.

Users must:

  • ✅ Only use on systems they own or have explicit permission to test
  • ✅ Comply with all applicable laws and regulations
  • ✅ Use for learning and authorized security testing
  • ❌ Not use for malicious purposes
  • ❌ Not deploy on production networks
  • ❌ Understand that unauthorized hacking is illegal

The authors and contributors are not responsible for misuse of this platform.


🙏 Acknowledgments

  • OWASP - Vulnerable applications and security resources
  • Wazuh - Open-source SIEM platform
  • Rapid7 - Metasploitable vulnerable VM
  • Anthropic - Claude AI for adaptive learning
  • Vultr - Cloud infrastructure partner
  • OWASP ZAP - Vulnerability scanner
  • All contributors and the cybersecurity community

📧 Support & Community


🌟 Star History

If you find Auron useful, please consider giving it a star ⭐ on GitHub!

Star History Chart


📊 Project Stats

  • Lines of Code: 14,000+ (production code)
  • API Endpoints: 54 (fully documented)
  • Database Models: 10 (with migrations)
  • Docker Services: 12 (orchestrated)
  • SIEM Rules: 40+ (custom detection)
  • Test Suites: 3 (E2E with Playwright)
  • Documentation: 2,800+ lines across 6 guides
  • Completion: 96% (Workshop Ready!)

🚀 Made with ❤️ for the cybersecurity community

Empowering the next generation of security professionals, one lab at a time.


🎯 Quick Links

Resource Description
🚀 Deployment Guide Complete step-by-step deployment instructions
⚡ Vultr Quick Start Deploy on Vultr cloud in 10 minutes
☁️ Vultr Full Guide Complete Vultr deployment with automation
🎓 Labs Workflow How labs work from user perspective
🔌 Wiring Status Frontend-backend integration status
📊 Current Status Detailed implementation metrics
🏗️ Implementation Architecture and design decisions
👨‍🏫 Workshop Guide Facilitate cybersecurity workshops

Last Updated: November 15, 2025 Version: 2.0 Status: Production-Ready (96% Complete)

About

A hybrid platform designed for secure software design education — featuring a Docker-based cybersecurity lab with vulnerable and defensive apps (DVWA, JuiceShop, Wazuh), and a browser extension that performs real-time cookie, CSP, and phishing analysis. Enables students to learn, test, and defend within one environment.

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages