flagify-com/soar-mcp

SOAR MCP Server

概述

SOAR MCP Server 是一个创新的安全编排平台集成解决方案，专为 OctoMation SOAR 平台 设计。通过 Model Context Protocol 将 SOAR (Security Orchestration, Automation and Response) 能力直接集成到各种 AI 客户端中，包括 Claude Desktop、Cherry Studio、Cursor、Trae 等。它提供了完整的安全事件管理、剧本执行、威胁情报查询等功能，让 AI 助手具备专业的网络安全响应能力。

🏗️ 系统架构

SOAR MCP Server 采用双服务器架构设计，包含 MCP 服务器、Web 管理服务器、业务逻辑层、数据存储层和外部系统集成层，提供完整的安全编排自动化解决方案。

🎯 OctoMation SOAR 平台

本项目专为 OctoMation SOAR 平台 设计，OctoMation 是一个功能强大的安全编排、自动化和响应平台，提供：

• 🛡️ 完整的安全工具链：支持主流安全产品和平台
• 📚 丰富的安全剧本：预置大量实用的安全响应剧本
• 🔄 灵活的工作流：可视化剧本编排和自动化执行
• 🌐 开放架构：支持自定义集成和扩展

核心优势

• 🔒 安全编排：无缝对接 OctoMation SOAR 平台
• 🤖 AI 驱动：通过多种 AI 客户端实现智能安全响应
• ⚡ 实时响应：快速处理安全事件和威胁
• 🌐 Web 管理：直观的可视化管理界面
• 🔧 灵活配置：支持多种部署和配置方式

功能特性

🛠️ MCP 工具集

SOAR MCP 服务器提供的完整工具集

剧本查询与执行

• list_playbooks_quick - 获取简洁的剧本列表（ID、name、displayName），适用于 AI 快速理解剧本选项
• query_playbook_execution_params - 根据剧本ID查询执行所需的参数定义
• execute_playbook - 执行指定的 SOAR 剧本，支持参数传递
• query_playbook_execution_status_by_activity_id - 根据活动ID查询剧本执行状态
• query_playbook_execution_result_by_activity_id - 根据活动ID查询剧本执行的详细结果

重要说明

• 剧本ID格式：支持 LONG 类型（64位整数），可以使用整数或字符串格式
• 执行流程：查询参数 → 执行剧本 → 检查状态 → 获取结果
• 兼容性：剧本ID 可能超出 JavaScript 安全整数范围，建议使用字符串格式

📊 MCP 资源

• soar://playbooks - SOAR 剧本列表

🌐 Web 管理界面

SOAR MCP 服务器 Web 管理界面 - 剧本管理页面

• 剧本管理：可视化剧本列表、状态管理、执行监控
• Token 管理：API 访问凭证的创建、管理和监控
• 系统配置：数据库连接、同步设置、API 配置
• 统计信息：系统状态、执行统计、性能监控

🚀 快速开始

本指南将带你从零开始部署和配置 SOAR MCP Server。

📋 环境要求

系统要求：

• Python 3.8+
• 4GB+ 内存
• 网络连接（用于 SOAR API 访问）

支持平台：

• Linux (Ubuntu 18.04+, CentOS 7+)
• macOS (10.14+)
• Windows 10/11

🛠️ 第一步：项目部署

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

🎉 恭喜！服务器已启动

首次运行时，系统会自动：

• ✅ 创建数据库和初始配置
• ✅ 生成管理员密码（控制台会显示）
• ✅ 启动 MCP 服务器和 Web 管理界面
• ⚠️ 跳过 SOAR 剧本同步（需要后续配置）

重要输出信息：

🔑 管理员密码: a$bC9*xYz2M&
📊 MCP服务: http://127.0.0.1:12345/mcp?token=<user_token>
🎛️  管理后台: http://127.0.0.1:12346/admin

SOAR MCP 服务器启动后的控制台输出界面

⚙️ 第二步：SOAR 平台配置

1. 访问管理后台

1. 打开浏览器，访问 http://127.0.0.1:12346/admin
2. 使用控制台显示的管理员密码登录
3. 点击导航栏的「系统配置」

2. 配置 SOAR 连接

在系统配置页面填入以下信息：

3. 测试和保存

1. 点击「测试连接」按钮验证配置
2. 看到 ✅ "API连接测试成功！" 后，点击「保存配置」
3. 系统将自动开始同步 SOAR 剧本数据

🤖 第三步：MCP 客户端配置

支持多种基于大模型的 MCP 客户端，包括但不限于：Cherry Studio、Claude Desktop、Cursor、Trae 等。

Cherry Studio（推荐）

在 Cherry Studio 中配置 SOAR MCP 服务器

1. 打开 Cherry Studio
2. 进入设置 → MCP 服务器
3. 编辑配置文件，添加以下内容：

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

4. 保存并重启 Cherry Studio

在 Cherry Studio 中成功使用 SOAR MCP 服务器功能

⚠️ 重要：将 token=xxxx 替换为从管理后台获取的实际API Token

Claude Desktop

编辑 Claude Desktop 的 MCP 配置文件：

位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

配置内容：

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

⚠️ 重要：

• 将 token=xxxx 替换为从管理后台获取的实际API Token
• Claude Desktop 需要重启才能加载新配置

其他 MCP 客户端

通用配置参数：

• 协议: HTTP
• 服务器 URL: http://127.0.0.1:12345/mcp?token=xxxx
• 认证: 通过URL参数传递token

🧪 第四步：功能验证

验证 MCP 连接

在 MCP 客户端中输入：

请列出所有可用的 SOAR 剧本

正常情况下会返回：

📋 当前可用的 SOAR 剧本：

1. 🔍 IP信誉检查剧本 (ID: "1907203516548373")
   - 内部名称: ip_reputation_check
   - 显示名称: IP信誉检查剧本
   - 状态: 启用中

完整执行流程示例

1. 查询剧本参数：

请查询剧本 1907203516548373 需要哪些执行参数

2. 执行剧本：

请执行剧本 1907203516548373，检查IP地址 192.168.1.100

3. 查看执行状态：

查看活动ID为 xxx 的剧本执行状态

4. 获取执行结果：

获取活动ID为 xxx 的剧本执行详细结果

🔧 管理工具

管理员密码重置

如果忘记了管理员密码，可以使用内置的重置脚本：

# 运行密码重置脚本
./reset_admin_password.sh

脚本特性：

• 🔒 安全随机密码生成（12位强密码）
• 🎨 用户友好的彩色界面
• ✅ 完善的环境检查和错误处理
• 🛡️ 确认机制防止误操作

使用示例：

$ ./reset_admin_password.sh

==========================================
    SOAR管理员密码重置工具 v1.0
==========================================

[INFO] 🔄 开始重置SOAR管理员密码...
[SUCCESS] ✅ 环境检查通过

[WARNING] ⚠️  这将重置管理员密码，旧密码将失效
是否继续? [y/N]: y

[SUCCESS] 🎉 管理员密码重置成功！

=================== 新密码信息 ===================
管理员密码: *UMiWSO7#QBe
==================================================

[WARNING] 请妥善保存此密码，重启服务后生效

高级配置

环境变量配置

如需固定配置，可创建 .env 文件：

# SOAR 平台配置
API_URL=https://your-soar-platform.com
API_TOKEN=your_jwt_token_here
SSL_VERIFY=0  # 关闭SSL验证（默认）

# MCP 服务器配置
MCP_PORT=12345
ADMIN_PORT=12346

# 高级配置
SYNC_INTERVAL=14400  # 同步周期（秒）
SOAR_TIMEOUT=30      # API超时（秒）

系统服务配置

创建 systemd 服务（Linux）：

sudo nano /etc/systemd/system/mcp-soar.service

[Unit]
Description=MCP SOAR Server
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/soar-mcp
Environment=PATH=/path/to/soar-mcp/venv/bin
ExecStart=/path/to/soar-mcp/venv/bin/python soar_mcp_server.py
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

# 启用并启动服务
sudo systemctl daemon-reload
sudo systemctl enable mcp-soar
sudo systemctl start mcp-soar

测试

运行测试套件

# 运行所有测试
python -m pytest tests/

# 运行 MCP 客户端测试
cd tests
python mcp_soar_client.py

# 运行自动化测试
./tests/test_automation.sh

测试剧本执行

使用 MCP 客户端工具进行测试：

# 测试 MCP 连接
cd tests
python mcp_soar_client.py

# 测试剧本执行功能
python test_new_playbook_tools.py --playbook-id 1907203516548373

配置说明

环境变量

数据库配置

支持多种数据库：

# SQLite（默认）
DATABASE_URL=sqlite:///data/soar_mcp.db

# PostgreSQL
DATABASE_URL=postgresql://user:pass@localhost/soar_mcp

# MySQL
DATABASE_URL=mysql+pymysql://user:pass@localhost/soar_mcp

故障排除

常见问题

1. MCP 连接失败

症状：AI 客户端无法连接到 MCP 服务器

解决方案：

# 检查服务状态
curl http://localhost:12345/health

# 检查端口占用
lsof -i :12345

# 查看日志
tail -f logs/mcp_server.log

2. API 认证失败

症状：403 Forbidden 或 401 Unauthorized

解决方案：

• 检查 .env 文件中的 API_TOKEN 是否正确
• 确认 token 未过期
• 验证 API 地址是否正确

3. 数据库连接问题

症状：数据库操作失败

解决方案：

# 检查数据库文件权限
ls -la soar_mcp.db

# 重新初始化数据库
python -c "from models import create_tables; create_tables()"

日志分析

# 查看 MCP 服务器日志
tail -f logs/mcp_server.log

# 查看 Web 服务日志
tail -f logs/web_server.log

# 查看数据库操作日志
tail -f logs/database.log

许可证

本项目采用 MIT 许可证。详情请参阅 文件。

支持与反馈

• 🐛 问题反馈：GitHub Issues
• 💬 讨论交流：GitHub Discussions
• 📧 邮件联系：support@wuzhi-ai.com

致谢

本项目的MCP服务器实现基于 FastMCP 框架构建。FastMCP 提供了优雅的 Python MCP 服务器开发体验，让我们能够快速构建高质量的 MCP 服务器。感谢 FastMCP 团队的优秀工作！

相关链接

• Model Context Protocol - MCP 官方文档
• FastMCP - Python MCP 服务器框架
• OctoMation Wiki - SOAR 平台文档
• 雾帜智能 - 公司官网