Home - capstone-hermes/hermes-fullstack GitHub Wiki

Hermes Fullstack - Educational Cybersecurity Platform

Security Warning OWASP ASVS License

Welcome to the Hermes Fullstack Documentation

Hermes is a comprehensive cybersecurity education platform consisting of three integrated components designed for security testing, vulnerability assessment, and hands-on learning. This platform provides a complete ecosystem for understanding, detecting, and exploiting web application vulnerabilities in a controlled educational environment.

🚨 Critical Security Warning

THIS PLATFORM CONTAINS INTENTIONAL SECURITY VULNERABILITIES

  • DO NOT deploy in production environments
  • DO NOT expose to public networks
  • USE ONLY in isolated, controlled environments
  • INTENDED FOR educational and training purposes only

🏗️ Platform Architecture

Hermes consists of three integrated components working together to provide a complete cybersecurity learning experience:

🕷️ WebScanner (Python)

Automated Vulnerability Scanner

  • Comprehensive web application security scanner
  • Automated detection of common vulnerabilities
  • Educational reporting with detailed explanations
  • Plugin-based architecture for extensibility
  • RESTful API for integration

🌐 Weak Website (Node.js/React)

Deliberately Vulnerable Web Application

  • Full-stack web application with intentional vulnerabilities
  • OWASP ASVS Level 1 compliance testing platform
  • Educational target for security testing practice
  • Real-world application patterns with security flaws

🖥️ GUI (Ionic/React)

Unified Security Testing Interface

  • User-friendly interface for security testing workflows
  • Integration hub for WebScanner and Weak Website
  • Educational dashboards and learning modules
  • Report generation and vulnerability visualization

📚 Component Documentation

WebScanner Documentation

Weak Website Documentation

GUI Documentation

🔒 Security & Vulnerabilities

Core Security Documentation

Exploitation Guides

🚀 Quick Start

Prerequisites

  • Docker and Docker Compose
  • Python 3.8+ (for WebScanner)
  • Node.js 18+ (for development)
  • Git

Launch Complete Platform

# Clone the repository
git clone <repository-url>
cd hermes-fullstack

# Start all components with Docker Compose
docker-compose up --build -d

# Access components
# GUI: http://localhost:8080
# Weak Website Client: http://localhost:8081
# Weak Website Server: http://localhost:3000
# WebScanner API: http://localhost:8000

Individual Component Setup

# WebScanner
cd web-scanner
python src/main.py https://localhost:8081

# Weak Website
cd weak-website
docker-compose -f docker-compose.dev.yml up -d

# GUI
cd gui
npm run dev

🎯 Learning Objectives

Comprehensive Security Education

This platform provides hands-on experience with:

For Students

  • Vulnerability Discovery: Learn to identify security weaknesses
  • Exploitation Techniques: Practice safe exploitation methods
  • Security Tool Usage: Master industry-standard security tools
  • Defensive Security: Understand security from both attack and defense perspectives

For Instructors

  • Practical Demonstrations: Show real vulnerability examples
  • Systematic Teaching: Structured learning progression
  • Assessment Tools: Evaluate student security knowledge
  • Safe Environment: Controlled testing platform

For Security Professionals

  • Tool Testing: Evaluate security scanner effectiveness
  • Methodology Validation: Test penetration testing approaches
  • Skill Development: Practice advanced security techniques
  • Training Delivery: Educational platform for team training

🔄 Component Integration

Workflow Integration

graph TD
    A[GUI Interface] --> B[Configure Scan Target]
    B --> C[Weak Website]
    C --> D[WebScanner Engine]
    D --> E[Vulnerability Detection]
    E --> F[Report Generation]
    F --> G[GUI Visualization]
    G --> H[Educational Content]

Educational Flow

  1. Setup: Deploy platform components
  2. Explore: Use GUI to understand weak website features
  3. Scan: Configure WebScanner to test weak website
  4. Analyze: Review discovered vulnerabilities
  5. Learn: Study exploitation techniques
  6. Practice: Perform manual exploitation
  7. Document: Generate comprehensive reports

🏫 Educational Context

Academic Integration

Perfect for:

  • Computer Science Courses: Web security, ethical hacking
  • Cybersecurity Programs: Hands-on penetration testing
  • Professional Training: Corporate security awareness
  • Certification Preparation: CEH, OSCP, CISSP

OWASP Alignment

  • OWASP ASVS: Application Security Verification Standard
  • OWASP Top 10: Most critical security risks
  • OWASP Testing Guide: Systematic testing methodology
  • OWASP ZAP: Integration with popular security tools

📊 Technology Stack

WebScanner (Python)

  • Framework: FastAPI
  • HTTP Client: Requests
  • Testing: pytest
  • Quality: flake8, black

Weak Website

  • Frontend: React 18 + TypeScript + TailwindCSS
  • Backend: NestJS + TypeScript + TypeORM
  • Database: MySQL 8.0+

GUI (Ionic/React)

  • Framework: Ionic + React
  • Language: TypeScript
  • Testing: Cypress (E2E), Jest (Unit)
  • Build: Vite

Infrastructure

  • Containerization: Docker + Docker Compose
  • Development: Docker Dev environments
  • Orchestration: Multi-container deployment

🛠️ Contributing

Documentation Standards

  • Follow GitHub wiki markdown conventions
  • Include practical examples and code snippets
  • Reference specific code locations with file paths and line numbers
  • Maintain cross-references between related pages

Development Guidelines

  • Implement educational vulnerabilities responsibly
  • Include clear security warnings
  • Provide detailed exploitation examples
  • Maintain educational focus in all features

📞 Support & Community

Getting Help

  1. Documentation: Search existing wiki pages
  2. Issue Tracker: Check GitHub issues for common problems
  3. Community: Engage with educational cybersecurity community
  4. OWASP Resources: Leverage OWASP documentation and tools

Reporting Issues

  • Use GitHub issue tracker
  • Provide detailed reproduction steps
  • Include environment information
  • Specify affected component (WebScanner/Weak Website/GUI)

⚖️ Legal and Ethical Guidelines

Responsible Use Principles

  • Educational Purpose Only: Use for authorized learning and testing
  • Isolated Environment: Never deploy on public or production systems
  • Respect Privacy: Use only test data, never real personal information
  • Follow Laws: Comply with local cybersecurity and computer crime laws

Ethical Testing Standards

  • Authorized Testing Only: Test only systems you own or have explicit permission
  • Responsible Disclosure: Report real vulnerabilities through proper channels
  • No Malicious Use: Never use these techniques for illegal activities
  • Educational Documentation: Maintain learning records and portfolios

Mission: Hermes empowers cybersecurity education through hands-on learning, combining theoretical knowledge with practical experience in a safe, controlled environment.

🧭 Navigation Guide

Getting Started

  1. Quick Start Guide - Platform deployment and setup
  2. Installation - Detailed installation instructions
  3. WebScanner Overview - Understand the scanning component
  4. GUI Overview - Explore the user interface

Learning Path

  1. Vulnerability Overview - Understand security weaknesses
  2. SQL Injection - Start with fundamental attacks
  3. Cross-Site Scripting - Client-side vulnerabilities
  4. Testing Methodology - Systematic assessment approach

Advanced Topics

Legend: ✅ Complete | 🚧 In Progress | 📋 Planned