Ludus
Um servidor Model Context Protocol (MCP) para automatizar ambientes de cyber range Ludus v1 e v2 por meio de assistentes de IA. Mais de 190 ferramentas para gerenciamento de range, blueprints, grupos, templates, cenários e integração com SIEM.
Documentação
Ludus FastMCP
Um servidor Model Context Protocol (MCP) para automatizar ambientes de cyber range Ludus por meio de assistentes de IA escritos em Python.
Visão Geral
O Ludus FastMCP permite o gerenciamento de cyber ranges Ludus com auxílio de IA por meio de comandos em linguagem natural. O servidor expõe 231 ferramentas em 23 módulos para gerenciamento do ciclo de vida do range, implantação de cenários, criação de templates, gerenciamento de roles Ansible e integração com monitoramento de segurança.
Requer Ludus 2.0 ou posterior. Esta versão tem como alvo apenas a API do Ludus 2.x, que é o que disponibiliza blueprints, grupos, fontes de conteúdo, acesso ao console de VMs, cotas e diagnósticos. O suporte à API do Ludus 1.x foi removido; fixe o ludus-fastmcp em uma versão 1.x se você ainda executa um servidor Ludus 1.x.
O cliente cobre todos os endpoints da API Ludus, validados contra um servidor Ludus 2.3.0 ativo.
Principais Capacidades
| Categoria | Descrição |
|---|---|
| Gerenciamento de Range | Criar, configurar, implantar e gerenciar ambientes de laboratório virtual |
| Blueprints | Criar, exportar, importar, compartilhar e aplicar configurações de range reutilizáveis |
| Fontes de Conteúdo | Adicionar catálogos git ou arquivos de templates, roles e laboratórios pré-construídos como GOAD |
| Grupos | Organizar usuários e ranges com controle de acesso baseado em grupos |
| Implantação de Cenários | Cenários pré-construídos para AD, equipes red/blue/purple e análise de malware |
| Construtor de Templates | Templates de SO personalizados, configurações de esqueleto e geração de YAML |
| Gerenciamento de Roles | Integração com Ansible Galaxy, roles personalizadas, roles de assinatura e controle de escopo |
| Integração SIEM | Suporte a Wazuh, Splunk, Elastic Stack e Security Onion |
| Configuração de IA | Conversão de linguagem natural para configuração YAML |
| Diagnósticos | Saúde do sistema, informações de licença, histórico de logs de implantação e ferramentas de migração |
| Cotas e Limites | Cotas de recursos por usuário e por grupo, além de desligamento automático de range (plugin) |
Plataformas Suportadas
Funciona com qualquer cliente compatível com MCP, incluindo Claude Desktop, VS Code (Cline), OpenWebUI e AnythingLLM.
Início Rápido
Requisitos
- Python 3.11+
- FastMCP 3.x (instalado automaticamente)
- Um servidor Ludus executando 2.0 ou posterior
- Chave de API Ludus, ou um token JWT para implantações Pro/SSO
Instalação
# 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 .
Configuração
Execute o assistente de configuração interativo:
ludus-fastmcp --setup
O assistente configura as credenciais da API, testa a conectividade e gera arquivos de configuração do cliente MCP.
Para opções de configuração manual, consulte o Guia de Configuração.
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 do 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
Exemplos de Interação
Uma vez conectado a um cliente MCP, interaja com seu ambiente 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
Exemplos de uso do Ludus-FastMCP com grok code por meio do Opencode.
Documentação
| Documento | Descrição |
|---|---|
| Introdução | Instalação, configuração e primeira implantação |
| Configuração | Variáveis de ambiente e configuração do cliente MCP |
| Referência de Ferramentas | Documentação completa para todas as 231 ferramentas |
| Cenários | Cenários de implantação pré-construídos |
| Solução de Problemas | Problemas comuns e soluções |
| Segurança | Recursos de segurança e melhores práticas |
Requisitos do Servidor Ludus
Esta versão fala apenas com a API do Ludus 2.x. Cada requisição vai para /api/v2;
não há caminho de código v1 restante para o qual recorrer.
Na primeira chamada, o cliente pergunta ao servidor sua versão e se recusa a continuar se ele não responder como um servidor 2.x, então uma incompatibilidade aparece uma vez, logo no início, em vez de um 404 confuso de qualquer ferramenta que você tenha executado:
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.
Defina LUDUS_API_VERSION=v2 para afirmar a versão você mesmo e pular essa verificação
(isso economiza uma requisição por sessão). LUDUS_API_VERSION=v1 é rejeitado na
inicialização em vez de ser silenciosamente ignorado.
Ainda no Ludus 1.x?
Fixe uma versão mais antiga:
pipx install "git+https://github.com/tjnull/Ludus-FastMCP@v1.0.0"
Atualizar o servidor é o melhor caminho: blueprints, fontes de conteúdo, grupos, cotas, histórico de logs de implantação e acesso ao console de VMs não existem na API 1.x.
Recursos controlados por plugin
Alguns recursos do Ludus são fornecidos como plugins de servidor que podem não estar carregados em uma instalação específica. Cotas e desligamento automático são os exemplos comuns. Quando um plugin está ausente, a API Ludus responde com HTTP 404 mesmo que a requisição esteja correta.
Em vez de relatar isso como um endpoint ausente, essas ferramentas retornam um resultado claro para que um assistente de IA não saia procurando por um bug 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."
}
Endpoints que um servidor não implementa (HTTP 501, como /range/sshconfig
em algumas versões) são relatados da mesma forma, com uma nota explícita de que tentar
novamente não ajudará.
Recursos
| Recurso | Link |
|---|---|
| Documentação Ludus | docs.ludus.cloud |
| Referência da API Ludus | api-docs.ludus.cloud |
| Ludus GitHub | github.com/badsectorlabs/ludus |
| Framework FastMCP | gofastmcp.com |
| Especificação MCP | modelcontextprotocol.io |
Suporte
- GitHub Issues - Relatórios de bugs e solicitações de recursos
- GitHub Discussions - Perguntas e discussão da comunidade
Licença
Este projeto é licenciado sob a Licença MIT. Consulte LICENSE para detalhes.
Aviso Legal
Este software é destinado a testes de segurança autorizados, fins educacionais e pesquisa em ambientes controlados. Os usuários são responsáveis pela conformidade com as leis aplicáveis e políticas organizacionais. Os autores não oferecem garantias e não assumem responsabilidade pelo uso ou uso indevido deste software.