Servidor MCP de SOAR

Un servidor de Model Context Protocol (MCP) basado en la plataforma OctoMation SOAR, que proporciona capacidades de orquestación, automatización y respuesta de seguridad a clientes de IA como Claude Desktop, Cherry Studio, Cursor, Trae, entre otros.

Características • Inicio rápido • Registro de cambios • Actualización desde versiones anteriores • Herramientas de gestión • Configuración • Características de seguridad • Solución de problemas

Descripción general

El servidor MCP de SOAR es una solución innovadora de integración de plataformas de orquestación de seguridad, diseñada específicamente para la plataforma OctoMation SOAR. A través del Model Context Protocol, integra capacidades de SOAR (Orquestación, Automatización y Respuesta de Seguridad) directamente en varios clientes de IA, incluyendo Claude Desktop, Cherry Studio, Cursor, Trae, etc. Proporciona una gestión completa de eventos de seguridad, ejecución de playbooks, consultas de inteligencia de amenazas y más, dotando a los asistentes de IA de capacidades profesionales de respuesta en ciberseguridad.

🆕 Resumen de la actualización v1.6.0

• Extracción de resultados clave: Se añaden palabras clave para nombres de nodos de acción de playbooks, permitiendo extraer nodos clave y resultados de activos de los resultados de ejecución de los playbooks.

• División semántica de resultados: Se añaden query_playbook_execution_overview_by_activity_id y query_playbook_execution_key_results_by_activity_id.

• Gestión de actualizaciones: Se añade el script de migración manual migrate_db.py, y el README se completa con riesgos y pasos de actualización.

• Visibilidad de versión: La versión actual se muestra en el encabezado, la página de estadísticas y el pie de página del panel de gestión, facilitando la verificación de la actualización por parte del usuario.

Para ver los cambios completos, consulte CHANGELOG.md.

🏗️ Arquitectura del sistema

El servidor MCP de SOAR adopta un diseño de arquitectura de doble servidor, que incluye el servidor MCP, el servidor de gestión web, la capa de lógica de negocio, la capa de almacenamiento de datos y la capa de integración de sistemas externos, proporcionando una solución completa de orquestación y automatización de seguridad.

Puntos clave de la arquitectura técnica

🎯 Plataforma OctoMation SOAR

Este proyecto está diseñado para la plataforma OctoMation SOAR, una potente plataforma de orquestación, automatización y respuesta de seguridad que ofrece:

• 🛡️ Cadena de herramientas de seguridad completa: Soporte para productos y plataformas de seguridad convencionales.

• 📚 Ricos playbooks de seguridad: Gran cantidad de playbooks de respuesta de seguridad prácticos preconfigurados.

• 🔄 Flujos de trabajo flexibles: Orquestación visual de playbooks y ejecución automatizada.

• 🌐 Arquitectura abierta: Soporte para integraciones y extensiones personalizadas.

Ventajas principales

• 🔒 Orquestación de seguridad: Integración perfecta con la plataforma OctoMation SOAR.

• 🤖 Impulsado por IA: Respuesta de seguridad inteligente a través de múltiples clientes de IA.

• ⚡ Arquitectura asíncrona: Funciones de herramientas MCP totalmente asíncronas, reutilización de pool de conexiones httpx.

• 🌐 Gestión Web: Interfaz de gestión visual intuitiva.

• 🔧 Configuración flexible: Soporte para múltiples métodos de despliegue y configuración.

• 🛡️ Refuerzo de seguridad: Hash de contraseñas bcrypt, persistencia de claves JWT, desensibilización de registros.

Características

🛠️ Conjunto de herramientas MCP

Conjunto completo de herramientas proporcionado por el servidor MCP de SOAR

Consulta y ejecución de playbooks

• list_playbooks_quick - Obtiene una lista concisa de playbooks (ID, nombre, nombre para mostrar), adecuada para que la IA comprenda rápidamente las opciones de playbooks.

• query_playbook_execution_params - Consulta la definición de parámetros necesarios para la ejecución según el ID del playbook.

• execute_playbook - Ejecuta el playbook de SOAR especificado, admite paso de parámetros (asíncrono).

• query_playbook_execution_status_by_activity_id - Consulta el estado de ejecución del playbook según el ID de actividad (asíncrono).

• query_playbook_execution_overview_by_activity_id - Consulta el resumen de resultados de ejecución del playbook según el ID de actividad (asíncrono).

• query_playbook_execution_key_results_by_activity_id - Consulta los resultados clave de ejecución del playbook según el ID de actividad (asíncrono).

Notas importantes

• Formato de ID de playbook: Admite tipo LONG (entero de 64 bits), se puede usar formato entero o de cadena.

• Flujo de ejecución: Consultar parámetros → Ejecutar playbook → Verificar estado → Consultar resumen de resultados / Consultar resultados clave.

• Compatibilidad: El ID del playbook puede exceder el rango de enteros seguros de JavaScript, se recomienda usar formato de cadena.

• Extracción de resultados clave: query_playbook_execution_key_results_by_activity_id no requiere pasar palabras clave adicionales; las palabras clave provienen de la configuración del playbook en el panel de gestión.

📊 Recursos MCP

• soar://playbooks - Lista de playbooks de SOAR

• soar://applications - Lista de aplicaciones de SOAR

• soar://executions - Registros de actividades de ejecución

🌐 Interfaz de gestión Web

Interfaz de gestión Web del servidor MCP de SOAR - Página de gestión de playbooks

• Gestión de playbooks: Lista visual de playbooks, gestión de estados, monitoreo de ejecución.

• Gestión de tokens: Creación, gestión y monitoreo de credenciales de acceso a la API.

• Configuración del sistema: Ajustes de conexión SOAR, configuración de sincronización, interruptor de verificación SSL.

• Gestión de contraseñas: Entrada independiente para cambio de contraseña de administrador y descripción de políticas de seguridad.

• Estadísticas: Estado del sistema, estadísticas de ejecución, tiempos de sincronización.

Configuración de extracción de resultados clave

En los detalles del playbook en el panel de gestión, puede configurar "Palabras clave de nombre de nodo de acción de playbook" para cada playbook:

• Admite la entrada de múltiples palabras clave presionando Enter, coma en inglés , o coma en chino ，.

• Existe una relación "o" entre múltiples palabras clave.

• El sistema coincidirá con estos nombres de nodos en nodeResultModels.displayName de los resultados de ejecución del playbook según la relación de inclusión.

• Una vez alcanzado, devolverá estos nodos y sus correspondientes assetResultModels.

Consejo: Para que la extracción de resultados clave sea más estable, se recomienda añadir estas palabras clave directamente en el nombre de visualización del nodo del playbook en SOAR, por ejemplo, [Inteligencia de amenazas] Consultar IP, [Aislamiento] Disposición del grupo de seguridad del host en la nube.

Entrada de configuración y visualización de "Palabras clave de nombre de nodo de acción de playbook" en el panel de gestión

🚀 Inicio rápido

Esta guía le llevará desde cero a desplegar y configurar el servidor MCP de SOAR.

📋 Requisitos del entorno

Requisitos del sistema:

• Python 3.9+

• 4GB+ de RAM

• Conexión de red (para acceso a la API de SOAR)

Plataformas compatibles:

• Linux (Ubuntu 18.04+, CentOS 7+)

• macOS (10.14+)

• Windows 10/11

🛠️ Paso 1: Despliegue del proyecto

Puede elegir entre despliegue nativo, despliegue con Docker o paquete de lanzamiento offline según sus necesidades reales.

Opción 1: Despliegue nativo de Python (recomendado para entorno de desarrollo)

1. Obtener el código del proyecto

# 克隆项目
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. Configuración del entorno

# 创建 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. Primer inicio

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

🎉 ¡Felicidades! El servidor se ha iniciado

Al ejecutarse por primera vez, el sistema automáticamente:

• ✅ Creará la base de datos y la configuración inicial.

• ✅ Generará la contraseña de administrador (solo se muestra una vez en la consola, no se escribe en el archivo de registro).

• ✅ Generará y persistirá la clave de firma JWT.

• ✅ Iniciará el servidor MCP y la interfaz de gestión Web.

• ⚠️ Omitirá la sincronización de playbooks de SOAR (requiere configuración posterior).

Información de salida importante:

============================================================
  🔑 管理员初始密码: 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

⚠️ Aviso de seguridad: La contraseña de administrador solo se muestra a través de la consola en el primer inicio y no se registrará en el archivo de registro. Asegúrese de guardarla inmediatamente. Si la pierde, puede usar ./reset_admin_password.sh para restablecerla.

🔐 Sugerencia de puesta en marcha: Después de iniciar sesión en el panel de fondo por primera vez, diríjase inmediatamente a la página "Gestión de contraseñas" en la barra de navegación para cambiar la contraseña de administrador antes de continuar con la configuración de inicialización de la plataforma SOAR.

Interfaz de salida de la consola después de iniciar el servidor MCP de SOAR

Opción 2: Despliegue en contenedor Docker (recomendado para entorno de servidor)

El proyecto incluye de forma nativa Dockerfile y docker-compose.yml, lo que simplifica enormemente el proceso de despliegue.

1. Construir directamente e iniciar el servicio en segundo plano:

# 为避免卷挂载时 sqlite db 尚未生成而被 Docker 误创建为空目录，请先进行本地文件预占位
mkdir -p logs && touch soar_mcp.db

# 一键构建镜像并启动
docker-compose up -d --build

2. Ver los registros de ejecución para obtener la contraseña inicial:

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

Opción 3: Empaquetado offline y despliegue remoto con un clic

Si necesita migrar el servicio probado a un servidor de intranet sin acceso a Internet, puede utilizar las herramientas de exportación de código e imagen que vienen con este proyecto para lograr un empaquetado y migración totalmente automatizados en la intranet:

1. Ejecutar el "empaquetado" en la máquina de desarrollo o máquina de salto que pueda construir imágenes:

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

2. Transferir el soar-mcp-release.tar.gz empaquetado al servidor de intranet de destino, descomprimir y usar:

tar -xzvf soar-mcp-release.tar.gz
cd soar-mcp-release

# 执行自动化一键部署脚本（已自带 docker load 镜像加载逻辑）
./install.sh

⚙️ Paso 2: Configuración de la plataforma SOAR

1. Acceder al panel de gestión

1. Abra el navegador y acceda a http://127.0.0.1:12346/admin

2. Inicie sesión con la contraseña de administrador mostrada en la consola.

3. Cuando SOAR no está configurado, el sistema entrará automáticamente en "Configuración del sistema" y mostrará la guía de configuración inicial.

2. Configurar la conexión SOAR

Ingrese la siguiente información en la página de configuración del sistema:

3. Probar y guardar

1. Haga clic en el botón "Probar conexión" para verificar la configuración.

2. Después de ver ✅ "¡Prueba de conexión API exitosa!", haga clic en "Guardar configuración".

3. El sistema comenzará automáticamente a sincronizar los datos de los playbooks de SOAR.

Nota: Los parámetros de conexión SOAR ahora se basan en la configuración de la base de datos; el servicio en ejecución ya no leerá API_URL, API_TOKEN, SSL_VERIFY de .env como configuración de tiempo de ejecución.

🤖 Paso 3: Configuración del cliente MCP

Admite una variedad de clientes MCP basados en grandes modelos, incluyendo pero no limitado a: Cherry Studio, Claude Desktop, Cursor, Trae, etc.

Cherry Studio (recomendado)

Configurar el servidor MCP de SOAR en Cherry Studio

1. Abrir Cherry Studio

2. Ir a Configuración → Servidores MCP

3. Editar el archivo de configuración y añadir el siguiente contenido:

   Método 1: Parámetros URL (buena compatibilidad)

   {
     "mcpServers": {
       "soar-mcp": {
         "type": "http",
         "name": "soar-mcp",
         "description": "SOAR 安全编排平台集成",
         "url": "http://127.0.0.1:12345/mcp?token=xxxx"
       }
     }
   }

   Método 2: Bearer Token (recomendado, más seguro)

   {
     "mcpServers": {
       "soar-mcp": {
         "type": "http",
         "name": "soar-mcp",
         "description": "SOAR 安全编排平台集成",
         "url": "http://127.0.0.1:12345/mcp",
         "headers": {
           "Authorization": "Bearer xxxx"
         }
       }
     }
   }

4. Guardar y reiniciar Cherry Studio