Mahoraga-Webapp-Defender

Sistema de defensa reactivo para sitios web impulsado por IA que detecta ataques, los analiza y parchea el código fuente de forma autónoma en tiempo real utilizando agentes LLM.

Introducción

Mahoraga Defender es una Prueba de Concepto de un sistema de defensa reactivo, independiente del tipo de atacante, y en tiempo real. El mecanismo central consiste en engañar a un adversario para que realice descubrimientos y ataques en un entorno benigno y falso (entorno "sombra") y registrar estos ataques. Luego, un agente LLM analiza los registros y entrega los detalles de cualquier exploit detectado a más agentes LLM para que corrijan las vulnerabilidades y desplieguen los parches.

El sistema está diseñado para ser totalmente automatizado, con optimización de costos de API en mente. Se creó una interfaz gráfica para monitorear fácilmente los registros de tráfico, la actividad de los agentes y el pipeline de parches, así como para controlar la cantidad de agentes a desplegar.

Sitio Web Objetivo

El sitio web objetivo (víctima) es un fork de crAPI (Completely Ridiculous API), una aplicación web intencionalmente vulnerable creada por OWASP para la enseñanza de pruebas de seguridad en APIs. crAPI simula una plataforma de propietarios de vehículos con microservicios que cubren las vulnerabilidades de API del OWASP Top 10. El defensor está diseñado para distinguir claramente entre sesiones de usuarios normales y adversarias, de modo que los usuarios normales no experimenten ninguna caída en la calidad de la experiencia de usuario mientras el defensor protege el sitio web de los atacantes.

Nuestro fork (crapi-fork/) añade:

• Honeypots plantados (credenciales señuelo, endpoints, tokens) para la detección de atacantes
• Un total de 12 banderas estilo CTF incrustadas en la superficie de ataque
• Un stack "sombra" paralelo con servicios idénticos y bases de datos separadas para la observación segura del atacante
• Enrutamiento de sesiones basado en nginx Lua que redirige de forma transparente las sesiones sospechosas de producción a la sombra

Se mantiene una copia prístina en crapi-original/ para poder reiniciar el entorno entre experimentos.

Arquitectura del Defensor Mahoraga

Entornos Duales

• Prod: atiende a usuarios reales a través del proxy inverso nginx (puerto 8888)
• Shadow: stack señuelo idéntico con bases de datos separadas, recibe el tráfico del atacante redirigido de forma transparente

Pipeline de Agentes

• Orquestador: coordina todo el pipeline. Gestiona los ciclos de vida de los agentes, las colas de parches/revisión, el estado de los tickets, el despliegue y la recuperación de fallos. Escala los agentes reparadores/revisores hacia arriba y hacia abajo en tiempo de ejecución.
• Watcher (basado en reglas): monitorea los registros de tráfico de producción y puntúa las sesiones según el nivel de amenaza utilizando coincidencia de patrones (fuerza bruta, inyección, enumeración, acceso a honeypot, etc.). Una vez que la puntuación de amenaza supera un umbral, desencadena la acción de redirección.
• Shadow Analyzer (agente LLM): lee los registros de tráfico del entorno sombra en un intervalo configurable para detectar exploits exitosos. Deduplica entradas de registro, detecta patrones de ataque y envía los exploits confirmados a la cola de reparación.
• Fixer (agente LLM): recibe informes de exploit, lee el código fuente relevante y lo parchea directamente en crapi-fork/. Opera en un entorno bash aislado con acceso restringido solo a crapi-fork/.
• Reviewer (agente LLM): verifica los parches en cuanto a corrección, alcance y seguridad. Los parches aprobados activan la acción de despliegue; los parches rechazados se devuelven al fixer con comentarios.

Al desplegar, los servicios Python se recargan en caliente mediante gunicorn (instantáneo), mientras que los servicios Java/Go se reconstruyen mediante docker compose up -d --build.

¿Por qué no hay un agente Tester? Consideramos agregar un agente dedicado de pruebas de usuario y un entorno de pruebas separado, pero ambos fueron eliminados para mantener el sistema ligero.

Cómo Empezar

Preparación

• Se recomienda usar un entorno virtual de conda o python (por ejemplo, conda create -n XYZ python=3.13, luego conda activate XYZ).
• Instalar requisitos: pip install -r requirements.txt

Experimento Completo: Defensor vs. Atacante

1. Ejecute ./start.sh desde el directorio raíz del proyecto — restablece el código fuente de crapi-fork/ desde crapi-original/, reconstruye todos los servicios, planta banderas y honeypots.
2. Ejecute el defensor: python3 -m harness.main --app-url http://localhost:8888 -v.
3. Comience a realizar pruebas de penetración en el sitio web en localhost:8888 (la descripción del desafío está en localhost:8888/challenge). Si realiza pruebas de penetración usando un agente de IA, el agente no debe tener acceso a los procesos internos de Docker, ya que esto se consideraría trampa.
4. Mientras realiza las pruebas, monitoree el panel del defensor en localhost:3000 para ver registros en tiempo real, acciones de los agentes, parches, banderas capturadas, etc.
5. Una vez finalizada la sesión, ejecute docker compose down -v para eliminar los contenedores Docker y las bases de datos que se iniciaron para este proyecto.

Panel de Control

Panel de control: http://localhost:3000

Una barra de estado global de agentes es visible en todas las pestañas, mostrando la salud del agente (activo/colgado/inactivo/error) con controles de escalado.

Registros

Visor de registros de solicitudes de producción/sombra en pantalla dividida en tiempo real con entradas coloreadas por severidad y agrupación de tráfico

Agentes

Feed de actividad por agente con indicaciones del sistema, llamadas a herramientas y etiquetas de modelo LLM

Pipeline

Tablero Kanban: Detectado → Reparando → Revisando → Desplegado, con panel de detalle redimensionable

Parches

Diffs de código, archivos modificados, comandos de reversión y línea de tiempo por parche

Configuración del LLM

El sistema utiliza cualquier API compatible con OpenAI. Configure los modelos en config/llm.yaml:

Para cambiar de proveedor, modifique provider y model, luego establezca la clave API correspondiente en harness/.env:

Proveedores compatibles: OpenAI, Gemini, Anthropic, Groq, Together, Ollama, Mistral, DeepSeek, Fireworks, xAI, Perplexity, OpenRouter, Zhipu. Agregue proveedores personalizados añadiendo su URL base a la sección providers en el YAML.

Nota: Solo unos pocos proveedores de API tienen un límite de tasa lo suficientemente alto como para soportar 3 o más agentes trabajando simultáneamente. Google Gemini es uno de ellos.

Stack Tecnológico

• LLMs: Cualquier API compatible con OpenAI (por defecto: Gemini 3 Flash Preview para agentes, Gemini 2.5 Flash para analizador)
• App Objetivo: crAPI modificado (Python/Django, Java/Spring Boot, Go, MongoDB, PostgreSQL)
• Enrutamiento: nginx con scripting Lua para redirección transparente de sesiones
• Puntuación: Puntuación de amenazas respaldada por Redis a través del plano de control FastAPI
• Panel de Control: React + Tailwind CSS, servido por FastAPI con WebSocket para actualizaciones en vivo
• Orquestación: Python asyncio con coordinación de agentes basada en colas

Agradecimientos Especiales

Agradecimientos especiales a d3lta05 (LinkedIn) y aleemladha por su ayuda con las pruebas de penetración.