SOAR MCP Server

Ein Model Context Protocol (MCP)-Server basierend auf der OctoMation SOAR-Plattform, der Sicherheitsorchestrierung, Automatisierung und Reaktionsfähigkeiten für KI-Clients wie Claude Desktop, Cherry Studio, Cursor, Trae usw. bereitstellt.

Funktionen • Schnellstart • Änderungsprotokoll • Upgrade von alten Versionen • Verwaltungstools • Konfigurationshinweise • Sicherheitsmerkmale • Fehlerbehebung

Übersicht

SOAR MCP Server ist eine innovative Integrationslösung für Sicherheitsorchestrierungsplattformen, die speziell für die OctoMation SOAR-Plattform entwickelt wurde. Durch das Model Context Protocol werden SOAR-Funktionen (Security Orchestration, Automation and Response) direkt in verschiedene KI-Clients integriert, darunter Claude Desktop, Cherry Studio, Cursor, Trae usw. Es bietet umfassende Funktionen für das Sicherheitsereignismanagement, die Playbook-Ausführung, die Abfrage von Bedrohungsinformationen und mehr, wodurch KI-Assistenten mit professionellen Cybersicherheits-Reaktionsfähigkeiten ausgestattet werden.

🆕 Zusammenfassung der Neuerungen in v1.6.0

• Extraktion von Schlüsselergebnissen: Neue Schlüsselwörter für Playbook-Aktionsknotennamen hinzugefügt, um wichtige Knoten und Asset-Ergebnisse aus den Playbook-Ausführungsergebnissen zu extrahieren.

• Semantische Ergebnisaufteilung: Neue Funktionen query_playbook_execution_overview_by_activity_id und query_playbook_execution_key_results_by_activity_id hinzugefügt.

• Upgrade-Governance: Neues manuelles Migrationsskript migrate_db.py hinzugefügt; README um Upgrade-Risiken und -Schritte ergänzt.

• Versionssichtbarkeit: Die aktuelle Version wird nun im Header, auf der Statistikseite und im Footer des Verwaltungs-Backends angezeigt, um Benutzern die Überprüfung des Upgrades zu erleichtern.

Die vollständigen Änderungen finden Sie in der CHANGELOG.md.

🏗️ Systemarchitektur

Der SOAR MCP Server verwendet ein Dual-Server-Architekturdesign, das einen MCP-Server, einen Web-Verwaltungsserver, eine Geschäftslogikschicht, eine Datenspeicherschicht und eine externe Systemintegrationsschicht umfasst und eine vollständige Lösung für die Sicherheitsorchestrierungsautomatisierung bietet.

Technische Architektur-Highlights

🎯 OctoMation SOAR-Plattform

Dieses Projekt wurde speziell für die OctoMation SOAR-Plattform entwickelt. OctoMation ist eine leistungsstarke Plattform für Sicherheitsorchestrierung, Automatisierung und Reaktion, die Folgendes bietet:

• 🛡️ Vollständige Sicherheits-Toolchain: Unterstützung für gängige Sicherheitsprodukte und -plattformen.

• 📚 Umfangreiche Sicherheits-Playbooks: Vorinstallierte, praktische Sicherheitsreaktions-Playbooks.

• 🔄 Flexibler Workflow: Visuelle Playbook-Orchestrierung und automatisierte Ausführung.

• 🌐 Offene Architektur: Unterstützung für benutzerdefinierte Integrationen und Erweiterungen.

Kernvorteile

• 🔒 Sicherheitsorchestrierung: Nahtlose Anbindung an die OctoMation SOAR-Plattform.

• 🤖 KI-gesteuert: Intelligente Sicherheitsreaktion über verschiedene KI-Clients.

• ⚡ Asynchrone Architektur: MCP-Werkzeugfunktionen sind vollständig asynchron, Wiederverwendung von httpx-Verbindungspools.

• 🌐 Web-Verwaltung: Intuitive visuelle Verwaltungsoberfläche.

• 🔧 Flexible Konfiguration: Unterstützung für verschiedene Bereitstellungs- und Konfigurationsmethoden.

• 🛡️ Sicherheitshärtung: bcrypt-Passwort-Hashing, JWT-Schlüsselpersistenz, Protokoll-Maskierung.

Funktionen

🛠️ MCP-Tool-Set

Das vollständige Tool-Set des SOAR MCP Servers

Playbook-Abfrage und -Ausführung

• list_playbooks_quick - Ruft eine kompakte Liste von Playbooks ab (ID, Name, Anzeigename), geeignet für die schnelle Auswahl durch die KI.

• query_playbook_execution_params - Fragt die für die Ausführung erforderlichen Parameterdefinitionen basierend auf der Playbook-ID ab.

• execute_playbook - Führt das angegebene SOAR-Playbook aus, unterstützt Parameterübergabe (asynchron).

• query_playbook_execution_status_by_activity_id - Fragt den Ausführungsstatus des Playbooks basierend auf der Aktivitäts-ID ab (asynchron).

• query_playbook_execution_overview_by_activity_id - Fragt die Übersicht der Playbook-Ausführungsergebnisse basierend auf der Aktivitäts-ID ab (asynchron).

• query_playbook_execution_key_results_by_activity_id - Fragt die Schlüsselergebnisse der Playbook-Ausführung basierend auf der Aktivitäts-ID ab (asynchron).

Wichtige Hinweise

• Playbook-ID-Format: Unterstützt LONG-Typen (64-Bit-Ganzzahlen), kann als Ganzzahl oder String verwendet werden.

• Ausführungsablauf: Parameter abfragen → Playbook ausführen → Status prüfen → Übersichtsergebnisse abfragen / Schlüsselergebnisse abfragen.

• Kompatibilität: Playbook-IDs können den Bereich sicherer JavaScript-Ganzzahlen überschreiten; die Verwendung des String-Formats wird empfohlen.

• Extraktion von Schlüsselergebnissen: query_playbook_execution_key_results_by_activity_id erfordert keine zusätzliche Übergabe von Schlüsselwörtern; die Schlüsselwörter stammen aus der Playbook-Konfiguration im Verwaltungs-Backend.

📊 MCP-Ressourcen

• soar://playbooks - Liste der SOAR-Playbooks

• soar://applications - Liste der SOAR-Anwendungen

• soar://executions - Aufzeichnungen der Ausführungsaktivitäten

🌐 Web-Verwaltungsoberfläche

SOAR MCP Server Web-Verwaltungsoberfläche - Playbook-Verwaltungsseite

• Playbook-Verwaltung: Visuelle Playbook-Liste, Statusverwaltung, Ausführungsüberwachung.

• Token-Verwaltung: Erstellung, Verwaltung und Überwachung von API-Zugangsdaten.

• Systemkonfiguration: SOAR-Verbindungseinstellungen, Synchronisationskonfiguration, SSL-Verifizierungs-Schalter.

• Passwortverwaltung: Separater Zugang zur Änderung des Administratorpassworts und Erläuterung der Sicherheitsrichtlinien.

• Statistiken: Systemstatus, Ausführungsstatistiken, Synchronisationszeit.

Konfiguration der Extraktion von Schlüsselergebnissen

In den Playbook-Details im Verwaltungs-Backend können für jedes Playbook „Schlüsselwörter für Playbook-Aktionsknotennamen“ konfiguriert werden:

• Unterstützt die Eingabe mehrerer Schlüsselwörter durch Enter, Kommas (Englisch , oder Chinesisch ，).

• Mehrere Schlüsselwörter stehen in einer „ODER“-Beziehung zueinander.

• Das System gleicht diese Knotennamen-Schlüsselwörter mit nodeResultModels.displayName in den Playbook-Ausführungsergebnissen ab.

• Bei einem Treffer werden diese Knoten und die entsprechenden assetResultModels zurückgegeben.

Tipp: Um die Extraktion von Schlüsselergebnissen stabiler zu machen, wird empfohlen, diese Schlüsselwörter direkt in die Anzeigenamen der Playbook-Knoten in SOAR aufzunehmen, z. B. [Bedrohungsinformationen] IP abfragen, [Isolierung] Cloud-Host-Sicherheitsgruppen-Behandlung.

Anzeige und Konfigurationseingang für „Schlüsselwörter für Playbook-Aktionsknotennamen“ im Verwaltungs-Backend

🚀 Schnellstart

Dieser Leitfaden führt Sie durch die Bereitstellung und Konfiguration des SOAR MCP Servers von Grund auf.

📋 Systemanforderungen

Systemanforderungen:

• Python 3.9+

• 4 GB+ RAM

• Netzwerkverbindung (für SOAR API-Zugriff)

Unterstützte Plattformen:

• Linux (Ubuntu 18.04+, CentOS 7+)

• macOS (10.14+)

• Windows 10/11

🛠️ Schritt 1: Projektbereitstellung

Sie können je nach Bedarf zwischen nativer Bereitstellung, Docker-Bereitstellung oder Offline-Paketveröffentlichung wählen.

Option 1: Native Python-Bereitstellung (empfohlen für Entwicklungsumgebungen)

1. Projektcode abrufen

# 克隆项目
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. Umgebungskonfiguration

# 创建 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. Erster Start

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

🎉 Herzlichen Glückwunsch! Der Server wurde gestartet.

Beim ersten Start führt das System automatisch folgende Schritte aus:

• ✅ Erstellung der Datenbank und der Erstkonfiguration.

• ✅ Generierung des Administratorpassworts (wird nur einmal in der Konsole angezeigt, nicht in die Protokolldatei geschrieben).

• ✅ Generierung und Persistierung des JWT-Signaturschlüssels.

• ✅ Start des MCP-Servers und der Web-Verwaltungsoberfläche.

• ⚠️ Überspringen der SOAR-Playbook-Synchronisation (erfordert spätere Konfiguration).

Wichtige Ausgabeinformationen:

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

⚠️ Sicherheitshinweis: Das Administratorpasswort wird nur beim ersten Start in der Konsole angezeigt und nicht in der Protokolldatei gespeichert. Bitte speichern Sie es unbedingt sofort. Falls es verloren geht, können Sie es mit ./reset_admin_password.sh zurücksetzen.

🔐 Empfehlung für den Live-Betrieb: Nach der ersten Anmeldung im Backend gehen Sie bitte sofort zur Seite „Passwortverwaltung“ in der Navigationsleiste, um das Administratorpasswort zu ändern, bevor Sie mit der Konfiguration der SOAR-Plattform fortfahren.

Konsolenausgabe nach dem Start des SOAR MCP Servers

Option 2: Docker-Container-Bereitstellung (empfohlen für Serverumgebungen)

Das Projekt enthält nativ ein Dockerfile und eine docker-compose.yml, was den Bereitstellungsprozess erheblich vereinfacht.

1. Direktes Erstellen und Starten des Dienstes im Hintergrund:

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

2. Anzeigen der Laufzeitprotokolle zum Abrufen des Anfangspassworts:

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

Option 3: Offline-Paketierung und Remote-Bereitstellung mit einem Klick

Wenn Sie den getesteten Dienst auf einen Intranet-Server ohne Internetzugang migrieren müssen, können Sie die mitgelieferten Code- und Image-Export-Tools des Projekts verwenden, um eine vollautomatische Paketierung und Migration im Intranet zu erreichen:

1. Führen Sie die „Paketierung“ auf einem Entwicklungsrechner oder einer Sprungstation aus, die Images erstellen kann:

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

2. Übertragen Sie das gepackte soar-mcp-release.tar.gz auf den Ziel-Intranet-Server und entpacken Sie es zur Verwendung:

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

⚙️ Schritt 2: Konfiguration der SOAR-Plattform

1. Zugriff auf das Verwaltungs-Backend

1. Öffnen Sie den Browser und rufen Sie http://127.0.0.1:12346/admin auf.

2. Melden Sie sich mit dem in der Konsole angezeigten Administratorpasswort an.

3. Wenn SOAR nicht konfiguriert ist, wechselt das System automatisch zur „Systemkonfiguration“ und zeigt den Einrichtungsassistenten an.

2. Konfiguration der SOAR-Verbindung

Geben Sie auf der Systemkonfigurationsseite die folgenden Informationen ein:

3. Testen und Speichern

1. Klicken Sie auf die Schaltfläche „Verbindung testen“, um die Konfiguration zu überprüfen.

2. Nachdem Sie ✅ „API-Verbindungstest erfolgreich!“ gesehen haben, klicken Sie auf „Konfiguration speichern“.

3. Das System beginnt automatisch mit der Synchronisation der SOAR-Playbook-Daten.

Hinweis: SOAR-Verbindungsparameter basieren nun auf der Datenbankkonfiguration; der laufende Dienst liest API_URL, API_TOKEN, SSL_VERIFY nicht mehr aus .env als Laufzeitkonfiguration.

🤖 Schritt 3: Konfiguration des MCP-Clients

Unterstützt eine Vielzahl von MCP-Clients, die auf großen Sprachmodellen basieren, einschließlich, aber nicht beschränkt auf: Cherry Studio, Claude Desktop, Cursor, Trae usw.