OtherF/cisco-xdr-mcp
GitHub: OtherF/cisco-xdr-mcp
为 Cisco XDR 提供只读 MCP 服务器，通过 38 个工具帮助安全人员通过 AI 助手查询事件、丰富威胁情报并进行取证分析。
Stars: 0 | Forks: 0
# cisco-xdr-mcp
用于 [Cisco XDR](https://www.cisco.com/site/us/en/products/security/xdr/index.html) API 的只读 MCP 服务器。为网络安全工程师、SOC 分析师和事件响应人员构建，他们希望通过 AI 助手调查事件、丰富可观测数据并查询威胁情报。
**7 个 API 范围共 38 个工具。只读操作 — 此服务器无法修改、创建或删除任何内容。**
## 前置条件
- Python 3.10+
- Cisco XDR API 客户端（客户端 ID + 客户端密码）
- 在您的 Cisco XDR 组织中[创建 API 凭据](https://docs.xdr.security.cisco.com/Content/Administration/api-clients.htm)
- Claude Desktop（或其他兼容 MCP 的客户端）
## 安装
```
# 克隆仓库
git clone https://github.com/OtherF/cisco-xdr-mcp.git
cd cisco-xdr-mcp
# 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# 安装包
pip install -e ".[dev]"
```
## 配置
复制示例环境文件并填写您的凭据：
```
cp .env.example .env
```
| 变量 | 必需 | 说明 |
|---|---|---|
| `CISCO_XDR_CLIENT_ID` | 是 | OAuth 2.0 客户端 ID |
| `CISCO_XDR_CLIENT_PASSWORD` | 是 | OAuth 2.0 客户端密码 |
| `CISCO_XDR_REGION` | 否 | `us`（默认）、`eu` 或 `apjc` |
**区域端点：**
| 区域 | 平台 URL |
|---|---|
| US | `https://visibility.amp.cisco.com` |
| EU | `https://visibility.eu.amp.cisco.com` |
| APJC | `https://visibility.apjc.amp.cisco.com` |
## Claude Desktop 设置
### 原生（macOS / Windows）
添加到您的 Claude Desktop 配置（Windows 上为 `%APPDATA%\Claude\claude_desktop_config.json`，macOS 上为 `~/Library/Application Support/Claude/claude_desktop_config.json`）：
```
{
"mcpServers": {
"cisco-xdr": {
"command": "cisco-xdr-mcp",
"env": {
"CISCO_XDR_CLIENT_ID": "client-...",
"CISCO_XDR_CLIENT_PASSWORD": "...",
"CISCO_XDR_REGION": "us"
}
}
}
}
```
### WSL（服务器在 WSL 中运行，Claude Desktop 在 Windows 上运行）
环境变量无法通过 `env` 块从 Claude Desktop 传递到 WSL。请改用 `.env` 文件：
```
# 在 WSL 中，进入项目目录
cp .env.example .env
# 编辑 .env 并填写凭据
```
然后添加到您的 Claude Desktop 配置（Windows 上为 `%APPDATA%\Claude\claude_desktop_config.json`）：
```
{
"mcpServers": {
"cisco-xdr": {
"command": "wsl.exe",
"args": [
"--",
"bash", "-c",
"cd /path/to/cisco-xdr-mcp && source .venv/bin/activate && exec python -m cisco_xdr_mcp"
]
}
}
}
```
服务器在启动时调用 `load_dotenv()` 并自动从 `.env` 文件读取凭据。
### 通过 SSH 的远程服务器（服务器在远程 Linux 主机上运行）
在远程主机上安装包，然后通过 SSH 使用密钥认证从 Claude Desktop 连接：
```
{
"mcpServers": {
"cisco-xdr": {
"command": "ssh",
"args": [
"-o", "StrictHostKeyChecking=accept-new",
"-i", "/path/to/ssh-key",
"user@remote-host",
"CISCO_XDR_CLIENT_ID='client-...' CISCO_XDR_CLIENT_PASSWORD='...' CISCO_XDR_REGION='us' cisco-xdr-mcp"
]
}
}
}
```
或从远程主机上的源代码运行：
```
{
"mcpServers": {
"cisco-xdr": {
"command": "ssh",
"args": [
"-o", "StrictHostKeyChecking=accept-new",
"-i", "/path/to/ssh-key",
"user@remote-host",
"CISCO_XDR_CLIENT_ID='client-...' CISCO_XDR_CLIENT_PASSWORD='...' CISCO_XDR_REGION='us' /path/to/cisco-xdr-mcp/.venv/bin/python -m cisco_xdr_mcp"
]
}
}
}
```
注意：
- SSH 密钥认证可避免交互式密码提示 — MCP 客户端需要此功能。
- `StrictHostKeyChecking=accept-new` 在首次连接时自动接受；验证主机指纹后可改为 `yes`。
- 凭据是内联环境变量 — 不会存储在远程主机上。
- 必须在远程主机上安装包：从克隆的副本运行 `pip install -e .`。
## 可用工具
许多工具使用路由参数将相关端点合并到单个工具中，减少提示令牌开销，同时保留完整的 API 覆盖范围。
### 事件（5 个工具）
| 工具 | 说明 |
|---|---|
| `xdr_search_incidents` | 按状态、受理人、类别、置信度和时间范围搜索事件 |
| `xdr_get_incident` | 获取特定事件的完整详情 |
| `xdr_get_incident_detail` | 按 `detail_type` 获取事件子资源：observables、indicators、targets、entities、graph、summary、linked_incidents、recommendations、report、export、status |
| `xdr_get_incident_events` | 获取按时间顺序排列的事件时间线（可选 `notable` 筛选） |
| `xdr_count_incidents` | 统计匹配筛选条件的事件数量，无需获取完整记录 |
### 调查（4 个工具）
| 工具 | 说明 |
|---|---|
| `xdr_search_investigations` | 搜索分析师驱动的 XDR 调查 |
| `xdr_get_investigation` | 获取特定调查的完整详情 |
| `xdr_get_investigation_detail` | 按 `detail_type` 获取调查子资源：summary、entities、graph、indicators、targets、observables、status |
| `xdr_get_investigation_events` | 获取调查的事件时间线 |
### 全球威胁情报（6 个工具）
| 工具 | 说明 |
|---|---|
| `xdr_search_global_intel` | 按 `entity_type` 搜索任何 CTIA 实体：indicator、sighting、actor、attack_pattern、campaign、malware、vulnerability、relationship、coa、tool |
| `xdr_get_observable_intel` | 按 `lookup_type` 丰富可观测数据：verdict、judgements、sightings、sighting_incidents、indicators |
| `xdr_get_observable_relationships` | 获取可观测数据的 STIX 关系（关联的活动、攻击者、恶意软件） |
| `xdr_get_global_entity` | 按类型和 ID 获取任何情报实体 |
| `xdr_get_attack_pattern_by_mitre_id` | 按 ID 查找 MITRE ATT&CK 技术（例如 T1059） |
| `xdr_get_entity_history` | 获取实体的按时间顺序排列的事件历史（设备轨迹） |
### 私有情报（9 个工具）
| 工具 | 说明 |
|---|---|
| `xdr_search_private_indicators` | 搜索您组织的私有威胁指标 |
| `xdr_get_private_verdict` | 获取可观测数据的私有裁决 |
| `xdr_search_private_assets` | 搜索私有资产记录（主机、设备、端点） |
| `xdr_search_private_target_records` | 搜索带有风险分数的目标记录 |
| `xdr_get_private_observable_sightings` | 获取可观测数据的私有 sightings |
| `xdr_search_private_sightings` | 搜索您组织的私有 sightings |
| `xdr_search_private_judgements` | 搜索您组织的私有威胁判断 |
| `xdr_search_private_entity` | 按 `entity_type` 搜索私有 STIX 实体：actor、campaign、malware、attack_pattern、vulnerability、relationship、coa、tool |
| `xdr_get_private_entity` | 按类型和 ID 获取私有 STIX 实体 |
### 案例手册（4 个工具）
| 工具 | 说明 |
|---|---|
| `xdr_search_casebooks` | 搜索用于组织调查笔记和可观测数据的案例手册 |
| `xdr_get_casebook` | 获取特定案例手册的完整详情 |
| `xdr_get_casebook_observables` | 获取案例手册中收集的所有可观测数据 |
| `xdr_get_casebook_summary` | 获取案例手册摘要及关联事件 |
### 仪表板（2 个工具）
| 工具 | 说明 |
|---|---|
| `xdr_list_dashboard_tiles` | 列出所有可用的仪表板图块及其元数据 |
| `xdr_get_tile_data` | 获取特定仪表板图块的数据 |
### 手册和任务（8 个工具）
| 工具 | 说明 |
|---|---|
| `xdr_list_playbooks` | 列出所有事件响应手册 |
| `xdr_get_playbook` | 获取手册详情，包括阶段和程序 |
| `xdr_get_incident_playbook_status` | 获取事件的手册执行状态 |
| `xdr_get_playbook_action_logs` | 获取已执行手册步骤的日志 |
| `xdr_get_playbook_phases` | 获取手册的阶段及其状态 |
| `xdr_get_incident_tasks` | 获取分配给事件的所有手册任务 |
| `xdr_list_tasks` | 列出所有事件的任务（按状态、受理人、事件筛选） |
| `xdr_get_task` | 按 ID 获取特定任务的详情 |
## 开发
```
# 运行所有测试
pytest
# 运行特定测试文件
pytest tests/test_incidents.py
# Lint 并自动修复
ruff check --fix src/ tests/
ruff format src/ tests/
# 类型检查
mypy src/
# 使用 MCP Inspector 进行交互式工具测试
npx @modelcontextprotocol/inspector cisco-xdr-mcp
```
## 架构
```
auth.py TokenManager OAuth 2.0 client credentials, asyncio.Lock
|
client.py APIClient Authenticated HTTP, error formatting, size guard
|
server.py FastMCP + lifespan Region validation, credential loading, context
|
tools/*.py @mcp.tool funcs One function per API operation
```
- **身份验证**：OAuth 2.0 客户端凭据（HTTP Basic Auth），针对 `{platform_url}/iroh/oauth2/token`。令牌被缓存并自动刷新，提前刷新时间为 60 秒。
- **输入验证**：所有工具输入都经过 Pydantic v2 模型验证。ID 路径参数经过 URL 编码并验证，拒绝路径遍历字符。
- **SSRF 防护**：所有 API 基础 URL 来自硬编码的区域映射 — 不允许用户配置 URL 覆盖。
- **响应大小保护**：超过 2 MB 的响应会被拒绝并返回详细错误信息。
## 安全
有关如何报告漏洞，请参阅 [SECURITY.md](SECURITY.md)。
## API 参考
CiscoDR API 文档：https://developer.cisco.com/docs/cisco-xdr/
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
标签：AI助手, AMSI绕过, API, API集成, CIDR输入, Cisco XDR, Claude Desktop, DAST, EDR, IOC, MCP, OAuth 2.0, Python, SOAR, 只读工具, 可观测性, 威胁情报, 威胁检测, 安全运营, 开发者工具, 恶意软件分析, 扫描框架, 无后门, 网络安全, 脆弱性评估, 自动化分析, 跨站脚本, 逆向工具, 隐私保护