SOAR MCP Server

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

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

概述

SOAR MCP Server 是一个创新的安全编排平台集成解决方案，专为 。通过 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 客户端实现智能安全响应

• ⚡ 异步架构：MCP 工具函数全异步，httpx 连接池复用

• 🌐 Web 管理：直观的可视化管理界面

• 🔧 灵活配置：支持多种部署和配置方式

• 🛡️ 安全加固：bcrypt 密码哈希、JWT 密钥持久化、日志脱敏

功能特性

🛠️ 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 剧本列表

• soar://applications - SOAR 应用列表

• soar://executions - 执行活动记录

🌐 Web 管理界面

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

• 剧本管理：可视化剧本列表、状态管理、执行监控

• Token 管理：API 访问凭证的创建、管理和监控

• 系统配置：SOAR 连接设置、同步配置、SSL 验证开关

• 统计信息：系统状态、执行统计、同步时间

🚀 快速开始

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

📋 环境要求

系统要求：

• Python 3.9+

• 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

🎉 恭喜！服务器已启动

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

• ✅ 创建数据库和初始配置

• ✅ 生成管理员密码（仅在控制台显示一次，不写入日志文件）

• ✅ 生成并持久化 JWT 签名密钥

• ✅ 启动 MCP 服务器和 Web 管理界面

• ⚠️ 跳过 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 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. 编辑配置文件，添加以下内容：

   方式一：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"
         }
       }
     }
   }

4. 保存并重启 Cherry Studio

在 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 <token>

  • 兼容: URL 参数 http://127.0.0.1:12345/mcp?token=xxxx

🧪 第四步：功能验证

验证 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 的剧本执行详细结果

📦 从旧版本升级

如果你正在从 v1.0.x 升级到 v1.1.0+，请注意以下重要变更。

数据库兼容性

好消息：数据库结构基本兼容，旧版数据库可以直接复用。

唯一的破坏性变更：管理员密码哈希算法从 SHA-256 升级为 bcrypt。旧密码无法在新版本中验证，升级后必须重置。

升级步骤

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

# 2. 更新代码
git pull origin main

# 3. 安装新依赖（新增 bcrypt）
source venv/bin/activate
pip install -r requirements.txt

# 4. 重置管理员密码（必须）
./reset_admin_password.sh --random

# 5. 启动服务
python3 soar_mcp_server.py

提示：升级后所有 SOAR 配置、剧本数据、Token 等均自动保留，仅需重置管理员密码即可正常使用。

🔧 管理工具

管理员密码重置

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

# 交互模式（推荐）- 可选随机生成或指定密码
./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] 密码立即生效，无需重启服务

高级配置

环境变量配置

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

# SOAR 平台配置
API_URL=https://your-soar-platform.com
API_TOKEN=your_jwt_token_here
SSL_VERIFY=1  # 1=启用SSL验证（默认），0=禁用（仅用于自签名证书的内网环境）

# 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 <your_token>

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

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

配置说明

环境变量

注：环境变量主要用于首次初始化。日常运行中配置通过 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_verify 设为 False，或在 .env 文件中设置 SSL_VERIFY=0。

5. 服务需要对外暴露

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

# 在 .env 中设置
BIND_HOST=0.0.0.0

许可证

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

支持与反馈

• 🐛 问题反馈：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 平台文档

• 雾帜智能 - 公司官网

雾帜智能@2025 | 最牛的SOAR | OctoMation

为 AI 赋能网络安全 🔒