CyberEdu MCP Server

Este é o servidor oficial do Model Context Protocol (MCP) para a plataforma CyberEdu CTF (cyber-edu.co / cyberedu.ro)

GitHub
8
Experimente este MCPPatrocinado

Documentação

Servidor MCP CyberEdu

Este é o servidor oficial do Model Context Protocol (MCP) para a plataforma CTF CyberEdu (https://cyber-edu.co / https://cyberedu.ro). Este servidor descobre e expõe automaticamente todos os métodos do CyberEduClient como ferramentas MCP, facilitando a interação com a plataforma CyberEdu por meio de clientes compatíveis com MCP.

Recursos

  • Descoberta Dinâmica de Ferramentas: Descobre automaticamente todos os métodos públicos do CyberEduClient e os expõe como ferramentas MCP
  • Zero Configuração para Novos Métodos: Quando novos métodos são adicionados ao CyberEduClient, eles se tornam automaticamente disponíveis como ferramentas MCP sem qualquer alteração de código
  • Type-Safe: Gera automaticamente esquemas JSON a partir de assinaturas de métodos e dicas de tipo
  • Tratamento de Erros: Tratamento abrangente de erros com mensagens de erro detalhadas

Visão Geral da Plataforma CyberEDU

A CyberEDU é uma plataforma de treinamento em segurança cibernética que oferece laboratórios práticos, simulações realistas e ambientes competitivos. É projetada para equipes de segurança empresarial, instituições acadêmicas, agências governamentais e aprendizes individuais.

Descrição Principal

A CyberEDU é uma plataforma abrangente de treinamento em segurança cibernética que oferece laboratórios práticos, simulações realistas e ambientes competitivos. É projetada para equipes de segurança empresarial, instituições acadêmicas, agências governamentais e aprendizes individuais que desejam desenvolver habilidades práticas de segurança cibernética por meio de cenários do mundo real.

Principais Diferenciais

  • Abordagem prática: Cyber ranges interativos onde os usuários atacam e defendem infraestrutura real (não apenas vídeos ou teoria)
  • Mapeamento MITRE ATT&CK: Cenários mapeados para MITRE ATT&CK, usando amostras reais de malware (contidas com segurança)
  • Melhor retenção: Retenção de habilidades 3,5x melhor em comparação ao aprendizado passivo
  • Cenários do mundo real: Simula técnicas reais de adversários e padrões de ataque

Componentes da Plataforma

  1. Cyber Range — Simulação de guerra cibernética em escala empresarial com topologias de rede complexas
  2. Cyber Labs — Mais de 650 laboratórios práticos mapeados para MITRE ATT&CK, baseados em navegador e com correção automática
  3. Tournament Suite — Competições gamificadas (CTFs, Red vs Blue, war games)

Estatísticas Principais

  • Mais de 30.000 usuários ativos em todo o mundo
  • Mais de 650 laboratórios práticos
  • Mais de 1.400 perfis de simulação
  • Mais de 500 eventos hospedados
  • Atendimento a mais de 45 países
  • Mais de 250 horas de conteúdo de treinamento

Públicos-Alvo

  • Estudantes: Treinamento focado em carreira com desafios CTF e rankings
  • Academia: Currículo com integração LMS e correção automática
  • Empresas: Avaliações técnicas de contratação, treinamento de equipes, mapeamento de conformidade
  • Governo: Implantações air-gapped, simulação OT/SCADA, defesa de infraestrutura crítica

Opções de Implantação

  • SaaS hospedado em nuvem (baseado em navegador, sem instalação)
  • On-premise (VMware, Proxmox, bare-metal)
  • Implantações air-gapped para ambientes classificados

Instalação

Clonar o Repositório

O cyberedu-client está incluído como um submódulo git. Clone com --recursive para obter tudo:

git clone --recursive https://github.com/CyberEDU-Cyber-Range/cyberedu-mcp.git
cd cyberedu-mcp

Se você já clonou sem --recursive, inicialize o submódulo:

git submodule update --init --recursive

Instalar Pacotes

Instale ambos os pacotes (cliente e servidor MCP):

macOS/Linux:

python3 -m venv venv  
source venv/bin/activate
pip install -e ".[local]"      # Installs with local cyberedu-client submodule
# Or for development:
# pip install -e ".[local,dev]"

Windows (PowerShell):

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -e ".[local]"      # Installs with local cyberedu-client submodule

Windows (Prompt de Comando):

python -m venv venv
venv\Scripts\activate.bat
pip install -e ".[local]"

Alternativa: Instale os pacotes separadamente:

pip install -e ./cyberedu-client
pip install -e .

Configuração

Persistência de Sessão (Recomendado)

O servidor MCP persiste automaticamente as credenciais de sessão em disco. Isso significa:

  • Defina seu cookie uma vez usando a ferramenta cyberedu_set_session_cookie, e ele será lembrado entre sessões MCP
  • Nenhuma variável de ambiente necessária após a primeira autenticação
  • A seleção de tenant é preservada quando você alterna de tenant

Localização do arquivo de sessão:

  • macOS/Linux: ~/.cyberedu-mcp/session.json
  • Windows: %USERPROFILE%\.cyberedu-mcp\session.json (por exemplo, C:\Users\YourName\.cyberedu-mcp\session.json)

O arquivo tem permissões restritas (somente leitura/gravação do proprietário) por segurança em sistemas Unix.

Variáveis de Ambiente (Alternativa)

Você também pode usar variáveis de ambiente. O servidor carrega as credenciais nesta ordem de prioridade:

  1. Credenciais persistidas em disco (maior prioridade)
  2. Variáveis de ambiente
  3. Padrões

Variáveis de ambiente:

  • CYBEREDU_SESSION_COOKIE: Seu cookie de sessão CyberEdu
    • Obtenha isso nas ferramentas de desenvolvedor do seu navegador após fazer login em https://app.cyber-edu.co
    • Procure pelo valor do cookie cyberedu_session
  • CYBEREDU_TENANT: Seu identificador de tenant (opcional, padrão "cyberedu")

Obtendo Seu Cookie de Sessão

Chrome/Edge:

  1. Abra as Ferramentas de Desenvolvedor (F12)
  2. Vá para a aba Application/Storage
  3. Navegue até Cookies → https://app.cyber-edu.co
  4. Encontre cyberedu_session e copie seu valor

Firefox:

  1. Abra as Ferramentas de Desenvolvedor (F12)
  2. Vá para a aba Storage
  3. Navegue até Cookies → https://app.cyber-edu.co
  4. Encontre cyberedu_session e copie seu valor

Uso

Executando o Servidor MCP

O servidor pode ser executado diretamente (para testes):

macOS/Linux:

python3 -m venv venv

source venv/bin/activate
python -m cyberedu_mcp

Windows:

python -m venv venv
.\venv\Scripts\Activate.ps1
python -m cyberedu_mcp

Configuração do Cliente MCP

Para usar este servidor com um cliente MCP (Cursor IDE ou Claude Desktop), adicione-o à sua configuração MCP.

Importante: Use o caminho completo para o executável Python no seu venv. Os clientes MCP executam servidores externamente e não terão acesso a um ambiente virtual ativado.

Exemplos macOS/Linux

Cursor IDE (~/.cursor/mcp.json):

{
  "mcpServers": {
    "cyberedu": {
      "command": "/path/to/cyberedu-mcp/venv/bin/python3",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "cyberedu": {
      "command": "/path/to/cyberedu-mcp/venv/bin/python3",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Exemplos Windows

Cursor IDE (%APPDATA%\Cursor\User\mcp.json ou C:\Users\YourName\.cursor\mcp.json):

{
  "mcpServers": {
    "cyberedu": {
      "command": "C:\\path\\to\\cyberedu-mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "cyberedu": {
      "command": "C:\\path\\to\\cyberedu-mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Exemplos Multiplataforma

VS Code (.vscode/mcp.json no seu workspace):

{
  "servers": {
    "cyberedu": {
      "type": "stdio",
      "command": "/path/to/cyberedu-mcp/venv/bin/python3",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Windows: Use C:\\path\\to\\cyberedu-mcp\\venv\\Scripts\\python.exe

Antigravity / Windsurf (mcp_config.json - acesse via loja MCP → Gerenciar Servidores MCP → Ver configuração bruta):

{
  "mcpServers": {
    "cyberedu": {
      "command": "/path/to/cyberedu-mcp/venv/bin/python3",
      "args": ["-m", "cyberedu_mcp"],
      "env": {}
    }
  }
}

Windows: Use C:\\path\\to\\cyberedu-mcp\\venv\\Scripts\\python.exe

Nota: As credenciais de sessão são persistidas em ~/.cyberedu-mcp/session.json, portanto, nenhuma variável de ambiente é necessária após a primeira autenticação via ferramenta cyberedu_set_session_cookie.

Ferramentas Disponíveis

O servidor expõe automaticamente todos os métodos públicos do CyberEduClient como ferramentas MCP. As ferramentas são prefixadas com cyberedu_ para evitar conflitos de nomenclatura.

Ferramentas de Gerenciamento de Sessão

Estas ferramentas permitem gerenciar autenticação e alternância de tenant sem reiniciar o servidor MCP. As credenciais são persistidas automaticamente em ~/.cyberedu-mcp/session.json:

  • cyberedu_get_session_status - Verifica se está autenticado, qual tenant está selecionado e se as credenciais estão persistidas
  • cyberedu_set_session_cookie - Define/atualiza o cookie de sessão para autenticação (persiste em disco)
  • cyberedu_switch_tenant - Alterna para um tenant/organização diferente (persiste em disco)
  • cyberedu_clear_session - Limpa as credenciais armazenadas do disco e da memória

Exemplo de uso:

  1. Verificar status: "Qual é o status da minha sessão CyberEdu?"
  2. Definir cookie: "Defina meu cookie de sessão CyberEdu para eyJ..." (necessário apenas uma vez, persiste!)
  3. Alternar tenant: "Alternar para o tenant myorg"
  4. Limpar credenciais: "Limpar minha sessão CyberEdu"

Ferramentas de Autenticação e Usuário

  • cyberedu_check_auth - Verifica autenticação e obtém informações do usuário
  • cyberedu_get_user_info - Obtém informações completas do usuário
  • cyberedu_list_tenants - Lista todos os tenants disponíveis
  • cyberedu_get_current_tenant_info - Obtém informações do tenant atual
  • cyberedu_get_user - Obtém informações do usuário por ID

Ferramentas de Desafios (Arquivo)

  • cyberedu_list_challenges - Lista todos os desafios (com filtros opcionais)
  • cyberedu_get_challenge - Obtém detalhes do desafio
  • cyberedu_get_challenge_difficulties - Obtém níveis de dificuldade disponíveis
  • cyberedu_get_challenge_tags - Obtém tags de desafio disponíveis
  • cyberedu_subscribe_to_challenge - Inscreve-se em um desafio

Ferramentas de Flag e Submissão (Arquivo)

  • cyberedu_get_flag - Obtém informações de flag/pergunta
  • cyberedu_submit_flag - Submete uma flag/resposta

Ferramentas de Arquivo (Arquivo)

  • cyberedu_download_file - Baixa um arquivo de desafio (use o parâmetro opcional save_path para salvar diretamente em disco)

Ferramentas de Serviço (Arquivo)

  • cyberedu_start_service - Inicia um serviço de desafio
  • cyberedu_get_service_status - Obtém status do serviço
  • cyberedu_extend_service - Estende o tempo do serviço
  • cyberedu_restart_service - Reinicia o serviço

Ferramentas de Competições

  • cyberedu_list_contests - Lista todas as competições disponíveis
  • cyberedu_get_contest - Obtém detalhes da competição
  • cyberedu_get_contest_ranks - Obtém o ranking da competição
  • cyberedu_get_contest_challenge - Obtém detalhes do desafio dentro de uma competição
  • cyberedu_subscribe_to_contest_challenge - Inscreve-se em um desafio de competição

Ferramentas de Flag e Submissão de Competições

  • cyberedu_get_contest_flag - Obtém informações de flag dentro de uma competição
  • cyberedu_submit_contest_flag - Submete uma flag dentro de uma competição

Ferramentas de Arquivo de Competições

  • cyberedu_download_contest_file - Baixa um arquivo de um desafio de competição (use o parâmetro opcional save_path para salvar diretamente em disco)

Ferramentas de Serviço de Competições

  • cyberedu_start_contest_service - Inicia um serviço dentro de uma competição
  • cyberedu_get_contest_service_status - Obtém status do serviço dentro de uma competição
  • cyberedu_extend_contest_service - Estende o tempo do serviço dentro de uma competição
  • cyberedu_restart_contest_service - Reinicia o serviço dentro de uma competição

Exemplos de Uso e Prompts

Exemplos de prompts para interagir com o servidor MCP CyberEdu:

Sessão e Autenticação

"Check my CyberEdu session status"
"Set my CyberEdu session cookie to eyJpdiI6Ik..."
"Switch to tenant 'mycompany'"

Desafios (Arquivo)

"List all web security challenges"
"Show me the easiest challenges from tenant unbreakable/rocsc"
"Show me hard difficulty forensics challenges"
"Get details for challenge abc123"
"Subscribe me to this challenge and start the service"
"Download challenge files to ./downloads/"
"Submit flag 'CTF{i-like-web-security-ctf-challenges}' for this challenge"

Competições

"List available CTF contests"
"Show leaderboard for contest 'defcamp ctf quals 2025'"
"Get challenge abc123 from contest 'rocsc26-quals'"
"Start service for this contest challenge"
"Submit flag 'FLAG{solved}' for contest challenge"

Exemplo de Fluxo de Trabalho

1. "List easy web challenges from tenant rocsc"
2. "Subscribe to 'why-xor' and start the service"
3. "Download the challenge files"
4. [Solve...]
5. "Submit flag 'CTF{xor-is-not-safe}'"

Arquitetura

Descoberta Dinâmica de Ferramentas

O servidor usa o módulo inspect do Python para descobrir automaticamente todos os métodos públicos da classe CyberEduClient. Para cada método:

  1. Descoberta de Método: Escaneia a classe em busca de métodos públicos (excluindo métodos privados e auxiliares)
  2. Geração de Esquema: Gera automaticamente esquema JSON a partir de assinaturas de métodos e dicas de tipo
  3. Registro de Ferramenta: Registra cada método como uma ferramenta MCP com metadados apropriados

Registro de Ferramentas

A classe ToolRegistry fornece um sistema flexível para gerenciar ferramentas:

  • Descoberta Automática: Descobre métodos de classes usando introspecção
  • Registro Manual: Permite registro manual de métodos personalizados
  • Organização por Categoria: Categoriza automaticamente métodos (auth, desafios, competições, serviços, etc.)

Extensibilidade

Para adicionar nova funcionalidade:

  1. Adicione métodos ao CyberEduClient: Basta adicionar novos métodos públicos à classe CyberEduClient
  2. Exposição Automática: O servidor MCP descobrirá e exporá automaticamente os novos métodos
  3. Sem Alterações no Código MCP: Nenhuma alteração necessária no código do servidor MCP

Para ferramentas personalizadas que não mapeiam diretamente para métodos do cliente:

from cyberedu_mcp.tool_registry import ToolRegistry

registry = ToolRegistry()

def custom_tool(param1: str, param2: int) -> dict:
    """Custom tool description."""
    return {"result": f"{param1}: {param2}"}

registry.register_method(
    name="custom_tool",
    method=custom_tool,
    description="A custom tool",
    category="custom"
)

Tratamento de Erros

O servidor fornece tratamento abrangente de erros:

  • Erros HTTP: Retorna informações detalhadas de erro HTTP, incluindo códigos de status e corpos de resposta
  • Erros de Validação: Retorna mensagens de erro claras para parâmetros ausentes ou inválidos
  • Erros do Cliente: Retorna informações de erro estruturadas para todas as exceções

Documentação

Documentação adicional está disponível na pasta docs/:

  • docs/index.md - Visão geral da documentação e referência rápida
  • docs/architecture.md - Design do servidor, descoberta de ferramentas e gerenciamento de sessão
  • docs/extending.md - Como adicionar ferramentas personalizadas e modificar o comportamento

Licença

MIT