Vulnerability Game

Образовательная платформа для обучения уязвимостям веб-приложений через интерактивные задачи по программированию. Пользователи проходят уровни, используя подготовленные уязвимости: от простых HTTP-запросов до SQL-инъекций.

Обзор

Сервис состоит из двух основных компонентов:

• Backend: сервис на Go, управляющий логикой игры, аутентификацией, прогрессом пользователя и выполнением кода в изолированных контейнерах
• Frontend: UI на React + Vite для решения задач

На каждом уровне пользователь встречает новую уязвимость, которую должен понять и использовать для прохождения.

Архитектура

Пользователь (браузер)
    ↓
React Frontend (8080)
    ↓
HTTP API (роутер go-chi)
    ├── Аутентификация: JWT через gRPC сервис
    ├── Управление пользователем: профиль, прогресс
    ├── Уровни: описание, подсказки, обработка вводов
    ├── Подсказки: контекстная помощь
    └── Выполнение кода: обёртывание и отправка в очередь
    ↓
Очередь Code Runner (канал в памяти)
    ↓
Container Manager (оркестрация Docker)
    ├── Запуск изолированных окружений Python
    ├── Захват вывода
    └── Применение ограничений ресурсов
    ↓
SQLite база данных
    ├── Пользователи (авторизация, прогресс)
    ├── Уровни (задачи)
    ├── Подсказки (по уровням)
    └── Связь пользователь-уровень (статус завершения)

Также запускаются два дополнительных сервера:

1. gRPC сервис аутентификации (127.0.0.1:8085): генерирует и валидирует JWT токены. Использует Google OAuth.
2. Curl Server (порт 9086): уязвимый HTTP сервер, который пользователи используют для curl запросах. Демонстрирует SQL-инъекции, command injection.

Стек технологий

Backend

• Go 1.23:
• go-chi: HTTP роутер и middleware
• SQLite:
• Docker SDK:
• gRPC + Protocol Buffers:
• JWT (golang-jwt):
• Google OAuth 2.0:
• slog:

Frontend

• React + Vite:
• TypeScript:

Основные возможности

Система уровней

Уровни хранятся в SQLite и представляют задачи по безопасности:

type Level struct {
    Id            int
    Name          string
    Description   string      // Описание задачи
    ExpectedInput string      // Что должен ввести пользователь
    StartInput    string      // Шаблон кода
}

Каждый уровень посвящён классу уязвимостей:

• Уровни 1–2: HTTP запросы через curl, раскрытие информации
• Уровень 3: подбор слабых учётных данных
• Уровни 4–5: command injection (доступ к файловой системе)
• Уровни 6–7: SQL-инъекции (UNION SELECT)
• Уровень 8: ломающие запросы (DROP TABLE)
• Уровни 9–10: переполнение стека

Отслеживание прогресса

type UserLevel struct {
    UserId          int
    LevelId         int
    IsCompleted     bool        // Задача решена
    LastInput       string      // Последняя отправка
    AttemptResponse string      // Ответ сервера
    Attempts        int         // Количество попыток
}

Конвейер выполнения кода

Когда пользователь отправляет код на уровнях 9–10:

1. Код оборачивается контекстом уровня (например, ограничения памяти для тестов ОПМ)
2. Задача ставится в очередь code runner
3. Container manager берёт из очереди и выполняет в изолированном Docker контейнере
4. Вывод захватывается и сравнивается с ожидаемым результатом
5. Ответ содержит статус прохождения/непрохождения

func (r *CodeRunner) NewTask(ctx context.Context, ...) func(context.Context) (domain.Response, error) {
    // Оборачивает код, ставит задачу, ждёт результата с таймаутом 10 секунд
}

Система подсказок

Каждый уровень может иметь несколько подсказок.

Аутентификация

• JWT токены генерируются сервисом gRPC
• TTL токена настраивается (по умолчанию 1 час)
• Secret хранится в переменной окружения
• Middleware валидирует подпись и извлекает email пользователя в контекст

Детали реализации

Схема базы данных

Миграции запускаются при старте через cfg.MigrationPath (по умолчанию ./internal/db/init.sql). Схема включает:

• users: Email, хеш пароля, интеграция OAuth, статистика прогресса
• levels: определение задач
• hints: подсказки по уровням
• user_levels: прогресс пользователя на каждом уровне
• apps: OAuth приложения

Конфигурация

Конфигурация загружается из ./internal/cfg/cfg.yaml с возможностью переопределения переменными окружения:

http_server:
  storage_path: "./internal/db/storage.db"
  address: "0.0.0.0:8080"
  
orchestrator_config:
  image_name: "code-runner"  # Docker образ для выполнения кода
  target_dir: "/home"        # Где выполняется код
  
grpc_config:
  address: "127.0.0.1:8085"  # Сервис аутентификации
  token_ttl: 1h

Требуемые переменные окружения:

• JWT_SECRET: secret для подписи JWT токенов
• GOOGLE_CLIENT_ID: Google OAuth client ID
• GOOGLE_CLIENT_SECRET: Google OAuth secret

Интеграция с Docker

Container manager:

1. Берёт образ code-runner (предоставляется пользователем)
2. Монтирует временную директорию с кодом
3. Запускает Python с файлом решения
4. Захватывает stdout/stderr и код выхода
5. Очищает контейнеры после выполнения

Ограничения ресурсов применяются per-level. На уровне 10 память ограничивается до 100МБ для тестирования ОПМ.

Цепочка middleware

Порядок обработки запроса:

1. CORS:
2. RequestID: уникальный ID для трассировки
3. Logger: стандартное HTTP логирование
4. Recoverer: ловит паники
5. Custom Auth: валидирует JWT и извлекает контекст пользователя

Запуск проекта

Backend

# Убедитесь, что конфиг существует
# backend/internal/cfg/cfg.yaml

# Установите переменные окружения
export JWT_SECRET=ваш-secret-ключ
export GOOGLE_CLIENT_ID=...
export GOOGLE_CLIENT_SECRET=...

# Из директории backend
go run main.go
# или
make run

Backend запускает:

1. HTTP сервер на порту 8080 (настраивается)
2. gRPC сервис аутентификации на 127.0.0.1:8085
3. Curl server на 9086

Инициализация базы данных

Запустите скрипт заполнения базы:

bash backend/internal/db/fill_db_script.sh

Создаёт SQLite БД со всеми уровнями, подсказками и таблицами пользователей.

Frontend

cd frontend
npm install
npm run dev

Frontend запускается на http://localhost:5173 (по умолчанию Vite).

Docker

docker build -f backend/Dockerfile -t code-runner .

Тестирование

make test

API endpoints

Аутентификация

• POST /auth/google - Google OAuth вход
• POST /auth/google/callback - OAuth callback

Данные пользователя

• GET /user?email=... - Профиль пользователя (email, попытки, пройденные уровни)

Уровни

• GET /levels - Список всех уровней
• GET /levels/{id} - Один уровень с подсказками

Отправка решения

• POST /submit - Отправить решение (body: {levelId, input})

Подсказки

• GET /hints?levelId=... - Получить подсказки уровня

Структура проекта

Ключевые директории:

• backend/ - Go бэкенд

  • main.go - точка входа сервера
  • internal/api/ - HTTP handlers (auth, levels, submit, hints, user)
  • internal/db/ - слой хранения SQLite
  • internal/cfg/ - загрузка конфигурации
  • internal/codeRunner/ - обёртывание выполнения кода
  • internal/containerMgr/ - оркестрация Docker
  • auth/ - gRPC сервис аутентификации
  • curlServer/ - уязвимый HTTP сервер для curl задач

• frontend/ - React + Vite фронтенд

• .github/ - конфигурация GitHub