cortex-mcp

TypeScript Node.js MCP License: MIT

StrangeBee/TheHive Project의 Cortex를 위한 MCP(Model Context Protocol) 서버입니다. Cortex는 분석기를 사용하여 관찰 가능 항목(IP, URL, 해시, 도메인, 이메일, 파일)의 분석을 자동화하고 대응기를 통해 대응 작업을 실행합니다. 이 MCP 서버는 Cortex의 전체 분석 및 관리 파이프라인을 LLM에 노출합니다.

기능

31개의 MCP 도구: 전체 Cortex API 영역을 포괄
4개의 MCP 리소스: Cortex 상태 탐색용
4개의 MCP 프롬프트: 가이드 워크플로우 제공 (설정, 조사, 분류)
전체 분석기/대응기 수명 주기: 정의 탐색, 활성화, 구성, 비활성화
관찰 가능 데이터 유형 자동 감지 (IP, 도메인, 해시, URL, 이메일)
분류 체계 집계를 포함한 모든 적용 가능한 분석기에 대한 대량 분석
드라이 런(dry-run) 지원을 포함한 작업 정리
사용자 API 키 관리 (생성, 갱신, 검색)
상태 관리를 포함한 조직 CRUD
이중 API 키 지원: 조직 수준 작업 + 슈퍼 관리자 관리

사전 요구 사항

Node.js 20 이상
실행 중인 Cortex 인스턴스 (v3.x 권장)
적절한 권한이 있는 Cortex API 키

설치

git clone https://github.com/solomonneas/cortex-mcp.git
cd cortex-mcp
npm install
npm run build

구성

변수	필수	기본값	설명
`CORTEX_URL`	예	-	Cortex 기본 URL (예: `http://cortex.example.com:9001`)
`CORTEX_API_KEY`	예	-	일반 작업을 위한 API 키 (조직 관리자 수준)
`CORTEX_SUPERADMIN_KEY`	아니요	-	조직/사용자/정의 관리를 위한 슈퍼 관리자 API 키
`CORTEX_VERIFY_SSL`	아니요	`true`	SSL 확인을 건너뛰려면 `false`로 설정
`CORTEX_TIMEOUT`	아니요	`30`	요청 시간 제한 (초)

사용법

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows)에 추가하세요:

{
  "mcpServers": {
    "cortex": {
      "command": "cortex-mcp",
      "env": {
        "CORTEX_URL": "http://cortex.example.com:9001",
        "CORTEX_API_KEY": "your-org-admin-key",
        "CORTEX_SUPERADMIN_KEY": "your-superadmin-key"
      }
    }
  }
}

Claude Code

claude mcp add cortex \
  --env CORTEX_URL=http://cortex.example.com:9001 \
  --env CORTEX_API_KEY=your-org-admin-key \
  --env CORTEX_SUPERADMIN_KEY=your-superadmin-key \
  -- cortex-mcp

현재 프로젝트뿐만 아니라 모든 디렉토리에서 사용할 수 있도록 --scope user를 추가하세요.

OpenClaw

npm 설치 바이너리 대신 소스 체크아웃에서 실행하는 경우, command/args를 빌드된 dist/index.js로 지정하세요:

openclaw mcp set cortex '{
  "command": "node",
  "args": ["/absolute/path/to/cortex-mcp/dist/index.js"],
  "env": {
    "CORTEX_URL": "http://cortex.example.com:9001",
    "CORTEX_API_KEY": "your-org-admin-key",
    "CORTEX_SUPERADMIN_KEY": "your-superadmin-key"
  }
}'

또는 전역 npm 설치를 사용하는 경우:

openclaw mcp set cortex '{
  "command": "cortex-mcp",
  "env": {
    "CORTEX_URL": "http://cortex.example.com:9001",
    "CORTEX_API_KEY": "your-org-admin-key",
    "CORTEX_SUPERADMIN_KEY": "your-superadmin-key"
  }
}'

그런 다음 OpenClaw 게이트웨이를 다시 시작하여 새 서버가 선택되도록 하세요:

systemctl --user restart openclaw-gateway
openclaw mcp list   # confirm "cortex" is registered

Hermes Agent

Hermes Agent는 mcp_servers 키 아래의 ~/.hermes/config.yaml에서 MCP 구성을 읽습니다. 항목을 추가하세요:

mcp_servers:
  cortex:
    command: "cortex-mcp"
    env:
      CORTEX_URL: "http://cortex.example.com:9001"
      CORTEX_API_KEY: "your-org-admin-key"
      CORTEX_SUPERADMIN_KEY: "your-superadmin-key"

또는 전역 npm 설치 대신 소스 체크아웃에서 실행하는 경우:

mcp_servers:
  cortex:
    command: "node"
    args: ["/absolute/path/to/cortex-mcp/dist/index.js"]
    env:
      CORTEX_URL: "http://cortex.example.com:9001"
      CORTEX_API_KEY: "your-org-admin-key"
      CORTEX_SUPERADMIN_KEY: "your-superadmin-key"

그런 다음 Hermes 세션 내에서 MCP를 다시 로드하세요:

/reload-mcp

Codex CLI

Codex CLI는 codex mcp add를 통해 MCP 서버를 등록합니다:

codex mcp add cortex \
  --env CORTEX_URL=http://cortex.example.com:9001 \
  --env CORTEX_API_KEY=your-org-admin-key \
  --env CORTEX_SUPERADMIN_KEY=your-superadmin-key \
  -- cortex-mcp

또는 소스 체크아웃에서 실행하는 경우:

codex mcp add cortex \
  --env CORTEX_URL=http://cortex.example.com:9001 \
  --env CORTEX_API_KEY=your-org-admin-key \
  --env CORTEX_SUPERADMIN_KEY=your-superadmin-key \
  -- node /absolute/path/to/cortex-mcp/dist/index.js

Codex는 [mcp_servers.cortex] 아래의 ~/.codex/config.toml에 항목을 작성합니다. 다음으로 확인하세요:

codex mcp list

독립 실행형

export CORTEX_URL=http://cortex.example.com:9001
export CORTEX_API_KEY=your-org-admin-key
npm start

MCP 도구 (31)

상태

도구	설명
`cortex_get_status`	Cortex 인스턴스 상태, 버전 및 구성 가져오기

분석기 도구

도구	설명
`cortex_list_analyzers`	활성화된 모든 분석기 나열 (데이터 유형별 필터링 가능)
`cortex_get_analyzer`	ID별 특정 분석기에 대한 세부 정보 가져오기
`cortex_run_analyzer`	분석을 위해 관찰 가능 항목을 특정 분석기에 제출
`cortex_run_analyzer_by_name`	ID 대신 이름으로 분석기 실행 (편의 래퍼)
`cortex_run_analyzer_file`	분석을 위해 파일(경로 또는 base64)을 분석기에 제출

분석기 정의 도구

도구	설명
`cortex_list_analyzer_definitions`	필터링(데이터 유형, 무료/구성 불필요, 검색)을 통해 260개 이상의 사용 가능한 분석기 정의 탐색
`cortex_enable_analyzer`	구성과 함께 현재 조직에서 분석기 정의 활성화
`cortex_disable_analyzer`	활성화된 분석기 비활성화(제거)

작업 도구

도구	설명
`cortex_get_job`	분석 작업의 상태 및 세부 정보 가져오기
`cortex_get_job_report`	완료된 분석 작업의 전체 보고서 가져오기
`cortex_wait_and_get_report`	작업이 완료될 때까지 기다린 후 보고서 반환
`cortex_list_jobs`	선택적 필터를 사용하여 최근 분석 작업 나열
`cortex_get_job_artifacts`	완료된 작업에서 아티팩트(추출된 IOC) 가져오기
`cortex_delete_job`	특정 작업 삭제
`cortex_cleanup_jobs`	상태 또는 기간별로 작업 대량 삭제 (드라이 런 지원)

대응기 도구

도구	설명
`cortex_list_responders`	활성화된 모든 대응기 나열 (데이터 유형별 필터링 가능)
`cortex_run_responder`	TheHive 엔티티에 대해 대응기 작업 실행

대응기 정의 도구

도구	설명
`cortex_list_responder_definitions`	필터링을 통해 137개 이상의 사용 가능한 대응기 정의 탐색
`cortex_enable_responder`	구성과 함께 대응기 정의 활성화
`cortex_disable_responder`	활성화된 대응기 비활성화(제거)

대량 작업

도구	설명
`cortex_analyze_observable`	자동 감지된 데이터 유형 및 집계된 분류 체계 결과와 함께 적용 가능한 모든 분석기 실행

조직 관리 (슈퍼 관리자)

도구	설명
`cortex_list_organizations`	모든 조직 나열
`cortex_get_organization`	조직 세부 정보 가져오기
`cortex_create_organization`	새 조직 생성
`cortex_update_organization`	조직 설명 또는 상태 업데이트

사용자 관리 (슈퍼 관리자)

도구	설명
`cortex_list_users`	모든 조직의 사용자 나열
`cortex_get_user`	사용자 세부 정보 가져오기
`cortex_create_user`	조직 내 새 사용자 생성
`cortex_renew_user_key`	사용자를 위한 새 API 키 생성 (이전 키 무효화)
`cortex_get_user_key`	사용자의 현재 API 키 검색

MCP 리소스 (4)

URI	설명
`cortex://analyzers`	기능이 포함된 활성화된 분석기
`cortex://analyzer-definitions`	구성 요구 사항이 포함된 260개 이상의 사용 가능한 분석기 정의
`cortex://responder-definitions`	구성 요구 사항이 포함된 137개 이상의 사용 가능한 대응기 정의
`cortex://jobs/recent`	최근 50개 분석 작업

MCP 프롬프트 (4)

프롬프트	설명
`analyze-observable`	Cortex를 통해 관찰 가능 항목을 분석하기 위한 가이드 워크플로우
`investigate-ioc`	의심스러운 IOC에 대한 심층 조사 워크플로우
`setup-cortex`	새로운 Cortex 인스턴스를 위한 가이드 설정 마법사 (무료 분석기 활성화, API 키 구성)
`triage-alert`	다중 관찰 가능 항목 분석 및 위험 평가를 포함한 구조화된 경고 분류 워크플로우

예시

처음부터 분석기 설정

1. Use cortex_list_analyzer_definitions with freeOnly=true to find analyzers
   that need no API keys.
2. Use cortex_enable_analyzer to enable "Abuse_Finder_3_0" with empty config.
3. Use cortex_analyze_observable with data "8.8.8.8" to analyze the IP.

관찰 가능 유형 자동 감지

Use cortex_analyze_observable with data "185.220.101.42"
(no dataType needed - auto-detects as IP)

오래된 실패 작업 정리

Use cortex_cleanup_jobs with status "Failure", dryRun true to preview,
then dryRun false to delete.

파일 분석

Use cortex_run_analyzer_file with analyzerId "Yara_3_0",
filePath "/tmp/suspicious.exe" to scan with YARA rules.

API 키 관리

Use cortex_renew_user_key with userId "analyst1" to rotate their API key.

보안 경고 분류

Use the triage-alert prompt with alertDescription "Suspicious outbound traffic
detected" and observables "185.220.101.42, evil.example.com, 44d88612fea8a8f36de82e1278abb02f"

지원되는 데이터 유형

유형	예시	자동 감지
`ip`	`8.8.8.8`, `2001:db8::1`	✅
`domain`	`example.com`	✅
`url`	`https://malware.example.com/payload`	✅
`hash`	MD5, SHA1, SHA256, SHA512	✅
`mail`	`user@example.com`	✅
`fqdn`	`mail.example.com`	도메인으로
`filename`	`malware.exe`	수동
`registry`	`HKLM\Software\Malware`	수동
`file`	바이너리 파일 업로드	수동
`other`	CVE, 사용자 지정 유형	수동

테스트

npm test              # Unit tests (36 tests)
npm run test:watch    # Watch mode
npm run lint          # Type check

# Integration tests (requires live Cortex instance)
CORTEX_URL=http://cortex:9001 \
CORTEX_API_KEY=your-key \
CORTEX_SUPERADMIN_KEY=your-superadmin-key \
npx vitest run tests/integration.test.ts

프로젝트 구조

cortex-mcp/
  src/
    index.ts                  # MCP server entry point
    config.ts                 # Environment config + validation
    client.ts                 # Cortex REST API client (full surface)
    types.ts                  # Cortex API type definitions
    resources.ts              # MCP resources (4)
    prompts.ts                # MCP prompts (2)
    tools/
      analyzers.ts            # Analyzer tools (list, get, run, run-by-name)
      analyzer-definitions.ts # Definition browsing, enable, disable
      jobs.ts                 # Job management + cleanup
      responders.ts           # Responder tools (list, run)
      responder-definitions.ts # Definition browsing, enable, disable
      bulk.ts                 # Bulk analysis with auto-detect
      status.ts               # Health/version check
      organizations.ts        # Org CRUD (superadmin)
      users.ts                # User CRUD + key management (superadmin)
  tests/
    client.test.ts            # API client unit tests
    tools.test.ts             # Tool handler unit tests
    integration.test.ts       # Live instance integration tests (21 tests)
  scripts/
    proxmox_install.sh        # Proxmox LXC deployment script

배포

Proxmox LXC

bash -c "$(wget -qLO - https://raw.githubusercontent.com/solomonneas/cortex-mcp/main/scripts/proxmox_install.sh)"

라이선스

MIT