内容
<p align="center">
<img src="docs/assets/cortex-mcp-banner.jpg" alt="cortex-mcp banner">
</p>
<h1 align="center">cortex-mcp</h1>
<p align="center">
<strong>一个允许AI客户端运行Cortex可观察性分析和响应的MCP服务器，端到端。</strong>
</p>
<p align="center">
<img src="https://img.shields.io/npm/v/thehive-cortex-mcp?style=for-the-badge&logo=npm&logoColor=white&label=thehive-cortex-mcp" alt="npm version">
<img src="https://img.shields.io/github/actions/workflow/status/lidless-labs/cortex-mcp/ci.yml?branch=main&style=for-the-badge&label=CI&logo=githubactions&logoColor=white" alt="CI status">
<img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT License">
<img src="https://img.shields.io/badge/MCP-server-7c3aed?style=for-the-badge" alt="MCP server">
<img src="https://img.shields.io/badge/node.js-20%2B-339933?style=for-the-badge&logo=nodedotjs&logoColor=white" alt="Node.js 20+">
</p>
<p align="center">
<strong>网站：</strong> <a href="https://lidless.dev/cortex-mcp">https://lidless.dev/cortex-mcp</a>
</p>
cortex-mcp是一个模型上下文协议（MCP）服务器，用于[Cortex](https://docs.strangebee.com/cortex/)，即StrangeBee/TheHive项目中的可观察性分析和主动响应引擎。它之所以存在，是因为分析师已经通过其网页UI或原始REST API手动驱动Cortex，而AI客户端可以更快地完成这项工作：检测一个指标，跨所有适用分析器聚合分类法判决，并提取工件，而无需任何人点击十几个作业。与通用HTTP桥不同，它通过公开Cortex的真实领域模型作为31种类型化的MCP工具，自动检测可观察数据类型，扩展分析，并将每个破坏性操作（响应器，删除，文件读取）限制在明确确认后面。
## 它做什么
cortex-mcp将一个MCP功能的AI客户端（Claude Desktop，Claude Code，Codex CLI，OpenClaw，Hermes等）连接到正在运行的Cortex实例，以便模型可以执行实际的可观察性分析和威胁情报丰富。Cortex是StrangeBee和TheHive SOAR堆栈中的分析器/响应器引擎：它针对可观察性（IP，域名，URL，文件哈希，电子邮件，文件）运行分析器，并针对TheHive实体执行响应器。该服务器使用Cortex的REST API，并将整个管道投射为MCP工具，资源和提示，以便代理可以浏览分析器定义，启用和配置它们，提交可观察性，等待作业报告，提取IOC工件和分类警报。自动检测将可观察性数据类型分类为分析之前，大批量分析扩展到适用分析器并聚合分类法结果，超级管理员工具涵盖组织和用户/API密钥管理。结果是会话式可观察性分析：询问“Cortex对`185.220.101.42`怎么看？”并获得聚合的多分析器判决。
## 尝试（复制粘贴MCP客户端配置）
将以下内容添加到您的MCP客户端配置中（此示例是Claude Desktop的`claude_desktop_config.json`；相同的`command`/`args`/`env`形状适用于Claude Code，Codex，OpenClaw和Hermes）。它直接使用`npx`运行已发布的npm包，无需克隆或构建：
```json
{
"mcpServers": {
"cortex": {
"command": "npx",
"args": ["-y", "thehive-cortex-mcp"],
"env": {
"CORTEX_URL": "http://cortex.example.com:9001",
"CORTEX_API_KEY": "your-org-admin-key",
"CORTEX_SUPERADMIN_KEY": "your-superadmin-key"
}
}
}
}
```
npm包名为[`thehive-cortex-mcp`](https://www.npmjs.com/package/thehive-cortex-mcp）；它安装了一个`cortex-mcp`二进制文件。仅当您想要组织和用户管理工具时，才设置`CORTEX_SUPERADMIN_KEY`。
## 先决条件
- 节点.js 20或更高版本
- 运行中的Cortex实例（推荐v3.x）
- 具有适当权限的Cortex API密钥
## 配置
| 变量 | 必需 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `CORTEX_URL` | 是 | - | Cortex基本URL（例如`http://cortex.example.com:9001`） |
| `CORTEX_API_KEY` | 是 | - | 用于常规操作的API密钥（组织管理员级别） |
| `CORTEX_SUPERADMIN_KEY` | 否 | - | 用于组织/用户/定义管理的超级管理员API密钥 |
| `CORTEX_VERIFY_SSL` | 否 | `true` | 设置为`false`以跳过SSL验证。仅适用于Cortex请求的范围限定HTTP调度器；它不会禁用整个Node进程的TLS验证过程。 |
| `CORTEX_TIMEOUT` | 否 | `30` | 秒为单位的请求超时时间 |
| `CORTEX_FILE_BASE_DIR` | 否 | - | `cortex_run_analyzer_file`可以读取文件的绝对基准目录。`filePath`仅限于此目录（检查真实路径以防止符号链接/..逃逸）；当未设置时，通过路径读取文件被拒绝，您必须通过`fileBase64`提交文件内容。 |
| `CORTEX_ALLOW_DESTRUCTIVE` | 否 | `0` | 设置为`1`（或`true`）以允许运行响应器（`cortex_run_responder`），这会引起现实世界的副作用。默认为关闭。响应器还需要每个调用的`confirm=true`。 |
| `CORTEX_MAX_FANOUT` | 否 | `10` | 在单个调用中，`cortex_analyze_observable`将提交的最大分析器数量，当扩展时。 |
### 安全和安全门
该服务器可以触发现实世界的动作并将可观察性提交给第三方服务，因此默认情况下会限制几个功能：
- **阻止任意文件读取。** `cortex_run_analyzer_file`仅在`CORTEX_FILE_BASE_DIR`内读取文件（检查真实路径以防止符号链接/..逃逸）。如果未配置基准目录，则基于路径的读取被拒绝；使用`fileBase64`显式提交内容。
- **响应器被限制。** `cortex_run_responder`需要`CORTEX_ALLOW_DESTRUCTIVE=1`在环境中**和**调用中的`confirm=true`。
- **单个项目破坏性工具需要确认。** `cortex_delete_job`和`cortex_disable_analyzer`需要`confirm=true`。
- **批量分析是保守的。** `cortex_analyze_observable`默认情况下不会扩展到每个分析器。传递显式的`analyzers`允许列表，或设置`fanOut=true`以运行所有适用分析器（上限为`CORTEX_MAX_FANOUT`）。
- **SSL验证范围限定。** 禁用`CORTEX_VERIFY_SSL`仅放松Cortex连接的TLS，而不适用于整个Node进程。
## 从源码安装
如果您更喜欢从checkout运行而不是`npx`:
```bash
git clone https://github.com/lidless-labs/cortex-mcp.git
cd cortex-mcp
npm install
npm run build
```
然后将您的客户端指向构建的二进制文件（参见下面的客户端配方）。
## 用法
### Claude 代码
```bash
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 \
-- npx -y thehive-cortex-mcp
```
添加`--scope user`使其可用于任何目录，而不仅仅是当前项目。
### OpenClaw
```bash
openclaw mcp set cortex '{
"command": "npx",
"args": ["-y", "thehive-cortex-mcp"],
"env": {
"CORTEX_URL": "http://cortex.example.com:9001",
"CORTEX_API_KEY": "your-org-admin-key",
"CORTEX_SUPERADMIN_KEY": "your-superadmin-key"
}
}'
```
如果您从源码checkout运行，请将`command`/`args`指向构建的`dist/index.js`:
```bash
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"
}
}'
```
然后重启OpenClaw网关以获取新的服务器：
```bash
systemctl --user restart openclaw-gateway
openclaw mcp list # 确认"cortex"已注册
```
### Hermes 代理
[Hermes Agent](https://github.com/NousResearch/hermes-agent)从`~/.hermes/config.yaml`下的`mcp_servers`键读取MCP配置。添加一个条目：
```yaml
mcp_servers:
cortex:
command: "npx"
args: ["-y", "thehive-cortex-mcp"]
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](https://github.com/openai/codex)通过`codex mcp add`注册MCP服务器：
```bash
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 \
-- npx -y thehive-cortex-mcp
```
Codex将条目写入`~/.codex/config.toml`下的`[mcp_servers.cortex]`。验证：
```bash
codex mcp list
```
### 独立
```bash
export CORTEX_URL=http://cortex.example.com:9001
export CORTEX_API_KEY=your-org-admin-key
npx -y thehive-cortex-mcp # 或`npm start`从源码checkout
```
## 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` | 将文件提交给分析器。`filePath`仅限于`CORTEX_FILE_BASE_DIR`（禁用时未设置）；或传递`fileBase64` |
### 分析器定义工具
| 工具 | 描述 |
| --- | --- |
| `cortex_list_analyzer_definitions` | 浏览所有可用的分析器定义并过滤（按数据类型，免费/无配置，搜索） |
| `cortex_enable_analyzer` | 在当前组织中启用分析器定义并配置 |
| `cortex_disable_analyzer` | 禁用（删除）启用的分析器（破坏性；需要`confirm=true`） |
### 作业工具
| 工具 | 描述 |
| --- | --- |
| `cortex_get_job` | 获取分析作业的状态和详细信息 |
| `cortex_get_job_report` | 获取已完成的分析作业的完整报告 |
| `cortex_wait_and_get_report` | 等待作业完成并返回报告 |
| `cortex_list_jobs` | 列出最近的分析作业，可选过滤 |
| `cortex_get_job_artifacts` | 从已完成的作业中获取工件（提取的IOC） |
| `cortex_delete_job` | 删除特定作业（破坏性；需要`confirm=true`） |
| `cortex_cleanup_jobs` | 按状态或年龄批量删除作业（带有dry-run） |
### 响应工具
| 工具 | 描述 |
| --- | --- |
| `cortex_list_responders` | 列出所有启用的响应器，可选按数据类型过滤 |
| `cortex_run_responder` | 对TheHive实体执行响应动作（破坏性；需要`CORTEX_ALLOW_DESTRUCTIVE=1`和`confirm=true`） |
### 响应器定义工具
| 工具 | 描述 |
| --- | --- |
| `cortex_list_responder_definitions` | 浏览所有可用的响应器定义并过滤 |
| `cortex_enable_responder` | 启用响应器定义并配置 |
| `cortex_disable_responder` | 禁用（删除）启用的响应器 |
### 批量操作
| 工具 | 描述 |
| --- | --- |
| `cortex_analyze_observable` | 对可观察性运行分析器（自动检测数据类型）并聚合分类法结果。传递`analyzers`允许列表，或`fanOut=true`运行所有适用分析器（上限为`CORTEX_MAX_FANOUT`） |
### 组织管理（超级管理员）
| 工具 | 描述 |
| --- | --- |
| `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` | 所有可用的分析器定义及其配置要求 |
| `cortex://responder-definitions` | 所有可用的响应器定义及其配置要求 |
| `cortex://jobs/recent` | 最近的50个分析作业 |
## MCP 提示（4个）
| 提示 | 描述 |
| --- | --- |
| `analyze-observable` | 通过Cortex分析可观察性的引导式工作流程 |
| `investigate-ioc` | 可疑IOC的深入调查工作流程 |
| `setup-cortex` | Cortex实例的新引导式设置向导（启用免费分析器，配置API密钥） |
| `triage-alert` | 结构化警报分类工作流程，带有多个可观察性分析和风险评估 |
## 示例
### 从头开始设置分析器
```
1. 使用 freeOnly=true 的 cortex_list_analyzer_definitions 查找不需要 API 密钥的分析器。
2. 使用 cortex_enable_analyzer 启用“Abuse_Finder_3_0”，并使用空配置。
3. 使用 cortex_analyze_observable 并 fanOut=true 运行所有适用的分析器（或传递分析器 ["Abuse_Finder"] 以限定范围）。
```
### 自动检测可观察类型
```
使用 cortex_analyze_observable 并带有数据“185.220.101.42”和 fanOut=true（不需要 dataType - 自动检测为 IP）。或传递一个 `analyzers` 允许列表以限制运行哪些分析器。
```
### 清理旧失败的作业
```
使用 cortex_cleanup_jobs 和 status="Failure"，dryRun=true 预览，然后 dryRun=false 删除。
```
### 分析文件
```
在服务器环境中设置 CORTEX_FILE_BASE_DIR=/srv/cortex-uploads。然后：
使用 analyzerId="Yara_3_0" 和 filePath="/srv/cortex-uploads/suspicious.exe" 调用 cortex_run_analyzer_file 以扫描 YARA 规则。
（文件路径在 CORTEX_FILE_BASE_DIR 之外被拒绝；或者传递 fileBase64。）
```
### 管理 API 密钥
```
使用 userId="analyst1" 调用 cortex_renew_user_key 以旋转其 API 密钥。
```
### 分类安全警报
```
使用带有警报描述“检测到可疑的外部流量”和可观察性“185.220.101.42，evil.example.com，44d88612fea8a8f36de82e1278abb02f”的 triage-alert 提示。
```
## 支持的数据类型
| 类型 | 示例 | 自动检测 |
| --- | --- | --- |
| `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` | 是 | <!-- content-guard: allow email -->
| `fqdn` | `mail.example.com` | 作为域名 |
| `filename` | `malware.exe` | 手动 |
| `registry` | `HKLM\Software\Malware` | 手动 |
| `file` | 二进制文件上传 | 手动 |
| `other` | CVEs, 自定义类型 | 手动 |
## 为什么不选择其他方案？
- **Cortex 网页 UI** 是为一位分析师手动点击作业而构建的。cortex-mcp 将相同的引擎置于 AI 客户端后面，以便会话式地进行分析、分类法聚合和工件提取，而不是通过十几个页面加载。
- **原始 REST 包装器或通用 HTTP MCP 桥** 提供给模型一个无类型的端点和领域知识。cortex-mcp 将分析器、响应器、作业、定义、组织和用户建模为 31 种类型化的工具，具有自动数据类型检测、受控扩展和内置安全门限，以便代理在 Cortex 的词汇表中工作，而不是从头开始重建 API。
- **将 Cortex 集成到 SOAR 运行手册或 n8n 流中** 适用于固定、预先编写的管道。此服务器适用于开放式路径：临时丰富、调查和分类，其中分析师（或代理）决定在结果出现时采取的下一步骤。
- **thehive-mcp**（配套服务器）驱动TheHive中的案件和警报管理。cortex-mcp是分析和响应层；这两个是互补的，而不是替代品。
## 什么是cortex-mcp？
- 它 **不是** Cortex的替代品或重新实现分析器。它调用您已经运行的Cortex实例；Cortex仍然执行分析。
- 它 **不是** SIEM、案件管理器或TheHive客户端。案件和警报工作流属于TheHive（参见thehive-mcp）。
- 它 **不是** 自动响应器。破坏性操作（响应器、作业删除、文件读取路径）默认情况下是关闭或需要确认的，并且永远不会在没有确认的情况下静默触发。
- 它 **不是** 一个托管服务。它作为一个stdio MCP服务器在您的客户端旁边运行；除了您配置的Cortex实例外，什么都不会发送到任何地方。
## 测试
```bash
npm test # 单元测试
npm run test:watch # 监视模式
npm run lint # 类型检查
# 集成测试（需要活动Cortex实例）
CORTEX_URL=http://cortex.example.com: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服务器入口点
config.ts # 环境配置 + 验证
client.ts # Cortex REST API客户端（完整表面）
types.ts # Cortex API类型定义
resources.ts # MCP资源（4）
prompts.ts # MCP提示（4）
tools/
analyzers.ts # 分析器工具（列表，获取，运行，运行按名称）
analyzer-definitions.ts # 定义浏览，启用，禁用
jobs.ts # 作业管理 + 清理
responders.ts # 响应器工具（列表，运行）
responder-definitions.ts # 定义浏览，启用，禁用
bulk.ts # 批量分析，自动检测
status.ts # 健康/版本检查
organizations.ts # 组织CRUD（超级管理员）
users.ts # 用户CRUD + 密钥管理（超级管理员）
tests/
client.test.ts # API客户端单元测试
tools.test.ts # 工具处理程序单元测试
integration.test.ts # 实时实例集成测试
scripts/
proxmox_install.sh # Proxmox LXC部署脚本
```
## 部署
### Proxmox LXC
```bash
bash -c "$(wget -qLO - https://raw.githubusercontent.com/lidless-labs/cortex-mcp/main/scripts/proxmox_install.sh)"
```
## 贡献
欢迎提交问题和拉取请求。参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解贡献路径，参见 [SECURITY.md](SECURITY.md) 报告漏洞。参与即表示您同意 [行为准则](CODE_OF_CONDUCT.md)。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器