内容
# CrowdStrike Falcon MCP 服务器
基于 [FalconPy](https://github.com/CrowdStrike/falconpy) （CrowdStrike官方Python SDK）和 [模型上下文协议](https://modelcontextprotocol.io) （MCP）构建的AI驱动的安全运营平台。包括MCP服务器、11个选项卡的Streamlit仪表盘（“Falcon摘要”）和用于查询Falcon安全数据的CLI客户端，支持自然语言查询。
## 功能特点
- **基于FalconPy构建** — 使用CrowdStrike官方Python SDK进行所有Falcon平台交互（12个服务类，只读）
- **13个MCP工具** — 搜索警报、检测、案件、漏洞、主机、ThreatGraph IOC、 安全态势、NGSIEM数据摄入、身份保护、云安全、暴露管理、FQL验证等
- **4个MCP资源** — FQL备忘录、严重性定义、MITRE ATT&CK映射、案件状态指南
- **5个MCP提示** — 案件分类、威胁狩猎、漏洞评估、执行摘要、身份风险审查
- **11个选项卡仪表盘** — 执行摘要、检测、案件、漏洞、身份、云安全、暴露、IOC搜索、数据摄入、FQL工具、AI聊天
- **多提供商LLM支持** — Anthropic和OpenAI API格式，通过`LLM_PROVIDER`环境变量选择
- **后台缓存** — 预先获取所有Falcon数据源，实现仪表盘即时加载，并支持文件持久化
- **CLI聊天客户端** — 交互式终端Q&A，全面访问工具
## 快速入门
### 前提条件
- Python 3.10+
- CrowdStrike Falcon API凭证（在Falcon控制台中的API客户端和密钥）
- [CrowdStrike FalconPy](https://github.com/CrowdStrike/falconpy) (>=1.6.0，通过requirements.txt安装)
- *(可选)* LLM端点（兼容Anthropic或OpenAI），用于AI聊天功能
### 安装
```bash
git clone <仓库地址> && cd crwd_mcp
bash setup.sh
```
设置脚本将执行以下操作：
1. 检查Python版本
2. 创建并激活虚拟环境
3. 安装依赖项
4. 引导您选择Falcon云区域并配置`.env`文件
5. 可选地运行测试套件
6. 可选地启动缓存守护进程
### 手动设置
```bash
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # 然后编辑.env文件，填写您的凭证
```
### 运行
```bash
source venv/bin/activate
# 仪表盘（11个选项卡布局，带AI聊天）
streamlit run mcp_dashboard.py
# MCP服务器（stdio — 用于IDE/编辑器集成）
python crwd_mcp_server.py
# CLI客户端（交互式聊天）
python mcp_api_client.py
# CLI客户端（单次查询）
python mcp_api_client.py "显示安全态势"
# 缓存守护进程（保持数据新鲜，以便仪表盘即时加载）
python falcon_cache_daemon.py [轮询间隔秒数]
```
## 架构
```
crwd_mcp_server.py MCP服务器：13个工具、4个资源、5个提示
mcp_api_client.py LLM API客户端，带有工具执行 + CLI聊天
mcp_dashboard.py Streamlit仪表盘（11个选项卡UI，带AI聊天）
falcon_cache.py 后台轮询缓存，带有文件持久化
falcon_cache_daemon.py 独立缓存守护进程
tests/ pytest单元测试（基于模拟）
conftest.py 共享夹具
test_server_tools.py 工具测试
test_fql_security.py FQL注入预防测试
test_cache.py 缓存测试
```
## MCP工具
| 工具 | 描述 |
|------|-------------|
| `search_alerts` | 按产品、严重性、时间范围搜索警报 |
| `get_host_details` | 按主机名获取设备信息 |
| `test_fql_filter` | 验证FQL筛选器语法 |
| `list_available_products` | 列出Falcon产品类型及其示例 |
| `search_cases` | 按状态、严重性、时间查询案件 |
| `search_detections` | 查询所有检测（EDR、3P、IDP、NGSIEM等） |
| `search_vulnerabilities` | 查询Spotlight漏洞 |
| `search_threatgraph` | IOC查找和边类型列表 |
| `get_security_posture` | 具有风险评分的执行安全概述 |
| `search_hosts` | 按平台、状态、最近时间搜索/统计主机 |
| `get_ngsiem_ingestion` | LogScale数据摄入量和主要来源 |
| `get_identity_protection` | 风险实体、风险评分、AD帐户数据 |
| `get_cloud_security` | 按严重性、提供商、服务划分的CSPM风险 |
| `get_exposure_management` | 外部攻击面资产 |
## 必需的API范围
| 范围 | 仪表盘部分 |
|-------|-------------------|
| `alerts:read` | 检测、严重性图表、MTTD/MTTR、1P/3P跟踪 |
| `hosts:read` | 主机KPI、传感器健康（RFM、版本） |
| `cases:read` | 按状态/严重性划分的案件 |
| `spotlight-vulnerabilities:read` | 按严重性划分的漏洞计数 |
| `threatgraph:read` | IOC查找 |
| `incidents:read` | CrowdScore仪表盘、事件摘要 |
| `discover:read` | 资产库存（托管、非托管、IoT、帐户、应用程序） |
| `exposure-management:read` | 外部攻击面 |
| `identity-protection:read` | 身份保护（风险实体、传感器） |
| `cloud-security:read` | 云安全（CSPM风险） |
缺少的范围会在侧边栏检测并显示，以便您知道需要启用的范围。
## 环境变量
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `FALCON_CLIENT_ID` | 是 | Falcon API客户端ID |
| `FALCON_CLIENT_SECRET` | 是 | Falcon API客户端密钥 |
| `FALCON_BASE_URL` | 是 | Falcon云基础URL（参见`.env.example`中的区域） |
| `LLM_ENDPOINT` | 否 | 用于AI聊天的LLM端点URL |
| `LLM_API_KEY` | 否 | LLM端点的API密钥 |
| `LLM_PROVIDER` | 否 | `anthropic`（默认）或`openai` |
| `LLM_MODEL` | 否 | 模型覆盖（默认：`claude-4-6-opus` / `gpt-4o`） |
`.env`文件支持使用注释/取消注释模式的多个CID配置文件。仪表盘侧边栏包含配置文件切换器。
## 测试
```bash
# 运行所有测试（不需要API凭证）
python -m pytest tests/ -v
# 运行特定测试文件
python -m pytest tests/test_server_tools.py -v
python -m pytest tests/test_fql_security.py -v
python -m pytest tests/test_cache.py -v
```
## 许可证
Apache License 2.0 — 请参阅 [LICENSE](LICENSE)。
