medienkompetenz-lernplattform/backend/lessons/LESSONS_DOCUMENTATION.md

# Security Awareness Lessons Documentation

This document provides comprehensive information about all available lessons in the platform, including learning objectives, content structure, interactive components, and implementation details.

---

## Table of Contents

1. [Phishing Email Detection Basics](#1-phishing-email-detection-basics)
2. [SQL Injection Attack - Online Shop Demo](#2-sql-injection-attack---online-shop-demo)
3. [Browser-in-the-Browser (BitB) Attack](#3-browser-in-the-browser-bitb-attack)
4. [Creating New Lessons](#creating-new-lessons)

---

## 1. Phishing Email Detection Basics

### Overview

**Lesson Key:** `phishing-email-basics`
**Difficulty:** Beginner
**Duration:** 15 minutes
**Category:** Social Engineering / Email Security

### Learning Objectives

By the end of this lesson, participants will be able to:
- Identify common characteristics of phishing emails
- Recognize suspicious sender addresses and domains
- Detect urgency tactics used by attackers
- Understand link verification techniques
- Apply best practices for handling suspicious emails

### Content Structure

#### Steps:

1. **Introduction to Phishing** (Content)
   - Definition and impact of phishing
   - Statistics on phishing attacks
   - Why email is a primary attack vector

2. **Common Red Flags** (Content)
   - Suspicious sender addresses
   - Spelling and grammar errors
   - Urgent or threatening language
   - Requests for sensitive information
   - Suspicious links and attachments

3. **Question 1: Identify Phishing Indicators** (Multiple Choice)
   - **Points:** 50 total
   - **Correct Answers:**
     - Misspelled sender domain (15 pts)
     - Generic greeting instead of name (10 pts)
     - Urgent threat about account closure (15 pts)
     - Suspicious link destination (10 pts)
   - **Topic:** Recognition of multiple warning signs

4. **Email Analysis Techniques** (Content)
   - How to inspect sender information
   - Hovering over links to check destinations
   - Checking email headers
   - Verifying legitimacy through official channels

5. **Question 2: Safe Email Practices** (Single Choice)
   - **Points:** 25 total
   - **Correct Answer:** "Hover over links to verify destination before clicking"
   - **Topic:** Proactive defense techniques

6. **Question 3: Reporting Procedures** (Free Text)
   - **Points:** 25 total
   - **Validation:** Must mention "report", "IT", and "forward"
   - **Topic:** Organizational response to phishing

### Scoring

- **Total Points:** 100
- **Passing Score:** 70%
- **Question Distribution:**
  - Multiple choice: 50 points (partial credit)
  - Single choice: 25 points (all or nothing)
  - Free text: 25 points (keyword-based)

### Implementation Details

**Files:**
- Config: `backend/lessons/configs/phishing-email-basics.yaml`
- Module: `backend/lessons/modules/phishing-email-basics/index.js`

**Question Types:**
- Uses standard base class validation
- No custom interactive components
- Text-based content delivery

### Best Practices for Teaching

- Start with real-world examples
- Show actual phishing emails (sanitized)
- Emphasize the cost of successful attacks
- Practice with interactive email analysis
- Reinforce reporting procedures

---

## 2. SQL Injection Attack - Online Shop Demo

### Overview

**Lesson Key:** `sql-injection-shop`
**Difficulty:** Intermediate
**Duration:** 20 minutes
**Category:** Web Application Security / OWASP Top 10

### Learning Objectives

By the end of this lesson, participants will be able to:
- Understand how SQL injection vulnerabilities work
- Recognize vulnerable code patterns
- Execute SQL injection attacks in a safe environment
- Understand the difference between vulnerable and secure queries
- Apply parameterized queries as the primary defense

### Content Structure

#### Steps:

1. **What is SQL Injection?** (Content)
   - Definition and mechanism
   - Types of damage (data theft, modification, deletion)
   - Authentication bypass techniques
   - Administrative operation exploitation

2. **Vulnerable Online Shop** (Interactive)
   - **Component:** `SQLShopDemo`
   - Live product search with vulnerable SQL backend
   - Real-time query visualization
   - Injection detection and explanation

3. **Question 1: Identify SQL Injection Payloads** (Multiple Choice)
   - **Points:** 40 total
   - **Correct Answers:**
     - `' OR '1'='1` (15 pts) - Always-true condition
     - `' UNION SELECT username, password FROM users--` (15 pts) - Data extraction
     - `'; DROP TABLE products--` (10 pts) - Destructive attack
   - **Topic:** Recognition of injection syntax

4. **How SQL Injection Works** (Content)
   - Query structure explanation
   - Normal vs malicious input comparison
   - Step-by-step breakdown of attacks
   - Impact demonstration

5. **Question 2: Prevention Methods** (Single Choice)
   - **Points:** 30 total
   - **Correct Answer:** "Use parameterized queries (prepared statements)"
   - **Topic:** Gold-standard defense mechanism

6. **Preventing SQL Injection** (Content)
   - Parameterized queries (primary defense)
   - Input validation strategies
   - Least privilege principle
   - Web Application Firewalls
   - Security auditing

7. **Question 3: Explain Parameterized Queries** (Free Text)
   - **Points:** 30 total
   - **Validation:** Must mention "parameter", "data", and "separate"
   - **Minimum Length:** 50 characters
   - **Topic:** Understanding separation of code and data

### Interactive Component: SQLShopDemo

#### Features:

**Mock Database:**
```javascript
products: 8 items (laptops, accessories, office supplies)
users: 3 accounts (admin, john_doe, jane_smith)
orders: 2 sample orders
```

**Attack Scenarios:**

1. **OR Injection:**
   - Input: `' OR '1'='1`
   - Result: Returns ALL products
   - Explanation: Bypasses WHERE clause with always-true condition

2. **UNION SELECT:**
   - Input: `' UNION SELECT id, username, password, role, 'LEAKED' FROM users--`
   - Result: Displays user credentials in product table
   - Explanation: Combines product data with user table

3. **DROP TABLE:**
   - Input: `'; DROP TABLE products--`
   - Result: Simulates table deletion
   - Explanation: Executes destructive SQL command

**UI Elements:**
- Search input with monospace font for code clarity
- "Vulnerable Search" button (red) - executes unsafe query
- "Safe Search" button (green) - uses parameterized query
- Quick-load example buttons
- Real-time SQL query display with syntax highlighting
- Injection detection warnings with emoji indicators
- Results table showing affected data
- Color-coded feedback (red for exploits, green for safe)

#### Technical Implementation:

**Backend Methods:**
```javascript
executeVulnerableQuery(searchTerm)
  - Simulates vulnerable string concatenation
  - Detects injection patterns
  - Returns appropriate results based on attack type

executeSafeQuery(searchTerm)
  - Demonstrates parameterized approach
  - Treats all input as literal data
  - Shows query with placeholder syntax

detectInjection(input)
  - Regex-based pattern matching
  - Identifies quotes, comments, SQL keywords

analyzeInjection(input)
  - Classifies injection type
  - Generates educational explanation
```

**Frontend API Call:**
```javascript
participantAPI.executeLessonAction(
  eventLessonId,
  'execute-query',
  { searchTerm, mode: 'vulnerable' | 'safe' }
)
```

### Scoring

- **Total Points:** 100
- **Passing Score:** 70%
- **Question Distribution:**
  - Multiple choice: 40 points (partial credit)
  - Single choice: 30 points
  - Free text: 30 points (keyword validation)

### Implementation Details

**Files:**
- Config: `backend/lessons/configs/sql-injection-shop.yaml`
- Module: `backend/lessons/modules/sql-injection-shop/index.js`
- Component: `frontend/src/components/lessons/InteractiveContent/SQLShopDemo.jsx`

**Dependencies:**
- Extends `LessonModule` base class
- Custom `executeVulnerableQuery` method
- Custom `executeSafeQuery` method
- Interactive data provider

**API Endpoint:**
- `POST /api/lesson/:eventLessonId/action/execute-query`
- Requires participant authentication
- Validates lesson is started

### Best Practices for Teaching

- Start with normal searches to establish baseline
- Progress from simple to complex injections
- Always compare vulnerable vs safe implementations
- Emphasize that filtering alone is insufficient
- Show real-world impact examples
- Demonstrate UNION attacks to highlight data exposure risk
- Use color coding to make injection obvious
- Provide immediate feedback on each attempt

### Real-World Context

**OWASP Ranking:** #3 in OWASP Top 10 (Injection)

**Notable Incidents:**
- 2019: British Airways breach (380,000 transactions)
- 2020: Freepik SQL injection (8.3 million accounts)
- Ongoing: Automated scanning for vulnerable endpoints

**Industry Standards:**
- OWASP recommends parameterized queries
- PCI DSS requires SQL injection prevention
- ISO 27001 covers secure coding practices

---

## 3. Browser-in-the-Browser (BitB) Attack

### Overview

**Lesson Key:** `browser-in-browser-attack`
**Difficulty:** Advanced
**Duration:** 25 minutes
**Category:** Social Engineering / Advanced Phishing

### Learning Objectives

By the end of this lesson, participants will be able to:
- Understand Browser-in-the-Browser attack methodology
- Differentiate between real and fake browser windows
- Apply physical testing techniques to detect fake popups
- Recognize OAuth/SSO popup security implications
- Understand why password managers provide protection

### Content Structure

#### Steps:

1. **What is Browser-in-the-Browser?** (Content)
   - Definition and attack mechanism
   - Why it's effective (mimics trusted UI)
   - Comparison to traditional phishing
   - Historical context (2022 emergence)

2. **How the Attack Works** (Content)
   - Traditional OAuth flow diagram
   - BitB attack flow comparison
   - Technical explanation (HTML/CSS fake browser)
   - Visual deception techniques

3. **Interactive BitB Demo** (Interactive)
   - **Component:** `BitBDemo`
   - Side-by-side real vs fake comparison
   - Interactive detection testing
   - Real-world attack examples

4. **Question 1: Detection Indicators** (Multiple Choice)
   - **Points:** 40 total
   - **Correct Answers:**
     - "Window cannot be dragged outside browser" (20 pts)
     - "Right-click shows 'Inspect Element' on address bar" (20 pts)
   - **Topic:** Physical behavior testing

5. **Detection Techniques** (Content)
   - Drag window test (primary method)
   - Address bar selectability check
   - Right-click inspection test
   - Pixel-perfect detail examination
   - Taskbar appearance verification
   - Browser extension usage

6. **Question 2: Safest Approach** (Single Choice)
   - **Points:** 35 total
   - **Correct Answer:** "Try to drag the popup outside browser window"
   - **Topic:** Practical defense technique

7. **Protecting Against BitB** (Content)
   - User defenses (testing, 2FA, manual navigation)
   - Developer responsibilities (education, redirect flow)
   - Organizational measures (training, hardware keys)

8. **Question 3: Password Manager Protection** (Free Text)
   - **Points:** 25 total
   - **Validation:** Must mention "domain", "autofill", and "real"
   - **Minimum Length:** 40 characters
   - **Topic:** Technical security controls

### Interactive Component: BitBDemo

#### Features:

**Two Scenarios:**

1. **Legitimate OAuth Popup (Simulated Real)**
   - Provider: Google
   - Domain: `accounts.google.com`
   - Indicators shown for educational purposes
   - Green "✅ REAL" badge

2. **BitB Attack (Fake Popup)**
   - Provider: Microsoft
   - Domain: `login.microsoftonline.com`
   - Trapped within page boundaries
   - Red "⚠️ FAKE" badge

**Interactive Tests:**

1. **Drag Test:**
   - Real: Would allow dragging (simulated)
   - Fake: Cannot drag outside browser
   - Feedback: Yellow warning appears when attempted

2. **Right-Click Test:**
   - Real: Browser context menu (simulated)
   - Fake: Shows "Inspect Element" menu
   - Feedback: Warning about HTML detection

3. **Visual Inspection:**
   - Fake window controls (non-functional buttons)
   - Fake address bar (styled HTML div)
   - Fake HTTPS lock icon (just an image)

**UI Elements:**
- Side-by-side scenario cards
- Provider-specific styling (Google blue, Microsoft blue)
- Launch buttons to open fake popups
- Dark overlay when popup is active
- Educational indicators list
- Real-world attack timeline
- Test instructions panel

**Realistic Browser Chrome:**
```
- macOS-style window controls (red, yellow, green)
- Address bar with lock icon
- Provider-specific branding
- Login form (email + password)
- Sign-in button
```

#### Technical Implementation:

**Frontend Structure:**
```javascript
renderFakeBrowser(scenario)
  - Creates modal overlay
  - Renders fake browser window
  - Applies provider styling
  - Handles drag attempts
  - Handles right-click detection
  - Shows feedback badges
```

**Drag Detection:**
```javascript
handleDragStart(e, isReal)
  - Sets dragAttempted flag
  - Prevents drag if fake (e.preventDefault)
  - Shows educational feedback
```

**Right-Click Detection:**
```javascript
handleAddressBarRightClick(e, isReal)
  - Sets inspectAttempted flag
  - Allows context menu on fake popup
  - Shows educational feedback
```

**Real-World Examples Data:**
```javascript
[
  { year: 2022, target: 'Corporate employees', provider: 'Microsoft OAuth' },
  { year: 2022, target: 'Cryptocurrency users', provider: 'Google Sign-in' },
  { year: 2023, target: 'GitHub developers', provider: 'GitHub OAuth' }
]
```

### Scoring

- **Total Points:** 100
- **Passing Score:** 75%
- **Question Distribution:**
  - Multiple choice: 40 points (physical testing)
  - Single choice: 35 points (best practice)
  - Free text: 25 points (technical understanding)

### Implementation Details

**Files:**
- Config: `backend/lessons/configs/browser-in-browser-attack.yaml`
- Module: `backend/lessons/modules/browser-in-browser-attack/index.js`
- Component: `frontend/src/components/lessons/InteractiveContent/BitBDemo.jsx`

**Dependencies:**
- Extends `LessonModule` base class
- Custom `getInteractiveData` method
- React state management for popups
- CSS-in-JS for fake browser styling

**Special Features:**
- Modal overlay system
- Drag prevention
- Context menu detection
- Provider theming
- Responsive design

### Best Practices for Teaching

- Emphasize that visual inspection alone is insufficient
- Demonstrate the drag test as the most reliable method
- Show how convincing the fake popups can be
- Discuss password manager benefits
- Explain why manual navigation is safest
- Reference real-world incidents
- Practice detection multiple times
- Warn about new variations

### Real-World Context

**Discovery:** 2022 by security researcher mr.d0x

**Attack Campaign Examples:**
- **March 2022:** Steam account phishing
- **April 2022:** Cryptocurrency exchange targeting
- **May 2022:** Corporate credential harvesting
- **2023:** GitHub and GitLab developer targeting

**Affected Platforms:**
- Any OAuth/SSO provider (Google, Microsoft, Facebook, GitHub)
- Banking sites with "secure" login popups
- Enterprise SSO systems
- Cryptocurrency wallets

**Why It's Effective:**
- Mimics trusted UI perfectly
- Bypasses traditional phishing training
- Works on security-aware users
- No browser warnings triggered
- HTTPS indicators can be faked

**Defense Evolution:**
- Hardware security keys (FIDO2/WebAuthn) immune
- Password managers check real domain
- Browser extensions can detect fake UI
- User education most critical

---

## Creating New Lessons

### Overview

This section provides guidance for creating new lessons in the platform.

### Lesson Structure

Every lesson consists of two main components:

1. **YAML Configuration File** (`lessons/configs/*.yaml`)
   - Defines lesson metadata
   - Structures content steps
   - Configures questions and answers
   - Sets scoring rules

2. **JavaScript Module** (`lessons/modules/*/index.js`)
   - Extends `LessonModule` base class
   - Implements custom validation logic
   - Provides interactive data
   - Handles special behaviors

### YAML Configuration Format

```yaml
lessonKey: "unique-lesson-identifier"
title: "Lesson Display Title"
description: "Brief description for lesson catalog"
difficultyLevel: "beginner|intermediate|advanced"
estimatedDuration: 15  # minutes
module: "module-directory-name"

steps:
  - id: "step-1"
    type: "content|question|interactive"
    title: "Step Title"
    content: "Step content (can be multiline)"

  - id: "question-1"
    type: "question"
    questionType: "single_choice|multiple_choice|free_text"
    question: "The question text?"
    options:  # for choice questions
      - id: "option-1"
        text: "Option text"
        isCorrect: true|false
        points: 10
    validationRules:  # for free_text questions
      keywords:
        required: ["keyword1", "keyword2"]
        partialCredit: 5
      minLength: 50
    maxPoints: 25
    feedback:
      correct: "Positive feedback"
      incorrect: "Educational feedback"

scoring:
  passingScore: 70
  maxTotalPoints: 100
```

### JavaScript Module Structure

```javascript
const LessonModule = require('../base/LessonModule');

class YourLessonModule extends LessonModule {
  constructor(config) {
    super(config);
  }

  // Optional: Custom answer validation
  async validateAnswer(questionId, answer) {
    // Custom logic here, or use:
    return super.validateAnswer(questionId, answer);
  }

  // Optional: Provide data for interactive components
  getInteractiveData(stepId) {
    if (stepId === 'your-interactive-step') {
      return {
        // Data your frontend component needs
      };
    }
    return null;
  }

  // Optional: Custom methods for lesson-specific actions
  yourCustomMethod(params) {
    // Implementation
  }
}

module.exports = YourLessonModule;
```

### Question Types

#### 1. Single Choice
```yaml
questionType: "single_choice"
options:
  - id: "correct-option"
    text: "The right answer"
    isCorrect: true
    points: 25
  - id: "wrong-option"
    text: "An incorrect answer"
    isCorrect: false
    points: 0
```
- Only one correct answer
- All-or-nothing scoring
- Radio button UI

#### 2. Multiple Choice
```yaml
questionType: "multiple_choice"
options:
  - id: "correct-1"
    text: "First correct answer"
    isCorrect: true
    points: 15
  - id: "correct-2"
    text: "Second correct answer"
    isCorrect: true
    points: 15
  - id: "wrong-1"
    text: "Incorrect answer"
    isCorrect: false
    points: 0
```
- Multiple correct answers
- Partial credit awarded per correct selection
- Checkbox UI

#### 3. Free Text
```yaml
questionType: "free_text"
validationRules:
  keywords:
    required: ["must", "contain", "these"]
    partialCredit: 10  # points if some keywords present
  minLength: 50  # minimum character count
maxPoints: 25
```
- Open-ended response
- Keyword-based validation
- Minimum length requirement

### Interactive Components

#### Creating a New Interactive Component

1. **Define in YAML:**
```yaml
- id: "interactive-demo"
  type: "interactive"
  title: "Interactive Demo"
  interactiveComponent: "YourComponentName"
  content: "Instructions for the interactive element"
```

2. **Provide Data in Module:**
```javascript
getInteractiveData(stepId) {
  if (stepId === 'interactive-demo') {
    return {
      data: 'Your component data',
      config: {}
    };
  }
  return null;
}
```

3. **Create React Component:**
```javascript
// frontend/src/components/lessons/InteractiveContent/YourComponent.jsx
import React from 'react';

const YourComponent = ({ lessonData, eventLessonId }) => {
  const interactiveData = lessonData?.interactiveData || {};

  return (
    <div>
      {/* Your interactive UI */}
    </div>
  );
};

export default YourComponent;
```

4. **Register in LessonView:**
```javascript
// frontend/src/pages/LessonView.jsx
import YourComponent from '../components/lessons/InteractiveContent/YourComponent';

// In render:
{currentStep.interactiveComponent === 'YourComponent' && (
  <YourComponent lessonData={lesson} eventLessonId={eventLessonId} />
)}
```

### Lesson-Specific Actions

For interactive components that need backend processing:

1. **Add Method to Module:**
```javascript
yourCustomAction(params) {
  // Process params
  return result;
}
```

2. **Handle in Controller:**
```javascript
// backend/src/controllers/lesson.controller.js
if (action === 'your-action' && lessonModule.yourCustomAction) {
  result = lessonModule.yourCustomAction(actionData);
}
```

3. **Call from Frontend:**
```javascript
participantAPI.executeLessonAction(
  eventLessonId,
  'your-action',
  { data }
)
```

### Seeding New Lessons

1. **Add to Catalog:**
```javascript
// backend/seed-lessons.js
const lessons = [
  {
    lesson_key: 'your-lesson-key',
    title: 'Your Lesson Title',
    description: 'Description',
    module_path: 'your-module-directory',
    config_path: 'your-config.yaml',
    difficulty_level: 'intermediate',
    estimated_duration: 20
  }
];
```

2. **Run Seed Script:**
```bash
docker exec lernplattform_backend node seed-lessons.js
```

### Best Practices

**Content Design:**
- Start with clear learning objectives
- Use progressive difficulty (easy → hard)
- Provide immediate feedback
- Include real-world examples
- Make it hands-on when possible

**Question Design:**
- Multiple choice: 2-4 options, avoid "all of the above"
- Free text: Clear validation criteria
- Feedback: Educational, not just correct/incorrect
- Points: Reflect question difficulty

**Interactive Elements:**
- Make them essential, not decorative
- Provide clear instructions
- Give immediate visual feedback
- Include educational explanations
- Allow experimentation

**Code Quality:**
- Follow existing patterns
- Handle errors gracefully
- Validate all inputs
- Comment complex logic
- Test thoroughly

**Security:**
- Never execute actual SQL
- Sandbox all demonstrations
- Validate on both frontend and backend
- Don't leak sensitive information
- Use appropriate warnings

### Testing New Lessons

1. **Lesson Content:**
   - All steps render correctly
   - Images/media load properly
   - Text formatting is correct

2. **Questions:**
   - Correct answers award proper points
   - Wrong answers give appropriate feedback
   - Partial credit calculates correctly
   - Free text validation works

3. **Interactive Components:**
   - Components load without errors
   - Actions execute successfully
   - Feedback displays correctly
   - Edge cases handled

4. **Scoring:**
   - Total points sum correctly
   - Passing threshold works
   - Score persists properly
   - Leaderboard updates

5. **Progress:**
   - Lesson marked as started
   - Navigation works (prev/next)
   - Completion triggers properly
   - Locked lessons stay locked

### File Checklist

- [ ] YAML config created
- [ ] Module directory created
- [ ] Module class implemented
- [ ] Interactive components (if any) created
- [ ] Seed script updated
- [ ] Lesson seeded to database
- [ ] Tested in browser
- [ ] Documentation updated

---

## Appendix

### Lesson Difficulty Guidelines

**Beginner:**
- Foundational concepts
- No prior security knowledge required
- 10-15 minute duration
- Basic terminology introduction
- Real-world relevance emphasized

**Intermediate:**
- Builds on basic security awareness
- Requires understanding of systems/networks
- 15-25 minute duration
- Hands-on demonstrations
- Technical explanations

**Advanced:**
- Assumes security knowledge
- Complex attack scenarios
- 20-30 minute duration
- In-depth technical details
- Sophisticated defenses

### Scoring Philosophy

- **Partial Credit:** Encourage learning, reward partial knowledge
- **Passing Score:** 70-75% allows mistakes while ensuring competency
- **Question Weight:** Harder questions = more points
- **Immediate Feedback:** Don't wait until end of lesson

### Content Style Guide

**Tone:**
- Professional but approachable
- Educational, not preachy
- Objective about risks
- Encouraging about defenses

**Formatting:**
- Use bullet points for lists
- Bold important terms on first use
- Code blocks for technical content
- Clear step-by-step instructions

**Examples:**
- Prefer real-world incidents
- Include dates and sources
- Show impact (financial, reputational)
- Demonstrate both attacks and defenses

---

## Support

For questions about lesson development:
- Review existing lessons as templates
- Check base class methods in `LessonModule.js`
- Test in development environment first
- Document any new patterns

**Last Updated:** 2026-01-12
**Platform Version:** 1.0.0
**Total Lessons:** 3