Ludus
Un servidor del Protocolo de Contexto de Modelo (MCP) para automatizar entornos de ciberrango Ludus v1 y v2 a través de asistentes de IA. Más de 190 herramientas para gestión de rangos, planos, grupos, plantillas, escenarios e integración con SIEM.
Documentación
Ludus FastMCP
Un servidor de Model Context Protocol (MCP) para automatizar entornos de cyber range de Ludus mediante asistentes de IA escritos en Python.
Descripción general
Ludus FastMCP permite la gestión impulsada por IA de cyber ranges de Ludus mediante comandos en lenguaje natural. El servidor expone 231 herramientas en 23 módulos para la gestión del ciclo de vida del range, despliegue de escenarios, creación de plantillas, gestión de roles de Ansible e integración con monitoreo de seguridad.
Requiere Ludus 2.0 o posterior. Esta versión está dirigida únicamente a la API de Ludus 2.x, que es la que hace disponibles blueprints, grupos, fuentes de contenido, acceso a consola de VM, cuotas y diagnósticos. Se eliminó el soporte para la API de Ludus 1.x; fija ludus-fastmcp a una versión 1.x si aún ejecutas un servidor Ludus 1.x.
El cliente cubre cada endpoint de la API de Ludus, validado contra un servidor Ludus 2.3.0 en vivo.
Capacidades clave
| Categoría | Descripción |
|---|---|
| Gestión de Ranges | Crear, configurar, desplegar y gestionar entornos de laboratorio virtual |
| Blueprints | Crear, exportar, importar, compartir y aplicar configuraciones de range reutilizables |
| Fuentes de Contenido | Añadir catálogos git o archivo de plantillas, roles y laboratorios preconstruidos como GOAD |
| Grupos | Organizar usuarios y ranges con control de acceso basado en grupos |
| Despliegue de Escenarios | Escenarios preconstruidos para AD, equipos rojo/azul/morado y análisis de malware |
| Constructor de Plantillas | Plantillas de SO personalizadas, configuraciones esqueleto y generación de YAML |
| Gestión de Roles | Integración con Ansible Galaxy, roles personalizados, roles de suscripción y control de alcance |
| Integración SIEM | Soporte para Wazuh, Splunk, Elastic Stack y Security Onion |
| Configuración de IA | Conversión de lenguaje natural a configuración YAML |
| Diagnósticos | Salud del sistema, información de licencia, historial de registros de despliegue y herramientas de migración |
| Cuotas y Límites | Cuotas de recursos por usuario y por grupo, más apagado automático de ranges (plugin) |
Plataformas compatibles
Funciona con cualquier cliente compatible con MCP, incluyendo Claude Desktop, VS Code (Cline), OpenWebUI y AnythingLLM.
Inicio rápido
Requisitos
- Python 3.11+
- FastMCP 3.x (se instala automáticamente)
- Un servidor Ludus ejecutando 2.0 o posterior
- Clave de API de Ludus, o un token JWT para despliegues Pro/SSO
Instalación
# Using pipx (recommended)
pipx install git+https://github.com/tjnull/Ludus-FastMCP
# From source
git clone https://github.com/tjnull/Ludus-FastMCP
cd Ludus-FastMCP
pip install -e .
Configuración
Ejecuta el asistente de configuración interactivo:
ludus-fastmcp --setup
El asistente configura las credenciales de API, prueba la conectividad y genera archivos de configuración del cliente MCP.
Para opciones de configuración manual, consulta la Guía de Configuración.
Uso
Servidor MCP (ludus-fastmcp)
ludus-fastmcp --setup # Interactive setup wizard
ludus-fastmcp --list-tools # List all 231 available tools
ludus-fastmcp --version # Display version information
ludus-fastmcp # Start MCP server
ludus-fastmcp --daemon # Run as background service
CLI de cliente (ludus-ai)
ludus-ai setup-llm # Configure local LLM (Ollama)
ludus-ai install anythingllm # Install AnythingLLM interface
ludus-ai tool list-tools # List available tools
ludus-ai tool call-tool <name> # Execute tools directly
Ejemplos de interacción
Una vez conectado a un cliente MCP, interactúa con tu entorno Ludus:
Show my current range status
Deploy an Active Directory lab with Wazuh monitoring
Create a snapshot named "pre-attack" for all VMs
Build a lab with 2 domain controllers and 5 workstations
Create a blueprint from my current range and share it with the red-team group
Show system diagnostics and storage usage
List all groups and their members
Ejemplos de uso de Ludus-FastMCP con grok code a través de Opencode.
Documentación
| Documento | Descripción |
|---|---|
| Primeros Pasos | Instalación, configuración y primer despliegue |
| Configuración | Variables de entorno y configuración del cliente MCP |
| Referencia de Herramientas | Documentación completa de las 231 herramientas |
| Escenarios | Escenarios de despliegue preconstruidos |
| Solución de Problemas | Problemas comunes y soluciones |
| Seguridad | Funciones de seguridad y mejores prácticas |
Requisitos del servidor Ludus
Esta versión habla únicamente la API de Ludus 2.x. Cada solicitud va a /api/v2;
no queda ninguna ruta de código v1 a la que recurrir.
En la primera llamada, el cliente solicita al servidor su versión y se niega a continuar si no responde como un servidor 2.x, de modo que un desajuste aparece una vez, al inicio, en lugar de como un 404 desconcertante de la herramienta que hayas ejecutado:
https://ludus.example:8080 does not serve the Ludus 2.x API
(GET /api/v2/ returned HTTP 404). This release requires Ludus 2.0 or later;
upgrade the server, or pin ludus-fastmcp to a 1.x release for a Ludus 1.x server.
Establece LUDUS_API_VERSION=v2 para afirmar la versión tú mismo y omitir esa comprobación
(ahorra una solicitud por sesión). LUDUS_API_VERSION=v1 se rechaza al
inicio en lugar de ignorarse silenciosamente.
¿Aún en Ludus 1.x?
Fija una versión anterior:
pipx install "git+https://github.com/tjnull/Ludus-FastMCP@v1.0.0"
Actualizar el servidor es el mejor camino: blueprints, fuentes de contenido, grupos, cuotas, historial de registros de despliegue y acceso a consola de VM no existen en absoluto en la API 1.x.
Funciones limitadas por plugins
Algunas capacidades de Ludus se distribuyen como plugins del servidor que pueden no estar cargados en una instalación determinada. Cuotas y apagado automático son los ejemplos comunes. Cuando un plugin está ausente, la API de Ludus responde con HTTP 404 incluso si la solicitud era correcta.
En lugar de informar eso como un endpoint faltante, esas herramientas devuelven un resultado claro para que un asistente de IA no vaya buscando un error inexistente:
{
"available": false,
"feature": "Quotas",
"error": "Quotas is not available on this Ludus server.",
"reason": "This capability is provided by a Ludus plugin that is not loaded on the server.",
"hint": "The request was well-formed. Do not retry or try alternative endpoints."
}
Los endpoints que un servidor no implementa en absoluto (HTTP 501, como /range/sshconfig
en algunas compilaciones) se informan de la misma manera, con una nota explícita de que reintentar
no ayudará.
Recursos
| Recurso | Enlace |
|---|---|
| Documentación de Ludus | docs.ludus.cloud |
| Referencia de API de Ludus | api-docs.ludus.cloud |
| Ludus GitHub | github.com/badsectorlabs/ludus |
| Framework FastMCP | gofastmcp.com |
| Especificación MCP | modelcontextprotocol.io |
Soporte
- GitHub Issues - Informes de errores y solicitudes de funciones
- GitHub Discussions - Preguntas y discusión comunitaria
Licencia
Este proyecto está licenciado bajo la Licencia MIT. Consulta LICENSE para más detalles.
Aviso legal
Este software está destinado a pruebas de seguridad autorizadas, fines educativos e investigación en entornos controlados. Los usuarios son responsables del cumplimiento de las leyes aplicables y las políticas organizacionales. Los autores no ofrecen garantías y no asumen responsabilidad por el uso o mal uso de este software.