Mahoraga Webapp Defender

AI-управляемая реактивная система защиты веб-приложений, предназначенная для отражения атак на основе ИИ в реальном времени.

Содержание

Mahoraga Webapp Defender

Введение

Mahoraga Defender — это PoC реактивной, не зависящей от типа атакующего системы защиты в реальном времени. Основной механизм заключается в том, чтобы заставить противника проводить разведку и атаки на безобидную, фальшивую среду («shadow»-среду) и регистрировать эти атаки. Затем LLM-агент анализирует логи и передаёт сведения о любых обнаруженных эксплойтах другим LLM-агентам для исправления уязвимостей и развёртывания патчей.

Система спроектирована для полной автоматизации с учётом оптимизации затрат на API. Создан графический интерфейс для удобного мониторинга логов трафика, активности агентов и конвейера патчинга, а также для контроля количества развёртываемых агентов.

Целевой веб-сайт

Целевой (жертвенный) веб-сайт — это форк crAPI (Completely Ridiculous API), намеренно уязвимого веб-приложения, созданного OWASP для обучения тестированию безопасности API. crAPI имитирует платформу владельцев автомобилей с микросервисами, охватывающими OWASP Top 10 уязвимостей API. Защитник спроектирован так, чтобы чётко различать обычные и вредоносные сессии пользователей, чтобы обычные пользователи не испытывали снижения качества обслуживания, пока защитник защищает сайт от атакующих.

Наш форк (crapi-fork/) добавляет:

Размещённые приманки (фейковые учётные данные, конечные точки, токены) для обнаружения атакующих
Всего 12 флагов в стиле CTF, встроенных в поверхность атаки
Параллельный «shadow»-стек с идентичными сервисами и отдельными базами данных для безопасного наблюдения за атакующим
Сессионную маршрутизацию на основе nginx Lua, которая прозрачно перенаправляет подозрительные сессии из prod в shadow

Чистая копия хранится в crapi-original/, чтобы среду можно было сбросить между экспериментами.

Архитектура Mahoraga Defender

Двойная среда

Prod: обслуживает реальных пользователей через обратный прокси nginx (порт 8888)
Shadow: идентичный фальшивый стек с отдельными базами данных, прозрачно получает перенаправленный трафик атакующего

Конвейер агентов

Orchestrator: координирует весь конвейер. Управляет жизненным циклом агентов, очередями патчей/рецензий, состоянием тикетов, развёртыванием и восстановлением после сбоев. Масштабирует количество агентов-исправителей/рецензентов во время выполнения.
Watcher (на основе правил): отслеживает логи prod-трафика и оценивает сессии по уровню угрозы с помощью сопоставления шаблонов (брутфорс, инъекции, перебор, доступ к приманкам и т.д.). Когда оценка угрозы превышает порог, запускает действие перенаправления.
Shadow Analyzer (LLM-агент): с настраиваемым интервалом читает логи трафика shadow-среды для обнаружения успешных эксплойтов. Дедуплицирует записи логов, обнаруживает шаблоны атак и передаёт подтверждённые эксплойты в очередь исправления.
Fixer (LLM-агент): получает отчёты об эксплойтах, читает соответствующий исходный код и исправляет его напрямую в crapi-fork/. Работает в изолированной bash-среде с доступом только к crapi-fork/.
Reviewer (LLM-агент): проверяет патчи на корректность, полноту охвата и безопасность. Одобренные патчи запускают действие развёртывания; отклонённые патчи возвращаются исправителю с обратной связью.

При развёртывании Python-сервисы горяче перезагружаются через gunicorn (мгновенно), а Java/Go-сервисы пересобираются через docker compose up -d --build.

Почему нет агента-тестировщика? Мы рассматривали добавление специального агента для тестирования пользователей и отдельной тестовой среды, но удалили оба, чтобы сохранить систему лёгкой.

Как начать

Подготовка

Рекомендуется использовать conda или виртуальное окружение Python (например, conda create -n XYZ python=3.13, затем conda activate XYZ).
Установите зависимости: pip install -r requirements.txt

Полный эксперимент: Защитник против Атакующего

Запустите ./start.sh из корневого каталога проекта — сбрасывает исходный код crapi-fork/ из crapi-original/, пересобирает все сервисы, размещает флаги и приманки.
Запустите защитника: python3 -m harness.main --app-url http://localhost:8888 -v.
Начните пентест сайта на localhost:8888 (описание заданий находится по адресу localhost:8888/challenge). Если пентест проводится с помощью ИИ-агента, агент не должен получать доступ к внутренним процессам Docker, так как это будет считаться мошенничеством.
Во время пентеста наблюдайте за панелью управления защитника на localhost:3000 для просмотра логов в реальном времени, действий агентов, патчей, захваченных флагов и т.д.
После завершения сессии выполните docker compose down -v, чтобы удалить контейнеры Docker и базы данных, созданные для этого проекта.

Панель управления

Панель управления: http://localhost:3000

На всех вкладках отображается глобальная строка состояния агентов, показывающая их здоровье (активен/завис/бездействует/ошибка) с элементами управления масштабированием.

Логи

Просмотр логов запросов prod/shadow в реальном времени с разделением экрана, цветовой кодировкой по степени серьёзности и группировкой трафика

Агенты

Лента активности каждого агента с системными промптами, вызовами инструментов и метками используемых LLM

Конвейер

Доска Канбан: Обнаружено → Исправляется → Проверяется → Развёрнуто, с изменяемой панелью деталей

Патчи

Различия в коде, изменённые файлы, команды отката и временная шкала для каждого патча

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

Система использует любой API, совместимый с OpenAI. Настройте модели в config/llm.yaml:

# Shadow Analyzer — reads shadow logs to detect exploits (no tool calling)
shadow_analyzer:
  provider: gemini
  model: gemini-2.5-flash
  api_key_env: GEMINI_API_KEY # defined in harness/.env
  pricing:
    input_per_million: 0.30
    output_per_million: 2.50

# Fixer — patches source code (tool-calling agent)
fixer:
  provider: gemini
  model: gemini-3-flash-preview
  api_key_env: GEMINI_API_KEY # defined in harness/.env
  pricing:
    input_per_million: 0.50
    output_per_million: 3.00

# Reviewer — verifies patches (tool-calling agent)
reviewer:
  provider: gemini
  model: gemini-3-flash-preview
  api_key_env: GEMINI_API_KEY # defined in harness/.env
  pricing:
    input_per_million: 0.50
    output_per_million: 3.00

Чтобы сменить провайдера, измените provider и model, затем установите соответствующий ключ API в harness/.env:

Поддерживаемые провайдеры: OpenAI, Gemini, Anthropic, Groq, Together, Ollama, Mistral, DeepSeek, Fireworks, xAI, Perplexity, OpenRouter, Zhipu. Добавьте собственных провайдеров, указав их базовый URL в разделе providers YAML.

providers:
  openai: https://api.openai.com/v1
  gemini: https://generativelanguage.googleapis.com/v1beta/openai/
  anthropic: https://api.anthropic.com/v1/
  groq: https://api.groq.com/openai/v1
  ... # add more if needed

Примечание: лишь некоторые API-провайдеры имеют достаточно высокий лимит запросов для одновременной работы 3+ агентов. Google Gemini — один из них.

Технологический стек

LLM: Любой API, совместимый с OpenAI (по умолчанию: Gemini 3 Flash Preview для агентов, Gemini 2.5 Flash для анализатора)
Целевое приложение: модифицированный crAPI (Python/Django, Java/Spring Boot, Go, MongoDB, PostgreSQL)
Маршрутизация: nginx с Lua-скриптингом для прозрачного перенаправления сессий
Оценка угроз: Redis-бэкенд с оценкой угроз через управляющий слой FastAPI
Панель управления: React + Tailwind CSS, обслуживается FastAPI с WebSocket для обновлений в реальном времени
Оркестрация: Python asyncio с координацией агентов на основе очередей

Особая благодарность

Особая благодарность d3lta05 (LinkedIn) и aleemladha за помощь в пентестинге.

Популярное

Mahoraga-Webapp-Defender