cortex-mcp

TypeScript Node.js MCP License: MIT

一个用于 StrangeBee/TheHive Project 开发的 Cortex 的 MCP（模型上下文协议）服务器。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`	设置为 `false` 以跳过 SSL 验证
`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 从 ~/.hermes/config.yaml 中的 mcp_servers 键读取 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 将条目写入 ~/.codex/config.toml 下的 [mcp_servers.cortex]。使用以下命令验证：

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