内容
# 思科 XDR MCP 服务器
MCP（模型上下文协议）服务器，暴露思科 XDR API 作为 AI 助手工具。连接到 XDR 门户（例如 https://xdr.us.security.cisco.com/），具有 **27 个工具**，涵盖 Inspect、调查、事件、响应操作、案件记录、威胁情报、工作流和管理。
## 功能
- **Inspect & 调查**：解析文本中的 IOC，完整的丰富信息（目击，判决，转折链接）
- **事件**：列出、获取、更新、工作日志、提取可观察值
- **响应操作**：发现和触发（阻止、隔离、检疫）
- **案件记录**：创建和管理调查案件记录
- **威胁情报**：指标、判断、馈送、目击
- **工作流**：列出、运行、监控自动化工作流
- **管理**：集成列表、配置文件
> **参见 [INSTALL.md](INSTALL.md)** 以获取详细的安装、API 参考、更改日志和故障排除信息。
## 凭证处理（重要）
**绝不将凭证放入 `mcp.json`。** 所有身份验证均从环境变量加载。
### 推荐：使用 `.env` 文件
1. 将 `.env.example` 复制到 `.env`
2. 添加您的 XDR API 客户端凭证：
```bash
cp .env.example .env
# 使用您的 XDR_CLIENT_ID 和 XDR_CLIENT_PASSWORD 编辑 .env
```
3. 配置 Cursor/Claude 运行服务器时加载环境变量。对于 stdio 传输，MCP 客户端通常继承 shell 环境。确保在启动前加载 `.env`（例如，通过 shell 或 IDE 中的 `dotenv`）。
### 创建 API 客户端凭证
1. 登录到 [思科 XDR](https://xdr.us.security.cisco.com/) （或您的地区）
2. 进入 **管理** > **API 客户端**
3. 创建具有适当范围的新 API 客户端（例如 `enrich:read`、`inspect:read`、`casebook`、`private-intel:read` 等）
4. 将客户端 ID 和客户端密码复制到 `.env`
参见：[思科 XDR API 客户端](https://docs.xdr.security.cisco.com/Content/Administration/api-clients.htm)
### 环境变量
| 变量 | 是否必需 | 描述 |
| --- | --- | --- |
| `XDR_CLIENT_ID` | 是 | OAuth2 客户端 ID |
| `XDR_CLIENT_PASSWORD` | 是 | OAuth2 客户端密码 |
| `XDR_REGION` | 否 | `us`、`eu` 或 `apjc`（默认：`us`） |
## 安装
```bash
cd xdr-mcp
npm install
cp .env.example .env
# 使用您的凭证编辑 .env
npm run build
npm start
```
## Docker
```bash
# 构建
docker build -t cisco-xdr-mcp .
# 运行（通过环境变量传递凭证）
docker run -it --rm \
-e XDR_CLIENT_ID=your_client_id \
-e XDR_CLIENT_PASSWORD=your_client_password \
-e XDR_REGION=us \
cisco-xdr-mcp
```
对于使用 stdio 的 MCP 客户端，您通常运行容器并附加 stdio。示例 `mcp.json`（无凭证）：
```json
{
"mcpServers": {
"cisco-xdr": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "XDR_CLIENT_ID",
"-e", "XDR_CLIENT_PASSWORD",
"-e", "XDR_REGION=us",
"cisco-xdr-mcp"
],
"env": {
"XDR_CLIENT_ID": "${XDR_CLIENT_ID}",
"XDR_CLIENT_PASSWORD": "${XDR_CLIENT_PASSWORD}"
}
}
}
}
```
注意：使用您的环境或秘密管理器提供 `XDR_CLIENT_ID` 和 `XDR_CLIENT_PASSWORD`；确切的语法取决于您的 MCP 客户端。
## MCP 配置（mcp.json）
Cursor 示例 - 使用环境变量，绝不硬编码秘密：
```json
{
"mcpServers": {
"cisco-xdr": {
"command": "node",
"args": ["/path/to/xdr-mcp/build/index.js"],
"env": {
"XDR_CLIENT_ID": "from_env_or_secret",
"XDR_CLIENT_PASSWORD": "from_env_or_secret",
"XDR_REGION": "us"
}
}
}
}
```
确保 `XDR_CLIENT_ID` 和 `XDR_CLIENT_PASSWORD` 来自您的 shell 环境或秘密管理器，而不是存储在 JSON 文件中。
## API 文档
- [思科 XDR API](https://developer.cisco.com/docs/cisco-xdr/)
- [身份验证](https://developer.cisco.com/docs/cisco-xdr/authentication/)
- [快速入门](https://developer.cisco.com/docs/cisco-xdr/getting-started/)
## 仓库结构
- **[INSTALL.md](INSTALL.md)** – 安装、API 参考、更改日志、故障排除（首选文档）
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) – 交互标准
- [CONTRIBUTING.md](CONTRIBUTING.md) – 如何贡献
- [SECURITY.md](SECURITY.md) – 安全策略和报告
- [AGENTS.md](AGENTS.md) – AI 编码代理指南
该项目遵循 [CiscoDevNet devnet-template](https://github.com/CiscoDevNet/devnet-template)。
## 许可证
Apache-2.0。参见 [LICENSE](LICENSE)。
