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、メール）
タクソノミ集約を伴う、該当する全アナライザーでの一括分析
ドライラン対応のジョブクリーンアップ
ユーザー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