SOAR MCP 서버

OctoMation SOAR 플랫폼 기반의 Model Context Protocol (MCP) 서버로, Claude Desktop, Cherry Studio, Cursor, Trae 등 AI 클라이언트에 보안 오케스트레이션, 자동화 및 대응 기능을 제공합니다.

기능 특징 • 빠른 시작 • 업데이트 로그 • 이전 버전에서 업그레이드 • 관리 도구 • 설정 설명 • 보안 특징 • 문제 해결

개요

SOAR MCP 서버는 OctoMation SOAR 플랫폼 전용으로 설계된 혁신적인 보안 오케스트레이션 플랫폼 통합 솔루션입니다. Model Context Protocol을 통해 SOAR(Security Orchestration, Automation and Response) 기능을 Claude Desktop, Cherry Studio, Cursor, Trae 등 다양한 AI 클라이언트에 직접 통합합니다. 완전한 보안 이벤트 관리, 플레이북 실행, 위협 인텔리전스 조회 등의 기능을 제공하여 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 서버는 MCP 서버, 웹 관리 서버, 비즈니스 로직 계층, 데이터 저장 계층 및 외부 시스템 통합 계층을 포함하는 이중 서버 아키텍처로 설계되어 완전한 보안 오케스트레이션 자동화 솔루션을 제공합니다.

기술 아키텍처 요점

🎯 OctoMation SOAR 플랫폼

본 프로젝트는 OctoMation SOAR 플랫폼 전용으로 설계되었습니다. OctoMation은 강력한 보안 오케스트레이션, 자동화 및 대응 플랫폼으로 다음을 제공합니다:

• 🛡️ 완전한 보안 툴체인: 주요 보안 제품 및 플랫폼 지원

• 📚 풍부한 보안 플레이북: 실용적인 보안 대응 플레이북 다수 내장

• 🔄 유연한 워크플로우: 시각적 플레이북 오케스트레이션 및 자동화 실행

• 🌐 개방형 아키텍처: 사용자 정의 통합 및 확장 지원

핵심 장점

• 🔒 보안 오케스트레이션: OctoMation SOAR 플랫폼과 원활한 연동

• 🤖 AI 기반: 다양한 AI 클라이언트를 통한 지능형 보안 대응

• ⚡ 비동기 아키텍처: MCP 도구 함수 전체 비동기, httpx 연결 풀 재사용

• 🌐 웹 관리: 직관적인 시각적 관리 인터페이스

• 🔧 유연한 설정: 다양한 배포 및 설정 방식 지원

• 🛡️ 보안 강화: 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_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 - 실행 활동 기록

🌐 웹 관리 인터페이스

SOAR MCP 서버 웹 관리 인터페이스 - 플레이북 관리 페이지

• 플레이북 관리: 시각적 플레이북 목록, 상태 관리, 실행 모니터링

• 토큰 관리: API 액세스 자격 증명 생성, 관리 및 모니터링

• 시스템 설정: SOAR 연결 설정, 동기화 설정, SSL 검증 스위치

• 비밀번호 관리: 독립적인 관리자 비밀번호 변경 및 보안 정책 설명

• 통계 정보: 시스템 상태, 실행 통계, 동기화 시간

핵심 결과 추출 설정

관리자 페이지의 플레이북 상세 정보에서 각 플레이북에 대해 "플레이북 액션 노드 이름 키워드"를 설정할 수 있습니다:

• Enter, 영문 쉼표 ,, 중문 쉼표 ，를 눌러 여러 키워드 입력 지원

• 여러 키워드 간에는 "OR" 관계 적용

• 시스템은 플레이북 실행 결과의 nodeResultModels.displayName에서 포함 관계에 따라 해당 노드 이름 키워드를 매칭함

• 매칭 성공 시, 해당 노드와 대응하는 assetResultModels를 반환함

팁: 핵심 결과 추출을 더 안정적으로 하려면 SOAR 플레이북 노드 표시 이름에 직접 해당 키워드를 추가하는 것을 권장합니다. 예: [위협 인텔리전스] IP 조회, [격리] 클라우드 호스트 보안 그룹 처리.

관리자 페이지의 "플레이북 액션 노드 이름 키워드" 표시 및 설정 입구

🚀 빠른 시작

이 가이드는 SOAR MCP 서버를 처음부터 배포하고 설정하는 방법을 안내합니다.

📋 환경 요구 사항

시스템 요구 사항:

• Python 3.9+

• 4GB+ RAM

• 네트워크 연결(SOAR API 액세스용)

지원 플랫폼:

• Linux (Ubuntu 18.04+, CentOS 7+)

• macOS (10.14+)

• Windows 10/11

🛠️ 1단계: 프로젝트 배포

실제 요구 사항에 따라 네이티브 배포, Docker 배포 또는 오프라인 패키지 배포를 선택할 수 있습니다.

방식 1: 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 서버 및 웹 관리 인터페이스 시작

• ⚠️ 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 플랫폼 초기 설정을 진행하십시오.

SOAR MCP 서버 시작 후 콘솔 출력 화면

방식 2: Docker 컨테이너 배포 (서버 환경 권장)

프로젝트에는 Dockerfile과 docker-compose.yml이 포함되어 있어 배포 프로세스가 크게 간소화됩니다.

1. 직접 빌드 및 백그라운드 서비스 시작:

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

2. 실행 로그를 확인하여 초기 비밀번호 획득:

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

방식 3: 오프라인 패키징 및 원격 원클릭 배포

테스트를 통과한 서비스를 외부 네트워크에 액세스할 수 없는 내부망 서버로 마이그레이션해야 하는 경우, 프로젝트에 포함된 코드 및 이미지 내보내기 도구를 사용하여 내부망 자동 패키징 마이그레이션을 구현할 수 있습니다:

1. 이미지를 빌드할 수 있는 개발 머신이나 점프 서버에서 "패키징" 실행:

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

2. 패키징된 soar-mcp-release.tar.gz를 대상 내부망 서버로 전송하고 압축을 풀어서 사용:

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

⚙️ 2단계: 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를 런타임 설정으로 읽지 않습니다.

🤖 3단계: MCP 클라이언트 설정

Cherry Studio, Claude Desktop, Cursor, Trae 등을 포함한 다양한 대규모 모델 기반 MCP 클라이언트를 지원합니다.

Cherry Studio (권장)

Cherry Studio에서 SOAR MCP 서버 설정

1. Cherry Studio 열기

2. 설정 → MCP 서버로 이동

3. 설정 파일 편집, 다음 내용 추가:

   방식 1: URL 파라미터 (호환성 좋음)

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

   방식 2: 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 방식이 더 안전하며, 토큰이 URL이나 로그에 노출되지 않습니다.

Claude Desktop

Claude Desktop의 MCP 설정 파일을 편집하십시오:

위치:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%Claudeclaude_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