310 lines
7.6 KiB
Markdown
310 lines
7.6 KiB
Markdown
# Security Awareness Learning Platform
|
|
|
|
A containerized web application for security awareness training with modular, expandable lessons. Participants join events using pseudonyms and complete interactive security lessons including phishing detection, SQL injection demos, and more.
|
|
|
|
## Features
|
|
|
|
- **Hub-Based Architecture**: Participants join events with pseudonyms (no registration required)
|
|
- **Interactive Lessons**: Phishing demos, SQL injection sandboxes, fake login forms, and more
|
|
- **Modular Lesson System**: Easy to expand by adding YAML configs and JavaScript modules
|
|
- **Weighted Scoring**: Configurable points and weights per lesson
|
|
- **Admin Panel**: Complete event and lesson management, participant data viewing
|
|
- **Container-Based**: Easy deployment with Docker Compose
|
|
|
|
## Technology Stack
|
|
|
|
- **Backend**: Node.js + Express
|
|
- **Frontend**: React + Vite
|
|
- **Database**: PostgreSQL 15
|
|
- **Containerization**: Docker + Docker Compose
|
|
- **Lesson Storage**: YAML/JSON configurations + JavaScript modules
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Docker and Docker Compose installed
|
|
- Git (optional, for version control)
|
|
|
|
### Setup Instructions
|
|
|
|
1. **Clone or download the project**
|
|
```bash
|
|
cd lernplattform
|
|
```
|
|
|
|
2. **Configure environment variables**
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` and set secure values for:
|
|
- `DB_PASSWORD` - Database password
|
|
- `JWT_SECRET` - JWT secret key (min 32 characters)
|
|
- `SESSION_SECRET` - Session secret (min 32 characters)
|
|
- `ADMIN_DEFAULT_PASSWORD` - Admin login password
|
|
|
|
3. **Start the application**
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
4. **Wait for services to be healthy**
|
|
```bash
|
|
docker-compose ps
|
|
```
|
|
|
|
All services should show "healthy" status.
|
|
|
|
5. **Access the application**
|
|
- Frontend: http://localhost (port 80)
|
|
- Backend API: http://localhost:3000
|
|
- Health check: http://localhost:3000/health
|
|
|
|
### Default Credentials
|
|
|
|
- **Admin Login**:
|
|
- Username: `admin`
|
|
- Password: Value set in `.env` (`ADMIN_DEFAULT_PASSWORD`)
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
lernplattform/
|
|
├── database/
|
|
│ └── init/
|
|
│ └── 01-schema.sql # Database schema
|
|
├── backend/
|
|
│ ├── src/
|
|
│ │ ├── config/ # Configuration files
|
|
│ │ ├── middleware/ # Express middleware
|
|
│ │ ├── routes/ # API routes
|
|
│ │ ├── controllers/ # Route controllers
|
|
│ │ ├── services/ # Business logic
|
|
│ │ └── models/ # Database queries
|
|
│ ├── lessons/
|
|
│ │ ├── configs/ # Lesson YAML configs
|
|
│ │ └── modules/ # Lesson JavaScript modules
|
|
│ ├── Dockerfile
|
|
│ └── package.json
|
|
├── frontend/
|
|
│ ├── src/
|
|
│ │ ├── pages/ # Page components
|
|
│ │ ├── components/ # Reusable components
|
|
│ │ ├── services/ # API services
|
|
│ │ └── styles/ # CSS styles
|
|
│ ├── Dockerfile
|
|
│ ├── nginx.conf
|
|
│ └── package.json
|
|
├── docker-compose.yml
|
|
└── .env.example
|
|
```
|
|
|
|
## Development
|
|
|
|
### Running in Development Mode
|
|
|
|
#### Backend Development
|
|
```bash
|
|
cd backend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
The backend will run on port 3000 with hot reload.
|
|
|
|
#### Frontend Development
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
The frontend will run on port 5173 with hot reload.
|
|
|
|
### Database Access
|
|
|
|
Connect to the PostgreSQL database:
|
|
```bash
|
|
docker-compose exec database psql -U lernplattform_user -d lernplattform
|
|
```
|
|
|
|
### Viewing Logs
|
|
|
|
```bash
|
|
# All services
|
|
docker-compose logs -f
|
|
|
|
# Specific service
|
|
docker-compose logs -f backend
|
|
docker-compose logs -f frontend
|
|
docker-compose logs -f database
|
|
```
|
|
|
|
## Adding New Lessons
|
|
|
|
Lessons are modular and easy to add. Each lesson consists of:
|
|
1. A YAML configuration file (`backend/lessons/configs/*.yaml`)
|
|
2. A JavaScript module (`backend/lessons/modules/*/index.js`)
|
|
|
|
### Step-by-Step Guide
|
|
|
|
1. **Create YAML configuration** in `backend/lessons/configs/`:
|
|
|
|
```yaml
|
|
lessonKey: "my-new-lesson"
|
|
title: "My New Lesson"
|
|
description: "Learn about security concept X"
|
|
difficultyLevel: "beginner"
|
|
estimatedDuration: 15
|
|
module: "my-new-lesson"
|
|
|
|
steps:
|
|
- id: "intro"
|
|
type: "content"
|
|
title: "Introduction"
|
|
content: "Educational content here..."
|
|
|
|
- id: "question-1"
|
|
type: "question"
|
|
questionType: "single_choice"
|
|
question: "What is the answer?"
|
|
options:
|
|
- id: "option-1"
|
|
text: "Correct answer"
|
|
isCorrect: true
|
|
points: 50
|
|
- id: "option-2"
|
|
text: "Wrong answer"
|
|
isCorrect: false
|
|
points: 0
|
|
maxPoints: 50
|
|
feedback:
|
|
correct: "Great job!"
|
|
incorrect: "Try again..."
|
|
|
|
scoring:
|
|
passingScore: 70
|
|
maxTotalPoints: 100
|
|
```
|
|
|
|
2. **Create JavaScript module** in `backend/lessons/modules/my-new-lesson/`:
|
|
|
|
```javascript
|
|
const LessonModule = require('../base/LessonModule');
|
|
|
|
class MyNewLesson extends LessonModule {
|
|
constructor(config) {
|
|
super(config);
|
|
}
|
|
|
|
// Override methods if custom validation needed
|
|
// Otherwise, base class handles standard question types
|
|
}
|
|
|
|
module.exports = MyNewLesson;
|
|
```
|
|
|
|
3. **Add lesson to database** (via admin panel or SQL):
|
|
|
|
```sql
|
|
INSERT INTO lessons (lesson_key, title, description, module_path, config_path, difficulty_level, estimated_duration)
|
|
VALUES ('my-new-lesson', 'My New Lesson', 'Description', 'my-new-lesson', 'my-new-lesson.yaml', 'beginner', 15);
|
|
```
|
|
|
|
4. **Assign lesson to event** via admin panel.
|
|
|
|
## API Documentation
|
|
|
|
### Participant Endpoints
|
|
|
|
- `POST /api/participant/join` - Join event with pseudonym
|
|
- `GET /api/participant/events` - List active events
|
|
- `GET /api/participant/event/:eventId/lessons` - Get lessons for event
|
|
- `GET /api/participant/lesson/:lessonId` - Get lesson content
|
|
- `POST /api/participant/lesson/:lessonId/answer` - Submit answer
|
|
- `GET /api/participant/progress` - Get progress
|
|
|
|
### Admin Endpoints
|
|
|
|
- `POST /api/admin/login` - Admin authentication
|
|
- `GET /api/admin/events` - List all events
|
|
- `POST /api/admin/events` - Create new event
|
|
- `PUT /api/admin/events/:eventId` - Update event
|
|
- `DELETE /api/admin/events/:eventId` - Delete event
|
|
- `POST /api/admin/events/:eventId/lessons` - Assign lesson to event
|
|
- `GET /api/admin/events/:eventId/participants` - View participant data
|
|
|
|
## Security Considerations
|
|
|
|
- All passwords are hashed with bcrypt
|
|
- JWT tokens for admin authentication
|
|
- Session tokens for participant authentication
|
|
- Parameterized SQL queries to prevent SQL injection
|
|
- CORS configured for security
|
|
- Security headers via Helmet.js
|
|
- Input validation on all endpoints
|
|
- Non-root user in Docker containers
|
|
|
|
## Troubleshooting
|
|
|
|
### Database Connection Issues
|
|
|
|
```bash
|
|
# Check database status
|
|
docker-compose ps database
|
|
|
|
# View database logs
|
|
docker-compose logs database
|
|
|
|
# Restart database
|
|
docker-compose restart database
|
|
```
|
|
|
|
### Backend Not Starting
|
|
|
|
```bash
|
|
# Check backend logs
|
|
docker-compose logs backend
|
|
|
|
# Verify environment variables
|
|
docker-compose exec backend env | grep DB_
|
|
|
|
# Restart backend
|
|
docker-compose restart backend
|
|
```
|
|
|
|
### Frontend Not Loading
|
|
|
|
```bash
|
|
# Check frontend logs
|
|
docker-compose logs frontend
|
|
|
|
# Verify nginx configuration
|
|
docker-compose exec frontend nginx -t
|
|
|
|
# Restart frontend
|
|
docker-compose restart frontend
|
|
```
|
|
|
|
### Reset Everything
|
|
|
|
```bash
|
|
# Stop all services
|
|
docker-compose down
|
|
|
|
# Remove volumes (WARNING: Deletes all data!)
|
|
docker-compose down -v
|
|
|
|
# Rebuild and start
|
|
docker-compose up --build -d
|
|
```
|
|
|
|
## License
|
|
|
|
ISC
|
|
|
|
## Support
|
|
|
|
For issues and questions, please open an issue in the project repository.
|