fspms/WSElements-mcp
GitHub: fspms/WSElements-mcp
一个基于 MCP 协议的服务器，让 AI 助手能够连接 WithSecure Elements 平台进行自动化安全分析、威胁狩猎和终端响应操作。
Stars: 0 | Forks: 0
# WithSecure Elements 的 MCP 服务器
一个用于将 AI 代理连接到 WithSecure Elements 以进行自动化安全分析和威胁搜寻的 MCP (Model Context Protocol) 服务器。
## 功能特性
- **事件**：访问和管理 Broad Context Detections (BCD)
- **安全事件**：检索和分析安全事件
- **组织**：管理组织信息
- **设备**：监控设备并执行操作
- **响应操作**：在设备上执行安全响应操作
- **软件更新**：安装软件更新并管理设备上的缺失更新
- **OAuth2 身份验证**：与 WithSecure Elements API 的安全集成
## 前置条件
- Python 3.10 或更高版本
- WithSecure Elements API 凭证 (Client ID, Client Secret)
- 组织 ID (可选，可通过 API 获取)
- Docker (用于容器化部署)
## 安装说明
### 使用 Docker (推荐)
运行 WithSecure Elements MCP 服务器的最简单方法是使用 Docker：
```
# 拉取最新镜像
docker pull ghcr.io/fspms/wselements-mcp:latest
# 使用环境变量运行
docker run --rm \
-e WITHSECURE_CLIENT_ID=your_client_id \
-e WITHSECURE_CLIENT_SECRET=your_client_secret \
-e WITHSECURE_BASE_URL=https://api.connect.withsecure.com \
-e WITHSECURE_ORGANIZATION_ID=your_organization_id \
-p 8000:8000 \
ghcr.io/fspms/wselements-mcp:latest \
--transport streamable-http --host 0.0.0.0 --port 8000
```
### 使用 Docker Compose
创建一个 `docker-compose.yml` 文件：
```
version: '3.8'
services:
withsecure-elements-mcp:
image: ghcr.io/fspms/wselements-mcp:latest
container_name: withsecure-elements-mcp
ports:
- "8000:8000"
environment:
- WITHSECURE_CLIENT_ID=your_client_id
- WITHSECURE_CLIENT_SECRET=your_client_secret
- WITHSECURE_BASE_URL=https://api.connect.withsecure.com
- WITHSECURE_ORGANIZATION_ID=your_organization_id
- MCP_DEBUG=false
- MCP_LOG_LEVEL=INFO
- WITHSECURE_MCP_MODULES=incidents,events,organizations,devices,response_actions,software_updates
command: ["--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8000"]
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
```
然后运行：
```
docker-compose up -d
```
### 使用 uv 安装
```
uv tool install withsecure-elements-mcp
```
### 使用 pip 安装
```
pip install withsecure-elements-mcp
```
## 配置
### 环境变量
创建一个包含以下信息的 `.env` 文件：
```
# WithSecure Elements API 配置
WITHSECURE_CLIENT_ID=your_client_id
WITHSECURE_CLIENT_SECRET=your_client_secret
WITHSECURE_BASE_URL=https://api.connect.withsecure.com
WITHSECURE_ORGANIZATION_ID=your_organization_id
WITHSECURE_API_SCOPE=read_write
# MCP Server 配置
MCP_DEBUG=false
MCP_LOG_LEVEL=INFO
WITHSECURE_MCP_MODULES=incidents,events,organizations,devices,response_actions,software_updates
```
### 可用环境
- **生产环境** : `https://api.connect.withsecure.com`
- **预发环境** : `https://api.connect-stg.fsapi.com`
- **CI 环境** : `https://api.connect-ci.fsapi.com`
### API Scope 配置
`WITHSECURE_API_SCOPE` 环境变量控制对 WithSecure Elements API 的访问级别：
- **`read_only`** : 仅限只读访问 (scope: `connect.api.read`)
- 如果你的 WithSecure client 配置为只读访问，请使用此选项
- 允许检索数据但不能修改
- 解决只读 client 的 "Scope not allowed for the client" 错误
- **`read_write`** : 完全读写访问 (scopes: `connect.api.read connect.api.write`)
- 如果你的 WithSecure client 拥有完全访问权限，请使用此选项
- 允许所有读写操作
- 默认选项
**只读 client 的配置示例：**
```
WITHSECURE_API_SCOPE=read_only
```
### 模块配置
服务器支持 7 个可以启用/禁用的主要模块：
- **`incidents`** : Broad Context Detections (BCD) 管理
- **`events`** : 安全事件分析和监控
- **`organizations`** : 组织信息和设置
- **`devices`** : 设备监控和管理
- **`response_actions`** : 安全响应操作执行
- **`software_updates`** : 软件更新安装、管理和扫描
## 使用方法
### 命令行
使用默认设置运行服务器 (stdio transport):
```
withsecure-elements-mcp
```
使用 SSE transport 运行：
```
withsecure-elements-mcp --transport sse
```
使用 streamable-http transport 运行：
```
withsecure-elements-mcp --transport streamable-http
```
在自定义端口上使用 streamable-http transport 运行：
```
withsecure-elements-mcp --transport streamable-http --host 0.0.0.0 --port 8080
```
### 模块配置
WithSecure Elements MCP 服务器支持多种方式来指定要启用的模块：
#### 1. 命令行参数 (最高优先级)
```
# 启用特定模块
withsecure-elements-mcp --modules incidents,events,organizations,devices,response_actions
# 仅启用一个模块
withsecure-elements-mcp --modules incidents
```
#### 2. 环境变量 (回退选项)
```
# 导出环境变量
export WITHSECURE_MCP_MODULES=incidents,events,organizations,devices,response_actions,software_updates
withsecure-elements-mcp
```
#### 3. 默认行为 (所有模块)
如果未指定模块，则默认启用所有可用模块。
### 作为库使用
```
from withsecure_elements_mcp.server import WithSecureElementsMCPServer
# 创建并运行 Server
server = WithSecureElementsMCPServer(
base_url="https://api.connect.withsecure.com",
debug=True,
enabled_modules=["incidents", "events", "organizations", "devices", "response_actions", "software_updates"]
)
# 使用 stdio transport 运行（默认）
server.run()
# 或使用 SSE transport 运行
server.run("sse")
# 或使用 streamable-http transport 运行
server.run("streamable-http", host="0.0.0.0", port=8080)
```
## 编辑器/助手集成
### MCP 配置
#### 使用 Docker
```
{
"mcpServers": {
"withsecure-elements-mcp": {
"command": "docker",
"args": [
"run",
"--rm",
"-p",
"8000:8000",
"-e",
"WITHSECURE_CLIENT_ID=your_client_id",
"-e",
"WITHSECURE_CLIENT_SECRET=your_client_secret",
"-e",
"WITHSECURE_BASE_URL=https://api.connect.withsecure.com",
"-e",
"WITHSECURE_ORGANIZATION_ID=your_organization_id",
"-e",
"MCP_DEBUG=false",
"-e",
"MCP_LOG_LEVEL=INFO",
"-e",
"WITHSECURE_MCP_MODULES=incidents,events,organizations,devices,response_actions,software_updates",
"ghcr.io/fspms/wselements-mcp:latest",
"--transport",
"streamable-http",
"--host",
"0.0.0.0",
"--port",
"8000"
]
}
}
}
```
#### 使用 HTTP Transport (当服务器已在运行时)
```
{
"mcpServers": {
"withsecure-elements-mcp": {
"url": "http://localhost:8000",
"transport": "http"
}
}
}
```
#### 使用 uvx (用于本地开发)
```
{
"mcpServers": {
"withsecure-elements-mcp": {
"command": "uvx",
"args": [
"--env-file",
"/path/to/.env",
"withsecure-elements-mcp"
]
}
}
}
```
### 带模块选择
```
{
"mcpServers": {
"withsecure-elements-mcp": {
"command": "uvx",
"args": [
"--env-file",
"/path/to/.env",
"withsecure-elements-mcp",
"--modules",
"incidents,events,response_actions"
]
}
}
}
```
## 可用模块
### 事件
- 列出事件
- 检索事件详情
- 归档/取消归档事件
- 更新事件状态
### 安全事件
- 列出安全事件
- 检索事件详情
- 根据条件筛选事件
### 组织
- 检索组织信息
- 列出可访问的组织
### 设备
- 列出设备
- 检索设备详情
- 对设备执行操作
- **发送完整状态**：从设备请求完整状态信息
- 强制设备将其完整状态发送到服务器
- 每次操作支持 1-5 台设备
- **重启系统**：重启设备 (仅限 Windows 计算机)
- 重启前显示的可选消息
- 每次操作支持 1-5 台设备
### 响应操作
- 列出响应操作响应
- 在设备上创建响应操作
- 执行安全操作，包括：
- **进程管理**：终止线程、终止进程、收集进程内存
- **内存分析**：完整内存转储、进程内存收集
- **文件操作**：收集文件、删除文件、隔离/取消隔离文件
- **系统控制**：运行命令、重启/关闭设备
- **网络隔离**：将设备与网络隔离、解除隔离
- **代理管理**：重启安全代理
### 软件更新
- **安装软件更新**：在设备上安装特定更新或按严重程度安装更新
- 安装特定公告 ID
- 按严重程度安装更新 (critical, important, everything)
- 升级期间强制关闭应用程序
- **获取缺失的更新**：检索设备的缺失软件更新列表
- 按严重程度筛选 (critical, important, moderate, low, unclassified)
- 按类别筛选 (security, nonSecurity, servicePack, securityTool, none)
- 限制结果数量 (1-200)
- **扫描更新**：在设备上触发手动软件更新扫描
- 强制设备检查可用更新
- 每次操作支持 1-5 台设备
## 示例
该项目在 `examples/` 目录中包含多个使用示例：
- **`basic_usage.py`** : 基本的服务器设置和配置
- **`sse_usage.py`** : Server-Sent Events transport 示例
- **`streamable_http_usage.py`** : HTTP transport 示例
### 快速入门示例
```
import asyncio
from withsecure_elements_mcp.server import WithSecureElementsMCPServer
async def main():
# Create server with all modules enabled
server = WithSecureElementsMCPServer(
debug=True,
enabled_modules=["incidents", "events", "organizations", "devices", "response_actions", "software_updates"]
)
# Run with stdio transport
await server.run("stdio")
if __name__ == "__main__":
asyncio.run(main())
```
## 开发
### 开发环境设置
```
# 克隆 repository
git clone https://github.com/withsecure/elements-mcp.git
cd elements-mcp
# 创建虚拟环境并安装依赖
uv sync --all-extras
# 激活虚拟环境
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# 或使用提供的启动脚本
# 在 Windows 上：
.\scripts\start.ps1
# 在 Linux/macOS 上：
./scripts/start.sh
```
### 运行测试
```
# 运行所有测试
pytest
# 运行测试并显示详细输出
pytest -v -s
```
## 许可证
本项目采用 MIT 许可证授权 - 详情请参阅 LICENSE 文件。
## 安全注意事项
- **API 凭证**：使用环境变量或密钥管理系统安全地存储你的 WithSecure API 凭证
- **网络安全**：在生产环境中使用 HTTPS
- **访问控制**：仅限授权用户访问 MCP 服务器
- **日志记录**：监控和审计所有 API 调用和响应操作
- **响应操作**：谨慎使用响应操作，因为它们可能会影响系统运行
## 故障排除
### 常见问题
1. **身份验证错误**：验证你的 API 凭证和组织 ID
2. **模块未找到**：确保模块已包含在 `WITHSECURE_MCP_MODULES` 中
3. **连接问题**：检查网络连接和 API endpoint URL
4. **权限错误**：验证你的 API 凭证是否具有必要的权限
### 调试模式
启用调试模式以获取详细日志：
```
# 环境变量
export MCP_DEBUG=true
# 命令行
withsecure-elements-mcp --debug
```
## 支持
这是一个社区驱动的开源项目。有关更多信息，请参阅我们的 SUPPORT 文件。
## 关于
将 AI 代理连接到 WithSecure Elements，以进行自动化安全分析和威胁搜寻。
标签：AI代理, API集成, Broad Context Detections, Docker容器化, EDR, FTP漏洞扫描, GPT, HTTP/HTTPS抓包, MCP服务器, Model Context Protocol, OAuth2认证, Python, WithSecure Elements, 事件管理, 可观测性, 威胁搜寻, 安全事件响应, 安全编排, 态势感知, 无后门, 漏洞管理, 端点检测与响应, 网络安全, 脆弱性评估, 脱壳工具, 自动化安全分析, 设备监控, 请求拦截, 软件更新, 隐私保护