SOAR MCP Server

SOAR MCP Server

SOAR MCP Server

基于 OctoMation SOAR 平台 的 Model Context Protocol (MCP) 服务器，为 Claude Desktop、Cherry Studio、Cursor、Trae 等 AI 客户端提供安全编排、自动化和响应能力。

  

功能特性 • 快速开始 • 更新日志 • 从旧版本升级 • 管理工具 • 配置说明 • 安全特性 • 故障排除

概述

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

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

技术架构要点

🎯 OctoMation SOAR 平台

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

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

核心优势

• 🔒 安全编排：无缝对接 OctoMation SOAR 平台
• 🤖 AI 驱动：通过多种 AI 客户端实现智能安全响应
• ⚡ 异步架构：MCP 工具函数全异步，httpx 连接池复用
• 🌐 Web 管理：直观的可视化管理界面
• 🔧 灵活配置：支持多种部署和配置方式
• 🛡️ 安全加固：bcrypt 密码哈希、JWT 密钥持久化、日志脱敏

功能特性

🛠️ MCP 工具集

SOAR 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_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 - 执行活动记录

🌐 Web 管理界面

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

• 剧本管理：可视化剧本列表、状态管理、执行监控
• Token 管理：API 访问凭证的创建、管理和监控
• 系统配置：SOAR 连接设置、同步配置、SSL 验证开关
• 密码管理：独立的管理员密码修改入口和安全策略说明
• 统计信息：系统状态、执行统计、同步时间

关键结果提取配置

在管理后台的剧本详情中，可以为每个剧本配置“剧本动作节点名称关键词”：

• 支持按 Enter、英文逗号 ,、中文逗号 ， 录入多个关键词
• 多个关键词之间是“或”关系
• 系统会在剧本执行结果的 nodeResultModels.displayName 中按包含关系匹配这些节点名称关键词
• 命中后，会返回这些节点及其对应的 assetResultModels

提示：为了让关键结果提取更稳定，建议在 SOAR 的剧本节点显示名称中直接加入这些关键词，例如 [威胁情报] 查询 IP、[隔离] 云主机安全组处置。

剧本动作节点名称关键词配置 *管理后台中的“剧本动作节点名称关键词”展示与配置入口*

🚀 快速开始

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

📋 环境要求

系统要求：

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

支持平台：

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

🛠️ 第一步：项目部署

您可以根据实际需求选择 原生部署、Docker 部署 或 离线打包发布。

方案一：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 服务器和 Web 管理界面
• ⚠️ 跳过 SOAR 剧本同步（需要后续配置）

重要输出信息：

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

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

⚠️ 安全提示：管理员密码仅在首次启动时通过控制台显示，不会记录到日志文件。请务必立即保存。如果遗失，可使用 ./reset_admin_password.sh 重置。

🔐 上线建议：首次登录后台后，请立即前往导航栏的「密码管理」页面修改管理员密码，再继续进行 SOAR 平台初始化配置。

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

方案二：Docker 容器部署 (推荐服务器环境使用)

项目原生包含 Dockerfile 和 docker-compose.yml，极大简化了部署流程。

1. 直接构建并后台启动服务：

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

1. 查看运行日志获取初始密码：

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

方案三：离线打包与远程一键部署

如果您需要将测试通过的服务迁移到无法访问外网的内网服务器上，可以使用本项目自带的代码与镜像导出工具，实现内网全自动打包迁移：

1. 在能够构建镜像的开发机或跳板机上执行“封包”：

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

1. 将打包好的 soar-mcp-release.tar.gz 传送到目标内网服务器中，解压即用：

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

⚙️ 第二步：SOAR 平台配置

1. 访问管理后台

1. 打开浏览器，访问 http://127.0.0.1:12346/admin
2. 使用控制台显示的管理员密码登录
3. 未配置 SOAR 时，系统会自动进入「系统配置」并显示首次配置引导

2. 配置 SOAR 连接

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

3. 测试和保存

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

说明：SOAR 连接参数现在以数据库配置为准，运行中的服务不会再从 .env 读取 API_URL、API_TOKEN、SSL_VERIFY 作为运行时配置。

🤖 第三步：MCP 客户端配置

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

Cherry Studio（推荐）

Cherry Studio MCP配置 *在 Cherry Studio 中配置 SOAR MCP 服务器*

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

方式一：URL 参数（兼容性好）

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

方式二：Bearer Token（推荐，更安全）

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

1. 保存并重启 Cherry Studio

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

⚠️ 重要：将 xxxx 替换为从管理后台获取的实际API Token。Bearer Token 方式更安全，Token 不会暴露在 URL 和日志中。

Claude Desktop

编辑 Claude Desktop 的 MCP 配置文件：

位置：

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

配置内容（URL 参数方式）：

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

配置内容（Bearer Token 方式，推荐）：

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

⚠️ 重要：

• 将 xxxx 替换为从管理后台获取的实际API Token
• Bearer Token 方式更安全，推荐优先使用
• Claude Desktop 需要重启才能加载新配置

其他 MCP 客户端

通用配置参数：

• 协议: HTTP (Streamable-HTTP)
• 服务器 URL: http://127.0.0.1:12345/mcp
• 认证方式（二选一）:

- 推荐: HTTP Header Authorization: Bearer - 兼容: URL 参数 http://127.0.0.1:12345/mcp?token=xxxx

🧪 第四步：功能验证

验证 MCP 连接

在 MCP 客户端中输入：

请列出所有可用的 SOAR 剧本

正常情况下会返回：

📋 当前可用的 SOAR 剧本：

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

完整执行流程示例

1. 查询剧本参数：

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

1. 执行剧本：

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

1. 查看执行状态：

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

1. 获取执行结果：

获取活动ID为 xxx 的剧本执行概览结果

1. 获取关键结果：

获取活动ID为 xxx 的剧本执行关键结果

本地单元测试

建议在改动剧本结果提取相关逻辑后，执行下面的本地单元测试：

python3 -m unittest discover -s tests -p 'test_playbook_result_views.py'

📦 从旧版本升级

当前版本相对旧版本有一项数据库结构新增和一项MCP 工具语义调整。如果你是新部署用户，可以直接忽略本节；如果你是带历史数据升级，请按下面步骤执行。

这次升级改了什么

1. 数据库变更

playbooks 表新增了一个字段：

result_focus_keywords TEXT DEFAULT '[]'

这个字段用于保存每个剧本配置的“剧本动作节点名称关键词”，供 query_playbook_execution_key_results_by_activity_id 自动筛选关键节点结果使用。

2. MCP 工具语义调整

剧本执行结果查询从单一结果查询拆成了两个语义化工具：

• query_playbook_execution_overview_by_activity_id
• query_playbook_execution_key_results_by_activity_id

如果你的 MCP 客户端提示词、脚本或自动化流程里显式写死了旧工具名 query_playbook_execution_result_by_activity_id，升级后需要同步改成新的工具名。

升级风险一览

数据库迁移说明

系统启动时会自动执行数据库初始化和迁移，核心逻辑在 DatabaseManager.init_db() 中，包含对旧版 playbooks 表补列的处理。

为了方便在生产环境中先迁移再启动，仓库额外提供了一个手动迁移脚本：

python3 migrate_db.py --db-path soar_mcp.db

脚本特性：

• 可重复执行，幂等
• 不会清空现有数据
• 如果字段已存在，会直接跳过
• 迁移完成后会打印当前 playbooks 表字段列表

推荐升级步骤

# 1. 停止旧服务

# 2. 备份旧数据库
cp soar_mcp.db soar_mcp.db.bak

# 3. 更新代码
git pull origin main

# 4. 安装或更新依赖
source venv/bin/activate
pip install -r requirements.txt

# 5. 先执行数据库迁移（推荐）
python3 migrate_db.py --db-path soar_mcp.db

# 6. 如果你是从 v1.0.x 升级到 v1.1.0+，再重置管理员密码
./reset_admin_password.sh --random

# 7. 启动服务
python3 soar_mcp_server.py

升级后检查项

升级完成后，建议至少确认下面几项：

1. 管理后台可以正常打开，剧本详情中能看到“剧本动作节点名称关键词”
2. 旧的 SOAR 配置、Token、剧本列表仍然存在
3. 调用 query_playbook_execution_overview_by_activity_id 能返回概览结果
4. 给某个剧本配置关键词后，调用 query_playbook_execution_key_results_by_activity_id 能返回关键结果
5. 如果你有自定义提示词或自动化脚本，确认它们已经改用新的结果查询工具名

提示：对于大多数已有用户，数据库数据本身没有破坏性变化；真正需要额外注意的是旧密码兼容性和旧 MCP 工具名切换。

🔧 管理工具

管理员密码重置

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

# 交互模式（推荐）- 可选随机生成或指定密码
./reset_admin_password.sh

# 直接生成随机密码
./reset_admin_password.sh --random

# 设置指定密码
./reset_admin_password.sh --set 'YourNewPassword'

脚本特性：

• 🔒 使用 bcrypt 安全哈希（与服务器一致）
• 🎨 交互式彩色界面，支持密码确认
• ⚡ 密码立即生效，无需重启服务
• ✅ 自动检测虚拟环境和依赖

使用示例：

$ ./reset_admin_password.sh

==========================================
    SOAR 管理员密码工具 v2.0 (bcrypt)
==========================================

请选择操作：
  1) 生成随机密码
  2) 设置指定密码
  q) 取消

请输入选项 [1/2/q]: 1

[SUCCESS] 🎉 管理员密码已更新！

======================================
  管理员密码: xK9#mBnP2vLq
======================================

[INFO] 密码立即生效，无需重启服务

高级配置

环境变量配置

SOAR 平台连接信息现在统一在管理后台初始化和维护，.env 只保留服务器自身运行参数：

# MCP 服务器配置
MCP_PORT=12345
ADMIN_PORT=12346
BIND_HOST=127.0.0.1  # 默认仅本地访问，设为 0.0.0.0 可对外暴露

# 日志配置
DEBUG=0
LOG_LEVEL=INFO

系统服务配置

创建 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

🔒 安全特性

v1.1.0+ 版本包含以下安全加固措施：

测试

运行测试套件

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

# 运行 Bearer Token 认证单元测试（无需启动服务器）
python tests/test_bearer_auth.py --unit-only

# 运行 Bearer Token 认证集成测试（需要服务器运行 + 有效Token）
python tests/test_bearer_auth.py --token 

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

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

配置说明

环境变量

注：SOAR 连接配置不再使用环境变量，统一通过 Web 管理后台管理并持久化到数据库中。

数据库配置

默认使用 SQLite，数据库文件在首次启动时自动创建：

# 默认 SQLite 路径
soar_mcp.db

故障排除

常见问题

1. MCP 连接失败

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

解决方案：

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

# 查看日志（日志文件按日期命名，自动轮转）
ls -la logs/
tail -f logs/soar_mcp_$(date +%Y%m%d).log

2. API 认证失败

症状：403 Forbidden 或 401 Unauthorized

解决方案：

• 检查管理后台中的 SOAR API 配置是否正确
• 确认 API Token 未过期
• 验证 API 地址是否可达

3. 管理员密码丢失

解决方案：

# 使用密码重置脚本
./reset_admin_password.sh --random

4. SSL 证书验证失败

症状：内网自签名证书导致 SOAR API 连接失败

解决方案： 在管理后台「系统配置」中关闭“SSL 证书验证”，保存后重新测试连接。

5. 服务需要对外暴露

默认情况下服务仅监听 127.0.0.1，如需局域网访问：

# 在 .env 中设置
BIND_HOST=0.0.0.0

许可证

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

支持与反馈

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

致谢

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

相关链接

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

*为 AI 赋能网络安全* 🔒