SOAR MCP Server

Сервер Model Context Protocol (MCP) на базе платформы OctoMation SOAR, предоставляющий возможности оркестрации безопасности, автоматизации и реагирования для AI-клиентов, таких как Claude Desktop, Cherry Studio, Cursor, Trae и других.

Функциональные возможности • Быстрый старт • Журнал изменений • Обновление с предыдущих версий • Инструменты управления • Конфигурация • Функции безопасности • Устранение неполадок

Обзор

SOAR MCP Server — это инновационное решение для интеграции платформы оркестрации безопасности, разработанное специально для платформы OctoMation SOAR. С помощью протокола Model Context Protocol возможности SOAR (Security Orchestration, Automation and Response) напрямую интегрируются в различные AI-клиенты, включая Claude Desktop, Cherry Studio, Cursor, Trae и другие. Сервер предоставляет полный набор функций для управления инцидентами безопасности, выполнения сценариев (playbooks), запросов к данным киберразведки и многого другого, наделяя AI-ассистентов профессиональными навыками реагирования на киберугрозы.

🆕 Краткий обзор обновлений v1.6.0

• Извлечение ключевых результатов: Добавлены ключевые слова для имен узлов действий сценария, что позволяет извлекать ключевые узлы и результаты по активам из результатов выполнения сценария.

• Семантическое разделение результатов: Добавлены query_playbook_execution_overview_by_activity_id и query_playbook_execution_key_results_by_activity_id.

• Управление обновлениями: Добавлен скрипт ручной миграции migrate_db.py, в README добавлены риски и шаги по обновлению.

• Видимость версии: Текущая версия отображается в заголовке панели управления, на странице статистики и в футере для удобства проверки пользователем.

Полный список изменений см. в CHANGELOG.md.

🏗️ Системная архитектура

SOAR MCP Server использует архитектуру с двумя серверами, включающую MCP-сервер, веб-сервер управления, уровень бизнес-логики, уровень хранения данных и уровень интеграции с внешними системами, предоставляя комплексное решение для автоматизации оркестрации безопасности.

Ключевые аспекты технической архитектуры

🎯 Платформа OctoMation SOAR

Данный проект разработан специально для платформы OctoMation SOAR. OctoMation — это мощная платформа для оркестрации, автоматизации и реагирования, предоставляющая:

• 🛡️ Полный стек инструментов безопасности: Поддержка основных продуктов и платформ безопасности.

• 📚 Богатая библиотека сценариев: Предустановлено множество практических сценариев реагирования на инциденты.

• 🔄 Гибкие рабочие процессы: Визуальное проектирование сценариев и автоматизированное выполнение.

• 🌐 Открытая архитектура: Поддержка пользовательских интеграций и расширений.

Ключевые преимущества

• 🔒 Оркестрация безопасности: Бесшовная интеграция с платформой OctoMation SOAR.

• 🤖 AI-ориентированность: Интеллектуальное реагирование на инциденты через различные AI-клиенты.

• ⚡ Асинхронная архитектура: Полностью асинхронные функции MCP-инструментов, повторное использование пула соединений httpx.

• 🌐 Веб-управление: Интуитивно понятный визуальный интерфейс управления.

• 🔧 Гибкая конфигурация: Поддержка различных способов развертывания и настройки.

• 🛡️ Усиленная безопасность: Хеширование паролей bcrypt, сохранение ключей JWT, маскирование данных в логах.

Функциональные возможности

🛠️ Набор инструментов MCP

Полный набор инструментов, предоставляемый SOAR MCP Server

Запрос и выполнение сценариев

• list_playbooks_quick - Получение краткого списка сценариев (ID, имя, отображаемое имя), подходит для быстрого понимания опций сценариев AI.

• query_playbook_execution_params - Запрос определений параметров, необходимых для выполнения, по ID сценария.

• execute_playbook - Выполнение указанного сценария SOAR, поддержка передачи параметров (асинхронно).

• query_playbook_execution_status_by_activity_id - Запрос статуса выполнения сценария по ID активности (асинхронно).

• query_playbook_execution_overview_by_activity_id - Запрос общих результатов выполнения сценария по ID активности (асинхронно).

• query_playbook_execution_key_results_by_activity_id - Запрос ключевых результатов выполнения сценария по ID активности (асинхронно).

Важные примечания

• Формат ID сценария: Поддерживается тип LONG (64-битное целое число), можно использовать как целое число, так и строку.

• Процесс выполнения: Запрос параметров → Выполнение сценария → Проверка статуса → Запрос общих результатов / Запрос ключевых результатов.

• Совместимость: ID сценария может выходить за пределы диапазона безопасных целых чисел JavaScript, рекомендуется использовать строковый формат.

• Извлечение ключевых результатов: query_playbook_execution_key_results_by_activity_id не требует передачи дополнительных ключевых слов; ключевые слова берутся из конфигурации сценария в панели управления.

📊 Ресурсы MCP

• soar://playbooks - Список сценариев SOAR.

• soar://applications - Список приложений SOAR.

• soar://executions - Журнал записей активности выполнения.

🌐 Веб-интерфейс управления

Веб-интерфейс управления SOAR MCP Server - страница управления сценариями

• Управление сценариями: Визуальный список сценариев, управление статусами, мониторинг выполнения.

• Управление токенами: Создание, управление и мониторинг учетных данных для доступа к API.

• Системная конфигурация: Настройки подключения к SOAR, конфигурация синхронизации, переключатель проверки SSL.

• Управление паролями: Отдельный вход для смены пароля администратора и описание политики безопасности.

• Статистика: Статус системы, статистика выполнения, время синхронизации.

Конфигурация извлечения ключевых результатов

В деталях сценария в панели управления можно настроить «Ключевые слова имен узлов действий сценария» для каждого сценария:

• Поддерживается ввод нескольких ключевых слов через Enter, запятую (английскую , или китайскую ，).

• Между несколькими ключевыми словами действует логика «ИЛИ».

• Система будет сопоставлять эти ключевые слова с nodeResultModels.displayName в результатах выполнения сценария.

• При совпадении будут возвращены эти узлы и соответствующие им assetResultModels.

Подсказка: Для более стабильного извлечения ключевых результатов рекомендуется добавлять эти ключевые слова непосредственно в отображаемые имена узлов сценария в SOAR, например: [Киберразведка] Запрос IP, [Изоляция] Обработка группы безопасности облачного хоста.

Отображение и точка настройки «Ключевых слов имен узлов действий сценария» в панели управления

🚀 Быстрый старт

Это руководство поможет вам развернуть и настроить SOAR MCP Server с нуля.

📋 Системные требования

Системные требования:

• Python 3.9+

• 4 ГБ+ оперативной памяти

• Сетевое подключение (для доступа к API SOAR)

Поддерживаемые платформы:

• Linux (Ubuntu 18.04+, CentOS 7+)

• macOS (10.14+)

• Windows 10/11

🛠️ Шаг 1: Развертывание проекта

Вы можете выбрать нативное развертывание, развертывание через Docker или автономную упаковку для релиза в зависимости от ваших потребностей.

Вариант 1: Нативное развертывание Python (рекомендуется для среды разработки)

1. Получение кода проекта

# 克隆项目
git clone https://github.com/flagify-com/soar-mcp.git
cd soar-mcp

# 或直接下载发布版本
wget https://github.com/flagify-com/soar-mcp/releases/latest/download/soar-mcp.zip
unzip soar-mcp.zip && cd soar-mcp

2. Настройка окружения

# 创建 Python 虚拟环境
python3 -m venv venv

# 激活虚拟环境
# Linux/macOS:
source venv/bin/activate
# Windows:
# venv\Scripts\activate

# 升级 pip 并安装依赖
pip install --upgrade pip
pip install -r requirements.txt

3. Первый запуск

# 直接启动服务器
python3 soar_mcp_server.py

🎉 Поздравляем! Сервер запущен

При первом запуске система автоматически:

• ✅ Создаст базу данных и начальную конфигурацию.

• ✅ Сгенерирует пароль администратора (отображается в консоли только один раз, не записывается в лог-файл).

• ✅ Сгенерирует и сохранит ключ подписи JWT.

• ✅ Запустит MCP-сервер и веб-интерфейс управления.

• ⚠️ Пропустит синхронизацию сценариев SOAR (требуется последующая настройка).

Важные выходные данные:

============================================================
  🔑 管理员初始密码: a$bC9*xYz2M&
  ⚠️  请妥善保管，此密码不会再次显示！
============================================================

📊 MCP服务: http://127.0.0.1:12345/mcp
   认证方式1: Authorization: Bearer <token> (推荐)
   认证方式2: http://127.0.0.1:12345/mcp?token=<token> (兼容)
🎛️  管理后台: http://127.0.0.1:12346/admin

⚠️ Совет по безопасности: Пароль администратора отображается в консоли только при первом запуске и не записывается в лог-файл. Обязательно сохраните его. Если он утерян, его можно сбросить с помощью ./reset_admin_password.sh.

🔐 Рекомендация по запуску: После первого входа в панель управления немедленно перейдите на страницу «Управление паролями» в навигационной панели, чтобы сменить пароль администратора, прежде чем приступать к инициализации платформы SOAR.

Интерфейс консоли после запуска SOAR MCP Server

Вариант 2: Развертывание в контейнере Docker (рекомендуется для серверной среды)

Проект содержит Dockerfile и docker-compose.yml, что значительно упрощает процесс развертывания.

1. Сборка и запуск сервиса в фоновом режиме:

   # 为避免卷挂载时 sqlite db 尚未生成而被 Docker 误创建为空目录，请先进行本地文件预占位
   mkdir -p logs && touch soar_mcp.db
   
   # 一键构建镜像并启动
   docker-compose up -d --build

2. Просмотр логов для получения начального пароля:

   # 强烈建议在此步查看日志，获取管理员初始随机密码
   docker-compose logs -f soar-mcp-server

Вариант 3: Автономная упаковка и удаленное развертывание в один клик

Если вам нужно перенести протестированный сервис на сервер во внутренней сети без доступа к интернету, вы можете использовать встроенные инструменты экспорта кода и образов для полной автоматизации переноса:

1. Выполните «упаковку» на машине разработки или сервере-трамплине, где можно собрать образ:

   # 此脚本会自动归档最新构建的 Docker 镜像和挂载目录，生成完全离线可用的发布包
   ./export_release.sh
   # 构建完成后当前目录将生成：soar-mcp-release.tar.gz

2. Перенесите упакованный soar-mcp-release.tar.gz на целевой сервер во внутренней сети и распакуйте для использования:

   tar -xzvf soar-mcp-release.tar.gz
   cd soar-mcp-release
   
   # 执行自动化一键部署脚本（已自带 docker load 镜像加载逻辑）
   ./install.sh

⚙️ Шаг 2: Конфигурация платформы SOAR

1. Доступ к панели управления

1. Откройте браузер и перейдите по адресу http://127.0.0.1:12346/admin.

2. Войдите, используя пароль администратора, отображенный в консоли.

3. Если SOAR не настроен, система автоматически перейдет в «Системную конфигурацию» и покажет руководство по первой настройке.

2. Настройка подключения к SOAR

Введите следующую информацию на странице системной конфигурации:

3. Тестирование и сохранение

1. Нажмите кнопку «Тест подключения» для проверки конфигурации.

2. После появления сообщения ✅ "API-подключение успешно!" нажмите «Сохранить конфигурацию».

3. Система автоматически начнет синхронизацию данных сценариев SOAR.

Примечание: Параметры подключения к SOAR теперь берутся из конфигурации базы данных; запущенный сервис больше не считывает API_URL, API_TOKEN, SSL_VERIFY из .env в качестве параметров времени выполнения.

🤖 Шаг 3: Конфигурация MCP-клиента

Поддерживаются различные MCP-клиенты на базе больших языковых моделей, включая, но не ограничиваясь: Cherry Studio, Claude Desktop, Cursor, Trae и другие.

Cherry Studio (рекомендуется)

Настройка SOAR MCP Server в Cherry Studio

1. Откройте Cherry Studio.

2. Перейдите в Настройки → MCP-серверы.

3. Отредактируйте файл конфигурации, добавив следующее содержимое:

   Способ 1: URL-параметры (хорошая совместимость)

   GXP